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 倍時間範圍。在該次重新連線初期，OpenClaw 可以自動回覆 Baileys 提前傳遞的離線訊息，範圍受限於傳入訊息 ID 的去重生命週期；初始啟動仍會保留較短的過時記錄防護。
• 傳出訊息時，目標帳號必須有作用中的 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 設定，而非各頻道設定。

使用 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 傳送者授權路徑。

問題回應

若 ask_user 提示包含一個非機密的單選問題，且有一至四個選項，WhatsApp 會在選項標籤旁顯示 1️⃣ 到 4️⃣。使用相符數字回應已送達的提示即可作答。OpenClaw 會透過閘道將數字對應至標準選項；過期或重複的點選會被忽略。多問題、多選及自由文字提示仍只能以文字回覆。一般 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 自動觸發行為，並在頻道／帳號的 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,    },  },}

注意事項：channels.whatsapp.ackReaction 仍會控制私人訊息與群組的適用資格；已排入佇列狀態使用與一般確認表情回應相同的有效表情符號；WhatsApp 每則訊息只有一個機器人表情回應欄位，因此生命週期更新會直接取代目前的表情回應，並在最終完成／錯誤狀態後還原確認表情回應。

多帳號與認證資訊

工具、動作與設定寫入

• 代理程式工具支援包含 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

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 對私訊沒有相同的附帶作用：direct["*"] 只會在私訊已由 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

相關內容

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