如何在 OpenClaw 快速整合 WhatsApp

每次想把 WhatsApp 接入自己的自動化流程時，總會卡在繁瑣的 API 申請或是難搞的連線穩定度。你可能只是想讓機器人能自動處理訊息，卻得先花大把時間研究通訊協定的底層細節，這種挫折感我們都懂。

OpenClaw 透過 WhatsApp Web (Baileys) 方案解決了這個問題，讓 Gateway 直接管理你的連線 Session，不需要複雜的審核流程就能直接開工。

需要準備的東西

根據源文檔，在開始之前請確保你具備以下條件：

• 已安裝 OpenClaw CLI
• 一個可用的 WhatsApp 帳號（建議使用專屬門號，雖然也支援個人門號）
• 基礎的 JSON5 編輯能力

快速開始

跟著這四個步驟，五分鐘內就能完成基本設定。

1. 設定 WhatsApp 存取政策

在你的配置文件中加入以下內容，定義誰可以傳送訊息給你的機器人。

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

2. 連結 WhatsApp (掃描 QR Code)

在終端機執行以下指令來進行登入：

openclaw channels login --channel whatsapp

如果你有多個帳號（例如工作用帳號），可以指定 account：

openclaw channels login --channel whatsapp --account work

3. 啟動 Gateway

啟動 Gateway 以接管 WhatsApp 的 Socket 連線與自動重連機制。

openclaw gateway

4. 核准配對請求

如果你在第一步使用了 pairing 模式，你需要手動核准第一次的配對：

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

部署建議方案

專屬門號（推薦方案）

這是最乾淨的運作模式。為 OpenClaw 準備一個獨立的 WhatsApp 身份，可以避免個人訊息干擾，路由界限也更清晰。

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

個人門號備援

如果你必須使用個人門號，OpenClaw 也支援 selfChatMode。系統會自動將你的門號加入 allowFrom，並開啟自我對話保護機制，避免機器人陷入無限迴圈。

運行機制須知

• 連線管理：Gateway 負責維護 WhatsApp 的 Socket 和自動重連。
• 發送限制：發送外部訊息時，目標帳號必須有活躍的 WhatsApp Listener。
• 自動過濾：系統會自動忽略狀態更新 (@status) 和廣播訊息 (@broadcast)。
• 群組隔離：群組對話會被隔離在獨立的 Session 中，格式為 agent:<agentId>:whatsapp:group:<jid>。

疑難排解

• 配對請求過期：配對請求的有效期限只有 1 小時，請抓緊時間核准。
• 請求上限：每個 Channel 同時最多只能有 3 個待處理的配對請求。
• 連線問題：如果連線不穩，請參考 Channel troubleshooting 進行診斷。
• 功能範圍：目前的架構僅支援基於 WhatsApp Web (Baileys) 的整合，不支援 Twilio WhatsApp。

如果你在設定過程中遇到任何問題，可以直接詢問我們的 AI Setup Assistant。

下一步

• Pairing 運作機制
• Channel 疑難排解指南
• Gateway 配置範例大全

開發 WhatsApp 機器人最煩人的就是控制誰能跟它說話。有時候你只想讓特定幾個人測試，結果全世界的訊息都塞進來；或者你想在群組裡安靜一點，機器人卻像過動兒一樣每句都回，搞得大家想把它踢出去。

這篇文章會帶你快速設定機器人的「社交邊界」，讓你精準決定誰能傳私訊、誰能在群組裡觸發機器人。

需要準備的東西

• channels.whatsapp 配置權限
• WhatsApp 帳號連接
• 基本的 YAML 設定經驗

快速開始

要讓機器人乖乖聽話，你需要從私訊、群組和標記機制這三個維度來設定。

1. 管理私訊 (DM) 政策

透過 channels.whatsapp.dmPolicy 決定誰可以開啟私訊對話：

• pairing (預設值)：配對模式。
• allowlist：只允許白名單內的號碼。
• open：完全開放（注意：allowFrom 必須包含 "*"）。
• disabled：禁用所有私訊。

關於 allowFrom 的細節：

• 接受 E.164 格式的號碼（系統內部會自動正規化）。
• 配對資訊會存在 channel allow-store，並與你設定的 allowFrom 合併。
• 如果你完全沒設白名單，預設會允許連動的本人號碼。
• 從機器人端主動發出的 fromMe 訊息不會觸發自動配對。

2. 群組權限與發言者政策

群組存取有兩層防護網：

