Skip to main content

WhatsApp 设置

Hermes 通过基于 Baileys 的内置桥接器连接 WhatsApp。该方式通过模拟 WhatsApp Web 会话实现 —— 并非 使用官方的 WhatsApp Business API。无需 Meta 开发者账号或企业验证。

非官方 API —— 账号封禁风险

WhatsApp 不支持 除 Business API 外的第三方机器人。使用第三方桥接器存在一定的账号受限风险。为降低风险，请注意：

  • 使用专用手机号码 作为机器人（不要使用你的个人号码）
  • 避免群发/垃圾信息 —— 保持对话式使用
  • 不要自动向未主动联系过的人发送消息
WhatsApp Web 协议更新

WhatsApp 会定期更新其 Web 协议，可能导致第三方桥接器暂时失效。当这种情况发生时，Hermes 将更新桥接依赖。如果在 WhatsApp 更新后机器人无法工作，请拉取最新版 Hermes 并重新配对。

两种模式​

模式工作原理适用场景
独立机器人号码（推荐）为机器人分配一个独立的手机号码。用户直接向该号码发送消息。清晰的用户体验、多用户支持、更低的封禁风险
个人自聊模式使用你自己的 WhatsApp。通过给自己发消息与代理互动。快速搭建、单用户、测试用途

前置条件​

  • Node.js v18+ 和 npm —— WhatsApp 桥接器以 Node.js 进程运行
  • 一部安装了 WhatsApp 的手机（用于扫描二维码）

与旧版基于浏览器的桥接器不同，当前基于 Baileys 的桥接器 不需要本地 Chromium 或 Puppeteer 依赖栈。

第一步：运行设置向导​

hermes whatsapp

向导将执行以下操作：

  1. 询问你希望使用的模式（bot 或 self-chat）
  2. 如需，自动安装桥接依赖
  3. 在终端中显示一个 二维码
  4. 等待你扫描

扫描二维码的方法：

  1. 打开手机上的 WhatsApp
  2. 进入 设置 → 已链接设备
  3. 点击 链接设备
  4. 用摄像头对准终端中的二维码

配对成功后，向导会确认连接并退出。你的会话将自动保存。

tip

如果二维码显示混乱，请确保终端宽度至少为 60 列，并支持 Unicode。也可尝试更换终端模拟器。

第二步：获取第二个手机号码（机器人模式）​

在机器人模式下，你需要一个尚未注册 WhatsApp 的手机号码。有三种选择：

方案成本注意事项
Google Voice免费仅限美国地区。访问 voice.google.com 获取号码。通过 Google Voice 应用接收短信完成 WhatsApp 验证。
预付费 SIM 卡一次性 $5–15任意运营商均可。激活后完成 WhatsApp 注册，之后可闲置于抽屉中。号码必须保持活跃（每 90 天打一次电话）。
VoIP 服务免费 – $5/月TextNow、TextFree 等。部分 VoIP 号码被 WhatsApp 屏蔽 —— 若首个号码无效，可尝试多个。

获取号码后：

  1. 在手机上安装 WhatsApp（或使用双卡版 WhatsApp Business 应用）
  2. 用新号码注册 WhatsApp
  3. 运行 hermes whatsapp 并从该 WhatsApp 账号扫描二维码

第三步：配置 Hermes​

将以下内容添加至你的 ~/.hermes/.env 文件中：

# Required
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" or "self-chat"

# Access control — pick ONE of these options:
WHATSAPP_ALLOWED_USERS=15551234567         # Comma-separated phone numbers (with country code, no +)
# WHATSAPP_ALLOWED_USERS=*                 # OR use * to allow everyone
# WHATSAPP_ALLOW_ALL_USERS=true            # OR set this flag instead (same effect as *)
允许所有发送者的快捷写法

设置 WHATSAPP_ALLOWED_USERS=* 可允许 所有 发送者（等同于 WHATSAPP_ALLOW_ALL_USERS=true）。这与 Signal 群组白名单机制 一致。若想使用配对流程，请移除这两个变量，依靠 私信配对系统。

可选的行为设置项（在 ~/.hermes/config.yaml 中）：

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore
  • unauthorized_dm_behavior: pair 是全局默认值。未知私信发送者将收到配对码。
  • whatsapp.unauthorized_dm_behavior: ignore 使 WhatsApp 对未经授权的私信保持静默，对于私密号码而言通常是更优选择。

