WhatsApp (web channel)

状态：仅支持通过 Baileys 使用 WhatsApp Web。Gateway 管理 Session。

快速设置（新手向）

  1. 如果可以的话，用一个独立的手机号（推荐）。
  2. 在 ~/.openclaw/openclaw.json 中配置 WhatsApp。
  3. 运行 openclaw channels login 扫描二维码（关联设备）。
  4. 启动 Gateway。

最简配置：

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

设计目标

  • 在一个 Gateway 进程中支持多个 WhatsApp 账号（多账号）。
  • 确定性路由：回复返回到 WhatsApp，不经过模型路由。
  • 模型能看到足够的上下文来理解引用回复。

配置写入

默认情况下，WhatsApp 可以通过 /config set|unset 触发配置更新（需要 commands.config: true）。

禁用方法：

{
  channels: { whatsapp: { configWrites: false } },
}

架构（谁管理什么）

  • Gateway 管理 Baileys socket 和收件箱循环。
  • CLI / macOS 应用与 Gateway 通信；不直接使用 Baileys。
  • 活跃监听器是发送消息的必要条件；否则发送会快速失败。

获取手机号（两种模式）

WhatsApp 需要真实的手机号进行验证。VoIP 和虚拟号码通常会被屏蔽。有两种支持的方式在 WhatsApp 上运行 OpenClaw：

独立号码（推荐）

为 OpenClaw 使用一个独立的手机号。体验最好，路由清晰，没有自聊模式的怪异行为。理想设置：闲置/旧的 Android 手机 + eSIM。让它保持连接 Wi‑Fi 和电源，然后通过二维码关联。

**WhatsApp Business：**你可以在同一设备上用不同号码使用 WhatsApp Business。这样可以很好地将个人 WhatsApp 分开——安装 WhatsApp Business 并在那里注册 OpenClaw 号码。

配置示例（独立号码，单用户白名单）：

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

Pairing 模式（可选）： 如果你想用 Pairing 而不是白名单，把 channels.whatsapp.dmPolicy 设为 pairing。未知发送者会收到配对码；批准方法： openclaw pairing approve whatsapp <code>

个人号码（备用方案）

快速备用方案：在你自己的号码上运行 OpenClaw。给自己发消息（WhatsApp 的”给自己发消息”功能）来测试，这样不会打扰联系人。在设置和实验期间，你需要在主手机上读取验证码。必须启用自聊模式。 当向导询问你的个人 WhatsApp 号码时，输入你将用来发消息的手机号（所有者/发送者），而不是助手号码。

配置示例（个人号码，自聊）：

{
  "whatsapp": {
    "selfChatMode": true,
    "dmPolicy": "allowlist",
    "allowFrom": ["+15551234567"]
  }
}

自聊回复默认使用 [{identity.name}]（如果设置了的话，否则用 [openclaw]），前提是 messages.responsePrefix 未设置。你可以显式设置它来自定义或禁用前缀（用 "" 来移除）。

号码获取建议

  • 本地 eSIM，从你所在国家的运营商获取（最可靠）
  • 预付费 SIM 卡 — 便宜，只需要接收一条验证短信

**避免使用：**TextNow、Google Voice、大多数”免费短信”服务 — WhatsApp 会积极屏蔽这些。

**提示：**号码只需要接收一条验证短信。之后，WhatsApp Web Session 会通过 creds.json 持久化。

为什么不用 Twilio？

  • 早期的 OpenClaw 版本支持 Twilio 的 WhatsApp Business 集成。
  • WhatsApp Business 号码不适合作为个人助手。
  • Meta 强制执行 24 小时回复窗口；如果你在过去 24 小时内没有回复，商业号码就无法发起新消息。
  • 大量或”健谈”的使用会触发激进的屏蔽，因为商业账号不是用来发送几十条个人助手消息的。
  • 结果：交付不可靠且经常被屏蔽，所以移除了支持。

登录 + 凭证

  • 登录命令：openclaw channels login（通过关联设备扫描二维码）。
  • 多账号登录：openclaw channels login --account <id>（<id> = accountId）。
  • 默认账号（省略 --account 时）：如果存在 default 则使用它，否则使用第一个配置的账号 id（排序后）。
  • 凭证存储在 ~/.openclaw/credentials/whatsapp/<accountId>/creds.json。
  • 备份副本在 creds.json.bak（损坏时恢复）。
  • 旧版兼容性：旧安装将 Baileys 文件直接存储在 ~/.openclaw/credentials/。
  • 登出：openclaw channels logout（或 --account <id>）删除 WhatsApp 认证状态（但保留共享的 oauth.json）。
  • 登出的 socket => 错误提示重新关联。

