WhatsApp

狀態：已可透過 WhatsApp Web (Baileys) 用於正式環境。閘道擁有已連結的工作階段；沒有獨立的 Twilio WhatsApp 頻道。

安裝

openclaw onboard 和 openclaw channels add --channel whatsapp 會在你第一次選取此外掛時提示安裝；如果缺少外掛，openclaw channels login --channel whatsapp 也會提供相同的安裝流程。開發版簽出使用本機外掛路徑；穩定版／測試版安裝會先從 ClawHub 安裝 @openclaw/whatsapp，失敗時再改用 npm。WhatsApp 執行階段隨核心 OpenClaw npm 套件之外的外部外掛提供，因此其執行階段相依套件會保留在外部外掛中。手動安裝：

openclaw plugins install clawhub:@openclaw/whatsapp

僅在登錄檔備援時使用未加修飾的 npm 套件 (@openclaw/whatsapp)；只有需要可重現的安裝時，才固定確切版本。

快速設定

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

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-authopenclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsappopenclaw pairing approve whatsapp <CODE>

部署模式

{  channels: {    whatsapp: {      dmPolicy: "allowlist",      allowFrom: ["+15551234567"],    },  },}

執行階段模型

• 閘道擁有 WhatsApp 通訊端與重新連線迴圈。
• 監控程式會分別追蹤兩個訊號：原始 WhatsApp Web 傳輸活動與應用程式訊息活動。安靜但仍保持連線的工作階段，不會只因近期未收到訊息而重新啟動；只有在固定的內部時間範圍內（使用者無法設定）未再收到傳輸框架，或應用程式訊息的靜默時間超過一般訊息逾時的 4 倍時，才會強制重新連線。最近曾有活動的工作階段剛重新連線後，第一個時間範圍會使用較短的一般訊息逾時，而非 4 倍的時間範圍。Baileys 在重新連線初期傳送的離線訊息，OpenClaw 可以自動回覆，範圍受傳入訊息 ID 的去重生命週期限制；初次啟動仍使用較短的過期歷史記錄防護。
• Baileys 通訊端計時設定明確列於 web.whatsapp.*：keepAliveIntervalMs（應用程式 ping 間隔）、connectTimeoutMs（開啟交握逾時）、defaultQueryTimeoutMs（Baileys 查詢等待時間，以及 OpenClaw 的傳出訊息傳送／上線狀態與傳入讀取回條逾時）。
• 傳出訊息必須有目標帳號的有效 WhatsApp 監聽器；否則傳送會立即失敗。
• 當 @+<digits> 和 @<digits> 權杖（位於文字與媒體標題中）符合目前參與者的中繼資料時，群組傳送會附加原生提及中繼資料，包括由 LID 支援的群組。
• 狀態與廣播聊天 (@status、@broadcast) 會被忽略。
• 直接聊天使用私訊工作階段規則（session.dmScope；預設的 main 會將私訊合併到代理程式的主要工作階段）。群組工作階段會依 JID 隔離 (agent:<agentId>:whatsapp:group:<jid>)。
• WhatsApp 頻道／電子報可透過其原生 @newsletter JID 明確指定為傳出目標，並使用頻道工作階段中繼資料 (agent:<agentId>:whatsapp:channel:<jid>)，而非私訊語意。
• WhatsApp Web 傳輸會遵循閘道主機上的標準 Proxy 環境變數（HTTPS_PROXY、HTTP_PROXY、NO_PROXY 及其小寫變體）。應優先使用主機層級的 Proxy 設定，而非個別頻道設定。
• 啟用 messages.removeAckAfterReply 後，OpenClaw 會在送達可見回覆時清除確認反應。

使用 MeowCaller 致電目前的要求者（實驗性）

此外掛可以在源自 WhatsApp 的代理程式回合中公開 whatsapp_call。它使用 MeowCaller 向目前已獲授權的要求者撥打 WhatsApp 語音通話，並在對方接聽後播放 OpenClaw TTS 訊息。此工具沒有目的地號碼參數，因此提示無法將通話重新導向。預設為停用。

{"channels": {"whatsapp": {  "actions": {    "calls": true  }}}}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.gitcd meowcallergit checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3fmkdir -p "$HOME/.local/bin"go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"mkdir -p "$state_dir"chmod 700 "$state_dir"meowcaller pair --store "$state_dir/wa-voip.db"

限制：僅限一對一傳出音訊通話、不支援任意目的地號碼、不與聊天連線共用驗證、個人號碼／傳訊給自己模式無法致電自身、合成音訊上限為 60 秒、除了 MeowCaller 完成接聽／播放／掛斷之外，沒有手機端可聽見性的回條；OpenClaw 會在有界限的 115–175 秒時間範圍後停止伴隨程序（涵蓋 MeowCaller 的連線、接聽、播放與關閉階段）。

核准提示

