Hermes Agent 接入 WhatsApp

先说清楚：用的是个人号，不是 WhatsApp Business API

本文讲的是用 @openclaw/whatsapp 插件挂一个 WhatsApp 个人账号（基于开源的 baileys 库，走 WhatsApp Web 协议），让这个账号自动回所有私聊和群里 @ 它的消息。如果你想接 WhatsApp Business API（Meta 官方付费 API），那是完全不同的接入方式，本文不覆盖。

个人号挂机器人 WhatsApp 官方不允许，账号有被封的可能。生产环境如果是给客户用的，最好申请 WhatsApp Business API。如果只是个人或小团队用，本文方案够用。

准备工作

• 已经在跑的 Hermes Agent（先看 安装指南）
• 一个 WhatsApp 账号 + 一台能扫码的手机
• 一个公网可达的 HTTPS URL（二维码图片要从 Hermes 网关拿）

第一步：on-demand 安装 @openclaw/whatsapp 插件

和微信渠道一样，@openclaw/whatsapp 不预装在 Hermes 镜像里。原因是 baileys 依赖一些原生加密模块，打镜像会拖慢启动。在 Hermes Web UI 上点 Connect Platforms → WhatsApp → Connect，Hermes 会自动跑：

# Hermes 内部执行
plugins install -l /app/dist/extensions/whatsapp

安装完成约 30s。如果 npm registry 在国内访问慢，可以预先在容器里 npm config set registry https://registry.npmmirror.com。

第二步：扫码登录（baileys 协议）

1. 插件安装完后 Hermes Web UI 会显示一个二维码（base64 图片）。
2. 手机打开 WhatsApp → 设置 → 已链接的设备 → 链接设备 → 扫这个二维码。
3. WhatsApp 提示“设备已链接”，Hermes 拿到 session credentials 写到 /app/data/whatsapp/auth/。
4. 之后容器重启不用重新扫码，登录态会自动恢复。

Multi-Device：你的手机不会被踢下线

和微信不同，WhatsApp 用 Multi-Device 协议（2021 之后默认开启），你的手机和机器人可以同时在线。这点比微信好很多 —— 你不用在“给机器人用”和“自己用”之间二选一。

但 Multi-Device 限制：链接的设备数最多 4 个（手机不算），你超过这个数会踢掉最早链接的设备。每个链接的设备 14 天没活动会自动失效。

第三步：hermes.json 配置字段

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "pairing",
      "allowFrom": [],
      "groupAtOnly": true
    }
  },
  "plugins": {
    "entries": {
      "whatsapp": { "enabled": true }
    }
  }
}

关键字段

• dmPolicy: "pairing"：陌生人发消息默认拒绝，必须先在 Web 网关配对绑定。
• groupAtOnly: true：群里只回 @ 它的消息，避免在大群里被刷屏或被群主踢出。
• allowFrom：白名单，填手机号（带国家代码，如 +8613800138000）或群 ID。

测试

• 用另一个 WhatsApp 账号给机器人发消息
• 到 https://你的-hermes-域名/pair 拿配对码，发给机器人完成绑定
• 之后正常对话即可，群聊里记得 @ 机器人

常见报错

二维码扫了之后 Hermes 没反应

• WhatsApp 在校验设备，正常等 5-10s
• 如果超过 30s 还没成功，看 docker logs hermes 2>&1 | grep -i baileys
• 有时候 baileys 协议升级后老版本插件失效，plugins update -l whatsapp 升级

2026-05-02 的 plugins install -l 回归

如果你看到日志里写 no installable version found for @openclaw/whatsapp，这是 npm registry 临时返回的“无可用版本”问题。Hermes 默认会从 /app/dist/extensions/whatsapp 这个 bundled fallback 装。如果这个目录也不存在（自定义镜像可能裁掉了），手动安装：plugins install -l /app/dist/extensions/whatsapp。

登录后过几天自动失效

WhatsApp Multi-Device 链接的设备 14 天没消息会自动失效。让机器人持续收消息（哪怕是测试消息）能续期。生产环境可以配 cron 每天自检 + 提醒重新扫码。

群里 @ 机器人不回

• WhatsApp 的 @ 不像 Slack/Discord 那么严格 —— 你必须用 WhatsApp 的 @ 功能（输入 @ 后从下拉选机器人），不是手打 @ 加名字
• groupAtOnly: true 但 baileys 没解析到 mentionedJid —— 看日志确认

账号被 ban

WhatsApp 风控触发时直接 ban 账号，不像微信只踢下线。常见触发：

• 新注册账号马上挂机器人
• 对陌生人主动发消息（机器人最好只被动回复，不要主动发）
• 同一个 IP 挂太多机器人
• 容器频繁换 IP（跨服务器迁移）

WhatsApp Business API 的对比

如果是给企业客户用，强烈建议走 WhatsApp Business API（通过 Meta Business 官方申请，需要营业执照和绿勾认证）。优点：不会被封、可以发模板消息、支持多 agent、有送达回执。缺点：申请慢（1-2 周）、按消息计费（约 $0.005-0.05 / 条）、营销消息有 24 小时窗口限制。

托管版：OpenClaw Launch

WhatsApp 渠道的运维负担：扫码、Multi-Device 续期、baileys 升级跟进、固定 IP 防风控。 OpenClaw Launch 托管版处理好了固定 IP、持久化 session、自动重连，在 Dashboard 点 Connect WhatsApp → 扫码就好。首月 $3，之后 $6/月。

下一步

• Hermes Agent 中文介绍
• 接入微信
• 接入 Telegram
• 接入 Discord
• OpenClaw 接入 WhatsApp