OpenClaw WhatsApp 整合完整指南

配對碼在 1 小時 後過期，每個頻道的待處理請求上限為 3 個。

白名單模式

只有 channels.whatsapp.allowFrom 中列出的電話號碼才能發起聊天。

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

開放模式

需要 channels.whatsapp.allowFrom 包含 "*" 。

注意： 您連結的 WhatsApp 號碼是隱式信任的 — 自訊息會跳過 dmPolicy 和 allowFrom 檢查。

已讀回執

預設情況下，閘道在接受入站 WhatsApp 訊息後會將其標記為已讀（藍色勾勾）。

全域停用：

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

按帳戶停用：

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

自聊天模式始終跳過已讀回執。

群組聊天支援

群組對應到專用工作階段。透過以下方式設定群組行為：

• 群組策略： channels.whatsapp.groupPolicy — open 、 disabled 或 allowlist （預設： allowlist ）
• 啟用模式：
  • mention （預設）：需要 @提及 或正則匹配
  • always ：始終觸發回應

透過僅限擁有者的命令切換啟用模式（必須作為獨立訊息發送）：

/activation mention
/activation always

擁有者由 channels.whatsapp.allowFrom 確定（如未設定則為您的 E.164 號碼）。

群聊歷史上下文

最近未處理的訊息（預設 50 則）會自動注入作為上下文：

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

每則訊息包含發送者後綴： [from: Name (+E164)] 。

群組中繼資料（主題 + 參與者）快取 5 分鐘。

確認回應

WhatsApp 可以在收到訊息時自動發送 emoji 回應，在機器人生成回覆之前提供即時回饋。

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

選項：

• emoji ：回應使用的 emoji（如 "👀"、"✅"）。為空或省略則停用該功能。
• direct （預設： true ）：在 DM 聊天中發送回應。
• group （預設： "mentions" ）：
  • "always" ：對所有群組訊息回應
  • "mentions" ：僅在機器人被 @提及 時回應
  • "never" ：從不在群組中回應

按帳戶覆寫：

{
  "whatsapp": {
    "accounts": {
      "work": {
        "ackReaction": {
          "emoji": "✅",
          "direct": false,
          "group": "always"
        }
      }
    }
  }
}

回應在收到訊息後立即發送，在輸入指示器或機器人回覆之前。失敗會被記錄但不會阻止機器人回覆。

訊息處理

入站訊息

• 訊息透過 Baileys messages.upsert 事件到達
• 狀態/廣播聊天被忽略
• 直接聊天使用 E.164 格式；群組使用 group JID
• 引用回覆上下文始終附加以提供對話上下文
• 純媒體訊息使用佔位符： <media:image|video|audio|document|sticker>

出站訊息

• 文字預設分塊為 4,000 字元 （可透過 channels.whatsapp.textChunkLimit 設定）
• 可選換行分塊：設定 channels.whatsapp.chunkMode="newline" 在長度分塊前按段落邊界分割
• 支援的媒體類型：圖片、影片、音訊、文件
• 音訊作為語音備忘錄（PTT）發送。OGG/Opus 格式效果最佳
• 標題僅在第一個媒體項目上
• 動態 GIF：WhatsApp 需要帶 gifPlayback: true 的 MP4 才能內嵌循環播放

媒體限制

• 入站 媒體儲存上限：50 MB（可透過 channels.whatsapp.mediaMaxMb 設定）
• 出站 媒體上限：每項 5 MB（可透過 agents.defaults.mediaMaxMb 設定）
• 圖片在上限內自動最佳化為 JPEG（調整大小 + 品質掃描）
• 超大媒體會導致錯誤；媒體回覆回退到文字警告

憑證與儲存

• 憑證儲存在： ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• 自動備份在 creds.json.bak （損壞時還原）
• 登出： openclaw channels logout （或 --account <id> ）刪除 WhatsApp 認證狀態但保留共用的 oauth.json

多帳戶支援

多個 WhatsApp 帳戶可以在單個閘道程序中執行。在設定中使用帳戶識別碼：

{
  channels: {
    whatsapp: {
      accounts: {
        personal: { /* 按帳戶設定 */ },
        work: { /* 按帳戶設定 */ },
      },
    },
  },
}

按帳戶設定支援覆寫 sendReadReceipts 、 ackReaction 、 mediaMaxMb 、 historyLimit 等。

為什麼不用 Twilio / WhatsApp Business API？

早期 OpenClaw 建置支援 Twilio 的 WhatsApp Business 整合，但已被移除，原因是：

• WhatsApp Business 號碼不適合個人助手
• Meta 強制執行 24 小時回覆視窗 — 如果過去 24 小時內沒有回應，商業號碼無法發起新訊息
• 高頻或「聊天式」使用會觸發積極封鎖，因為商業帳戶不是為個人助手式訊息設計的
• 結果：投遞不可靠且頻繁被封鎖

設定速查參考

| 設定鍵 | 描述 | |---|---| | channels.whatsapp.dmPolicy | DM 策略： pairing / allowlist / open / disabled | | channels.whatsapp.selfChatMode | 為個人號碼設定啟用 | | channels.whatsapp.allowFrom | DM 白名單（E.164 電話號碼） | | channels.whatsapp.sendReadReceipts | 自動已讀回執（預設：true） | | channels.whatsapp.ackReaction | 訊息收到時自動回應 | | channels.whatsapp.groupPolicy | 群組策略： open / disabled / allowlist | | channels.whatsapp.textChunkLimit | 出站文字分塊大小（預設：4000） | | channels.whatsapp.mediaMaxMb | 入站媒體上限（預設：50 MB） | | channels.whatsapp.configWrites | 允許透過 /config 命令寫入設定 | | agents.defaults.mediaMaxMb | 出站媒體上限（預設：5 MB） |

疑難排解

未連結 / 需要 QR 碼登入

症狀： channels status 顯示 linked: false 或警告「Not linked」。

修復： 在閘道主機上執行 openclaw channels login 並掃描 QR 碼（WhatsApp > 設定 > 連結裝置）。

已連結但斷線 / 重連迴圈

症狀： channels status 顯示 running, disconnected 或警告「Linked but disconnected」。

修復： 執行 openclaw doctor 或重新啟動閘道。如果問題持續，透過 openclaw channels login 重新連結並檢查 openclaw logs --follow 。

Bun 執行環境問題

Bun 不建議使用 。WhatsApp（Baileys）和 Telegram 在 Bun 上不穩定。請使用 Node.js 執行閘道。

重連行為

閘道使用退避策略（ web.reconnect ），可設定 initialMs 、 maxMs 、 factor 、 jitter 和 maxAttempts 。如果達到最大嘗試次數，Web 監控停止（降級模式）。已登出的 socket 停止並需要重新連結。

後續步驟

• Telegram 整合指南
• Discord 整合指南
• 官方 WhatsApp 文件