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.

​

安装（按需）

• 新手引导（openclaw onboard）和 openclaw channels add --channel whatsapp 会在你第一次选择 WhatsApp 插件时提示安装它。
• 当插件尚未存在时，openclaw channels login --channel whatsapp 也会提供安装流程。
• Dev 渠道 + git checkout：默认使用本地插件路径。
• Stable/Beta：在当前官方发布标签上使用 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 和重连循环。
• 重连看门狗使用 WhatsApp Web 传输活动，而不只是入站应用消息量，因此安静的已关联设备会话不会仅仅因为最近没人发送消息而被重启。如果传输帧持续到达，但在看门狗窗口内没有处理任何应用消息，更长的应用静默上限仍会强制重连；对于最近活跃会话的临时重连，在第一个恢复窗口内，该应用静默检查会使用正常消息超时。
• Baileys socket 时序在 web.whatsapp.* 下显式配置：keepAliveIntervalMs 控制 WhatsApp Web 应用 ping，connectTimeoutMs 控制打开握手超时，defaultQueryTimeoutMs 控制 Baileys 查询超时。
• 出站发送要求目标账号有活跃的 WhatsApp 监听器。
• 当文本和媒体标题中的 @+<digits> 与 @<digits> 令牌匹配当前 WhatsApp 参与者元数据（包括 LID 支持的群组）时，群组发送会附加原生 mention 元数据。
• Status 和广播聊天会被忽略（@status、@broadcast）。
• 重连看门狗遵循 WhatsApp Web 传输活动，而不只是入站应用消息量：只要传输帧持续，安静的已关联设备会话就会保持在线，但传输停滞会在后续远端断开路径之前强制重连。
• 直接聊天使用私信会话规则（session.dmScope；默认 main 会将私信折叠到智能体主会话）。
• 群组会话相互隔离（agent:<agentId>:whatsapp:group:<jid>）。
• WhatsApp Channels/Newsletters 可以用其原生 @newsletter JID 作为显式出站目标。出站 newsletter 发送使用渠道会话元数据（agent:<agentId>:whatsapp:channel:<jid>），而不是私信会话语义。
• WhatsApp Web 传输会遵循 Gateway 网关主机上的标准代理环境变量（HTTPS_PROXY、HTTP_PROXY、NO_PROXY / 小写变体）。优先使用主机级代理配置，而不是 WhatsApp 渠道专用代理设置。
• 启用 messages.removeAckAfterReply 时，OpenClaw 会在可见回复送达后清除 WhatsApp ack 反应。

​

插件钩子和隐私

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

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

​

访问控制和激活

​

个人号码和自聊行为

• 跳过自聊轮次的已读回执
• 忽略否则会 ping 你自己的 mention-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）

​

多账号和凭证

​

工具、操作和配置写入

• 智能体工具支持包括 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 对私信没有相同的副作用。direct["*"] 只会在私信已通过 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

​

相关内容

• 配对
• 群组
• 安全性
• 渠道路由
• 多智能体路由
• 故障排除