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，之后可将 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)

消息格式化与送达​

WhatsApp 支持 流式（渐进式）响应 —— 机器人会实时编辑消息，随着 AI 生成文本逐步更新，效果如同 Discord 和 Telegram。内部，WhatsApp 被归类为 TIER_MEDIUM 类别的送达能力平台。

分块处理​

长回复将自动按每块 4,096 字符（WhatsApp 实际显示限制）进行拆分。无需手动配置 —— 网关会自动处理分块并依次发送。

WhatsApp 兼容的 Markdown​

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

MarkdownWhatsApp显示效果
**bold***bold*加粗
~~strikethrough~~~strikethrough~删除线
# Heading*Heading*加粗文字（无原生标题）
[link text](url)link text (url)内联链接

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

工具执行进度​

当代理调用工具（网页搜索、文件操作等）时，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 包含发送者号码（带国家代码，无 + 或空格），或设为 * 以允许所有人。在 WHATSAPP_DEBUG=true 中设置 .env 并重启网关，可在 bridge.log 中查看原始消息事件。 | | 机器人向陌生人回复配对码 | 若希望未经授权的私信被静默忽略，请在 whatsapp.unauthorized_dm_behavior: ignore 中设置 ~/.hermes/config.yaml。 |

安全性​

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 中解绑设备 → 设置 → 已链接设备
  • 日志中的电话号码已部分脱敏，但仍需审查您的日志保留策略