WhatsApp 接入——全球用户最多的聊天应用

各位小伙伴，今天咱们来聊聊怎么把 Hermes Agent 接到 WhatsApp 上。毕竟这可是全球用户量最大的聊天应用，谁不想让自己的 Agent 在里面大显身手呢？

好消息：不需要企业认证！

以前接入 WhatsApp 官方 API 需要注册 Meta 开发者账号、通过企业认证，麻烦得要命。现在 Hermes 内置了一个基于 Baileys 的桥接器，它模拟的是 WhatsApp Web 会话，完全不需要官方 Business API 那套流程。

你只需要一条命令：

hermes gateway setup

然后选择 WhatsApp，跟着向导走就行。

两种玩法，任你挑选

模式	怎么玩	适合谁
独立机器人号码（推荐）	专门弄个手机号给机器人，别人直接给这个号发消息	多人使用、体验干净、封号风险低
个人自聊模式	用你自己的 WhatsApp，给自己发消息就是跟 Agent 对话	快速测试、单人使用

准备工作

Node.js v18+ 和 npm
一部装了 WhatsApp 的手机（用来扫二维码）

好消息是，现在的桥接器不需要 Chromium 或 Puppeteer 那一堆浏览器依赖了，轻量多了！

第一步：运行向导

hermes whatsapp

向导会问你选哪种模式，然后显示一个二维码。扫码步骤：

打开手机上的 WhatsApp
进入 设置 → 已链接设备
点击 链接设备
对着终端里的二维码扫一下

配对成功后会话会自动保存，下次不用重新扫码。

小提示：如果二维码显示乱码，把终端窗口拉宽到至少 60 列，或者换个终端模拟器试试。

第二步：搞一个专用号码（机器人模式）

如果你选了机器人模式，需要一个还没注册过 WhatsApp 的号码：

方案	费用	备注
Google Voice	免费	仅限美国
预付费 SIM 卡	一次性 $5-15	激活后 SIM 卡可以放抽屉里，但号码得保持活跃（每 90 天打个电话）
VoIP 服务	免费到 $5/月	TextNow、TextFree 等，有些号码可能被 WhatsApp 屏蔽

第三步：配置 Hermes

编辑 ~/.hermes/.env 文件：

# 必填
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" 或 "self-chat"

# 访问控制——选一种：
WHATSAPP_ALLOWED_USERS=15551234567         # 逗号分隔的手机号（带国家码，不要加 +）
# WHATSAPP_ALLOWED_USERS=*                 # 或者用 * 允许所有人
# WHATSAPP_ALLOW_ALL_USERS=true            # 或者设置这个（效果同 *）

小提示：WHATSAPP_ALLOWED_USERS=* 就是允许所有发送者，跟 WHATSAPP_ALLOW_ALL_USERS=true 一个意思。想走配对流程的话，这两个变量都别设，交给 DM 配对系统处理就行。

还可以在 ~/.hermes/config.yaml 里调整未授权消息的行为：

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

群聊怎么管（机器人模式）

群聊走的是群策略，跟私聊白名单是两码事。WHATSAPP_GROUP_POLICY（或 whatsapp.group_policy）默认是 pairing，也就是群里啥都不转发。改成 allowlist 再用 WHATSAPP_GROUP_ALLOWED_USERS（或 whatsapp.group_allow_from）填上群 JID（逗号分隔，形如 120363001234567890@g.us），就能放行指定群；设成 open 则放行机器人所在的全部群。放行之后发送者还要按普通规则过一遍：设了 WHATSAPP_ALLOWED_USERS 的话，群成员得在白名单里（或已配对）才行。

默认机器人会回复群里每一条被放行的消息，想让它只在被 @、被回复或者收到 /commands 时才吭声，就设 require_mention: true（或 WHATSAPP_REQUIRE_MENTION=true）。

然后启动网关：

hermes gateway              # 前台运行
hermes gateway install      # 安装为用户服务
sudo hermes gateway install --system   # Linux 开机自启

多 Profile：一个网关，多个 WhatsApp 会话

如果你用 Hermes 的多 Profile 功能（比如工作号、私人号分开），宿主网关可以为每个 Profile 单独跑一个配对的 WhatsApp 会话。给第二个 Profile 配对只要：

hermes -p work whatsapp