入站流程（DM + 群组）

  • WhatsApp 事件来自 messages.upsert（Baileys）。
  • 收件箱监听器在关闭时分离，以避免在测试/重启中累积事件处理器。
  • 状态/广播聊天会被忽略。
  • 直接聊天使用 E.164；群组使用群组 JID。
  • DM 策略：channels.whatsapp.dmPolicy 控制直接聊天访问（默认：pairing）。
    • Pairing：未知发送者收到配对码（通过 openclaw pairing approve whatsapp <code> 批准；码在 1 小时后过期）。
    • Open：需要 channels.whatsapp.allowFrom 包含 "*"。
    • 你关联的 WhatsApp 号码是隐式信任的，所以自己的消息会跳过 channels.whatsapp.dmPolicy 和 channels.whatsapp.allowFrom 检查。

个人号码模式（备用方案）

如果你在个人 WhatsApp 号码上运行 OpenClaw，启用 channels.whatsapp.selfChatMode（见上面的示例）。

行为：

  • 出站 DM 永远不会触发配对回复（防止骚扰联系人）。
  • 入站未知发送者仍然遵循 channels.whatsapp.dmPolicy。
  • 自聊模式（allowFrom 包含你的号码）避免自动已读回执并忽略提及 JID。
  • 为非自聊 DM 发送已读回执。

已读回执

默认情况下，Gateway 会在接受入站 WhatsApp 消息后将其标记为已读（蓝色勾号）。

全局禁用：

{
  channels: { whatsapp: { sendReadReceipts: false } },
}

按账号禁用：

{
  channels: {
    whatsapp: {
      accounts: {
        personal: { sendReadReceipts: false },
      },
    },
  },
}

注意：

  • 自聊模式总是跳过已读回执。

WhatsApp 常见问题：发送消息 + Pairing

关联 WhatsApp 后，OpenClaw 会给随机联系人发消息吗？ 不会。默认 DM 策略是 pairing，所以未知发送者只会收到配对码，他们的消息不会被处理。OpenClaw 只回复它收到的聊天，或者你显式触发的发送（Agent/CLI）。

WhatsApp 上的 Pairing 是怎么工作的？ Pairing 是未知发送者的 DM 门禁：

  • 来自新发送者的第一条 DM 返回一个短码（消息不会被处理）。
  • 批准方法：openclaw pairing approve whatsapp <code>（用 openclaw pairing list whatsapp 列出）。
  • 码在 1 小时后过期；待处理请求每个 Channel 最多 3 个。

多个人可以在一个 WhatsApp 号码上使用不同的 OpenClaw 实例吗？ 可以，通过 bindings 将每个发送者路由到不同的 Agent（peer kind: "dm"，发送者 E.164 如 +15551234567）。回复仍然来自同一个 WhatsApp 账号，直接聊天会合并到每个 Agent 的主 Session，所以每人使用一个 Agent。DM 访问控制（dmPolicy/allowFrom）对每个 WhatsApp 账号是全局的。参见 Multi-Agent Routing。

为什么向导会询问我的手机号？ 向导用它来设置你的白名单/所有者，这样你自己的 DM 就被允许了。它不用于自动发送。如果你在个人 WhatsApp 号码上运行，使用同一个号码并启用 channels.whatsapp.selfChatMode。

消息规范化（模型看到的内容）

  • Body 是当前消息正文及其信封。
  • 引用回复上下文总是被追加： 
    [Replying to +1555 id:ABC123]
<quoted text or <media:...>>
[/Replying]
  • 回复元数据也会设置：
    • ReplyToId = stanzaId
    • ReplyToBody = 引用正文或媒体占位符
    • ReplyToSender = E.164（如果已知）
  • 纯媒体入站消息使用占位符：
    • <media:image|video|audio|document|sticker>