第一層：群組成員白名單 (channels.whatsapp.groups)

• 如果省略此項，所有群組都符合資格。
• 如果有設定，則作為群組白名單（支援 "*"）。

第二層：群組發言者政策 (channels.whatsapp.groupPolicy + groupAllowFrom)

• open：跳過發言者白名單檢查。
• allowlist：發言者必須符合 groupAllowFrom 或 *。
• disabled：封鎖所有群組進入的訊息。

提示：如果 groupAllowFrom 沒設定，系統會自動退而求其次使用 allowFrom 的設定。如果你完全沒設定 channels.whatsapp 區塊，群組政策預設會是 open。

3. 標記偵測與啟用指令

在群組中，機器人預設需要被標記才會回應。偵測機制包含：

• 直接在 WhatsApp 標記機器人的 identity。
• 自定義的標記正則表達式 (agents.list[].groupChat.mentionPatterns，若無則參考 messages.groupChat.mentionPatterns)。
• 隱性回覆偵測（當使用者回覆機器人的訊息時）。

你也可以透過指令動態調整 Session 等級的啟用狀態（僅限 Owner）：

• /activation mention：標記才回應。
• /activation always：每句都回應。

4. 本人號碼與自我對話行為

如果你用連接的本人號碼跟機器人聊天（Self-chat），會觸發特殊的保護機制：

• 自動跳過讀取回條 (Read receipts)。
• 忽略標記 JID 的自動觸發行為，避免你自己標記自己。
• 如果沒設 messages.responsePrefix，回覆會預設加上 [{identity.name}] 或 [openclaw]。

疑難排解

• 機器人在群組裡不回話？ 檢查 channels.whatsapp.groupPolicy 是否被設為 disabled，或者確認你的標記方式是否符合 mentionPatterns 的設定。

• 私訊無法開啟對話？ 確認 dmPolicy 是否為 pairing 或 allowlist。如果是 allowlist，請檢查該號碼是否已加入 allowFrom。

需要更多幫助？請諮詢 AI Setup Assistant

下一步

• Message Configuration
• Identity Management
• Channel Security
• API Reference

處理 WhatsApp 訊息最頭痛的地方，通常在於處理那些不一致的格式。當使用者傳來一張圖片、一段語音，或者引用了很久以前的一條訊息時，你的後端邏輯很容易就會亂成一團，難以維持對話的連貫性。

為了讓你更輕鬆地開發機器人，系統會將這些複雜的傳入資料進行「標準化」處理，確保你的程式碼收到的內容是整潔且帶有上下文的。

需要準備的東西

在開始調整配置之前，請確保你已經具備：

• 一個運作中的 WhatsApp 帳號整合
• 基本的 Gateway 配置權限

快速開始

這裡有四個關於訊息標準化的核心機制，幫助你快速掌握訊息的處理方式。

1. 處理回覆上下文

當使用者在 WhatsApp 中引用某條訊息進行回覆時，系統會將這些資訊封裝在一個標準的「信封（Envelope）」中。除了 ReplyToId、ReplyToBody 等元數據外，訊息內容會被加上特定的標籤：

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

這樣你的 AI 或處理邏輯就能立刻理解這條訊息是在回應什麼。

2. 媒體佔位符與位置資訊

如果使用者傳送的是純媒體（如圖片或貼圖），系統會將其轉化為易於解析的文字佔位符。地理位置和聯絡人資訊也會在路由之前被轉化為文字上下文：

• <media:image>
• <media:video>
• <media:audio>
• <media:document>
• <media:sticker>

3. 群組歷史訊息注入

在群組對話中，如果機器人被觸發時有一段時間沒說話，系統可以自動將未處理的歷史訊息緩衝並作為上下文注入，讓機器人「進入狀況」。

你可以透過以下配置調整（預設限制為 50 條）：

• 配置路徑：channels.whatsapp.historyLimit
• 備用路徑：messages.groupChat.historyLimit
• 設定為 0 則禁用此功能

注入的訊息會帶有明確的標示：

• [Chat messages since your last reply - for context]
• [Current message - respond to this]

4. 管理已讀回執 (Read Receipts)

預設情況下，當你成功接收 WhatsApp 訊息後，系統會自動發送已讀回執。如果你想關閉這個功能，可以進行全域設定或針對特定帳號設定。

全域禁用：

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

針對特定帳號（例如 work 帳號）覆蓋設定：

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}

疑難排解

為什麼我發給自己的訊息沒有顯示已讀？