配对完再给这个 Profile 打开 WhatsApp 就行。如果某个 Profile 开了 WhatsApp 但还没配对（没有 creds.json），它会被跳过，状态显示为 whatsapp_unpaired，并提示你去跑配对命令。

端口这块的规则是这样的：

如果你在配置里显式写了 platforms.whatsapp.extra.bridge_port，那就用它，优先级最高。
否则，第二个 Profile 会自动在 3001 到 3999 之间挑一个没被其他 Profile 占用的空闲端口，并把它存进自己的 platforms/whatsapp/bridge_port 文件，下次启动接着用。
你也可以提前手动建好这个文件、写个端口号进去；想换端口就把文件删了，让它重新分配。
主 Profile（启动用的那个）默认用 3000，除非它自己也有那个文件（比如它以前当过 secondary），那就继续用文件里记录的端口，网关和 hermes send --to whatsapp:<chat_id> 都会走这个端口。

小提示：如果你让每个 Profile 各跑各的网关（而不是共用一个多路复用网关），那它们默认都会抢 3000，得手动给每个 Profile 在 config.yaml 里指定不同端口：

platforms:
  whatsapp:
    extra:
      bridge_port: 3001        # 每个 Profile 一个独立端口

还有几个容易踩的坑：

网关认桥接器是靠它在 /health 里报告的会话目录。如果某个桥接器服务的是别的 Profile 的会话，它永远不会被接管、也不会被停掉，第二个 Profile 的 WhatsApp 会以 whatsapp_bridge_foreign_session 报错启动失败，错误里会写明端口和另一个会话。
如果某个进程占着端口但没及时响应 /health，它也不会被干掉，WhatsApp 会以可重试的 whatsapp_bridge_unresponsive 失败。
只有当端口上运行的桥接器能被该 Profile 自己的会话 pidfile 认出来（pid、内核启动时间和启动端口都对得上，也就是网关崩溃后留下的那种）时，secondary 才会接管它；不健康的也会按同一身份回收并重启。端口上绑定的其他任何进程，只对该 Profile 是致命错误——给它设一个不同的空闲 bridge_port，或者把占端口的进程停掉，其他 Profile 照常运行。
hermes send --to whatsapp:<chat_id> 和定时任务投递都会检查这个字段，绝不会把消息发到别的 Profile 的桥接器上，也不会发给 /health 检查失败的桥接器。
如果你改了 session_path，记得每个 Profile 用不同的路径，否则几个 Profile 会共用同一个 WhatsApp 登录。
用旧版 Hermes 启动的桥接器不报告会话目录，会被重启一次（相当于桥接器升级后的正常操作）。

排查某个 Profile 的 WhatsApp 状态，用：

hermes gateway status --profile work

它会报告这个 Profile 自己的 WhatsApp 适配器，而不是共享入口。

会话持久化

会话数据保存在 ~/.hermes/platforms/whatsapp/session，重启不用重新扫码。但注意：这个目录包含加密密钥，千万别分享或提交到代码仓库！

消息合并（防抖）

WhatsApp 是一条一条投递消息的，所以快速连发（转发的一批、粘贴拆分的、多行文本）本来会为每个片段单独触发一次 Agent 调用——既浪费 token，又会给出好几条割裂的回复。适配器会把同一聊天里连续的文字消息先缓存起来，等一小段安静期后合并成一个请求派发（默认 0.3s，超长片段延长到 1s；上限分别是 2s / 4s）。可以在 config.yaml 里调整：

platforms:
  whatsapp:
    extra:
      text_batch_delay_seconds: 0.3         # 合并前的安静期（最大 2.0）
      text_batch_split_delay_seconds: 1.0   # 接近拆分阈值时的延长延迟（最大 4.0）

会话失效怎么办？

如果手机重置、WhatsApp 更新或者手动解绑导致连接断开，重新运行 hermes whatsapp 再扫一次码就行。

最后提醒：封号风险

WhatsApp 官方并不支持第三方机器人（Business API 除外），所以用桥接器有小概率被限制账号。降低风险的办法：

用专用号码，别拿个人号玩
别发垃圾消息，保持对话式使用
不要主动给没先给你发消息的人发信息

另外，WhatsApp 偶尔会更新 Web 协议导致桥接器暂时失效，这时候拉取最新版 Hermes 重新配对就行。

好了，快去试试吧！让你的 Agent 在 WhatsApp 上大展身手～