群组

  • 群组映射到 agent:<agentId>:whatsapp:group:<jid> Session。
  • 群组策略：channels.whatsapp.groupPolicy = open|disabled|allowlist（默认 allowlist）。
  • 激活模式：
    • mention（默认）：需要 @提及 或正则匹配。
    • always：总是触发。
  • /activation mention|always 仅限所有者使用，必须作为独立消息发送。
  • 所有者 = channels.whatsapp.allowFrom（如果未设置则为自己的 E.164）。
  • 历史注入（仅待处理）：
    • 最近的_未处理_消息（默认 50 条）插入在： [Chat messages since your last reply - for context]（Session 中已有的消息不会重新注入）
    • 当前消息在： [Current message - respond to this]
    • 发送者后缀追加：[from: Name (+E164)]
  • 群组元数据缓存 5 分钟（主题 + 参与者）。

回复交付（线程）

  • WhatsApp Web 发送标准消息（当前 Gateway 中没有引用回复线程）。
  • 回复标签在此 Channel 上被忽略。

确认反应（收到时自动反应）

WhatsApp 可以在收到消息后立即自动发送表情反应，在机器人生成回复之前。这为用户提供即时反馈，表明他们的消息已被接收。

配置：

{
  "whatsapp": {
    "ackReaction": {
      "emoji": "👀",
      "direct": true,
      "group": "mentions"
    }
  }
}

选项：

  • emoji（字符串）：用于确认的表情（例如 ”👀”、”✅”、”📨”）。空或省略 = 功能禁用。
  • direct（布尔值，默认：true）：在直接/DM 聊天中发送反应。
  • group（字符串，默认："mentions"）：群组聊天行为：
    • "always"：对所有群组消息反应（即使没有 @提及）
    • "mentions"：仅在机器人被 @提及时反应
    • "never"：从不在群组中反应

按账号覆盖：

{
  "whatsapp": {
    "accounts": {
      "work": {
        "ackReaction": {
          "emoji": "✅",
          "direct": false,
          "group": "always"
        }
      }
    }
  }
}

行为说明：

  • 反应在消息收到后立即发送，在输入指示器或机器人回复之前。
  • 在 requireMention: false（激活：always）的群组中，group: "mentions" 会对所有消息反应（不仅仅是 @提及）。
  • 发送即忘：反应失败会被记录，但不会阻止机器人回复。
  • 群组反应会自动包含参与者 JID。
  • WhatsApp 忽略 messages.ackReaction；请使用 channels.whatsapp.ackReaction。

Agent 工具（反应）

  • 工具：whatsapp，react 动作（chatJid、messageId、emoji，可选 remove）。
  • 可选：participant（群组发送者）、fromMe（对你自己的消息反应）、accountId（多账号）。
  • 反应移除语义：参见 /tools/reactions。
  • 工具门控：channels.whatsapp.actions.reactions（默认：启用）。

限制

  • 出站文本被分块到 channels.whatsapp.textChunkLimit（默认 4000）。
  • 可选换行分块：设置 channels.whatsapp.chunkMode="newline" 在长度分块之前按空行（段落边界）拆分。
  • 入站媒体保存上限为 channels.whatsapp.mediaMaxMb（默认 50 MB）。
  • 出站媒体项上限为 agents.defaults.mediaMaxMb（默认 5 MB）。

出站发送（文本 + 媒体）

  • 使用活跃的 web 监听器；如果 Gateway 未运行则报错。
  • 文本分块：每条消息最多 4k（可通过 channels.whatsapp.textChunkLimit 配置，可选 channels.whatsapp.chunkMode）。
  • 媒体：
    • 支持图片/视频/音频/文档。
    • 音频作为 PTT 发送；audio/ogg => audio/ogg; codecs=opus。
    • 标题仅在第一个媒体项上。
    • 媒体获取支持 HTTP(S) 和本地路径。
    • 动画 GIF：WhatsApp 期望 MP4 带 gifPlayback: true 以实现内联循环。
      • CLI：openclaw message send --media <mp4> --gif-playback
      • Gateway：send 参数包含 gifPlayback: true

语音笔记（PTT 音频）

WhatsApp 将音频作为语音笔记（PTT 气泡）发送。

  • 最佳效果：OGG/Opus。OpenClaw 将 audio/ogg 重写为 audio/ogg; codecs=opus。
  • [[audio_as_voice]] 对 WhatsApp 被忽略（音频已经作为语音笔记发送）。

