WhatsApp

狀態：透過 WhatsApp Web（Baileys）已可用於生產環境。Gateway 擁有已連結的工作階段。

# 安裝（按需）

• Onboarding（openclaw onboard）和 openclaw channels add --channel whatsapp 會在你第一次選取 WhatsApp Plugin 時提示安裝。
• 當 Plugin 尚未存在時，openclaw channels login --channel whatsapp 也會提供安裝流程。
• Dev channel + git checkout：預設使用本機 Plugin 路徑。
• Stable/Beta：在目前官方 release tag 上使用 npm 套件 @openclaw/whatsapp。

仍可手動安裝：

openclaw plugins install @openclaw/whatsapp

使用裸套件可跟隨目前的官方 release tag。只有在需要可重現安裝時，才釘選精確版本。

在 Windows 上，WhatsApp Plugin 在 npm install 期間需要 PATH 上有 Git，因為其 Baileys/libsignal 依賴項之一是從 git URL 擷取。安裝 Git for Windows，然後重新啟動 shell 並重新執行安裝：

winget install --id Git.Git -e

只要 Portable Git 的 bin 目錄位於 PATH 上，也可以使用。

# 快速設定

{
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-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

# 部署模式

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

# 執行階段模型

• Gateway 擁有 WhatsApp socket 和重新連線迴圈。
• 重新連線 watchdog 使用 WhatsApp Web 傳輸活動，而不只使用傳入應用程式訊息量，因此安靜的已連結裝置工作階段不會只因為最近沒有人傳送訊息而重新啟動。如果傳輸 frame 持續抵達但 watchdog 視窗內未處理任何應用程式訊息，較長的應用程式靜默上限仍會強制重新連線；對最近活躍工作階段的暫時重新連線之後，該應用程式靜默檢查會在第一個復原視窗使用正常訊息逾時。
• Baileys socket 時序在 web.whatsapp.* 下明確設定：keepAliveIntervalMs 控制 WhatsApp Web 應用程式 ping，connectTimeoutMs 控制開啟交握逾時，而 defaultQueryTimeoutMs 控制 Baileys 查詢逾時。
• 傳出傳送需要目標帳號有作用中的 WhatsApp 監聽器。
• 群組傳送會針對文字與媒體標題中的 @+<digits> 和 @<digits> 權杖附加原生提及中繼資料，前提是該權杖符合目前 WhatsApp 參與者中繼資料，包括以 LID 支援的群組。
• 狀態和廣播聊天會被忽略（@status、@broadcast）。
• 重新連線 watchdog 會遵循 WhatsApp Web 傳輸活動，而不只看傳入應用程式訊息量：只要傳輸 frame 持續，安靜的已連結裝置工作階段就會保持連線，但傳輸停滯會在較晚的遠端中斷連線路徑之前很早就強制重新連線。
• 直接聊天使用 DM 工作階段規則（session.dmScope；預設 main 會將 DM 收斂到代理程式主工作階段）。
• 群組工作階段會隔離（agent:<agentId>:whatsapp:group:<jid>）。
• WhatsApp Channels/Newsletters 可以使用其原生 @newsletter JID 作為明確傳出目標。傳出 newsletter 傳送使用通道工作階段中繼資料（agent:<agentId>:whatsapp:channel:<jid>），而非 DM 工作階段語意。
• WhatsApp Web 傳輸遵循 Gateway 主機上的標準 Proxy 環境變數（HTTPS_PROXY、HTTP_PROXY、NO_PROXY / 小寫變體）。優先使用主機層級 Proxy 設定，而非通道特定的 WhatsApp Proxy 設定。
• 啟用 messages.removeAckAfterReply 時，OpenClaw 會在可見回覆送達後清除 WhatsApp ack 反應。

# Plugin hook 與隱私

WhatsApp 傳入訊息可能包含個人訊息內容、電話號碼、 群組識別碼、寄件者名稱，以及工作階段關聯欄位。因此， 除非你明確選擇加入，WhatsApp 不會將傳入的 message_received hook payload 廣播給 Plugin：

{
  channels: {
    whatsapp: {
      pluginHooks: {
        messageReceived: true,
      },
    },
  },
}

你可以將選擇加入範圍限定為一個帳號：

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          pluginHooks: {
            messageReceived: true,
          },
        },
      },
    },
  },
}

只有在你信任 Plugin 可接收傳入 WhatsApp 訊息內容與識別碼時，才啟用此選項。

# 存取控制與啟用

# 個人號碼與自我聊天行為

當已連結的自身號碼也存在於 allowFrom 時，WhatsApp 自我聊天防護會啟用：

• 略過自我聊天回合的讀取回條
• 忽略原本會 ping 你自己的提及 JID 自動觸發行為
• 如果未設定 messages.responsePrefix，自我聊天回覆預設為 [{identity.name}] 或 [openclaw]

# 訊息正規化與情境

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

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

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

# 傳送、分段與媒體

# 回覆引用

WhatsApp 支援原生回覆引用，也就是傳出回覆會可見地引用傳入訊息。使用 channels.whatsapp.replyToMode 控制。

預設為 "off"。個別帳號覆寫使用 channels.whatsapp.accounts.<id>.replyToMode。

{
  channels: {
    whatsapp: {
      replyToMode: "first",
    },
  },
}

# 反應等級

channels.whatsapp.reactionLevel 控制 agent 在 WhatsApp 上使用 emoji 反應的廣泛程度：

預設："minimal"。

個別帳號覆寫使用 channels.whatsapp.accounts.<id>.reactionLevel。