WhatsApp 可以將執行與外掛核准提示顯示為 👍/👎 反應，由頂層核准轉送設定控制：

{  approvals: {    exec: {      enabled: true,      mode: "session",    },    plugin: {      enabled: true,      mode: "targets",      targets: [{ channel: "whatsapp", to: "+15551234567" }],    },  },}

approvals.exec 與 approvals.plugin 彼此獨立；啟用 WhatsApp 頻道只會連結傳輸層，除非啟用相符的核准類別並將其路由至該處，否則不會傳送任何內容。工作階段模式僅會針對源自 WhatsApp 的核准傳送原生表情符號核准。目標模式會對明確目標使用共用轉送管線，不會建立獨立的核准者私訊扇出。

WhatsApp 核准反應要求在 allowFrom（或 "*"）中明確指定核准者。defaultTo 設定的是一般預設訊息目標，而非核准者清單。手動 /approve 命令在解析核准前，仍會通過一般的 WhatsApp 傳送者授權路徑。

外掛掛鉤與隱私權

傳入的 WhatsApp 訊息可能包含個人內容、電話號碼、群組識別碼、傳送者名稱及工作階段關聯欄位。除非你選擇加入，否則 WhatsApp 不會將傳入的 message_received 掛鉤承載資料廣播給外掛：

{  channels: {    whatsapp: {      pluginHooks: {        messageReceived: true,      },    },  },}

請在 channels.whatsapp.accounts.<id>.pluginHooks.messageReceived 下將選擇加入的範圍限制為單一帳號。僅應對你信任且可存取傳入 WhatsApp 內容與識別碼的外掛啟用此功能。

存取控制與啟用

已設定的 ACP 繫結

WhatsApp 透過頂層 bindings[] 支援持久性 ACP 繫結：

{  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "direct", id: "+15555550123" },      },    },    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "group", id: "120363424282127706@g.us" },      },    },  ],}

直接聊天會比對 E.164 號碼；群組會比對 WhatsApp 群組 JID。群組允許清單、傳送者政策及提及／啟用閘門會在 OpenClaw 確保繫結的 ACP 工作階段存在之前執行。符合的繫結會取得該路由的所有權——廣播群組不會將該輪對話分送至一般 WhatsApp 工作階段。

個人號碼與自我聊天行為

當已連結的自身號碼也存在於 allowFrom 中時，系統會啟用自我聊天保護措施：略過自我聊天輪次的已讀回條、忽略會提及你自己的提及 JID 自動觸發行為，並在未設定 messages.responsePrefix 時，預設將回覆傳送至 [{identity.name}]（或 [openclaw]）。

訊息正規化與內容脈絡

[Replying to <sender> id:<stanzaId>]<quoted body or media placeholder>[/Replying]

{ channels: { whatsapp: { sendReadReceipts: false } } }

傳送、分段與媒體

回覆引用

channels.whatsapp.replyToMode 控制原生回覆引用（傳出的回覆會明顯引用傳入訊息）：

各帳號覆寫：channels.whatsapp.accounts.<id>.replyToMode。

{ channels: { whatsapp: { replyToMode: "first" } } }

回應層級

channels.whatsapp.reactionLevel 控制代理程式使用表情符號回應的範圍：

各帳號覆寫：channels.whatsapp.accounts.<id>.reactionLevel。

{ channels: { whatsapp: { reactionLevel: "ack" } } }

確認回應

channels.whatsapp.ackReaction 會在收到傳入訊息時立即傳送回應，並受 reactionLevel 限制（當 "off" 時會抑制）：

