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 开机自启

会话持久化

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

会话失效怎么办？

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

最后提醒：封号风险

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

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

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

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