{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

# 確認反應

WhatsApp 支援透過 channels.whatsapp.ackReaction 在收到傳入訊息時立即傳送確認反應。 確認反應受 reactionLevel 閘控，當 reactionLevel 為 "off" 時會被抑制。

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

行為注意事項：

• 在傳入訊息被接受後立即傳送（回覆前）
• 失敗會被記錄，但不會封鎖正常回覆傳送
• 群組模式 mentions 會在提及觸發的回合中反應；群組啟用 always 會作為此檢查的略過方式
• WhatsApp 使用 channels.whatsapp.ackReaction（舊版 messages.ackReaction 不在此處使用）

# 多帳號與認證

# 工具、動作與設定寫入

• Agent 工具支援包含 WhatsApp 反應動作（react）。
• 動作閘門：
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• 預設啟用由通道發起的設定寫入（透過 channels.whatsapp.configWrites=false 停用）。

# 疑難排解

openclaw channels login --channel whatsapp
openclaw channels status

{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}

openclaw doctor
openclaw logs --follow

# 系統提示

WhatsApp 透過 groups 和 direct 對應表支援 Telegram 風格的群組與直接聊天系統提示。

群組訊息的解析階層：

有效的 groups 對應表會先被決定：如果帳號定義自己的 groups，它會完整取代根層 groups 對應表（不進行深層合併）。接著提示查找會在產生的單一對應表上執行：

1. 群組專屬系統提示（groups["<groupId>"].systemPrompt）：當對應表中存在特定群組項目，且其 systemPrompt 鍵已定義時使用。如果 systemPrompt 是空字串（""），萬用字元會被抑制，且不會套用任何系統提示。
2. 群組萬用字元系統提示（groups["*"].systemPrompt）：當對應表中完全不存在特定群組項目，或該項目存在但未定義 systemPrompt 鍵時使用。

直接訊息的解析階層：

有效的 direct 對應表會先被決定：如果帳號定義自己的 direct，它會完整取代根層 direct 對應表（不進行深層合併）。接著提示查找會在產生的單一對應表上執行：

1. Direct 專屬系統提示 (direct["<peerId>"].systemPrompt)：當地圖中存在特定對等項目，且其 systemPrompt 鍵已定義時使用。若 systemPrompt 是空字串 ("")，則會抑制萬用字元，且不套用任何系統提示。
2. Direct 萬用字元系統提示 (direct["*"].systemPrompt)：當地圖中完全沒有特定對等項目，或該項目存在但未定義 systemPrompt 鍵時使用。

與 Telegram 多帳號行為的差異： 在 Telegram 中，多帳號設定會刻意對所有帳號抑制根層級 groups，即使某些帳號未定義自己的 groups 也一樣，以防止 bot 接收其不屬於的群組訊息。WhatsApp 不套用這項保護：根層級 groups 與根層級 direct 一律會由未定義帳號層級覆寫的帳號繼承，無論設定了多少帳號。在多帳號 WhatsApp 設定中，若你想要每個帳號各自的群組或 Direct 提示，請在每個帳號下明確定義完整地圖，而不是依賴根層級預設值。

重要行為：

• channels.whatsapp.groups 同時是每個群組的設定地圖，也是聊天層級的群組允許清單。在根層級或帳號範圍中，groups["*"] 代表「該範圍允許所有群組進入」。
• 只有在你已經希望該範圍允許所有群組進入時，才加入萬用字元群組 systemPrompt。如果你仍只希望固定一組群組 ID 符合資格，請不要使用 groups["*"] 作為提示預設值。請改為在每個明確列入允許清單的群組項目上重複該提示。
• 群組進入與傳送者授權是分開的檢查。groups["*"] 會擴大可進入群組處理流程的群組集合，但它本身不會授權這些群組中的每個傳送者。傳送者存取仍由 channels.whatsapp.groupPolicy 與 channels.whatsapp.groupAllowFrom 分別控制。
• channels.whatsapp.direct 對 DM 沒有相同的副作用。direct["*"] 只會在 DM 已由 dmPolicy 加上 allowFrom 或配對儲存規則允許之後，提供預設的 Direct 聊天設定。

範例：

{
  channels: {
    whatsapp: {
      groups: {
        // Use only if all groups should be admitted at the root scope.
        // Applies to all accounts that do not define their own groups map.
        "*": { systemPrompt: "Default prompt for all groups." },
      },
      direct: {
        // Applies to all accounts that do not define their own direct map.
        "*": { systemPrompt: "Default prompt for all direct chats." },
      },
      accounts: {
        work: {
          groups: {
            // This account defines its own groups, so root groups are fully
            // replaced. To keep a wildcard, define "*" explicitly here too.
            "[email protected]": {
              requireMention: false,
              systemPrompt: "Focus on project management.",
            },
            // Use only if all groups should be admitted in this account.
            "*": { systemPrompt: "Default prompt for work groups." },
          },
          direct: {
            // This account defines its own direct map, so root direct entries are
            // fully replaced. To keep a wildcard, define "*" explicitly here too.
            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },
            "*": { systemPrompt: "Default prompt for work direct chats." },
          },
        },
      },
    },
  },
}

# 設定參考指標

主要參考：

• 設定參考 - WhatsApp

高訊號 WhatsApp 欄位：

• 存取：dmPolicy、allowFrom、groupPolicy、groupAllowFrom、groups
• 傳遞：textChunkLimit、chunkMode、mediaMaxMb、sendReadReceipts、ackReaction、reactionLevel
• 多帳號：accounts.<id>.enabled、accounts.<id>.authDir、帳號層級覆寫
• 操作：configWrites、debounceMs、web.enabled、web.heartbeatSeconds、web.reconnect.*、web.whatsapp.*
• 工作階段行為：session.dmScope、historyLimit、dmHistoryLimit、dms.<id>.historyLimit
• 提示：groups.<id>.systemPrompt、groups["*"].systemPrompt、direct.<id>.systemPrompt、direct["*"].systemPrompt

# 相關

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