OpenClaw WhatsApp 頻道
即時通訊
中等
透過 Baileys 協定將 OpenClaw 連接至 WhatsApp。此整合方式無需商業 API,只需用手機掃描 QR Code 即可讓 AI 助手在 WhatsApp 上收發訊息。建議使用獨立手機號碼以獲得更清晰的路由。
快速資訊
難度中等
分類即時通訊
支援功能數5 / 6
WhatsApp 支援功能
文字訊息
支援
媒體與檔案
支援
表情回應
支援
討論串
不支援
語音訊息
支援
群組聊天
支援
WhatsApp 前置條件
- WhatsApp 專用手機號碼(建議與個人號碼分開)
- 伺服器已安裝 Node.js 18+(不建議使用 Bun)
- OpenClaw Gateway 已執行並設定完成
WhatsApp 快速設定
1
新增 WhatsApp 頻道設定
在 ~/.openclaw/openclaw.json 中新增 WhatsApp 頻道設定。設定 dmPolicy(allowlist、pairing 或 open)和 allowFrom 清單來控制誰可以向您的助手發送訊息。
2
執行登入命令並掃描 QR Code
在終端機執行 'openclaw channels login',將顯示一個 QR Code。用手機 WhatsApp 掃描(設定 > 已連結的裝置 > 連結裝置)。憑證將儲存至 ~/.openclaw/credentials/whatsapp/。
3
發送測試訊息
從另一部手機向您的 WhatsApp 號碼發送私訊。如果使用 allowlist 策略,請確認發送者號碼在 allowFrom 清單中。如果使用預設的 pairing 策略,請透過 'openclaw pairing approve whatsapp <code>' 核准發送者。
WhatsApp 設定範例
config.json
{
"channels": {
"whatsapp": {
"dmPolicy": "allowlist",
"allowFrom": ["+15551234567"]
}
}
}WhatsApp 深入了解
架構概述
OpenClaw 透過 Baileys 函式庫連接 WhatsApp —— 這是一個逆向工程實作的開源 WhatsApp Web 多裝置協定。與官方 WhatsApp Business API(需要 Meta 核准且按對話收費)不同,Baileys 透過模擬已連結裝置直接連接。
架構很簡單：您的手機作為主要裝置,Gateway 充當已連結的伴侶裝置。訊息照常透過 WhatsApp 的伺服器傳輸 —— OpenClaw 只是攔截入站訊息,交給您的 AI 處理,然後將回覆發回。
由於連接基於手機,您的手機必須保持在線。如果手機離線超過約 14 天,WhatsApp 會取消連結。
Baileys 原生支援多裝置 —— 每個手機號碼最多可連結 4 個裝置,Gateway 算其中之一。
手機號碼設定
強烈建議使用專用手機號碼。雖然您可以使用個人號碼,但將個人和機器人對話混在一起會造成路由混亂,也可能打擾您的聯絡人。
您需要一個能接收簡訊或語音來電的真實手機號碼,用於 WhatsApp 初始註冊。註冊完成後,該號碼只需保持在安裝了 WhatsApp 的手機上處於活躍狀態即可。
openclaw.json
{
"channels": {
"whatsapp": {
"accounts": {
"default": {
"phone": "+15551234567"
}
}
}
}
}避免使用 VoIP 號碼(如 TextNow、Google Voice、免費簡訊服務)—— WhatsApp 經常封鎖 VoIP 註冊的帳號。使用真實 SIM 卡、預付費 SIM 卡或專用 eSIM 以獲得最佳可靠性。
登入與憑證
設定好頻道後,您需要將手機與 Gateway 配對。執行登入命令,終端機中會顯示一個 QR Code。用手機上的 WhatsApp 掃描它(設定 → 已連結的裝置 → 連結裝置)。
憑證會自動儲存至 ~/.openclaw/credentials/whatsapp/<accountId>/creds.json,並在重啟後保持有效。系統會自動建立備份檔案(creds.json.bak)以便在檔案損壞時復原。除非工作階段過期或被手動撤銷,您只需掃描一次 QR Code。
終端機
openclaw channels login whatsapp如果在無顯示器的伺服器上執行,使用 --qr-terminal 參數可以將 QR Code 以 ASCII 圖形直接呈現在終端機中。
私訊策略
私訊(DM)策略控制誰可以與您的 AI 助手互動。OpenClaw 支援四種策略：
• pairing(預設)—— 新聯絡人需要完成配對流程。他們發送訊息後會收到一個配對碼,您在 CLI 中批准或拒絕。批准後即可自由聊天。
• allowlist —— 只有 allowFrom 清單中明確列出的手機號碼可以給機器人發訊息。其他人將被靜默忽略。
• open —— 任何給該號碼發訊息的人都會收到回覆。在正式環境中請謹慎使用。
• disabled —— 完全關閉私訊處理。機器人不會回應任何私訊。
openclaw.json
{
"channels": {
"whatsapp": {
"dmPolicy": "pairing",
"allowFrom": ["+15551234567", "+15559876543"]
}
}
}群組管理
OpenClaw 可以參與 WhatsApp 群組聊天。預設情況下,群組支援是停用的,以避免在共享對話中產生不必要的 AI 回覆。
啟用後,機器人僅在被提及名字或被設定的關鍵字觸發時才會回覆。您可以控制哪些群組處於活躍狀態以及機器人如何被啟動。
openclaw.json
{
"channels": {
"whatsapp": {
"groupPolicy": "allowlist",
"groupActivation": "mention",
"groupAllowList": ["group-jid-1", "group-jid-2"]
}
}
}群組 JID 可以在 Gateway 記錄中找到——當收到群組訊息時,查看訊息載荷中的 'from' 欄位。
已讀回執
您可以設定 OpenClaw 在處理訊息時是否傳送已讀回執(藍色雙勾)。預設會傳送已讀回執,以保持自然的對話感覺。
如果您希望機器人看起來不那麼「活躍」,或者您在非同步處理訊息,可以停用已讀回執。
openclaw.json
{
"channels": {
"whatsapp": {
"sendReadReceipts": true
}
}
}確認表情回覆
OpenClaw 可以在 AI 回覆產生之前,先對收到的訊息新增一個表情回覆作為確認。這很有用,因為 AI 回覆可能需要幾秒鐘,表情回覆可以讓發送者知道訊息已被收到。
您可以分別為私訊和群組聊天設定不同的表情回覆,或完全停用此功能。
openclaw.json
{
"channels": {
"whatsapp": {
"ackReaction": {
"emoji": "👀",
"direct": true,
"group": true
}
}
}
}發送訊息與媒體
OpenClaw 支援透過 WhatsApp 傳送文字、圖片、文件、音訊和影片。媒體檔案會被自動處理 —— Gateway 將它們上傳至 WhatsApp 的伺服器並傳送相應的訊息類型。
對於較長的 AI 回覆,文字會被自動分段以保持在 WhatsApp 的訊息大小限制內。您可以設定分段大小和行為。
預設入站媒體大小限制為 50 MB(mediaMaxMb)。發送媒體限制為 5 MB(agents.defaults.mediaMaxMb),超大圖片會自動進行 JPEG 最佳化和壓縮。
速率限制與傳送限制
WhatsApp 對已連結裝置有速率限制。雖然個人帳號沒有官方公佈的明確限制,但傳送訊息過快過多可能觸發暫時封鎖或帳號限制。
OpenClaw 內建了速率限制機制來保護您的帳號。預設設定較為保守,適合大多數使用場景。
openclaw.json
{
"channels": {
"whatsapp": {
"textChunkLimit": 5,
"mediaMaxMb": 50
}
}
}為什麼不用 Twilio / WhatsApp Business API？
您可能想知道為什麼 OpenClaw 使用 Baileys 而不是官方的 WhatsApp Business API(透過 Twilio、MessageBird 等)。原因如下：
• 成本 —— Business API 按對話收費(根據地區約 $0.005–$0.08 每則訊息)。對於個人或小團隊使用,費用會迅速累積。Baileys 是免費的。
• 核准 —— Business API 需要 Meta 驗證、註冊企業和訊息範本核准。Baileys 可以使用任何個人 WhatsApp 帳號。
• 彈性 —— Business API 對發送訊息有嚴格的範本要求和 24 小時對話視窗。Baileys 沒有這些限制。
• 自託管 —— 使用 Baileys,一切都在您的伺服器上執行。沒有第三方 API 供應商能看到您的訊息。
權衡在於可靠性：Business API 是官方支援的,而 Baileys 依賴逆向工程,如果 WhatsApp 更改協定可能會失效。對於大多數自託管使用場景,這個權衡是值得的。
WhatsApp 設定參考
| Key | Type | Default | Description |
|---|---|---|---|
| dmPolicy | string | "pairing" | 控制誰可以私訊機器人。選項：pairing、allowlist、open、disabled |
| selfChatMode | string | "disabled" | 如何處理您發給自己的訊息。選項：disabled、ai、note |
| allowFrom | string[] | [] | 允許給機器人發訊息的手機號碼清單(dmPolicy 為 allowlist 時使用) |
| sendReadReceipts | boolean | true | 處理訊息時是否傳送藍色雙勾已讀回執 |
| ackReaction.emoji | string | "👀" | 用於確認收到訊息的表情符號 |
| ackReaction.direct | boolean | true | 在私訊中傳送確認表情 |
| ackReaction.group | boolean | true | 在群組聊天中傳送確認表情 |
| textChunkLimit | number | 5 | 每次 AI 回覆的最大文字分段數 |
| mediaMaxMb | number | 50 | 最大入站媒體檔案大小(MB)。發送限制由 agents.defaults.mediaMaxMb 控制(預設 5 MB) |
| groupPolicy | string | "disabled" | 群組聊天策略。選項：disabled、allowlist、open |
| groupActivation | string | "mention" | 群組中如何觸發機器人。選項：mention、always |
| historyLimit | number | 50 | 作為 AI 上下文包含的最近訊息數量 |
| chunkMode | string | "split" | 如何處理長回覆。選項：split、newline、truncate |
| messagePrefix | string | "" | 新增至所有發送訊息前的可選前綴 |
| accounts.<id>.* | object | {} | 每個帳號的設定(手機號碼、憑證路徑、覆蓋設定) |
dmPolicy
Type: stringDefault: "pairing"
控制誰可以私訊機器人。選項：pairing、allowlist、open、disabled
selfChatMode
Type: stringDefault: "disabled"
如何處理您發給自己的訊息。選項：disabled、ai、note
allowFrom
Type: string[]Default: []
允許給機器人發訊息的手機號碼清單(dmPolicy 為 allowlist 時使用)
sendReadReceipts
Type: booleanDefault: true
處理訊息時是否傳送藍色雙勾已讀回執
ackReaction.emoji
Type: stringDefault: "👀"
用於確認收到訊息的表情符號
ackReaction.direct
Type: booleanDefault: true
在私訊中傳送確認表情
ackReaction.group
Type: booleanDefault: true
在群組聊天中傳送確認表情
textChunkLimit
Type: numberDefault: 5
每次 AI 回覆的最大文字分段數
mediaMaxMb
Type: numberDefault: 50
最大入站媒體檔案大小(MB)。發送限制由 agents.defaults.mediaMaxMb 控制(預設 5 MB)
groupPolicy
Type: stringDefault: "disabled"
群組聊天策略。選項：disabled、allowlist、open
groupActivation
Type: stringDefault: "mention"
群組中如何觸發機器人。選項：mention、always
historyLimit
Type: numberDefault: 50
作為 AI 上下文包含的最近訊息數量
chunkMode
Type: stringDefault: "split"
如何處理長回覆。選項：split、newline、truncate
messagePrefix
Type: stringDefault: ""
新增至所有發送訊息前的可選前綴
accounts.<id>.*
Type: objectDefault: {}
每個帳號的設定(手機號碼、憑證路徑、覆蓋設定)
WhatsApp 常見問題
WhatsApp 故障排除
WhatsApp 顯示「未連結」或 QR Code 無法掃描
工作階段憑證可能已過期,或者手機上的 WhatsApp 應用程式更新後使連結的工作階段失效。
刪除 ~/.openclaw/credentials/whatsapp/ 目錄下的憑證資料夾,然後重新執行 'openclaw channels login whatsapp' 進行配對。確保掃描 QR Code 時手機網路連線穩定。
機器人已連接但不斷重複斷開
通常發生在手機長時間離線,或另一個已連結裝置與 Gateway 工作階段衝突時。
確保您的手機保持網路連線。檢查是否已超過已連結裝置的 4 個裝置上限。在 WhatsApp 設定 → 已連結的裝置中移除未使用的已連結裝置,然後重新登入。
訊息傳送失敗(逾時或投遞失敗)
速率限制、網路問題,或收件人已封鎖您的號碼。
檢查 Gateway 記錄中的具體錯誤碼。如果看到速率限制錯誤,減少傳送頻率。如果是網路問題,確認您的伺服器網路穩定。嘗試從手機手動傳送訊息以確認號碼未被限制。