WhatsApp

Documentation Index

Fetch the complete documentation index at: https://docs.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 也會提供安裝流程。
• 開發通道 + git checkout：預設使用本機 Plugin 路徑。
• Stable/Beta：當目前套件已發布時，使用 npm 套件 @openclaw/whatsapp。

openclaw plugins install @openclaw/whatsapp

​

快速設定

{
  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 listener。
• 狀態與廣播聊天會被忽略（@status、@broadcast）。
• 重新連線 watchdog 追蹤 WhatsApp Web 傳輸活動，而不只是傳入應用程式訊息量：安靜的已連結裝置工作階段會在傳輸 frame 持續時保持連線，但傳輸停滯會在較晚的遠端斷線路徑之前就強制重新連線。
• 直接聊天使用 DM 工作階段規則（session.dmScope；預設 main 會將 DM 收合至代理程式主工作階段）。
• 群組工作階段是隔離的（agent:<agentId>:whatsapp:group:<jid>）。
• WhatsApp Web 傳輸會遵循 gateway 主機上的標準 proxy 環境變數（HTTPS_PROXY、HTTP_PROXY、NO_PROXY / 小寫變體）。請優先使用主機層級 proxy 設定，而非通道特定的 WhatsApp proxy 設定。
• 啟用 messages.removeAckAfterReply 時，OpenClaw 會在可見回覆送達後清除 WhatsApp ack reaction。

​

Plugin hook 與隱私

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

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

​

存取控制與啟用

​

個人號碼與自我聊天行為

• 跳過自我聊天回合的讀取回條
• 忽略 mention-JID 自動觸發行為，否則它會 ping 你自己
• 如果未設定 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",
    },
  },
}

​

確認 reactions

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

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

​

多帳號與憑證

​

工具、動作與設定寫入

• Agent 工具支援包含 WhatsApp reaction 動作（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

​

系統 prompts

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

1. 直接對象專屬系統 prompt（direct["<peerId>"].systemPrompt）：當特定對象項目存在於 map 中，且其 systemPrompt 鍵已定義時使用。如果 systemPrompt 是空字串（""），wildcard 會被抑制，且不套用任何系統 prompt。
2. 直接對象 wildcard 系統 prompt（direct["*"].systemPrompt）：當特定對象項目完全不存在於 map 中，或項目存在但未定義 systemPrompt 鍵時使用。

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

{
  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

​

相關

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