Skip to main content

​
WhatsApp（網頁頻道）

狀態：透過 WhatsApp Web（Baileys）已可正式使用。Gateway 擁有連結的工作階段。

Pairing（配對）

未知發送者的預設 DM 政策為配對。

Channel troubleshooting（頻道疑難排解）

跨頻道診斷與修復手冊。

Gateway configuration（Gateway 設定）

完整的頻道設定模式與範例。

​
快速設定

1

設定 WhatsApp 存取政策

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}
2

連結 WhatsApp（QR）

openclaw channels login --channel whatsapp
針對特定帳號：
openclaw channels login --channel whatsapp --account work
3

啟動 gateway

openclaw gateway
4

核准第一個配對請求（使用配對模式時）

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
配對請求 1 小時後過期。每個頻道最多保留 3 個待處理請求。
OpenClaw 建議盡可能在獨立號碼上執行 WhatsApp。（頻道 metadata 和上線流程針對該設定最佳化，但個人號碼設定也受支援。）

​
部署模式

這是最乾淨的操作模式：
  • OpenClaw 的獨立 WhatsApp 身份
  • 更清晰的 DM allowlist 和路由邊界
  • 降低自我聊天混淆的可能性
最小政策模式：
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}
上線支援個人號碼模式並寫入適合自我聊天的基準設定：
  • dmPolicy: "allowlist"
  • allowFrom 包含你的個人號碼
  • selfChatMode: true
在執行時，自我聊天保護根據連結的自身號碼和 allowFrom 作用。
目前 OpenClaw 頻道架構中的訊息平台頻道是基於 WhatsApp Web（Baileys）的。內建聊天頻道登錄中沒有單獨的 Twilio WhatsApp 訊息頻道。

​
執行時模型

  • Gateway 擁有 WhatsApp socket 和重連迴圈。
  • 出站傳送需要目標帳號有活動的 WhatsApp 監聽器。
  • 狀態和廣播聊天被忽略（@status、@broadcast）。
  • 直接聊天使用 DM 工作階段規則（session.dmScope；預設 main 將 DM 合併到 agent 主要工作階段）。
  • 群組工作階段隔離（agent:<agentId>:whatsapp:group:<jid>）。

​
存取控制與啟動

channels.whatsapp.dmPolicy 控制直接聊天存取：
  • pairing（預設）
  • allowlist
  • open（需要 allowFrom 包含 "*"）
  • disabled
allowFrom 接受 E.164 格式號碼（內部正規化）。多帳號覆蓋：channels.whatsapp.accounts.<id>.dmPolicy（和 allowFrom）對該帳號優先於頻道層級預設。執行時行為細節：
  • 配對在頻道允許儲存中持久化，並與設定的 allowFrom 合併
  • 若未設定 allowlist，連結的自身號碼預設被允許
  • 出站 fromMe DM 永遠不會自動配對

​
個人號碼和自我聊天行為

當連結的自身號碼也出現在 allowFrom 中時，WhatsApp 自我聊天保護會啟動：
  • 跳過自我聊天回合的已讀回執
  • 忽略否則會 ping 你自己的 mention-JID 自動觸發行為
  • 若未設定 messages.responsePrefix，自我聊天回覆預設為 [{identity.name}] 或 [openclaw]

​
訊息正規化和上下文

入站 WhatsApp 訊息被包裝在共享的入站封包中。若存在引用回覆，上下文以此形式附加：
[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]
回覆 metadata 欄位在可用時也會填充（ReplyToId、ReplyToBody、ReplyToSender、發送者 JID/E.164）。
僅媒體的入站訊息使用佔位符正規化，例如：
  • <media:image>
  • <media:video>
  • <media:audio>
  • <media:document>
  • <media:sticker>
位置和聯絡人 payload 在路由前正規化為文字上下文。
對於群組，未處理的訊息可以緩衝並在 bot 最終被觸發時作為上下文注入。
  • 預設限制：50
  • 設定：channels.whatsapp.historyLimit
  • 備用：messages.groupChat.historyLimit
  • 0 停用
注入標記：
  • [Chat messages since your last reply - for context]
  • [Current message - respond to this]
已讀回執對接受的入站 WhatsApp 訊息預設啟用。全域停用：
{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}
每帳號覆蓋：
{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}
即使全域啟用，自我聊天回合也跳過已讀回執。