然后启动网关：

hermes gateway              # Foreground
hermes gateway install      # Install as a user service
sudo hermes gateway install --system   # Linux only: boot-time system service

网关将自动使用已保存的会话启动 WhatsApp 桥接器。

会话持久化​

Baileys 桥接器将会话数据保存在 ~/.hermes/platforms/whatsapp/session 目录下。这意味着：

  • 会话可跨重启保留 —— 无需每次重启都重新扫描二维码
  • 会话数据包含加密密钥和设备凭证
  • 切勿分享或提交此会话目录 —— 它相当于对 WhatsApp 账号的完全访问权限

重新配对​

如果会话中断（手机重置、WhatsApp 更新、手动解绑），你将在网关日志中看到连接错误。修复方法如下：

hermes whatsapp

这将生成一个新的二维码。再次扫描即可重建会话。网关会自动处理 临时断连（如网络波动、手机短暂离线）。

语音消息​

Hermes 支持 WhatsApp 语音消息功能：

  • 接收：语音消息（.ogg opus 格式）将由配置的 STT 提供商自动转录：本地 faster-whisper、Groq Whisper (GROQ_API_KEY)，或 OpenAI Whisper (VOICE_TOOLS_OPENAI_KEY)
  • 发送：TTS 回复将以 MP3 音频附件形式发送
  • 代理回复默认前缀为 "⚕ Hermes Agent"。你可在 config.yaml 中自定义或禁用：
# ~/.hermes/config.yaml
whatsapp:
  reply_prefix: ""                          # Empty string disables the header
  # reply_prefix: "🤖 *My Bot*\n──────\n"  # Custom prefix (supports \n for newlines)

故障排查​

问题解决方案
二维码无法扫描确保终端宽度 ≥60 列。尝试更换终端。确认扫描的是正确的 WhatsApp 账号（机器人号码，非个人账号）。
二维码过期二维码每约 20 秒刷新一次。若超时，请重新运行 hermes whatsapp。
会话无法持久化检查 ~/.hermes/platforms/whatsapp/session 是否存在且可写。若容器化部署，请将其挂载为持久卷。
意外登出WhatsApp 在长时间无活动后会自动解除设备绑定。请保持手机开机并联网，必要时使用 hermes whatsapp 重新配对。
桥接崩溃或陷入重连循环重启网关，更新 Hermes，若会话因 WhatsApp 协议变更失效则重新配对。
WhatsApp 更新后机器人停止工作更新 Hermes 至最新版本，然后重新配对。
macOS：提示“Node.js 未安装”但终端中 node 可用launchd 服务不会继承你的 shell PATH。运行 hermes gateway install 以将当前 PATH 重新注入 plist，然后 hermes gateway start。详情参见 网关服务文档。
消息未被接收确认 WHATSAPP_ALLOWED_USERS 包含发送者号码（带国家代码，不含 + 或空格），或设为 * 以允许所有人。在 .env 中设置 WHATSAPP_DEBUG=true，重启网关后可在 bridge.log 查看原始消息事件。
机器人向陌生人回复配对码若希望未授权私信被静默忽略，请在 ~/.hermes/config.yaml 中设置 whatsapp.unauthorized_dm_behavior: ignore。

安全性​

warning

上线前务必配置访问控制。通过设置 WHATSAPP_ALLOWED_USERS 限定特定手机号码（含国家代码，不含 +），使用 * 允许所有人，或设置 WHATSAPP_ALLOW_ALL_USERS=true。若未设置以上任一选项，网关将 拒绝所有传入消息，作为安全保护措施。

默认情况下，未经认证的私信仍会收到配对码回复。若希望私密 WhatsApp 号码对陌生人完全静默，可设置：

whatsapp:
  unauthorized_dm_behavior: ignore
  • ~/.hermes/platforms/whatsapp/session 目录包含完整的会话凭证 —— 请像保护密码一样保护它
  • 设置文件权限：chmod 700 ~/.hermes/platforms/whatsapp/session
  • 使用 专用手机号码 作为机器人，以隔离个人账户风险
  • 若怀疑账号泄露，请在 WhatsApp 中解绑设备：→ 设置 → 已链接设备
  • 日志中的手机号码已部分脱敏，但仍需审查日志保留策略