消息平台

WhatsApp

状态：通过 WhatsApp Web（Baileys）达到生产就绪。网关管理已链接的会话。

配对

默认私聊策略：对未知发送者启用配对模式。

频道故障排除

跨频道诊断与修复指南。

网关配置

完整的频道配置模式与示例。

快速设置

本节带你完成 WhatsApp 频道的基础配置，四步即可启动运行。

步骤 1：配置 WhatsApp 访问策略

首先在配置文件中设置谁可以与你的智能体通信：

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

步骤 2：链接 WhatsApp（扫码）

运行以下命令，终端会显示二维码，用 WhatsApp 扫码即可链接：

openclaw channels login --channel whatsapp

如果有多个账户，指定账户名称：

openclaw channels login --channel whatsapp --account work

步骤 3：启动网关

openclaw gateway

步骤 4：批准首次配对请求（使用配对模式时）

如果你配置了 dmPolicy: "pairing"，首次有人给你发消息时会生成配对请求，需要手动批准：

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

配对请求 1 小时后过期。每个频道的待处理请求最多保留 3 个。

ℹ️ OpenClaw 建议尽可能使用独立的手机号码运行 WhatsApp。虽然频道元数据和入门流程已针对这种场景优化，但使用个人号码同样受支持。

部署模式

运行时模型

了解 WhatsApp 频道在运行时的行为特点：

  • 网关管理 WhatsApp 套接字连接和自动重连
  • 发送消息需要目标账户有活跃的 WhatsApp 监听器
  • 状态广播和官方广播会被忽略（@status、@broadcast）
  • 私聊使用 DM 会话规则（session.dmScope；默认 main 会把私聊合并到智能体主会话）
  • 群聊会话相互隔离（格式：agent:<agentId>:whatsapp:group:<jid>）

访问控制与激活

channels.whatsapp.dmPolicy 控制谁能发起私聊：

  • pairing（默认）：首次发消息需要配对批准
  • allowlist：仅白名单用户可发消息
  • open：所有人可发消息（需配置 allowFrom: ["*"]）
  • disabled：禁用私聊

allowFrom 接受 E.164 格式的电话号码（系统会自动规范化）。

多账户覆盖：channels.whatsapp.accounts.<id>.dmPolicy 和 allowFrom 会覆盖该账户的频道级默认值。

运行时行为细节：

  • 配对记录持久化到频道允许存储中，与配置的 allowFrom 合并生效
  • 如果没有配置白名单，默认允许已链接的本机号码
  • 自己发出的 fromMe 私聊消息不会自动配对

个人号码与自聊行为

当已链接的本机号码也在 allowFrom 中时，WhatsApp 自聊保护机制会自动激活：

  • 跳过自聊消息的已读回执
  • 忽略会 ping 到自己的提及 JID 自动触发行为
  • 如果未设置 messages.responsePrefix，自聊回复默认添加 [{identity.name}] 或 [openclaw] 前缀

消息规范化与上下文

消息送达、分块与媒体

确认表情反应

WhatsApp 支持在收到消息时立即回复一个表情作为确认：

{
  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 配置字段：

  • 访问控制：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

相关链接

TwitchZalo