2026 年腾讯微信 ClawBot 安装与注意事项：一键 CLI、版本兼容矩阵与安全边界 Runbook

接微信前最常见的六种踩坑（先认清再扫码）

1. Gateway 未常驻就扫码：笔记本合盖后通道掉线，误以为是「微信插件坏了」。
2. 宿主与插件版本错配：OpenClaw 已升到 2026.3.22+，仍装着 1.0.x 线路插件，启动时报兼容性错误。
3. 用主微信号接生产 Agent：内容经腾讯侧处理，敏感词与账号风控不可控。
4. 给 Agent 过大工作目录：微信里一句「整理桌面」可能触及整个用户目录。
5. 把群聊当目标场景：当前能力以单聊为主，群 @ 与多人群文件策略不同。
6. 能收消息却不能跑工具：根因常在 tools.profile，而非微信通道本身——见工具不执行 Runbook。

腾讯在 GitHub 维护 openclaw-weixin 插件，并通过 npm 发布 @tencent-weixin/openclaw-weixin-cli（2026 年 5 月仍活跃更新）。安装器会读取本机 openclaw --version，按兼容矩阵选择 latest（2.0.x）或 legacy（1.0.x）dist-tag，再调用 openclaw plugins install 与扫码登录——这比手工猜版本号更贴近「可复现运维」。

前置清单：Gateway、微信客户端与网络

在运行 CLI 之前，建议逐项打勾：

• OpenClaw Gateway 已启动且 openclaw gateway status 为健康；远程部署时确认只有一个权威 Gateway 进程。
• Node 基线：与站内其它 2026 Runbook 一致，推荐 Node 24；过低版本可能导致 CLI 与 Gateway 分裂。
• 微信客户端：iOS 8.0.70+、安卓 8.0.69+（以腾讯文档与社区教程为准，升级后再扫码）。
• 出站网络：运行 Gateway 的主机需能访问 npm 与腾讯侧握手端点；公司代理需提前写入环境变量。
• 变更窗口：若即将 openclaw update，先 backup create（见升级护航文）。

一键安装：openclaw-weixin-cli

在已安装 openclaw CLI 的机器上执行（可与 Gateway 同机，或通过 SSH 登录远程 Mac）：

扫码成功后，用文件传输助手或专用小号发一条探针消息，确认 Gateway 日志出现入站事件。若 Control UI 里暂时看不到「微信」通道，社区常见做法是更新控制台并强刷浏览器缓存（Windows：Ctrl+F5；macOS：Cmd+Shift+R）。

手动安装路径（CI / 无交互环境）

当 npx 向导无法弹出二维码（无 TTY、纯 SSH）时，改用手动四步：

注意事项：产品边界、合规与权限（必读）

下列限制来自腾讯侧 Public Beta 说明与社区实测汇总，应写进团队 Runbook，而不是事后才发现：

• 单聊为主：不要规划「微信群机器人」替代企业微信应用；群场景能力随时可能调整。
• 文件只进不出：可接收用户发来的文件供 Agent 分析，但不能可靠地把大文件「发回」微信对话。
• 24 小时互动窗口：长时间未互动后，主动推送可能被丢弃；适合「你问我答」，不适合无人值守强推送营销。
• 一号一「虾」：一个微信号通常只能绑定一只龙虾实例；一只 Gateway 可服务多个已登录微信号（多账号条目）。
• 内容与合规：消息经腾讯基础设施处理；金融、加密货币等敏感词可能被过滤；服务条款保留调整或终止权利。
• 工作目录最小权限：在 AGENTS.md / 工具策略中限定可写路径；勿把 $HOME 整盘暴露给微信触发的工具链。

六步「装插件—扫码—验收—加固」Runbook

1. 冻结版本指纹：记录 openclaw --version、插件版本、Gateway 部署形态（本机 / Docker / 远程 Mac）。
2. 备份：生产环境先 openclaw backup create，避免扫码状态与配对丢失无法回滚。
3. 安装插件：优先 openclaw-weixin-cli install；失败再走手动 plugins install。
4. 扫码与探针：专用小号 → 文件传输助手发测试句 → 查 Gateway 日志入站。
5. 权限加固：收窄工具目录、检查 tools.profile 是否为 coding 或 full（按团队策略）。
6. 7×24 落点：把 Gateway 迁到常电主机；笔记本仅 SSH 转发 Control UI（见 SSH 常驻 Runbook）。

三条应写进变更单的量化口径

• 通道可用率：7 日内微信入站成功率（排除用户 24h 未互动导致的丢弃），目标 ≥99%（在常电 Gateway 前提下）。
• 插件错配次数：升级 OpenClaw 后未重跑兼容安装器的次数；生产目标为 0。
• 账号隔离：绑定 ClawBot 的微信号中，主号占比目标为 0。

收束：微信是入口，稳定宿主才是底座

只在个人笔记本上扫码、合盖即断线，会把「Agent 自动化」变成「偶尔能聊的玩具」。腾讯云 Lighthouse 等一键镜像能降低首次装 OpenClaw 的门槛，但若 Gateway 仍随本地电源策略起伏，微信通道的 SLA 依然不可审计。

对需要 7×24 单聊接入、可工单化变更、目录边界清晰 的团队，把 OpenClaw + openclaw-weixin 固定在 MACCOME 六国独占远程 Mac（M4 / M4 Pro）上，通常比在睡眠笔记本上与二维码、probe 超时搏斗更省总运维成本；公开档位可先对照多地区节点与租期指南，再与SSH 转发常驻 Runbook 串联拓扑。