這是正常現象。即使你開啟了全域已讀回執，系統在處理「跟自己對話（Self-chat）」的訊息時，會自動跳過發送已讀回執。

如何調整群組訊息注入的數量？

如果你覺得 50 條訊息太多或太少，可以直接修改 channels.whatsapp.historyLimit。如果你希望完全不要注入歷史訊息，將該值設為 0 即可。

---

如果你在配置過程中遇到任何問題，可以直接詢問我們的 AI Setup Assistant。

下一步

• 了解 WhatsApp 帳號配置
• 深入研究訊息路由邏輯

在開發 WhatsApp 機器人時，你可能遇過訊息太長被系統直接切斷，或是想傳送語音訊息卻因為格式不對而失敗。處理這些媒體與傳輸細節通常很瑣碎，如果沒有處理好，使用者體驗就會大打折扣。

這篇文章會帶你快速掌握 WhatsApp Channel 的進階配置，從訊息自動分段到多帳號憑證管理，幫你避開常見的坑。

需要準備的東西

在開始調整設定之前，請確保你已經準備好：

• 已安裝並配置好的 OpenClaw 環境
• 至少一個已連線的 WhatsApp 帳號
• 基本的 JSON 配置文件修改能力

快速開始

如果你想讓機器人在收到訊息時立刻給個回應（例如顯示「正在讀取」的表情符號），可以在設定檔中加入這段：

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions",
      },
    },
  },
}

訊息分段 (Text Chunking)

當你的機器人回覆內容太長時，OpenClaw 會自動幫你處理分段，避免觸發 WhatsApp 的限制。

• 預設限制：channels.whatsapp.textChunkLimit 預設為 4000 個字元。
• 分段模式：你可以透過 channels.whatsapp.chunkMode 調整模式：
  • length：單純依長度切分。
  • newline：優先尋找段落邊界（空白行），如果找不到才會退回到長度切分模式。

媒體傳輸行為

WhatsApp 支援多種媒體格式，OpenClaw 在背後幫你做了不少優化：

• 支援格式：支援 image, video, audio (PTT 語音訊息) 以及 document。
• 語音優化：audio/ogg 會自動被重寫為 audio/ogg; codecs=opus，確保在 WhatsApp 上能以語音訊息格式正常播放。
• GIF 動畫：在傳送影片時，設定 gifPlayback: true 就能實現 GIF 自動播放效果。
• 文字標題：當你一次傳送多個媒體檔案時，caption 會自動套用到第一個媒體物件上。
• 來源彈性：媒體來源可以是 HTTP(S) 網址、file:// 協議或是本地檔案路徑。

媒體大小限制與自動縮減

為了確保傳輸成功率，系統設有大小上限：

• 接收限制：channels.whatsapp.mediaMaxMb 預設為 50 (MB)。
• 發送限制：自動回覆的上限為 agents.defaults.mediaMaxMb，預設為 5MB。
• 自動優化：圖片會自動進行尺寸調整與品質壓縮，以符合大小限制。
• 錯誤處理：如果媒體傳送失敗，系統會發送文字警告訊息作為替代方案，而不是完全沒有反應。

訊息讀取回饋 (Acknowledgment reactions)

你可以設定 channels.whatsapp.ackReaction 讓機器人在收到訊息後立即給予表情符號回饋。

• 觸發時機：在機器人正式產生回覆內容前就會立即傳送。
• 群組模式：
  • mentions：只在機器人被標記（mention）時才反應。
  • always：繞過檢查，在群組中對所有訊息做出反應。
• 注意：這項功能使用 channels.whatsapp.ackReaction 設定，舊版的 messages.ackReaction 已不再使用。

多帳號與憑證管理

如果你需要同時管理多個 WhatsApp 帳號，OpenClaw 提供了清晰的結構。

帳號選擇

• 帳號 ID 來自 channels.whatsapp.accounts。
• 預設帳號：優先尋找名為 default 的帳號，若無則按字母排序選擇第一個帳號。

憑證路徑

• 目前路徑：~/.openclaw/credentials/whatsapp/<accountId>/creds.json。
• 備份機制：系統會自動產生 creds.json.bak。
• 相容性：舊版位於 ~/.openclaw/credentials/ 的憑證仍會被識別並自動遷移。

登出行為

使用 CLI 指令可以清除特定帳號的驗證狀態： openclaw channels logout --channel whatsapp [--account <id>]

在舊版目錄中，oauth.json 會被保留，但 Baileys 相關的驗證檔案會被移除。

