WhatsApp

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

安裝（按需）

• 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

winget install --id Git.Git -e

​

快速設定

{
  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 與隱私

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

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

​

存取控制與啟用

​

個人號碼與自我聊天行為

• 略過自我聊天回合的讀取回條
• 忽略原本會 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,
        },
      },
    },
  },
}

​

傳送、分段與媒體

​

回覆引用

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

​

反應等級

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

​

確認反應

{
  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

​

系統提示

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

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

• 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.
            "120363406415684625@g.us": {
              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

• 存取：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

​

相關

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