WhatsApp(Web 渠道)

状态:仅支持通过 Baileys 的 WhatsApp Web。网关拥有会话。

快速设置(初学者)

如果可能,使用独立的电话号码(推荐)。
在 ~/.openclaw/openclaw.json 中配置 WhatsApp。
运行 openclaw channels login 扫描二维码(关联设备)。
启动网关。

最小配置:

json5

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

目标

一个网关进程中支持多个 WhatsApp 账户(多账户)。
确定性路由:回复返回到 WhatsApp,无模型路由。
模型能看到足够的上下文来理解引用回复。

配置写入

默认情况下,WhatsApp 允许写入由 /config set|unset 触发的配置更新(需要 commands.config: true)。

禁用方式:

json5

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

架构(谁拥有什么)

网关拥有 Baileys socket 和收件箱循环。
CLI / macOS 应用与网关通信;不直接使用 Baileys。
活动监听器是出站发送所必需的;否则发送会快速失败。

获取电话号码(两种模式)

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

专用号码(推荐)

为 OpenClaw 使用独立的电话号码。最佳用户体验,清晰的路由,没有自聊怪异行为。理想设置:备用/旧 Android 手机 + eSIM。让它保持 Wi‑Fi 和电源连接,并通过二维码关联。

WhatsApp Business: 您可以在同一设备上使用不同号码的 WhatsApp Business。非常适合将您的个人 WhatsApp 分开 — 安装 WhatsApp Business 并在那里注册 OpenClaw 号码。

示例配置(专用号码,单用户白名单):

json5

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

配对模式(可选): 如果您想要配对而不是白名单,将 channels.whatsapp.dmPolicy 设置为 pairing。未知发送者会获得配对码;批准方式: openclaw pairing approve whatsapp <code>

个人号码(备选)

快速备选:在您自己的号码上运行 OpenClaw。给自己发消息(WhatsApp "给自己发消息")进行测试,这样不会打扰联系人。在设置和实验期间,预期在主手机上读取验证码。必须启用自聊模式。 当向导询问您的个人 WhatsApp 号码时,输入您将从其发送消息的手机(所有者/发送者),而不是助手号码。

示例配置(个人号码,自聊):

json

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

当 messages.responsePrefix 未设置时,自聊回复默认为 [{identity.name}](如果设置)(否则为 [openclaw])。显式设置它以自定义或禁用前缀(使用 "" 移除它)。

号码来源提示

本地 eSIM 来自您所在国家的移动运营商(最可靠)
- 奥地利:hot.at
- 英国:giffgaff — 免费 SIM,无合同
预付费 SIM — 便宜,只需接收一条验证短信

避免: TextNow、Google Voice、大多数"免费短信"服务 — WhatsApp 会大力屏蔽这些。

提示: 号码只需接收一条验证短信。之后,WhatsApp Web 会话通过 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)。
- 配对:未知发送者获得配对码(通过 openclaw pairing approve whatsapp <code> 批准;码在 1 小时后过期)。
- 开放:需要 channels.whatsapp.allowFrom 包含 "*"。
- 您的关联 WhatsApp 号码隐式受信任,因此自我消息跳过 channels.whatsapp.dmPolicy 和 channels.whatsapp.allowFrom 检查。

个人号码模式(备选)

如果您在个人 WhatsApp 号码上运行 OpenClaw,启用 channels.whatsapp.selfChatMode(见上面的示例)。

行为:

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

已读回执

默认情况下,网关在接受入站 WhatsApp 消息后将其标记为已读(蓝色勾号)。

全局禁用:

json5

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

按账户禁用:

json5

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

注意:

自聊模式始终跳过已读回执。

WhatsApp 常见问题:发送消息 + 配对

当我关联 WhatsApp 时,OpenClaw 会给随机联系人发消息吗?
不会。默认 DM 策略是配对,因此未知发送者只会获得配对码,他们的消息不会被处理。OpenClaw 只回复它收到的聊天,或您显式触发的发送(代理/CLI)。

WhatsApp 上的配对如何工作?
配对是未知发送者的 DM 门控:

来自新发送者的第一条 DM 返回一个短代码(消息不被处理)。
批准方式:openclaw pairing approve whatsapp <code>(用 openclaw pairing list whatsapp 列出)。
代码在 1 小时后过期;每个渠道的待处理请求上限为 3 个。

多个人可以在一个 WhatsApp 号码上使用不同的 OpenClaw 实例吗?
可以,通过 bindings 将每个发送者路由到不同的代理(对等 kind: "dm",发送者 E.164 如 +15551234567)。回复仍然来自同一个 WhatsApp 账户,直接聊天会折叠到每个代理的主会话,因此每人使用一个代理。DM 访问控制(dmPolicy/allowFrom)对每个 WhatsApp 账户是全局的。请参阅多代理路由。

为什么在向导中询问我的电话号码?
向导使用它来设置您的白名单/所有者,以便允许您自己的 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> 会话。
群组策略: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](会话中已有的消息不会重新注入)
- 当前消息在: [Current message - respond to this]
- 追加发送者后缀:[from: Name (+E164)]
群组元数据缓存 5 分钟(主题 + 参与者)。

回复交付(线程)

WhatsApp Web 发送标准消息(当前网关中没有引用回复线程)。
此渠道忽略回复标签。

