WhatsApp

透過 WhatsApp Web (Baileys) 整合 OpenClaw 與 WhatsApp，支援私訊和群組聊天。

OpenClaw 的 WhatsApp 整合透過 WhatsApp Web (Baileys) 運作，已達到正式環境就緒狀態。Gateway 管理連結工作階段和連線生命週期。

快速設定

設定包含四個步驟：

1. 在 openclaw.json 中定義存取策略（私訊和群組策略搭配允許清單）
2. 透過 QR code 連結 WhatsApp：openclaw channels login --channel whatsapp
3. 啟動 Gateway：openclaw gateway
4. 如有需要，核准配對請求

系統支援專用號碼和個人號碼兩種部署方式。建議使用專用的 WhatsApp 號碼以獲得更乾淨的操作體驗。

存取控制

兩個主要的策略層級控制訊息接收：

私訊策略

dmPolicy 設定接受以下模式：

• pairing（預設）— 需要核准新的傳送者
• allowlist — 僅限預先核准的電話號碼
• open — 允許任何傳送者
• disabled — 封鎖所有私訊

系統會將電話號碼正規化為 E.164 格式，並將配對結果持久化儲存。

群組策略

採用雙層控制：群組成員允許清單搭配傳送者策略。預設需要提及才會回應，除非另行設定。系統會檢查明確提及、正規表示式模式或回覆機器人的偵測。

訊息處理

接收的訊息會進行正規化處理。僅包含媒體的訊息會轉換為佔位符（如 <media:image>），引用回覆會附加帶有傳送者識別的上下文。對於群組，未處理的訊息可在機器人最終被觸發時作為上下文緩衝。

傳送功能

• 文字分段預設為 4,000 字元，可設定模式偏好（length 或 newline）
• 支援圖片、影片、音訊和文件等媒體類型
• 自動最佳化過大的媒體，並在多媒體傳送中對第一個項目套用說明文字

多帳號支援

帳號憑證儲存在 ~/.openclaw/credentials/whatsapp/<accountId>/creds.json。如果存在 default 帳號則使用該帳號，否則按字母順序使用第一個設定的帳號 ID。帳號層級的設定會覆寫頻道預設值。

疑難排解

常見問題包括：

• 取消連結 — 使用 openclaw channels login 重新連結
• 重新連線迴圈 — 使用 openclaw doctor 診斷
• 群組訊息過濾 — 驗證 groupPolicy 和允許清單設定
• 執行環境不相容 — 注意 Bun 和 Node 的差異警告
• 外送訊息失敗 — 確保目標帳號有活動中的 WhatsApp 監聽器