工具、動作與配置寫入

• Action 支援：機器人工具現在支援 WhatsApp 的 react（反應）動作。
• 功能開關：
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• 配置自動寫入：由 Channel 發起的配置寫入預設是開啟的，你可以透過 channels.whatsapp.configWrites=false 來關閉它。

疑難排解

• 媒體傳送失敗：如果圖片或影片太大導致傳送失敗，請檢查 agents.defaults.mediaMaxMb 的設定。OpenClaw 會嘗試傳送文字警告，你可以根據 log 檢查是否觸發了縮減機制。
• 表情符號沒出現：確保你使用的是 channels.whatsapp.ackReaction 而非舊版欄位。如果在群組中沒反應，檢查 group 參數是否設定為 mentions 或 always。
• 憑證問題：如果帳號連線異常，可以檢查 ~/.openclaw/credentials/whatsapp/<accountId>/ 下的 creds.json 是否損壞，或嘗試使用 logout 指令後重新登入。

如果你在設定過程中遇到任何問題，可以直接詢問 AI Setup Assistant 獲取即時協助。

下一步

• WhatsApp Provider Setup
• Agent Tools and Actions
• Managing Multiple Channels

寫程式最煩的不是寫代碼，而是代碼寫好後，連線卻莫名其妙斷掉，或是訊息發出去後像石沉大海。你可能正看著終端機裡的錯誤訊息發呆，心裡想著明明配置都對，為什麼就是不通？這篇文幫你整理了最常見的坑，幫你省下通宵除錯的時間。

需要準備的東西

在開始排錯前，請確保你已經準備好以下環境（根據源文件要求）：

• 已安裝 Node.js（注意：請避開 Bun）
• 已安裝 Openclaw CLI 工具
• 一個準備好掃描 QR Code 的 WhatsApp 帳號

快速開始

如果你發現服務怪怪的，先跑這兩步通常能解決 80% 的問題：

1. 重新登入：強制觸發 QR Code 掃描。

   openclaw channels login --channel whatsapp

2. 檢查狀態：確認目前的連線進度。

   openclaw channels status

疑難排解

這裡列出了你在運行 WhatsApp Gateway 時可能遇到的具體問題與對策。

狀態顯示 Not linked (需要掃描 QR Code)

如果你看到頻道狀態回報為 not linked，表示你的 session 已經失效或從未建立。

解決方法： 直接執行登入指令並檢查狀態：

openclaw channels login --channel whatsapp
openclaw channels status

已連線但不斷斷線或陷入重連循環

有時候帳號顯示已連結，但日誌裡卻全是斷線重連的訊息。

解決方法： 先使用診斷工具檢查環境，再觀察即時日誌：

openclaw doctor
openclaw logs --follow

如果問題持續，建議直接用 channels login 重新綁定。

發送訊息時顯示 No active listener

當你想發送 Outbound 訊息卻立即失敗，通常是因為目標帳號沒有活著的 Gateway Listener。

檢查清單：

• 確認 Gateway 服務正在運行。
• 確認該帳號已成功連結且在線。

群組訊息被意外忽略

如果個人訊息正常，但群組訊息沒反應，請依序檢查這四個配置項：

1. groupPolicy 的設定是否正確。
2. groupAllowFrom 或 allowFrom 的過濾規則。
3. groups 白名單（allowlist）是否有漏掉該群組。
4. 提及限制（requireMention 與 mentionPatterns）。

Bun 運行環境警告

如果你在 Bun 環境下執行 WhatsApp Gateway，可能會遇到穩定性問題。

建議方案： WhatsApp Gateway 的 runtime 應該使用 Node.js。目前 Bun 被標記為不相容，無法保證 WhatsApp 或 Telegram Gateway 的穩定運作。

Configuration Reference

如果你需要更深入的調整，可以參考以下關鍵欄位。

核心參考：

• Configuration reference - WhatsApp

高優先級欄位：

• 存取控制：dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• 訊息傳遞：textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction
• 多帳號管理：accounts.<id>.enabled, accounts.<id>.authDir, 以及各帳號的獨立覆寫（overrides）
• 運維配置：configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
• Session 行為：session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

---

遇到奇怪的 Bug 搞不定？試試我們的 AI Setup Assistant，它能根據你的配置給出具體建議。

下一步

• Pairing - 深入了解配對流程
• Channel routing - 設定訊息路由規則
• Troubleshooting - 更多通用排錯技巧