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+、Android 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 向导无法彈出QR 碼（无 TTY、純 SSH）时，改用手動四步：

注意事項：產品邊界、合规与权限（必讀）

下列限制來自騰訊側 Public Beta 說明与社区實測彙整，应寫進团队 Runbook，而不是事後才發現：

• 單聊為主：不要規劃「微信群機器人」替代企業微信应用；群情境能力隨時可能調整。
• 檔案只進不出：可接收用户傳來的檔案供 Agent 分析，但不能可靠地把大檔案「傳回」微信對話。
• 24 小时互動視窗：長時間未互動后，主動推送可能被丟棄；適合「你問我答」，不適合無人值守強推送行銷。
• 一號一 OpenClaw 實例：一個微信帳號通常只能綁定一個OpenClaw 實例；一個 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）上，通常比在睡眠中的筆電上与QR 碼、probe 逾時拉鋸更省总維運成本；公開方案可先對照多地區節點與租期指南，再與SSH 轉發常駐 Runbook 串接拓撲。