OpenClaw WhatsApp 整合完整指南
連接 OpenClaw 與 WhatsApp 的分步指南。使用 Baileys 透過 WhatsApp Web 協定與您的 AI 助手聊天。
OpenClaw Guides
Tutorial Authors
概述
WhatsApp 整合允許您直接透過 WhatsApp 與 OpenClaw AI 助手聊天。OpenClaw 使用 WhatsApp Web via Baileys — 閘道擁有工作階段並管理所有通訊。您將像在瀏覽器上連結 WhatsApp Web 一樣連結您的 WhatsApp 帳戶。
前提條件
開始之前，請確保您有：
- 已安裝 OpenClaw 且閘道正在執行
- 一個擁有真實手機號碼的 WhatsApp 帳戶（VoIP 和虛擬號碼通常會被 WhatsApp 封鎖）
- Node.js 執行環境（不建議使用 Bun — WhatsApp/Baileys 在 Bun 上執行不穩定）
取得電話號碼
WhatsApp 需要真實手機號碼進行驗證。有兩種支援的模式：
專用號碼（建議）
使用獨立電話號碼執行 OpenClaw。這提供最佳使用者體驗，路由清晰，沒有自聊天問題。理想設定是備用/舊 Android 手機 + eSIM — 保持 Wi-Fi 和電源連接，然後透過 QR 碼連結。
號碼取得提示：
- 本地 eSIM — 來自您所在國家的電信業者（最可靠）
- 預付費 SIM 卡 — 便宜，只需接收一則驗證簡訊
- 避免使用： TextNow、Google Voice 及大多數「免費簡訊」服務 — WhatsApp 會積極封鎖這些
號碼只需接收一則驗證簡訊。之後，WhatsApp Web 工作階段透過 creds.json 持久保存。
提示： 您可以在同一裝置上使用不同號碼執行 WhatsApp Business。非常適合將個人 WhatsApp 分開 — 安裝 WhatsApp Business 並用 OpenClaw 號碼註冊。
個人號碼（備選方案）
快速備選：在您自己的號碼上執行 OpenClaw。給自己發訊息（WhatsApp「給自己發訊息」）進行測試，避免打擾聯絡人。這種情況下必須啟用自聊天模式。
步驟 1：設定 WhatsApp
編輯 ~/.openclaw/openclaw.json。
專用號碼設定
{
channels: {
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+15551234567"],
},
},
}
將 +15551234567 替換為您希望允許與助手聊天的電話號碼（E.164 格式）。
個人號碼設定（自聊天模式）
{
"whatsapp": {
"selfChatMode": true,
"dmPolicy": "allowlist",
"allowFrom": ["+15551234567"]
}
}
使用自聊天模式時，輸入您發送訊息的電話號碼（擁有者/發送者），而非助手號碼。自聊天回覆預設使用 [{identity.name}] 作為前綴（如未設定則為 [openclaw]）。您可以透過 messages.responsePrefix 自訂，或設定為 "" 來移除。
步驟 2：連結您的 WhatsApp 帳戶
執行登入命令：
openclaw channels login
這將在終端機顯示 QR 碼。在手機上：
- 開啟 WhatsApp
- 前往 設定 > 連結裝置
- 點擊 連結裝置
- 掃描終端機中顯示的 QR 碼
對於多帳戶設定，指定帳戶：
openclaw channels login --account <accountId>
省略 --account 時的預設帳戶：如果存在 default 則使用它，否則使用第一個設定的帳戶 ID（按排序）。
步驟 3：啟動閘道
啟動 OpenClaw 閘道開始接收訊息。閘道擁有 Baileys socket 和收件迴圈 — CLI 和 macOS 應用程式與閘道通訊，不直接使用 Baileys。
重要： 出站發送需要活躍的監聽器；否則發送會快速失敗。
DM 存取控制
OpenClaw 透過 channels.whatsapp.dmPolicy 提供三種 DM 策略模式：
配對模式（預設）
未知發送者會收到一個有時間限制的配對碼。他們的訊息在批准前不會被處理。
# 批准配對請求 openclaw pairing approve whatsapp <code> # 列出待處理的配對請求 openclaw pairing list 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 停止並需要重新連結。