媒体限制 + 优化

  • 默认出站上限：5 MB（每个媒体项）。
  • 覆盖：agents.defaults.mediaMaxMb。
  • 图片自动优化为 JPEG 以保持在上限内（调整大小 + 质量扫描）。
  • 超大媒体 => 错误；媒体回复回退到文本警告。

Heartbeat

  • Gateway Heartbeat 记录连接健康状况（web.heartbeatSeconds，默认 60 秒）。
  • Agent Heartbeat 可以按 Agent 配置（agents.list[].heartbeat）或全局配置 通过 agents.defaults.heartbeat（当没有设置按 Agent 条目时的回退）。
    • 使用配置的 Heartbeat Prompt（默认：Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.）+ HEARTBEAT_OK 跳过行为。
    • 交付默认到最后使用的 Channel（或配置的目标）。

重连行为

  • 退避策略：web.reconnect：
    • initialMs、maxMs、factor、jitter、maxAttempts。
  • 如果达到 maxAttempts，web 监控停止（降级）。
  • 登出 => 停止并要求重新关联。

配置快速映射

  • channels.whatsapp.dmPolicy（DM 策略：pairing/allowlist/open/disabled）。
  • channels.whatsapp.selfChatMode（同号设置；机器人使用你的个人 WhatsApp 号码）。
  • channels.whatsapp.allowFrom（DM 白名单）。WhatsApp 使用 E.164 电话号码（无用户名）。
  • channels.whatsapp.mediaMaxMb（入站媒体保存上限）。
  • channels.whatsapp.ackReaction（消息收到时自动反应：{emoji, direct, group}）。
  • channels.whatsapp.accounts.<accountId>.*（按账号设置 + 可选 authDir）。
  • channels.whatsapp.accounts.<accountId>.mediaMaxMb（按账号入站媒体上限）。
  • channels.whatsapp.accounts.<accountId>.ackReaction（按账号确认反应覆盖）。
  • channels.whatsapp.groupAllowFrom（群组发送者白名单）。
  • channels.whatsapp.groupPolicy（群组策略）。
  • channels.whatsapp.historyLimit / channels.whatsapp.accounts.<accountId>.historyLimit（群组历史上下文；0 禁用）。
  • channels.whatsapp.dmHistoryLimit（DM 历史限制，以用户轮次计）。按用户覆盖：channels.whatsapp.dms["<phone>"].historyLimit。
  • channels.whatsapp.groups（群组白名单 + 提及门控默认值；使用 "*" 允许所有）
  • channels.whatsapp.actions.reactions（门控 WhatsApp 工具反应）。
  • agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）
  • messages.groupChat.historyLimit
  • channels.whatsapp.messagePrefix（入站前缀；按账号：channels.whatsapp.accounts.<accountId>.messagePrefix；已弃用：messages.messagePrefix）
  • messages.responsePrefix（出站前缀）
  • agents.defaults.mediaMaxMb
  • agents.defaults.heartbeat.every
  • agents.defaults.heartbeat.model（可选覆盖）
  • agents.defaults.heartbeat.target
  • agents.defaults.heartbeat.to
  • agents.defaults.heartbeat.session
  • agents.list[].heartbeat.*（按 Agent 覆盖）
  • session.*（scope、idle、store、mainKey）
  • web.enabled（为 false 时禁用 Channel 启动）
  • web.heartbeatSeconds
  • web.reconnect.*

日志 + 故障排除

  • 子系统：whatsapp/inbound、whatsapp/outbound、web-heartbeat、web-reconnect。
  • 日志文件：/tmp/openclaw/openclaw-YYYY-MM-DD.log（可配置）。
  • 故障排除指南：Gateway troubleshooting。

故障排除（快速）

未关联 / 需要二维码登录

  • 症状：channels status 显示 linked: false 或警告 “Not linked”。
  • 修复：在 Gateway 主机上运行 openclaw channels login 并扫描二维码（WhatsApp → 设置 → 关联的设备）。

已关联但断开连接 / 重连循环

  • 症状：channels status 显示 running, disconnected 或警告 “Linked but disconnected”。
  • 修复：openclaw doctor（或重启 Gateway）。如果持续存在，通过 channels login 重新关联并检查 openclaw logs --follow。

Bun Runtime

  • 不推荐 Bun。WhatsApp（Baileys）和 Telegram 在 Bun 上不可靠。 用 Node 运行 Gateway。（参见入门 Runtime 说明。）