确认反应(接收时自动反应)

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

配置:

json

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

选项:

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

按账户覆盖:

json

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

行为说明:

反应在消息接收时立即发送,在输入指示器或机器人回复之前。
在 requireMention: false(激活:始终)的群组中,group: "mentions" 将对所有消息做出反应(不仅仅是 @提及)。
发射后不管:反应失败会被记录,但不会阻止机器人回复。
参与者 JID 自动包含在群组反应中。
WhatsApp 忽略 messages.ackReaction;请改用 channels.whatsapp.ackReaction。

代理工具(反应)

工具: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 监听器;如果网关未运行则出错。
文本分块:每条消息最大 4k(通过 channels.whatsapp.textChunkLimit 可配置,可选 channels.whatsapp.chunkMode)。
媒体:
- 支持图像/视频/音频/文档。
- 音频作为 PTT 发送;audio/ogg => audio/ogg; codecs=opus。
- 标题仅在第一个媒体项上。
- 媒体获取支持 HTTP(S) 和本地路径。
- 动画 GIF:WhatsApp 期望带有 gifPlayback: true 的 MP4 用于内联循环。
  - CLI:openclaw message send --media <mp4> --gif-playback
  - 网关:send 参数包括 gifPlayback: true

语音笔记(PTT 音频)

WhatsApp 将音频作为语音笔记(PTT 气泡)发送。

最佳结果:OGG/Opus。OpenClaw 将 audio/ogg 重写为 audio/ogg; codecs=opus。
WhatsApp 忽略 [[audio_as_voice]](音频已作为语音笔记发送)。

媒体限制 + 优化

默认出站上限:5 MB(每个媒体项)。
覆盖:agents.defaults.mediaMaxMb。
图像自动优化为上限以下的 JPEG(调整大小 + 质量扫描)。
超大媒体 => 错误;媒体回复回退到文本警告。

心跳

网关心跳记录连接健康(web.heartbeatSeconds,默认 60s)。
代理心跳可以按代理配置(agents.list[].heartbeat)或通过 agents.defaults.heartbeat 全局配置(当未设置按代理条目时的回退)。
- 使用配置的心跳提示(默认: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 跳过行为。
- 交付默认为最后使用的渠道(或配置的目标)。

重连行为

退避策略:web.reconnect:
- initialMs、maxMs、factor、jitter、maxAttempts。
如果达到 maxAttempts,Web 监控停止(降级)。
已登出 => 停止并要求重新关联。

配置快速映射

channels.whatsapp.dmPolicy(DM 策略:配对/白名单/开放/禁用)。
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.*(按代理覆盖)
session.*(范围、空闲、存储、mainKey)
web.enabled(为 false 时禁用渠道启动)
web.heartbeatSeconds
web.reconnect.*

日志 + 故障排除

子系统:whatsapp/inbound、whatsapp/outbound、web-heartbeat、web-reconnect。
日志文件:/tmp/openclaw/openclaw-YYYY-MM-DD.log(可配置)。
故障排除指南:网关故障排除。

故障排除(快速)

未关联 / 需要二维码登录

症状:channels status 显示 linked: false 或警告"未关联"。
修复:在网关主机上运行 openclaw channels login 并扫描二维码(WhatsApp → 设置 → 关联设备)。

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

症状:channels status 显示 running, disconnected 或警告"已关联但断开连接"。
修复:openclaw doctor(或重启网关)。如果持续存在,通过 channels login 重新关联并检查 openclaw logs --follow。

Bun 运行时

不推荐 Bun。WhatsApp(Baileys)和 Telegram 在 Bun 上不可靠。使用 Node 运行网关。(请参阅入门指南的运行时说明。)

WhatsApp(Web 渠道) ​

快速设置(初学者) ​

目标 ​

配置写入 ​

架构(谁拥有什么) ​

获取电话号码(两种模式) ​

专用号码(推荐) ​

个人号码(备选) ​

号码来源提示 ​

为什么不用 Twilio? ​

登录 + 凭证 ​

入站流程(DM + 群组) ​

个人号码模式(备选) ​

已读回执 ​

WhatsApp 常见问题:发送消息 + 配对 ​

消息规范化(模型看到的内容) ​

群组 ​

回复交付(线程) ​

确认反应(接收时自动反应) ​

代理工具(反应) ​

限制 ​

出站发送(文本 + 媒体) ​

语音笔记(PTT 音频) ​

媒体限制 + 优化 ​

心跳 ​

重连行为 ​

配置快速映射 ​

日志 + 故障排除 ​

故障排除(快速) ​

WhatsApp(Web 渠道)

快速设置(初学者)

目标

配置写入

架构(谁拥有什么)

获取电话号码(两种模式)

专用号码(推荐)

个人号码(备选)

号码来源提示

为什么不用 Twilio?

登录 + 凭证

入站流程(DM + 群组)

个人号码模式(备选)

已读回执

WhatsApp 常见问题:发送消息 + 配对

消息规范化(模型看到的内容)

群组

回复交付(线程)

确认反应(接收时自动反应)

代理工具(反应)

限制

出站发送(文本 + 媒体)

语音笔记(PTT 音频)

媒体限制 + 优化

心跳

重连行为

配置快速映射

日志 + 故障排除

故障排除(快速)