官方插件 · 扫码绑定 · 灰度门槛 · 六步 Runbook · 生产避坑
2026 年 OpenClaw 对 IM 通道采用核心与插件分离：核心只提供通用 channel 契约与 Gateway 路由；微信登录、Tencent iLink API、媒体上下传与账号监听由外部 npm 包 @tencent-weixin/openclaw-weixin 负责，CLI 中通道 id 为 openclaw-weixin。面向用户的名称是 WeChat / ClawBot；包名与配置路径仍用 Weixin，排障时请统一搜 openclaw-weixin，避免在配置文件里搜错关键字。
与社区自研「Webhook 转发微信消息到 OpenClaw」不同，官方插件走扫码登录 + 本机凭证落盘。Gateway 启动后由插件为每个已配置账号启动 Weixin monitor，入站消息经 channel 契约规范化后路由到 Agent，出站再经插件回写。这意味着 Gateway 必须与扫码登录在同一台机器（或同一状态目录）；在 A 机 SSH 扫码、在 B 机跑 Gateway 的典型错配，会直接表现为「扫了但收不到」。
官方插件：通过 openclaw plugins install 或 npx @tencent-weixin/openclaw-weixin-cli install 安装，版本线与 OpenClaw 主版本绑定（见第二节）。
Gateway 角色：发现插件 manifest、加载入口、管理 Agent 与 session；微信特有逻辑不在 core 仓库。
能力边界：当前元数据标明支持单聊与媒体，群聊未在官方能力列表中；勿把 Telegram 群 Bot 经验直接套用。
Sidecar 行为：插件可在 Gateway 旁启动 helper 监听 Tencent API；旧版 OpenClaw 曾出现 stale cleanup 误杀父 Gateway 导致重启循环，需保持 core 与插件同步更新。
访问控制：单聊仍走 OpenClaw 标准 pairing / allowlist，新发送者需 openclaw pairing approve，与 多通道加固清单 的白名单叙事一致。
微信通道的成败多半在「插件版本 + Gateway 重启 + 扫码机器一致」三件事；模型强弱排在它们之后。
在执行任何 install 指令前，请把下列项目写进变更单并逐项勾选。插件在启动时会检查宿主 OpenClaw 版本，不匹配会拒绝加载而非降级运行。微信客户端侧需能进入「我 → 设置 → 插件」看到 ClawBot 入口；部分账号仍处灰度，未见入口时应先更新 App 而非反复重装 npm 包。
| 检查项 | 要求 | 不符时的动作 |
|---|---|---|
| OpenClaw 主版本 | 2.x 插件需 >=2026.3.22；1.x legacy 对应 >=2026.1.0 <2026.3.22 | 升级 OpenClaw 或 plugins install @tencent-weixin/openclaw-weixin@legacy |
| 微信客户端 | 手机端能扫描登录 QR；建议 iOS/Android 均更新到 2026 年 3 月后版本 | 确认 App 已更新；灰度未开则等待或换测试号 |
| Node 运行环境 | 与 OpenClaw 安装文一致（常见 22.14+） | 先跑 openclaw doctor，见安装排障文 |
| 账号策略 | 建议小号 / 测试号隔离生产主号；多账号需配置 session.dmScope | 多账号时设 per-account-channel-peer 避免 session 串线 |
| 常驻节点 | Gateway 需 7×24；笔记本休眠会断 monitor | 迁移至 VPS 或远程 Mac 服务器，见第六节 |
npm 镜像与跨境网络会影响 npx 首次拉包时间；在生产服务器上请预留足够磁盘与出站带宽，并在 screen 或 systemd 下执行安装，避免 SSH 断线留下半成品。若团队已在 Docker 路径跑 Gateway，请先对照 Compose 基线文 确认插件目录挂载与重启策略，再装微信插件。
@tencent-weixin npm 作用域，与社区非官方桥接包名不同，装错包会导致 Gateway 加载不到 manifest。官方提供两条等价路径；选一条写进 Runbook 即可，勿在同一变更单混用导致版本漂移。
npx -y @tencent-weixin/openclaw-weixin-cli@latest install openclaw gateway restart
openclaw plugins install "@tencent-weixin/openclaw-weixin" openclaw config set plugins.entries.openclaw-weixin.enabled true openclaw plugins list openclaw gateway restart
CLI 自动选版：openclaw-weixin-cli 会检测已装 OpenClaw 版本并安装兼容插件 tag（latest 或 legacy）。
手动路径：适合已锁定 npm registry、需离线镜像或 CI 可重现的团队；安装后务必 enabled true。
重启 Gateway：两条路径都必须 openclaw gateway restart，否则 manifest 不会被重新加载。
验证安装：openclaw plugins list 应出现 openclaw-weixin；再跑 openclaw --version 对照相容表。
扫码登录：在 Gateway 主机执行 openclaw channels login --channel openclaw-weixin，手机微信扫码确认。
首条回环：从已允许账号发送短文本，同时 openclaw logs --follow；无回复先查 pairing 而非换模型。
提示：若启动报错「requires compiled runtime output for TypeScript entry」，代表 npm 包缺少编译产物；应更新/重装插件或暂时 enabled false 降级，勿在生产同时改模型路由。
登录必须在运行 Gateway 的同一台机器执行；QR 过期需重新生成，勿把终端截图转传过久才扫。
openclaw channels login --channel openclaw-weixin openclaw channels status --probe openclaw pairing list openclaw-weixin openclaw pairing approve openclaw-weixin <CODE>
| 维度 | 微信 openclaw-weixin | Telegram / Discord 等 |
|---|---|---|
| 身份绑定 | 手机扫码登录，凭证落本机状态目录 | Bot Token / OAuth，多为配置文件或环境变量 |
| 公网回调 | 插件主动连 Tencent API，非典型 webhook 入口 | 常需 HTTPS webhook 或长连，受反代与 TLS 影响大 |
| 群聊 | 目前能力元数据未标群聊 | Discord / Telegram 群组为一级场景 |
| 多账号 | 重复 login；建议 dmScope per-account-channel-peer | 多 Bot Token 或多 workspace 条目 |
| 访问控制 | pairing + allowlist | 各平台 allowlist / 频道权限模型 |
验收顺序建议固定为：plugins list → gateway status → channels status --probe → 微信首条消息 → Gateway 日志三段式（通道事件 / Gateway request / 模型 provider）。与 运行期排障文 的分层一致，可避免深夜同时改反代与模型 tag。
下列症状在 2026 年工单中反复出现；请用通道 / Gateway / 模型三段式定位，与运行期排障文对齐，避免在同一变更单里同时改插件、反代与模型 tag。
| 症状 | 先查 | 常见动作 |
|---|---|---|
| 扫码后无 ClawBot 联系人 | QR 是否过期、是否同一 Gateway 主机 | 重新 login；确认手机微信版本与灰度 |
| channels 已装但离线 | enabled 与 Gateway 进程 | config set ... enabled true 后 restart |
| Gateway 反复重启 | core 与插件版本、sidecar cleanup | 同步升级 OpenClaw 与插件；plugins install --force |
| 收得到但不回复 | pairing 待核准、allowlist | pairing list + approve；勿先调模型 |
| 群聊无反应 | 能力边界 | 改单聊验收；群场景另评估其他通道 |
| 媒体失败 | 文件大小、插件媒体 API 限额 | 缩小附件；查插件 release note |
npm view @tencent-weixin/openclaw-weixin version 输出。注意：暂时停用请 config set plugins.entries.openclaw-weixin.enabled false 后 restart，而非直接删状态目录；否则下次 login 可能与残留 session 冲突。
个人笔记本适合验证扫码与首条回环；当 ClawBot 要承接值班告警、夜间 cron 或多人共用 Gateway 时，应把插件状态目录、Gateway 数据与扫码主机一并迁到可合同化的 24/7 节点。纯 Linux VPS 若未规划 outbound 带宽与进程保活，微信 monitor 在重启后容易出现「假在线」。
Compose / Docker：依 基线文 锁 image digest；插件目录与状态卷持久化，重启策略 unless-stopped。
加固：listener、反代、审计字段对照 多通道加固清单；微信虽非典型 webhook，仍要限制管理口暴露。
日志三段式：通道事件 ID、Gateway request、模型 provider 分栏；MTTR 可从数小时压到一轮 on-call。
备援 Gateway：重大升级前备份状态目录与配置；参考 24/7 常驻文 做 daemon 与开机自启验收。
对需要稳定 ClawBot 单聊、可审计变更与固定 SLA 的小团队，VpsMesh 的 Mac Mini 云端租赁通常是更优解：Apple Silicon 节点便于 Gateway 与 Ollama 或云端 API 同机部署，带宽与磁盘可预测；价格见 价格页，部署与远程连接见 帮助中心。验收后每周记录 Gateway uptime、pairing 拒绝率与插件版本，仅在超过阈值时升级或增加备援节点。