官方插件 · 掃碼綁定 · 灰度門檻 · 六步 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 必須與掃碼登入在同一台機器（或同一狀態目錄），遠端 SSH 掃碼卻在本機跑 Gateway 的典型錯配會直接導致「掃了但收不到」。
官方插件：透過 openclaw plugins install 或 npx @tencent-weixin/openclaw-weixin-cli install 安裝，版本線與 OpenClaw 主版本綁定（見第二節）。
Gateway 角色：發現插件 manifest、載入入口、管理 Agent 與 session；微信特有邏輯不在 core repo。
能力邊界：目前元資料標示支援單聊與媒體，群聊未在官方能力列表中；勿把 Telegram 群 Bot 經驗直接套用。
Sidecar 行為：插件可在 Gateway 旁啟動 helper 監聽 Tencent API；舊版 OpenClaw 曾出現 stale cleanup 誤殺父 Gateway 導致重啟迴圈，需保持 core 與插件同時更新。
存取控制：單聊仍走 OpenClaw 標準 pairing / allowlist，新發送者需 openclaw pairing approve，與 多通道加固清單 的白名單敘事一致。
微信通道的成敗多半在「插件版本 + Gateway 重啟 + 掃碼機器一致」三件事；模型強弱排在它們之後。
在執行任何 install 指令前，請把下列項目寫進變更單並逐項勾選。插件在啟動時會檢查宿主 OpenClaw 版本，不匹配會拒絕載入而非降級運行。
| 檢查項 | 要求 | 不符時的動作 |
|---|---|---|
| OpenClaw 主版本 | 2.x 插件需 >=2026.3.22；1.x legacy 對應 >=2026.1.0 <2026.3.22 | 升級 OpenClaw 或 plugins install @tencent-weixin/openclaw-weixin@legacy |
| 微信客戶端 | 手機端需能掃描登入 QR；部分能力受官方灰度與插件版本影響 | 確認 App 已更新；灰度未開則等待或換測試帳號 |
| Node 執行環境 | 與 OpenClaw 安裝文一致（常見 22.14+） | 先跑 openclaw doctor，見安裝排障文 |
| 帳號策略 | 建議小號 / 測試號隔離生產主號；多帳號需設定 session.dmScope | 多帳號時設 per-account-channel-peer 避免 session 串線 |
| 常駐節點 | Gateway 需 7×24；筆電休眠會斷 monitor | 遷移至 VPS 或遠端 Mac 伺服器，見第六節 |
npm 鏡像與跨境網路會影響 npx 首次拉包時間；在生產伺服器上請預留足夠磁碟與 outbound 頻寬，並在 screen 或 systemd 下執行安裝，避免 SSH 斷線留下半成品。若團隊已在 Docker 路徑跑 Gateway，請先對照 Compose 基線文 確認插件目錄掛載與重啟策略，再裝微信插件。
官方提供兩條等價路徑；選一條寫進 Runbook 即可，勿在同一變更單混用導致版本漂移。
npx -y @tencent-weixin/openclaw-weixin-cli 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 對照相容表。
提示：若啟動報錯「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>
產生 QR：執行 login 子命令，手機微信掃碼並確認；成功後憑證寫入 OpenClaw 狀態目錄。
確認通道：微信聯絡人列表應出現 ClawBot 或對應 Bot 入口（以官方 UI 為準）。
首條回環：從已允許的微信帳號發送短文本，同時 openclaw logs --follow；無回覆先查 pairing 而非換模型。
探針：channels status --probe 與 多通道探針文 的判據順序一致。
| 維度 | 微信 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 / 頻道權限模型 |
下列症狀在 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 拒絕率與插件版本，僅在超過閾值時升級或增加備援節點。