Skip to main content

​
WhatsApp（Web 渠道）

状态：通过 WhatsApp Web（Baileys）实用的生产环境准备就绪。网关拥有关联会话。

配对

默认的私信策略是对未知发送者进行配对。

渠道故障排查

跨渠道诊断和修复操作手册。

网关配置

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

​
快速设置

1

配置 WhatsApp 访问策略

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

关联 WhatsApp（二维码）

openclaw channels login --channel whatsapp
针对特定账户：
openclaw channels login --channel whatsapp --account work
3

启动网关

openclaw gateway
4

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

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
配对请求在 1 小时后过期。每个渠道最多同时待处理请求为 3 个。
OpenClaw 推荐在可能的情况下使用独立号码运行 WhatsApp。（渠道元数据和引导流程针对该设置进行了优化，但也支持个人号码设置。）

​
部署模式

这是最清晰的运营模式：
  • 为 OpenClaw 提供独立的 WhatsApp 身份
  • 更清晰的私信允许列表和路由边界
  • 降低自聊混淆的可能性
最简政策模式：
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}
引导支持个人号码模式，并写入适合自聊的基线：
  • dmPolicy: "allowlist"
  • allowFrom 包含您的个人号码
  • selfChatMode: true
运行时，自聊保护基于关联的自号码和 allowFrom。
当前 OpenClaw 渠道架构中，消息平台渠道基于 WhatsApp Web（Baileys）。内置聊天渠道注册表中没有独立的 Twilio WhatsApp 消息渠道。

​
运行时模型

  • 网关拥有 WhatsApp 套接字和重连循环。
  • 出站发送要求目标账户存在活跃的 WhatsApp 监听器。
  • 状态和广播聊天被忽略（@status，@broadcast）。
  • 直接聊天使用私信会话规则（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 自聊保护措施：
  • 自聊轮次跳过已读回执
  • 忽略会触发自己提醒的提及 JID 自动触发行为
  • 如果未设置 messages.responsePrefix，自聊回复默认为 [{identity.name}] 或 [openclaw]

​
消息规范化与上下文

收到的 WhatsApp 消息被包装在共享的入站信封中。如果存在引用回复，附加上下文形式为：
[回复给 <sender> id:<stanzaId>]
<引用正文或媒体占位符>
[/回复结束]
支持填充回复元数据字段（ReplyToId、ReplyToBody、ReplyToSender、发送者 JID/E.164）当可用时。
仅媒体入站消息规范为占位符，如：
  • <media:image>
  • <media:video>
  • <media:audio>
  • <media:document>
  • <media:sticker>
位置和联系人负载在路由前被规范为文本上下文。
对于群组，未处理的消息可缓冲并在机器人最终被触发时注入为上下文。
  • 默认限制：50
  • 配置：channels.whatsapp.historyLimit
  • 后备：messages.groupChat.historyLimit
  • 设置为 0 禁用
注入标记：
  • [从您上次回复以来的聊天消息 - 用于上下文]
  • [当前消息 - 回复此内容]
默认为接受的入站 WhatsApp 消息启用已读回执。全局禁用：
{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}
按账户覆盖：
{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}
自聊轮次即使全局启用也跳过已读回执。

​
投递、分块和媒体

  • 默认分块限制：channels.whatsapp.textChunkLimit = 4000
  • channels.whatsapp.chunkMode = "length" | "newline"
  • newline 模式优先段落边界（空行），然后回退为长度安全分块
  • 支持图片、视频、音频（PTT 语音便签）和文档负载
  • audio/ogg 会重写为 audio/ogg; codecs=opus 以兼容语音便签
  • 支持通过在视频发送时设置 gifPlayback: true 播放动画 GIF
  • 多媒体回复负载时，字幕应用于第一个媒体项
  • 媒体来源可为 HTTP(S)、file:// 或本地路径
  • 入站媒体保存上限：channels.whatsapp.mediaMaxMb（默认 50）
  • 出站自动回复媒体上限：agents.defaults.mediaMaxMb（默认 5MB）
  • 图像会自动优化（调整大小/质量）以适应限制
  • 媒体发送失败时，首项回退发送文字警告，而非静默丢弃响应

​
回复确认表情

WhatsApp 支持通过 channels.whatsapp.ackReaction 在入站接收后即时发送确认表情。 
{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}
行为说明：
  • 在入站消息接受后立即发送（回复前）
  • 失败时记录日志，但不阻止正常回复发送
  • 群组模式 mentions 在提及触发时反应；群组激活 always 作为该检查的绕过
  • WhatsApp 使用 channels.whatsapp.ackReaction（这里不使用旧版的 messages.ackReaction）

​
多账户与凭证

  • 账户 ID 来源于 channels.whatsapp.accounts
  • 默认账户选择：如果存在 default，选择该账户，否则选择第一个配置的账户 ID（排序）
  • 账户 ID 内部标准化以便查找
  • 当前认证路径：~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • 备份文件：creds.json.bak
  • 旧版默认认证路径 ~/.openclaw/credentials/ 仍被识别/迁移以支持默认账户流程
运行 openclaw channels logout --channel whatsapp [--account <id>] 清除该账户的 WhatsApp 认证状态。旧版认证目录中 oauth.json 会被保留，Baileys 认证文件被删除。

​
工具、动作和配置写入

  • 代理工具支持 WhatsApp 回复动作（react）。
  • 动作门控：
    • channels.whatsapp.actions.reactions
    • channels.whatsapp.actions.polls
  • 渠道发起的配置写入默认启用（通过设置 channels.whatsapp.configWrites=false 可禁用）。

​
故障排除

症状：渠道状态报告未关联。解决：
openclaw channels login --channel whatsapp
openclaw channels status
症状：已关联账户反复断开或尝试重连。解决：
openclaw doctor
openclaw logs --follow
如有需要，使用 channels login 重新关联。
出站发送在目标账户无活动网关监听时快速失败。确认网关已运行且账户已关联。
请按此顺序检查：
  • groupPolicy
  • groupAllowFrom / allowFrom
  • groups 允许列表条目
  • 提及门控（requireMention + 提及模式）
  • openclaw.json 中重复键（JSON5）：后面条目覆盖前面，确保每个作用域中只有一个 groupPolicy
WhatsApp 网关运行时应使用 Node。Bun 被标记为不兼容，不能稳定运行 WhatsApp/Telegram 网关。

​
配置参考指针

主要参考： 高频 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

​
相关