{  channels: {    whatsapp: {      ackReaction: {        emoji: "👀",        direct: true,        group: "mentions", // always | mentions | never      },    },  },}

注意事項：傳入訊息獲接受後會立即傳送（回覆前）；若存在 ackReaction 但沒有 emoji，WhatsApp 會使用所路由代理程式的身分表情符號，並以「👀」作為備援（若不需要確認回應，請省略 ackReaction 或設定 emoji: ""）；失敗會記錄於日誌，但不會阻止回覆傳送；群組模式 mentions 僅會在由提及觸發的輪次中回應，而群組啟用 always 會略過此檢查；WhatsApp 僅使用 channels.whatsapp.ackReaction（舊版 messages.ackReaction 不適用於此處）。

生命週期狀態回應

設定 messages.statusReactions.enabled: true，可讓 WhatsApp 在一輪對話期間取代確認回應，而不是留下靜態的收件表情符號，並依序切換已排入佇列、思考中、工具活動、壓縮、完成及錯誤等狀態：

{  messages: {    statusReactions: {      enabled: true,      emojis: {        deploy: "🛫",        build: "🏗️",        concierge: "💁",      },    },  },}

注意事項：channels.whatsapp.ackReaction 仍會控制直接訊息與群組的適用資格；已排入佇列狀態會使用與一般確認回應相同的有效表情符號；WhatsApp 對每則訊息僅有一個機器人回應位置，因此生命週期更新會就地取代目前的回應；messages.removeAckAfterReply: true 會在設定的完成／錯誤保留時間後清除最終狀態回應；工具表情符號類別包括 tool、coding、web、deploy、build 與 concierge。

多帳號與認證資訊

工具、動作與設定寫入

• 代理程式工具支援包含 WhatsApp 回應動作（react）。
• 動作閘門：channels.whatsapp.actions.reactions、channels.whatsapp.actions.polls（現有動作預設為 true）、channels.whatsapp.actions.calls（預設為 false，請參閱上方的 MeowCaller）。
• 由頻道發起的設定寫入預設為啟用；可透過 channels.whatsapp.configWrites: false 停用。

疑難排解

openclaw channels login --channel whatsappopenclaw channels status

{  web: {    whatsapp: {      keepAliveIntervalMs: 15000,      connectTimeoutMs: 60000,      defaultQueryTimeoutMs: 60000,    },  },}

openclaw channels status --probeopenclaw doctoropenclaw logs --followopenclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \  ~/.openclaw/credentials/whatsapp/<accountId>.bakopenclaw channels logout --channel whatsapp --account <accountId>openclaw channels login --channel whatsapp --account <accountId>

系統提示詞

WhatsApp 可透過 groups 與 direct 對應表，支援用於群組及直接聊天的 Telegram 風格系統提示詞。

群組訊息的解析方式：系統會先決定有效的 groups 對應表——如果帳號有定義自己的 groups 鍵，無論內容為何，都會完整取代根層級的 groups 對應表（不進行深層合併）。接著會在這個唯一的結果對應表中查詢提示詞：

1. 群組專屬提示詞（groups["<groupId>"].systemPrompt）：當群組項目存在，且其 systemPrompt 鍵已定義時使用。空字串（""）會抑制萬用字元，且不套用任何提示詞。
2. 群組萬用字元提示詞（groups["*"].systemPrompt）：當特定群組項目不存在，或存在但沒有 systemPrompt 鍵時使用。

直接訊息會依照相同模式，針對 direct 對應表與 direct["*"] 進行解析。

**與 Telegram 的差異：**在多帳號設定中，Telegram 會對每個帳號抑制根層級的 groups（即使帳號本身沒有 groups），以防止機器人收到其未加入群組的訊息。WhatsApp 不會套用這項保護——任何沒有自有覆寫的帳號都會繼承根層級的 groups/direct，不受帳號數量影響。在多帳號 WhatsApp 設定中，如果要使用個別帳號提示詞，請在每個帳號下明確定義完整的對應表。

重要行為：

• channels.whatsapp.groups 同時是個別群組設定對應表與聊天層級群組允許清單。在根層級或帳號範圍中，groups["*"] 都表示該範圍「允許所有群組」。
• 只有在已確定要允許該範圍中的所有群組時，才加入萬用字元 systemPrompt。若只要讓一組固定的群組 ID 符合資格，請在每個明確列入允許清單的項目中重複提示詞，而不要使用 groups["*"]。
• 群組准入與傳送者授權是兩項獨立的檢查。groups["*"] 會擴大哪些群組能進入群組處理流程；它不會授權這些群組中的每位傳送者——這仍由 groupPolicy/groupAllowFrom 控制。
• channels.whatsapp.direct 對 DM 沒有同等的附帶效果：direct["*"] 只會在 DM 已由 dmPolicy 加上 allowFrom 或配對儲存區規則允許後，提供預設設定。

範例：

{  channels: {    whatsapp: {      groups: {        // 僅在根層級應允許所有群組時使用。        // 套用至未定義自有 groups 對應表的所有帳號。        "*": { systemPrompt: "所有群組的預設提示詞。" },      },      direct: {        // 套用至未定義自有 direct 對應表的所有帳號。        "*": { systemPrompt: "所有直接聊天的預設提示詞。" },      },      accounts: {        work: {          groups: {            // 此帳號定義了自己的 groups，因此根層級 groups 會被完整            // 取代。若要保留萬用字元，也請在此明確定義 "*"。            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "專注於專案管理。",            },            // 僅在此帳號應允許所有群組時使用。            "*": { systemPrompt: "工作群組的預設提示詞。" },          },          direct: {            // 此帳號定義了自己的 direct 對應表，因此根層級 direct 項目會            // 被完整取代。若要保留萬用字元，也請在此明確定義 "*"。            "+15551234567": { systemPrompt: "特定工作直接聊天的提示詞。" },            "*": { systemPrompt: "工作直接聊天的預設提示詞。" },          },        },      },    },  },}

設定參考指引

主要參考：設定參考資料 - WhatsApp

相關內容

• 配對
• 群組
• 安全性
• 頻道路由
• 多代理程式路由
• 疑難排解