官方 @tencent-weixin/openclaw-weixin · 版本矩阵 · 灰度入口 · 八步 Runbook
腾讯 ClawBot 把个人微信接到 OpenClaw 的官方路径，是外部通道插件 @tencent-weixin/openclaw-weixin（通道 ID：openclaw-weixin），而不是把 Bot 写进 OpenClaw 核心仓库。若你已在租用远程 Mac 上跑 Gateway，却卡在「插件装了但宿主版本不兼容」「扫码在 SSH 里看不清」「多账号私信串会话」「手机里没有 ClawBot 灰度开关」——本文按可审计运维写法给出：与《企业微信 OpenClaw 安全指南》正交的个人号边界、SSH × VNC 决策矩阵、八步 Runbook、四条可贴工单结论，以及 FAQ。前置建议先对照《十分钟安装路线图》把 CLI/Gateway 跑通，再装微信插件；若计划暴露控制台到公网，务必并行阅读《Gateway 公网 HTTPS 反代》，避免把本机凭据目录与 18789 裸端口一起暴露。
个人微信接入的真实难点，集中在宿主版本、登录介质、会话隔离与产品灰度四件事上；模型好不好用反而是后排问题。
宿主与插件双版本：OpenClaw ≥ 2026.3.22 才应装 openclaw-weixin 2.x（npm latest）；更低宿主若强装 latest，启动时会报宿主版本不兼容并拒绝加载。
扫码必须在 Gateway 同机：openclaw channels login --channel openclaw-weixin 输出的 QR 与 token 落盘路径，默认假设与正在运行的 Gateway 是同一台机器、同一用户上下文；纯 SSH 转发终端常导致「扫了但没写入你看的那个 HOME」。
多账号私信串线：重复执行 login 会新增账号条目；不设 session.dmScope 时，多个微信号的消息可能进同一 DM 桶。
能力边界：单聊为主：官方文档写明当前插件元数据未声明群聊；不要按「微信群 @ 机器人」预期验收。
ClawBot 灰度与通道插件并存：手机微信「设置」里的 ClawBot 入口仍在灰度放量（常见需较新客户端，如 8.0.70+）；没有灰度入口不代表 Gateway 侧一定不能走 openclaw-weixin 扫码，但产品 UI 与通道状态要对齐记录，避免工单混谈。
与企业微信混淆：个人号插件不是企业微信自建应用/回调那套；合规、凭据轮换与审计模型完全不同，见企业微信专题。
| 验收动作 | 仅 SSH | 建议 VNC | 通过标准 |
|---|---|---|---|
| openclaw --version / doctor | 足够 | 可选 | 宿主 ≥ 2026.3.22（走 2.x 时） |
| npx -y @tencent-weixin/openclaw-weixin-cli install | 足够 | 可选 | 安装器选对 dist-tag，无版本冲突 |
| channels login 扫码 | ASCII QR 易误扫 | 同用户桌面终端 + 手机对照 | status probe 显示已连接账号 |
| ClawBot 灰度开关 | 无法操作手机 UI | 手机实机 + 工单记录版本号 | 灰度可见或明确「未命中灰度」 |
| 配对 allowlist | CLI approve | IM 侧发测试私信观察拦截 | 陌生 sender 须 pairing 批准 |
| Gateway 18789 / 反代 | curl 本机探针 | 浏览器 Network + 控制台 | 与扫码部署文同级的「只监听回环或走 TLS 反代」 |
个人微信接入的最低成本做法：SSH 装插件与拉日志 + VNC 同用户扫码与控制台互证，而不是二选一。
若你刚升级过 OpenClaw 并遇到插件冷注册表变慢，先按v2026.4.25 插件注册表 repair对齐 CLI/Gateway 同源，再装 openclaw-weixin，可避免「插件 enabled 但 Gateway 仍是旧构建」的混合版本假象。
冻结与备份：导出 OpenClaw 配置与状态目录；记录 openclaw --version、Gateway 构建号、launchd 用户。新环境可先走十分钟路线图。
确认宿主 ≥ 2026.3.22：不足则先升级 OpenClaw，或让安装器自动选 compat 轨道；不要手写 @latest 碰运气。
推荐：统一安装器：执行 npx -y @tencent-weixin/openclaw-weixin-cli install，由安装器检测 openclaw --version 并选择 compat 或 latest dist-tag，随后引导扫码与 Gateway 重启。
手动路径（工单可复现）：openclaw plugins install "@tencent-weixin/openclaw-weixin"，再 openclaw config set plugins.entries.openclaw-weixin.enabled true；宿主 < 2026.3.22 时勿强行 latest。
多账号隔离：若会登录第二个微信号，执行 openclaw config set session.dmScope per-account-channel-peer，按「账号 + 通道 + 对端」拆 DM 会话，避免 A 号上下文污染 B 号。
同机扫码登录：在 Gateway 所在机器、与守护进程同一用户执行 openclaw channels login --channel openclaw-weixin；VNC 下看清 QR 与确认页。登录成功后凭据写入 OpenClaw 状态目录（本机敏感数据）。
访问控制：对未知私信发送者使用 pairing：openclaw pairing list openclaw-weixin 与 openclaw pairing approve openclaw-weixin <CODE>；不要把「任何人都能触发 Agent」当成默认。
重启与探针：openclaw gateway restart 后跑 openclaw channels status --probe；从已配对微信发一条单聊测试，保留 Gateway 日志片段写入变更单。若 Gateway 重启循环，对照文档同时升级 OpenClaw 与插件（sidecar 清理问题在较新版本已通用修复）。
openclaw --version openclaw doctor # 推荐：自动匹配插件 dist-tag npx -y @tencent-weixin/openclaw-weixin-cli install # 手动（宿主已 >= 2026.3.22） openclaw plugins install "@tencent-weixin/openclaw-weixin" openclaw config set plugins.entries.openclaw-weixin.enabled true openclaw config set session.dmScope per-account-channel-peer openclaw channels login --channel openclaw-weixin openclaw gateway restart openclaw channels status --probe openclaw plugins list
ClawBot 灰度（手机侧）：在已命中灰度的账号上，于微信「设置」中打开 ClawBot 相关入口并按产品说明绑定；仍须保证远程 Gateway 上 openclaw-weixin 通道已连接。灰度未命中时，以通道扫码 + pairing 的可审计链路为准做验收，勿把手机 UI 缺失误判为服务器故障。
Sidecar 监控腾讯 iLink API 时，若曾出现 Gateway 被辅助进程误杀的重启环，应在成对升级 OpenClaw 与插件后再判稳；排障日志可检索 openclaw-weixin、ilink、pairing 关键字，并与《任务无回复排查》对照「通道有入站但 Agent 无回包」分支。
个人微信插件把账号 token 存在 Gateway 机器本地，这台远程 Mac 在运维上应视为高敏感资产：
磁盘与备份：状态目录进入备份策略前先做访问控制；不要把含 token 的目录同步到公开网盘。
配对默认拒绝：未 approve 的 sender 不应驱动 Agent 执行 shell/文件工具；生产环境建议维护 allowlist 并定期审计 pairing list。
Gateway 暴露面：参考公网反代清单：禁止将 18789 直接映射到公网而无认证；微信凭据与控制台应不同安全域思考。
用户上下文：SSH 用户 ≠ VNC 桌面用户时，最常见事故是「装给了 A、扫给了 B、Gateway 跑在 C」；与守护进程文一起固化同用户 checklist。
产品灰度：ClawBot 入口与通道插件可分别演进；变更单应分别记录「手机灰度命中与否」与「openclaw-weixin probe 是否 connected」。
| 核对项 | VNC 侧证据 | SSH 侧证据 | 通过标准 |
|---|---|---|---|
| 插件 enabled | 控制台通道列表显示 weixin | plugins list | enabled true，无宿主不兼容报错 |
| 扫码登录 | 终端 QR 清晰、手机确认成功 | 状态目录新增账号条目 | probe：connected |
| 单聊回复 | 微信客户端看到助手回复 | Gateway 入站/出站日志 | 往返 < 预期 SLA（先短句烟测） |
| pairing 拦截 | 陌生号私信不触发执行 | pairing pending 列表 | approve 后才响应 |
| ClawBot 灰度 | 设置页入口截图 + 版本号 | N/A（手机） | 命中灰度或文档化未命中 |
在租用远程 Mac 上，VNCMac 一类节点的价值是：Gateway、扫码终端与（必要时）18789 控制台落在同一图形会话，把个人微信接入从「跨用户猜 HOME」收敛为可复现的二十分钟验收。Windows 主力机团队可固定「SSH 装插件 + VNC 扫码 + 手机灰度」三轨值班模板，与v2026.4.25 扫码部署共用证据链格式。
CLI、Gateway 与首次对话。
阅读 →HTTPS、监听矩阵与面最小化。
阅读 →组织凭据、回调与合规面。
阅读 →IM 授权与 18789 控制台验收。
阅读 →ClawBot 仍在微信客户端灰度阶段，需较新版本且账号在名单内。未命中时请以 openclaw-weixin 扫码 + Gateway probe 作为通道验收依据，并在工单注明手机微信版本与是否灰度。
不能。2.x 要求宿主 ≥ 2026.3.22；请升级 OpenClaw 或运行 npx -y @tencent-weixin/openclaw-weixin-cli install 自动选择 compat/legacy 轨道。
不是。本文是腾讯 @tencent-weixin/openclaw-weixin 个人号通道；企业微信请走自建应用/回调与组织审计流程，见企业微信安全指南。
当前官方文档注明插件能力元数据未声明群聊支持。验收请使用已配对联系人的单聊；群场景需等待插件发行说明更新。
终端可输出 QR，但远程场景强烈建议 VNC 与 Gateway 守护进程同用户操作，避免凭据写入错误 HOME；手机 ClawBot 设置亦需在实机完成。
腾讯 ClawBot 与 openclaw-weixin 把个人微信接进 OpenClaw 的门槛已经很低，但真正决定稳不稳的仍是：宿主版本矩阵、同机同用户扫码、per-account-channel-peer 会话隔离、pairing 安全默认值，以及接受单聊优先、群聊未声明的产品边界。自有 Mac 或自建 VPS 仍要承担睡眠唤醒、出口 IP 与多人抢用同一桌面时的上下文错位；在可租用的远程 Apple Silicon 上，把 Gateway 与扫码终端放在同一 VNC 桌面，通常能把「装上了但收不到私信」从数小时扯皮压到二十分钟可审计验收。
若你需要一台便于完成本文第六节同款图形化扫码与控制台互证的远程 Mac，可通过 VNCMac 下单：购买页选节点与套餐；连接步骤见帮助中心（SSH-VNC）。