Hermes 通过内置的 Baileys bridge 接入 WhatsApp。它模拟的是 WhatsApp Web 会话，不是官方 WhatsApp Business API，因此不需要 Meta 开发者账号或 Business 审核。
非官方 API，存在封号风险
请尽量使用专用手机号，不要批量群发，不要主动给未联系过你的人发消息。
两种模式
| Mode | How it works | Best for |
|---|---|---|
| Separate bot number (recommended) | 使用一个专门给 bot 的号码 | 更清晰的使用体验、更低风险 |
| Personal self-chat | 使用你自己的 WhatsApp 给自己发消息 | 快速测试、单人使用 |
前提条件
- Node.js v18+ 和 npm
- 一台安装了 WhatsApp 的手机，用于扫码登录
第 1 步：运行设置向导
hermes whatsapp
向导会：
- 询问使用 bot 还是 self-chat 模式
- 安装 bridge 依赖
- 在终端中显示二维码
- 等待你扫码
第 2 步：配置 Hermes
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot
WHATSAPP_ALLOWED_USERS=15551234567
# WHATSAPP_ALLOWED_USERS=*
# WHATSAPP_ALLOW_ALL_USERS=true
可选配置示例：
whatsapp:
unauthorized_dm_behavior: ignore
第 3 步：启动网关
hermes gateway
网关会自动使用已保存的会话启动 WhatsApp bridge。
会话持久化
Baileys 会把会话保存到 ~/.hermes/platforms/whatsapp/session：
- 重启后无需重新扫码
- 其中包含完整会话凭据
- 不要共享或提交这个目录
重新配对
如果会话失效：
hermes whatsapp
重新扫码即可。
语音消息
- 入站：自动通过配置好的 STT 大模型提供商（provider）转写
- 出站：TTS 回复作为 MP3 音频附件发送
- 默认会带
Hermes Agent前缀，可在config.yaml中自定义reply_prefix
消息格式与投递
- 支持流式响应
- 长消息按 4096 字符 自动分块
- Markdown 会自动转换为更适合 WhatsApp 的格式
- 工具调用进度会实时显示
故障排除
| Problem | Solution |
|---|---|
| 二维码扫不上 | 确认终端足够宽，且使用正确的 WhatsApp 账号扫码 |
| 二维码过期 | 重新运行 hermes whatsapp |
| 会话没保存 | 检查 ~/.hermes/platforms/whatsapp/session 是否存在且可写 |
| 更新后失效 | 升级 Hermes，并重新配对 |
| 收不到消息 | 检查 WHATSAPP_ALLOWED_USERS 或设置为 * |
安全
- 上线前务必配置访问控制
~/.hermes/platforms/whatsapp/session中保存的是完整会话凭据- 建议为 bot 使用专用手机号