OpenClaw WhatsApp 配置指南

状态

WhatsApp Web 通过 Baileys。Gateway 拥有会话。

快速设置（初学者）

• 如果可能，使用单独的电话号码（推荐）
• 在 ~/.openclaw/openclaw.json 中配置 WhatsApp
• 运行 openclaw channels login 扫描二维码（关联设备）
• 启动网关

最小配置：

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

目标

• 在一个 Gateway 进程中运行多个 WhatsApp 账号（多账号）
• 确定性路由：回复返回到 WhatsApp，无模型路由
• 模型看到足够的上下文来理解引用回复

架构（谁拥有什么）

• Gateway 拥有 Baileys 套接字和收件箱循环
• CLI / macOS 应用与网关通信；不直接使用 Baileys
• 出站发送需要活动的监听器；否则发送快速失败

获取电话号码（两种模式）

WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常被阻止。

专用号码（推荐）

为 OpenClaw 使用单独的电话号码。最佳用户体验，干净的路由，没有自我聊天的问题。理想设置：备用/旧 Android 手机 + eSIM。保持 Wi-Fi 和电源连接，通过 QR 关联。

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

示例配置（专用号码，单用户允许列表）：

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

配对模式（可选）：

如果想要配对而不是允许列表，将 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（最可靠）
  • 奥地利: hot.at
  • 英国: giffgaff — 免费 SIM，无合同
• 预付费 SIM — 便宜，只需要接收一条 SMS 进行验证

避免: TextNow、Google Voice、大多数”免费 SMS”服务——WhatsApp 积极阻止这些。

提示: 该号码只需要接收一条验证 SMS。之后，WhatsApp Web 会话通过 creds.json 持久化。

为什么不用 Twilio？

• 早期 OpenClaw 版本支持 Twilio 的 WhatsApp Business 集成
• WhatsApp Business 号码不适合个人助手
• Meta 强制执行 24 小时回复窗口；如果您在过去 24 小时内没有回复，企业号码无法发起新消息
• 高容量或”健谈”的使用会触发积极阻止，因为企业账号不意味着发送数十条个人助手消息
• 结果：不可靠的投递和频繁阻止，因此已删除支持

登录 + 凭据

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

入站流程（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 消息标记为已读（蓝色对勾），一旦它们被接受。

全局禁用：

{
  "channels": { 
    "whatsapp": { "sendReadReceipts": false } 
  }
}

每个账号禁用：

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

注意：

• 自我聊天模式始终跳过已读回执

配置快速映射

日志 + 故障排除

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

快速故障排除

未关联 / 需要 QR 登录

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

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

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

来源: https://docs.openclaw.ai/channels/whatsapp