跳到主要内容

WhatsApp 配置

Hermes 通过基于 Baileys 的内置网桥连接到 WhatsApp。这通过模拟 WhatsApp Web 会话实现——不是通过官方 WhatsApp Business API。无需 Meta 开发者账户或企业认证。

非官方 API——封禁风险

WhatsApp 不官方支持 Business API 以外的第三方机器人。使用第三方网桥存在账户受限的小风险。为降低风险：

  • 为机器人使用专用手机号（不要使用你的个人号码）
  • 不要发送批量/垃圾消息——保持对话式使用
  • 不要自动向未主动发消息的人发送出站消息
WhatsApp Web 协议更新

WhatsApp 会定期更新其 Web 协议，这可能会暂时破坏与第三方网桥的兼容性。当发生这种情况时，Hermes 会更新网桥依赖项。如果机器人在 WhatsApp 更新后停止工作，请拉取最新的 Hermes 版本并重新配对。

两种模式​

模式工作方式最适合
独立机器人号码（推荐）为机器人专用一个手机号。人们直接向该号码发消息。简洁的用户体验，多用户，更低封禁风险
个人自聊使用你自己的 WhatsApp。你给自己发消息来与 Agent 对话。快速设置，单用户，测试

前提条件​

  • Node.js v18+ 和 npm——WhatsApp 网桥作为 Node.js 进程运行
  • 安装了 WhatsApp 的手机（用于扫描二维码）

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

步骤 1：运行设置向导​

hermes whatsapp

向导将：

  1. 询问你想要哪种模式（机器人或自聊）
  2. 如果需要，安装网桥依赖项
  3. 在终端中显示二维码
  4. 等待你扫描

扫描二维码：

  1. 在手机上打开 WhatsApp
  2. 前往 设置 → 关联设备
  3. 点击关联设备
  4. 将摄像头对准终端二维码

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

提示

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

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

对于机器人模式，你需要一个尚未注册 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 账户扫描二维码

步骤 3：配置 Hermes​

在 ~/.hermes/.env 文件中添加以下内容：

# 必需
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" 或 "self-chat"

# 访问控制——选择以下选项之一：
WHATSAPP_ALLOWED_USERS=15551234567         # 逗号分隔的手机号（含国家代码，不含 +）
# WHATSAPP_ALLOWED_USERS=*                 # 或使用 * 允许所有人
# WHATSAPP_ALLOW_ALL_USERS=true            # 或设置此标志（效果同 *）
允许所有人的简写

设置 WHATSAPP_ALLOWED_USERS=* 允许所有发送者（等效于 WHATSAPP_ALLOW_ALL_USERS=true）。这与 Signal 群组允许列表保持一致。要使用配对流程，请删除这两个变量并依赖 DM 配对系统。

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

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore
  • unauthorized_dm_behavior: pair 是全局默认值。未知的私信发送者会收到配对码。
  • whatsapp.unauthorized_dm_behavior: ignore 使 WhatsApp 对未授权的私信保持沉默，这通常是私人号码的更好选择。

然后启动网关：

hermes gateway              # 前台运行
hermes gateway install      # 安装为用户服务
sudo hermes gateway install --system   # 仅 Linux：启动时运行的系统服务

网关会使用保存的会话自动启动 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 音频文件附件的形式发送
  • Agent 响应默认以"⚕ Hermes Agent"为前缀。你可以在 config.yaml 中自定义或禁用：
# ~/.hermes/config.yaml
whatsapp:
  reply_prefix: ""                          # 空字符串禁用标题
  # reply_prefix: "🤖 *My Bot*\n──────\n"  # 自定义前缀（支持 \n 换行）

消息格式与发送​

WhatsApp 支持流式（渐进式）响应——机器人在 AI 生成文本时实时编辑其消息，就像 Discord 和 Telegram 一样。在内部，WhatsApp 被归类为 TIER_MEDIUM 平台，具有中等发送能力。

分块​

长响应会在每块 4,096 字符处自动分割（WhatsApp 的实际显示限制）。无需任何配置——网关处理分割并按顺序发送各块。

WhatsApp 兼容的 Markdown​

AI 响应中的标准 Markdown 会自动转换为 WhatsApp 的原生格式：

MarkdownWhatsApp显示效果
**粗体***粗体*粗体
~~删除线~~~删除线~删除线
# 标题*标题*粗体文本（无原生标题）
[链接文本](url)链接文本 (url)行内 URL

代码块和行内代码保持原样，因为 WhatsApp 原生支持三反引号格式。

工具进度​

当 Agent 调用工具（网络搜索、文件操作等）时，WhatsApp 会显示实时进度指示器，显示正在运行哪个工具。默认启用——无需配置。

故障排除​

问题解决方案
二维码无法扫描确保终端足够宽（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 → 设置 → 已关联设备中解除设备关联
  • 日志中的手机号已部分脱敏，但请检查你的日志保留策略