WhatsApp - 全球即时通讯接入

OpenClaw 通过 Baileys（非官方 WhatsApp Web API 库）实现与 WhatsApp 的对接，支持多设备登录、群组消息、媒体处理等完整功能。

前置要求

• 一个有效的 WhatsApp 账号（需绑定手机号）
• Node.js 18+ 环境
• OpenClaw Gateway（网关）已安装并运行

关于 Baileys

Baileys 是一个社区维护的非官方 WhatsApp Web API 库，无需 Selenium 或浏览器即可与 WhatsApp 通信。由于是非官方方案，请注意遵守 WhatsApp 的使用条款。

登录配置

第一步：QR Code（二维码）扫码登录

在终端执行以下命令，按照提示用手机扫描二维码完成登录：

openclaw channels login --channel whatsapp

扫码成功后，终端会显示 Logged in successfully 提示。

第二步：编辑配置文件

在 OpenClaw 配置文件中启用 WhatsApp Channel（频道）：

{
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "pairing",       // DM Policy（私信策略）: pairing | allowlist | open
      allowFrom: ["628xxx"],     // 允许的手机号白名单（国际格式，不带+号）
      groupPolicy: "allowlist",  // Group Policy（群组策略）
      allowGroups: []            // 允许的群组 JID 列表
    }
  }
}

第三步：重启 Gateway

openclaw gateway restart

Multi-device（多设备）支持

WhatsApp 原生支持多设备登录，OpenClaw 作为 Linked Device（关联设备）接入，不会影响手机端正常使用。最多可同时关联 4 台设备。

注意

如果你在手机上退出了 WhatsApp 账号或卸载了应用，所有关联设备（包括 OpenClaw）将自动断开连接。

群组消息设置

配置 OpenClaw 在群组中响应消息：

{
  channels: {
    whatsapp: {
      enabled: true,
      groupPolicy: "allowlist",
      allowGroups: ["120363xxx@g.us"],  // 群组 JID
      groupRequireMention: true         // 需要 @机器人 才响应
    }
  }
}

获取群组 JID 的方式：查看 Gateway 日志中的 groupId 字段，或在群组中发送测试消息后查看日志输出。

Media（媒体）处理

OpenClaw 支持接收和发送以下媒体类型：

类型	接收	发送	说明
Image（图片）	✅	✅	支持 JPG/PNG/WebP
Voice（语音）	✅	✅	自动转录为文本
Document（文档）	✅	✅	PDF/Office 等
Video（视频）	✅	❌	仅接收
Sticker（贴纸）	✅	❌	仅接收

Session（会话）持久化与重连

OpenClaw 会自动保存 Session 信息到本地，Gateway 重启后无需重新扫码。Session 文件存储位置：

~/.openclaw/channels/whatsapp/session/

自动重连

当网络中断或 WhatsApp 服务器断开连接时，OpenClaw 会自动尝试重连，默认重试间隔为 5 秒，最多重试 10 次。

Rate Limits（速率限制）与防封建议

WhatsApp 对自动化消息有严格的 Rate Limits，违规可能导致账号被封禁：

防封须知

• 消息频率：建议每分钟不超过 20 条消息，避免短时间内大量发送
• 新账号保护期：新注册的 WhatsApp 号码前 7 天尤其要控制发送频率
• 避免群发：不要向大量未联系过的号码发送消息
• 内容多样化：避免重复发送完全相同的消息内容
• 人机混合使用：建议该手机号同时保持一定的手动使用频率

常见问题

QR Code 扫码超时

QR Code 有效期约 60 秒。如果超时，重新执行登录命令即可刷新：

openclaw channels login --channel whatsapp

随机断开连接

WhatsApp 服务器可能会定期断开 Linked Device 的连接。如果频繁断连：

1. 检查网络稳定性
2. 确保手机端 WhatsApp 保持在线
3. 更新 Baileys 到最新版本：openclaw update

Relogin Loop（重复登录循环）

如果出现反复要求重新登录的情况：

# 清除本地 Session 后重新登录
openclaw channels logout --channel whatsapp
openclaw channels login --channel whatsapp

如果问题依然存在，删除 Session 目录后重试：

rm -rf ~/.openclaw/channels/whatsapp/session/
openclaw channels login --channel whatsapp

DM Policy（私信策略）说明

策略	说明
pairing	用户需先通过 Pairing Code（配对码）验证后才能对话
allowlist	仅 allowFrom 列表中的号码可以发送消息
open	任何人都可以直接发送消息（不推荐用于生产环境）

🇨🇳 中国用户须知

WhatsApp 在中国大陆无法直接访问，需要通过 VPN 或代理才能使用。如果你的 OpenClaw 服务器部署在中国境内，需要为 Gateway 配置代理：

{
  channels: {
    whatsapp: {
      proxy: "http://your-proxy:port"  // HTTP/SOCKS5 代理地址
    }
  }
}

替代方案：如果主要面向国内用户，建议使用企业微信、钉钉或飞书等国内 IM 平台。WhatsApp 更适合面向海外客户的业务场景，如跨境电商客服、海外团队沟通等。

注册提示：注册 WhatsApp 需要非中国大陆的手机号或可接收国际短信的号码。可以使用中国香港、东南亚等地区的号码注册。