WhatsApp 接入：扫个码就能让你的 Hermes 上线聊天

嘿，朋友们！今天咱们来聊聊怎么把 Hermes 接到 WhatsApp 上。别紧张，整个过程比你想象的简单多了——不用注册 Meta 开发者账号，不用申请企业认证，甚至不需要一台公网服务器。你只需要一部装了 WhatsApp 的手机，扫个码，完事儿。

这玩意儿是怎么工作的？

Hermes 用的是基于 Baileys 的桥接方案，原理是模拟一个 WhatsApp Web 会话。简单说，就是让你的 Hermes 像 WhatsApp 网页版一样登录，然后就能收发消息了。

注意：这不是官方的 WhatsApp Business API，所以有小概率被限制账号的风险。建议用专用号码跑机器人，别拿自己日常用的号去折腾。

两种玩法，任你选

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

准备工作

Node.js v18+ 和 npm（桥接器是 Node.js 进程）
一部装了 WhatsApp 的手机（用来扫码）

好消息是：现在的桥接器不需要 Chromium 或 Puppeteer 那套重型依赖了，轻量得很。

第一步：跑设置向导

hermes whatsapp

向导会一步步带你走：

选择模式（bot 或 self-chat）
自动安装依赖
在终端显示二维码
等你扫码

扫码步骤：

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

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

小提示：如果二维码显示乱码，检查终端宽度是否至少 60 列，并确认支持 Unicode。换个终端模拟器也行。

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

机器人模式需要一个没注册过 WhatsApp 的号码。三个选择：

方案	费用	说明
Google Voice	免费	仅限美国，去 voice.google.com 申请
预付费 SIM 卡	5-15 美元一次性	激活验证后可以放抽屉里，但号码要保持活跃（每 90 天打个电话）
VoIP 服务	免费到 5 美元/月	TextNow、TextFree 等，有些号码可能被 WhatsApp 屏蔽，多试几个

拿到号码后，在手机上注册 WhatsApp，然后跑 hermes 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            # 或者设这个标志（效果同 *）

可选的行为设置，在 ~/.hermes/config.yaml 里：

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

pair 是全局默认，陌生人私信会收到配对码
ignore 让 WhatsApp 对未授权私信保持沉默，私人号码推荐这个

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

群聊走的是群策略，跟私信白名单是两码事。WHATSAPP_GROUP_POLICY（或 whatsapp.group_policy）默认是 pairing，也就是群里啥都不转发。想放行的话：

设成 allowlist，再用 WHATSAPP_GROUP_ALLOWED_USERS（或 whatsapp.group_allow_from）填群 JID（逗号分隔，形如 120363001234567890@g.us），只有列表里的群能进
设成 open，机器人所在的每个群都放行

群消息进来后，发送者还会再按普通规则查一遍：如果你设了 WHATSAPP_ALLOWED_USERS，参与者得在白名单里（或已配对）才行；没设发送者白名单时，allowlist 只认群 JID 列表，open 仍然要求参与者已配对或开了 WHATSAPP_ALLOW_ALL_USERS=true。

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

然后启动网关：

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

会话持久化

会话数据保存在 ~/.hermes/platforms/whatsapp/session，所以重启不用重新扫码。但要注意：这个目录包含加密密钥和设备凭证，千万别分享或提交到代码仓库，谁拿到谁就能完全控制你的 WhatsApp 账号。

重新配对

如果会话失效（手机重置、WhatsApp 更新、手动解绑），网关日志会报连接错误。解决办法很简单：

hermes whatsapp

重新扫码配对就行。

搞定！现在你的 Hermes 已经能通过 WhatsApp 聊天了。记住：保持对话式使用，别群发垃圾消息，这样账号风险就能降到最低。有问题随时在评论区聊！