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：开机自启系统服务

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

如果你用 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（主 profile）默认用 3000 端口——除非它自己也有那个记录文件（说明它以前当过次级），这时它的网关和 hermes send --to whatsapp:<chat_id> 都会继续用记录里的端口。

几个要注意的点：

次级 profile 只有在自己的 session pidfile 能对上某个正在跑的桥接进程时（pid、内核启动时间、启动端口都对得上），才会接管它——这通常就是网关崩溃后留下的现场。不健康的桥接会被按同样的身份识别并重启。
如果端口被别的进程占着，只有那个 profile 会报致命错误，其他 profile 照常运行。解决办法：把 platforms.whatsapp.extra.bridge_port 设成一个别的空闲端口，或者把占端口的进程停掉。
网关靠桥接在 /health 里报告的会话目录来识别桥接。如果桥接服务的是另一个 profile 的会话，它永远不会被接管、也不会被停掉——第二个 profile 的 WhatsApp 会以 whatsapp_bridge_foreign_session 失败，并告诉你端口和对方的会话。
如果端口被占着但 /health 迟迟不响应，那个进程也不会被动，WhatsApp 会以可重试的 whatsapp_bridge_unresponsive 失败。
hermes send --to whatsapp:<chat_id> 和定时任务投递也会检查同一个字段，不会往别的 profile 的桥接、或 /health 失败的桥接发消息。
如果你改了 session_path，每个 profile 都要用不同的路径，否则几个 profile 会共用同一个 WhatsApp 登录。
旧版 Hermes 启动的桥接不报告会话目录，会被重启一次（相当于桥接更新后的处理）。
hermes gateway status --profile work 报告的是该 profile 自己的 WhatsApp 适配器，而不是共享入口。

如果每个 profile 各跑各的网关（而不是共用一个多路复用网关），那它们默认都用 3000 端口，除非你另外配置。给每个 profile 在 config.yaml 里分配一个不同的端口：

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

会话持久化

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

重新配对

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

hermes whatsapp

重新扫码配对就行。

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