2026 年騰訊微信 ClawBot 接入 OpenClaw：一鍵安裝、版本相容與 Mac VPS 避坑 Runbook（含決策矩陣與 FAQ）
2026 年騰訊在個人微信灰度推出官方 ClawBot 插件，開發者終於能把日常 IM 入口接到 OpenClaw Gateway，而不必繞道企微或第三方橋接。但「先跑通 OpenClaw 再掃碼」的順序、openclaw-weixin 2.0.x 與 1.0.x 的版本矩陣，以及僅單聊、24 小時互動窗口等硬限制，決定了這不是裝個 npm 包就完事。本文面向已在 Mac/Linux 跑通 Gateway、微信已灰度到 ClawBot（iOS 8.0.70+ / 安卓 8.0.69+）的開發者：給決策矩陣、灰度自檢、Mac VPS 前置、七步 Runbook、版本與限制對照表、分層排障與 FAQ，幫你在 Apple Silicon Mac 雲上完成可審計的 7×24 部署。
目錄
1. 決策矩陣：個人微信 ClawBot vs 企微/飛書 vs Telegram
若團隊已在企微沉澱流程，企微接入文仍是首選；ClawBot 的價值在「個人微信習慣 + 官方插件」——適合開發者自用助理、小團隊非正式協作，而非合規群聊機器人。
| 維度 | 個人微信 ClawBot | 企微 / 飛書 | Telegram / Discord |
|---|---|---|---|
| 入口習慣 | 個人微信日常對話 | 企業協作與審批 | 海外或技術社群 |
| 群聊 | 不支援（僅單聊） | 支援 @bot | 支援 mention |
| 合規路徑 | 內容經騰訊伺服器 | 企業域控與審計 | 自建 Bot API |
| 7×24 常駐 | Mac VPS + launchd | 同左 | 同左；見多通道 Runbook |
2. 灰度自檢：ClawBot 入口與版本門檻
部署前請在手機微信確認：設定 → 插件 → ClawBot 入口可見。iOS 需 8.0.70 及以上，安卓 8.0.69 起灰度中；無入口時只能等待全量，不宜在 VPS 上反覆重裝插件。建議使用小號綁定，避免主號工作流被實驗性 Agent 打斷。灰度通過後再在 Mac VPS 上跑 OpenClaw 本體冒煙，切勿倒序掃碼——Gateway 未就緒時 QR 常過期或通道顯示 online 卻不回覆。
- 無 ClawBot 入口：確認 App 版本，非灰度帳號只能等待。
- 有入口但未綁定：先完成 VPS 側 Gateway 與 Provider 驗收。
- 已綁定其他 OpenClaw：一微信号約束，須先解綁再掃新 QR。
3. Mac VPS 前置：Node 22、18789 與同使用者 HOME
openclaw-weixin 是 Gateway 插件，不是獨立 Bot 程序。半安裝狀態下直接 npx 裝通道，常見症狀是 QR 能出、重啟後 session 丟失。前置清單如下；細節可對照五步入門與網關 Runbook。
- 執行環境：Node.js 22+；
openclaw --version與openclaw doctor無半安裝告警。 - Gateway：
lsof -i :18789或openclaw gateway status顯示監聽。 - 模型 Provider：至少一條 LLM 路由可用，否則通道在線也無回覆。
- 帳戶對齊：launchd plist 的
UserName與 CLI 同一 macOS 使用者，HOME一致。 - 權限審計：插件目錄最小權限；第三方 Skill 先走ClawHub 審計。
openclaw gateway status
openclaw --version
echo "USER=$USER HOME=$HOME"
4. 七步 Runbook：本體 → CLI 安裝 → 掃碼 → 驗收
推薦順序固定為「本體冒煙 → 官方 CLI → 掃碼 → 重啟 → 單聊驗收 → launchd 常駐復驗」。CLI 會依 OpenClaw 版本自動選 dist-tag，手動路徑僅在 CLI 失敗時使用。首次綁定建議在變更窗口內完成：QR 通常有時效，且掃碼後須立即做單聊往返以確認 session 已寫入 Gateway 工作目錄；若與 Telegram 等多通道並行，請在驗收訊息中帶上可識別前綴，避免 session 路由混淆。
- 本體冒煙：doctor 通過，18789 監聽，最小 Agent 對話可用。
- 一鍵 CLI 安裝：見下方命令；完成後檢查插件目錄與 openclaw.json 增量。
- 手動備選：
openclaw plugins install @tencent-weixin/openclaw-weixin，再openclaw channels login weixin。 - 掃碼綁定：終端 QR 出現後，手機 ClawBot 插件內掃描；逾時則 restart 後重試。
- Gateway 重啟：
openclaw gateway restart，openclaw gateway status顯示 weixin 通道 online。 - 單聊驗收：向 ClawBot 發純文字，確認 Agent 回覆與 JSONL
toolCallId。 - 7×24 復驗：launchctl 重載或節點重啟後重跑步驟 6；掉線對照下方排障表。
# 手動備選
openclaw plugins install @tencent-weixin/openclaw-weixin
openclaw channels login weixin
openclaw gateway restart
openclaw gateway status
5. 版本矩陣與 ClawBot 硬限制對照
版本不匹配時插件會拒絕載入，日誌常見 semver 或 peer dependency 告警。升級 OpenClaw 後按五月版本線 Runbook驗收，必要時重新執行 CLI install。
| openclaw-weixin | OpenClaw 要求 | 備註 |
|---|---|---|
| 2.0.x | ≥ 2026.3.22 | 現行推薦；CLI 預設 dist-tag |
| 1.0.x legacy | 舊版 OpenClaw | 僅存量相容；新部署勿釘扎 |
| 限制項 | 說明 | 運營建議 |
|---|---|---|
| 僅單聊 | 不支援群聊 @bot | 群場景用企微或 Telegram |
| 純文字為主 | 無圖文混排等富媒體 | 長文拆段或走其他通道 |
| 24h 互動窗口 | 超過未互動的主動推送可能丟棄 | 定時 ping 或 cron 喚醒對話 |
| 一號一綁定 | 同一微信號不可多 Gateway | 解綁後再掃新 QR |
| 資料路徑 | 內容經騰訊伺服器中轉 | 勿發送敏感憑證；工作目錄最小權限 |
6. 分層排障：無 QR、版本拒載、在線不回
「微信不通」按層排查：協議/QR → 插件版本 → Gateway 18789 → Provider/路由 → 單聊策略。每層對齊 JSONL 與 openclaw gateway status --deep，避免只重啟不看日誌。若 Telegram 等其他通道正常而僅微信失效，優先懷疑插件 semver 或 QR session，而非模型 Provider；若所有通道均不回，則回到網關 18789 與 launchd 使用者對齊。變更窗口內保留掃碼前後的 doctor 輸出，便於與同事或值班交接。
| 症狀 | 根因 | 修復 |
|---|---|---|
| 無 QR / 協議配置失敗 | Gateway 未就緒或 HOME 分裂 | doctor + 同使用者 CLI；見網關 Runbook |
| 插件拒絕載入 | openclaw-weixin 與 OpenClaw 版本不匹配 | 升級至 ≥2026.3.22 或重跑 CLI install |
| 掃碼後掉線 | 本機休眠或 launchd 使用者不一致 | Mac VPS 常駐 + plist UserName 對齊 |
| 在線不回 / 只收不發 | Provider 限流或 session 路由錯 | 查模型路由；多通道時見多通道 Runbook |
7. FAQ
問：ClawBot 能與 Telegram、Slack 等並行嗎？ 可以；須分通道配置 session 命名空間，並按多通道 Runbook 做最小對話驗收。
問：為何 Mac VPS 優於本機？ 筆電休眠斷連；Mac 雲 launchd 常駐、固定 IP 與 HOME，更適合 7×24 長連。
問：海外節點能用嗎？ 取決於微信帳號與騰訊服務可达性；生產建議同區低延遲，並監控掉線率。
問：安卓何時全量？ 以騰訊官方公告為準；目前 8.0.69 灰度中，無入口請等待而非強裝舊版插件。全量後仍須遵守單聊與 24h 窗口等產品限制。
8. 結論
成功標準：OpenClaw 本體 → CLI 安裝 → 掃碼 → 18789 單聊可復現。ClawBot 適合個人微信入口，不替代企微合規群聊；版本矩陣與 24h 窗口必須寫進變更單。要把微信通道與其他 IM、Skill 並行常駐，租賃 VPSMAC Apple Silicon Mac 雲節點把 Gateway、插件目錄與 launchd 收進同一 Runbook 更穩妥；見網關 Runbook、多通道驗收與Skill 審計。