跳到主要内容

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. 将摄像头对准终端中的二维码

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

提示

如果二维码显示混乱，请确保你的终端宽度至少为 60 列，并支持 Unicode。你也可以尝试使用其他终端模拟器。

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

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

选项成本说明
Google Voice免费仅限美国地区。访问 voice.google.com 获取号码。通过 Google Voice 应用接收短信完成 WhatsApp 验证。
预付费 SIM 卡一次性 5–15 美元任意运营商。激活后，验证 WhatsApp，之后 SIM 卡可存放于抽屉中。号码必须保持活跃（每 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。

安全性​

注意

上线前请配置访问控制。通过设置 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 中解绑设备 → 设置 → 已链接设备
  • 日志中的电话号码已部分脱敏，但仍需审查您的日志保留策略