OpenClaw WhatsApp 渠道
即时通讯
中等
通过 Baileys 协议将 OpenClaw 连接到 WhatsApp。此集成方式无需商业 API，只需用手机扫描二维码即可让 AI 助手在 WhatsApp 上收发消息。推荐使用独立手机号以获得更清晰的路由。
快速信息
难度中等
分类即时通讯
支持功能数5 / 6
WhatsApp 支持的功能
文本消息
支持
媒体与文件
支持
消息反应
支持
消息线程
不支持
语音消息
支持
群聊
支持
WhatsApp 前置条件
- WhatsApp 专用手机号（推荐与个人号分开）
- 服务器已安装 Node.js 18+（不推荐使用 Bun）
- OpenClaw Gateway 已运行并配置
WhatsApp 快速设置
1
添加 WhatsApp 渠道配置
在 ~/.openclaw/openclaw.json 中添加 WhatsApp 渠道配置。设置 dmPolicy（allowlist、pairing 或 open）和 allowFrom 列表来控制谁可以向你的助手发消息。
2
运行登录命令并扫描二维码
在终端运行 'openclaw channels login'，将显示一个二维码。用手机 WhatsApp 扫描（设置 > 关联设备 > 关联新设备）。凭证将保存到 ~/.openclaw/credentials/whatsapp/。
3
发送测试消息
从另一部手机向你的 WhatsApp 号码发送私信。如果使用 allowlist 策略，确保发送者号码在 allowFrom 列表中。如果使用默认的 pairing 策略，需通过 'openclaw pairing approve whatsapp <code>' 审批发送者。
WhatsApp 配置示例
config.json
{
"channels": {
"whatsapp": {
"dmPolicy": "allowlist",
"allowFrom": ["+15551234567"]
}
}
}WhatsApp 深入了解
架构概述
OpenClaw 通过 Baileys 库连接 WhatsApp —— 这是一个逆向工程实现的开源 WhatsApp Web 多设备协议。与官方 WhatsApp Business API（需要 Meta 审批且按对话收费）不同，Baileys 通过模拟关联设备直接连接。
架构很简单：你的手机作为主设备，Gateway 充当关联的伴侣设备。消息照常通过 WhatsApp 的服务器传输 —— OpenClaw 只是拦截入站消息，交给你的 AI 处理，然后将回复发回。
由于连接基于手机，你的手机必须保持在线。如果手机离线超过约 14 天，WhatsApp 会取消关联。
Baileys 原生支持多设备 —— 每个手机号最多可关联 4 个设备，Gateway 算其中之一。
手机号设置
强烈建议使用专用手机号。虽然你可以用个人号码，但将个人和机器人对话混在一起会造成路由混乱，也可能打扰你的联系人。
你需要一个能接收短信或语音来电的真实手机号，用于 WhatsApp 初始注册。注册完成后，该号码只需保持在安装了 WhatsApp 的手机上处于活跃状态即可。
openclaw.json
{
"channels": {
"whatsapp": {
"accounts": {
"default": {
"phone": "+15551234567"
}
}
}
}
}避免使用 VoIP 号码（如 TextNow、Google Voice、免费短信服务）—— WhatsApp 经常封禁 VoIP 注册的账号。使用真实 SIM 卡、预付费 SIM 卡或专用 eSIM 以获得最佳可靠性。
登录与凭证
配置好渠道后，你需要将手机与 Gateway 配对。运行登录命令，终端中会显示一个二维码。用手机上的 WhatsApp 扫描它（设置 → 关联设备 → 关联新设备）。
凭证会自动保存到 ~/.openclaw/credentials/whatsapp/<accountId>/creds.json，并在重启后保持有效。系统会自动创建备份文件（creds.json.bak）以便在文件损坏时恢复。除非会话过期或被手动撤销，你只需扫描一次二维码。
终端
openclaw channels login whatsapp如果在无显示器的服务器上运行，使用 --qr-terminal 参数可以将二维码以 ASCII 图形直接渲染在终端中。
私信策略
私信（DM）策略控制谁可以与你的 AI 助手交互。OpenClaw 支持四种策略：
• pairing（默认）—— 新联系人需要完成配对流程。他们发送消息后会收到一个配对码，你在 CLI 中批准或拒绝。批准后即可自由聊天。
• allowlist —— 只有 allowFrom 列表中明确列出的手机号可以给机器人发消息。其他人将被静默忽略。
• open —— 任何给该号码发消息的人都会收到回复。生产环境中请谨慎使用。
• disabled —— 完全关闭私信处理。机器人不会响应任何私信。
openclaw.json
{
"channels": {
"whatsapp": {
"dmPolicy": "pairing",
"allowFrom": ["+15551234567", "+15559876543"]
}
}
}群组管理
OpenClaw 可以参与 WhatsApp 群聊。默认情况下，群组支持是禁用的，以避免在共享对话中产生不必要的 AI 回复。
启用后，机器人仅在被提及名字或被配置的关键词触发时才会回复。你可以控制哪些群组处于活跃状态以及机器人如何被激活。
openclaw.json
{
"channels": {
"whatsapp": {
"groupPolicy": "allowlist",
"groupActivation": "mention",
"groupAllowList": ["group-jid-1", "group-jid-2"]
}
}
}群组 JID 可以在 Gateway 日志中找到——当收到群组消息时，查看消息载荷中的 'from' 字段。
已读回执
你可以配置 OpenClaw 在处理消息时是否发送已读回执（蓝色双勾）。默认会发送已读回执，以保持自然的对话感觉。
如果你希望机器人看起来不那么「活跃」，或者你在异步处理消息，可以禁用已读回执。
openclaw.json
{
"channels": {
"whatsapp": {
"sendReadReceipts": true
}
}
}确认表情回复
OpenClaw 可以在 AI 回复生成之前，先对收到的消息添加一个表情回复作为确认。这很有用，因为 AI 回复可能需要几秒钟，表情回复可以让发送者知道消息已被收到。
你可以分别为私信和群聊配置不同的表情回复，或完全禁用此功能。
openclaw.json
{
"channels": {
"whatsapp": {
"ackReaction": {
"emoji": "👀",
"direct": true,
"group": true
}
}
}
}出站消息与媒体
OpenClaw 支持通过 WhatsApp 发送文本、图片、文档、音频和视频。媒体文件会被自动处理 —— Gateway 将它们上传到 WhatsApp 的服务器并发送相应的消息类型。
对于较长的 AI 回复，文本会被自动分块以保持在 WhatsApp 的消息大小限制内。你可以配置分块大小和行为。
默认入站媒体大小限制为 50 MB（mediaMaxMb）。出站媒体限制为 5 MB（agents.defaults.mediaMaxMb），超大图片会自动进行 JPEG 优化和压缩。
速率限制与发送限制
WhatsApp 对关联设备有速率限制。虽然个人账号没有官方公布的明确限制，但发送消息过快过多可能触发临时封禁或账号限制。
OpenClaw 内置了速率限制机制来保护你的账号。默认设置较为保守，适合大多数使用场景。
openclaw.json
{
"channels": {
"whatsapp": {
"textChunkLimit": 5,
"mediaMaxMb": 50
}
}
}为什么不用 Twilio / WhatsApp Business API？
你可能想知道为什么 OpenClaw 使用 Baileys 而不是官方的 WhatsApp Business API（通过 Twilio、MessageBird 等）。原因如下：
• 成本 —— Business API 按对话收费（根据地区约 $0.005–$0.08 每条消息）。对于个人或小团队使用，费用会迅速累积。Baileys 是免费的。
• 审批 —— Business API 需要 Meta 验证、注册企业和消息模板审批。Baileys 可以使用任何个人 WhatsApp 账号。
• 灵活性 —— Business API 对出站消息有严格的模板要求和 24 小时对话窗口。Baileys 没有这些限制。
• 自托管 —— 使用 Baileys，一切都在你的服务器上运行。没有第三方 API 提供商能看到你的消息。
权衡在于可靠性：Business API 是官方支持的，而 Baileys 依赖逆向工程，如果 WhatsApp 更改协议可能会失效。对于大多数自托管使用场景，这个权衡是值得的。
WhatsApp 配置参考
| Key | Type | Default | Description |
|---|---|---|---|
| dmPolicy | string | "pairing" | 控制谁可以私信机器人。选项：pairing、allowlist、open、disabled |
| selfChatMode | string | "disabled" | 如何处理你发给自己的消息。选项：disabled、ai、note |
| allowFrom | string[] | [] | 允许给机器人发消息的手机号列表（dmPolicy 为 allowlist 时使用） |
| sendReadReceipts | boolean | true | 处理消息时是否发送蓝色双勾已读回执 |
| ackReaction.emoji | string | "👀" | 用于确认收到消息的表情符号 |
| ackReaction.direct | boolean | true | 在私信中发送确认表情 |
| ackReaction.group | boolean | true | 在群聊中发送确认表情 |
| textChunkLimit | number | 5 | 每次 AI 回复的最大文本分块数 |
| mediaMaxMb | number | 50 | 最大入站媒体文件大小（MB）。出站限制由 agents.defaults.mediaMaxMb 控制（默认 5 MB） |
| groupPolicy | string | "disabled" | 群聊策略。选项：disabled、allowlist、open |
| groupActivation | string | "mention" | 群聊中如何触发机器人。选项：mention、always |
| historyLimit | number | 50 | 作为 AI 上下文包含的最近消息数量 |
| chunkMode | string | "split" | 如何处理长回复。选项：split、newline、truncate |
| messagePrefix | string | "" | 添加到所有外发消息前的可选前缀 |
| accounts.<id>.* | object | {} | 每个账号的设置（手机号、凭证路径、覆盖配置） |
dmPolicy
Type: stringDefault: "pairing"
控制谁可以私信机器人。选项：pairing、allowlist、open、disabled
selfChatMode
Type: stringDefault: "disabled"
如何处理你发给自己的消息。选项：disabled、ai、note
allowFrom
Type: string[]Default: []
允许给机器人发消息的手机号列表（dmPolicy 为 allowlist 时使用）
sendReadReceipts
Type: booleanDefault: true
处理消息时是否发送蓝色双勾已读回执
ackReaction.emoji
Type: stringDefault: "👀"
用于确认收到消息的表情符号
ackReaction.direct
Type: booleanDefault: true
在私信中发送确认表情
ackReaction.group
Type: booleanDefault: true
在群聊中发送确认表情
textChunkLimit
Type: numberDefault: 5
每次 AI 回复的最大文本分块数
mediaMaxMb
Type: numberDefault: 50
最大入站媒体文件大小（MB）。出站限制由 agents.defaults.mediaMaxMb 控制（默认 5 MB）
groupPolicy
Type: stringDefault: "disabled"
群聊策略。选项：disabled、allowlist、open
groupActivation
Type: stringDefault: "mention"
群聊中如何触发机器人。选项：mention、always
historyLimit
Type: numberDefault: 50
作为 AI 上下文包含的最近消息数量
chunkMode
Type: stringDefault: "split"
如何处理长回复。选项：split、newline、truncate
messagePrefix
Type: stringDefault: ""
添加到所有外发消息前的可选前缀
accounts.<id>.*
Type: objectDefault: {}
每个账号的设置（手机号、凭证路径、覆盖配置）
WhatsApp 常见问题
WhatsApp 故障排查
WhatsApp 显示「未关联」或二维码无法扫描
会话凭证可能已过期，或者手机上的 WhatsApp 应用更新后使关联会话失效。
删除 ~/.openclaw/credentials/whatsapp/ 目录下的凭证文件夹，然后重新运行 'openclaw channels login whatsapp' 进行配对。确保扫描二维码时手机网络连接稳定。
机器人已连接但不断反复断开
通常发生在手机长时间离线，或另一个关联设备与 Gateway 会话冲突时。
确保你的手机保持网络连接。检查是否已超过关联设备的 4 个设备上限。在 WhatsApp 设置 → 关联设备 中移除未使用的关联设备，然后重新登录。
消息发送失败（超时或投递失败）
速率限制、网络问题，或收件人已拉黑你的号码。
检查 Gateway 日志中的具体错误码。如果看到速率限制错误，减少发送频率。如果是网络问题，确认你的服务器网络稳定。尝试从手机手动发送消息以确认号码未被限制。