WhatsApp（Web 渠道）

状态：通过 WhatsApp Web (Baileys) 生产就绪。网关拥有链接的会话。

配对

未知发送者的默认 DM 策略是配对。

渠道故障排除

跨渠道诊断和修复手册。

网关配置

完整的渠道配置模式和示例。

快速设置

配置 WhatsApp 访问策略

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

链接 WhatsApp (QR)

openclaw channels login --channel whatsapp

对于特定账户：

openclaw channels login --channel whatsapp --account work

启动网关

openclaw gateway

批准首个配对请求（如果使用配对模式）

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

配对请求在 1 小时后过期。每个渠道的待处理请求上限为 3 个。

OpenClaw 建议在可能的情况下为 WhatsApp 使用独立的号码。（渠道元数据和入职流程针对该设置进行了优化，但也支持个人号码设置。）

部署模式

运行时模型

网关拥有 WhatsApp 套接字和重连循环。
出站发送需要目标账户的活动 WhatsApp 监听器。
状态和广播聊天被忽略（@status、@broadcast）。
直接聊天使用 DM 会话规则（session.dmScope；默认 main 将 DM 折叠到代理主会话）。
群组会话是隔离的（agent:<agentId>:whatsapp:group:<jid>）。

访问控制和激活

channels.whatsapp.dmPolicy 控制直接聊天访问：

pairing（默认）
allowlist
open（需要 allowFrom 包含 "*"）
disabled

allowFrom 接受 E.164 风格的号码（内部规范化）。

多账户覆盖：channels.whatsapp.accounts.<id>.dmPolicy（和 allowFrom）优先于该账户的渠道级默认值。

运行时行为详情：

配对持久化在渠道允许存储中并与配置的 allowFrom 合并
如果未配置允许列表，默认允许链接的自我号码
出站 fromMe DM 永远不会自动配对

个人号码和自我聊天行为

当链接的自我号码也存在于 allowFrom 中时，WhatsApp 自我聊天保护会激活：

跳过自我聊天回合的已读回执
忽略否则会 ping 您自己的提及-JID 自动触发行为
如果未设置 messages.responsePrefix，自我聊天回复默认为 [{identity.name}] 或 [openclaw]

消息标准化和上下文

发送、分块和媒体

确认反应

WhatsApp 支持通过 channels.whatsapp.ackReaction 在入站接收时立即确认反应。

{
  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 禁用）。

故障排除

配置参考指针

主要参考：

配置参考 - WhatsApp

高信号 WhatsApp 字段：

访问：dmPolicy、allowFrom、groupPolicy、groupAllowFrom、groups
发送：textChunkLimit、chunkMode、mediaMaxMb、sendReadReceipts、ackReaction
多账户：accounts.<id>.enabled、accounts.<id>.authDir、账户级覆盖
运维：configWrites、debounceMs、web.enabled、web.heartbeatSeconds、web.reconnect.*
会话行为：session.dmScope、historyLimit、dmHistoryLimit、dms.<id>.historyLimit

WhatsApp