​
傳遞、分塊和媒體

  • 預設區塊限制：channels.whatsapp.textChunkLimit = 4000
  • channels.whatsapp.chunkMode = "length" | "newline"
  • newline 模式偏好段落邊界（空行），然後退回到長度安全分塊
  • 支援圖片、影片、音訊（PTT 語音筆記）和文件 payload
  • audio/ogg 被改寫為 audio/ogg; codecs=opus 以兼容語音筆記
  • 透過影片傳送的 gifPlayback: true 支援動態 GIF 播放
  • 傳送多媒體回覆 payload 時，說明套用到第一個媒體項目
  • 媒體來源可以是 HTTP(S)、file:// 或本地路徑
  • 入站媒體儲存上限：channels.whatsapp.mediaMaxMb（預設 50）
  • 出站媒體傳送上限：channels.whatsapp.mediaMaxMb（預設 50）
  • 每帳號覆蓋使用 channels.whatsapp.accounts.<accountId>.mediaMaxMb
  • 圖片自動最佳化（調整大小/品質調整）以符合限制
  • 媒體傳送失敗時，第一個項目備用發送文字警告而非靜默丟棄回應

​
確認 reactions

WhatsApp 透過 channels.whatsapp.ackReaction 在入站接受時支援立即的 ack reaction。 
{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}
行為注意：
  • 在入站被接受後立即傳送（回覆前）
  • 失敗被記錄但不阻止一般回覆傳遞
  • 群組模式 mentions 在 mention 觸發的回合中 react；群組啟動 always 作為此檢查的繞過
  • WhatsApp 使用 channels.whatsapp.ackReaction（此處不使用舊版 messages.ackReaction）

​
多帳號和憑證

  • 帳號 ID 來自 channels.whatsapp.accounts
  • 預設帳號選擇：若存在 default，否則第一個設定的帳號 ID（排序）
  • 帳號 ID 在查詢時內部正規化
  • 目前驗證路徑：~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • 備份檔案：creds.json.bak
  • ~/.openclaw/credentials/ 中的舊版預設驗證仍可識別/遷移用於預設帳號流程
openclaw channels logout --channel whatsapp [--account <id>] 清除該帳號的 WhatsApp 驗證狀態。在舊版驗證目錄中，oauth.json 保留，而 Baileys 驗證檔案被移除。

​
工具、動作和設定寫入

  • Agent 工具支援包括 WhatsApp reaction 動作（react）。
  • 動作閘道：
    • channels.whatsapp.actions.reactions
    • channels.whatsapp.actions.polls
  • 頻道發起的設定寫入預設啟用（透過 channels.whatsapp.configWrites=false 停用）。

​
疑難排解

症狀：頻道狀態報告未連結。修復：
openclaw channels login --channel whatsapp
openclaw channels status
症狀：已連結的帳號反覆斷開或嘗試重連。修復：
openclaw doctor
openclaw logs --follow
若需要，使用 channels login 重新連結。
當目標帳號沒有活動的 gateway 監聽器時，出站傳送快速失敗。確認 gateway 正在執行且帳號已連結。
依序檢查：
  • groupPolicy
  • groupAllowFrom / allowFrom
  • groups allowlist 條目
  • mention 閘道（requireMention + mention 模式）
  • openclaw.json 中的重複鍵（JSON5）：後面的條目覆蓋前面的，所以每個範圍只保留一個 groupPolicy
WhatsApp gateway 執行時應使用 Node。Bun 被標記為不相容，不適用於穩定的 WhatsApp/Telegram gateway 操作。

​
設定參考指標

主要參考： WhatsApp 高信號欄位：
  • 存取：dmPolicy、allowFrom、groupPolicy、groupAllowFrom、groups
  • 傳遞：textChunkLimit、chunkMode、mediaMaxMb、sendReadReceipts、ackReaction
  • 多帳號：accounts.<id>.enabled、accounts.<id>.authDir、帳號層級覆蓋
  • 操作：configWrites、debounceMs、web.enabled、web.heartbeatSeconds、web.reconnect.*
  • 工作階段行為：session.dmScope、historyLimit、dmHistoryLimit、dms.<id>.historyLimit

​
相關