ByteNoteByteNote
字

字节笔记本

2026年6月21日

hermes教程-WhatsApp

#AI 前沿
API中转
¥120
每日科技简报 · 每天一篇,快速了解科技圈大事

WhatsApp 设置

Hermes 通过基于 Baileys 的内置桥接器连接到 WhatsApp。其工作原理是模拟一个 WhatsApp Web 会话——并非通过官方的 WhatsApp Business API。无需 Meta 开发者账户或 Business 验证。

运行 hermes gateway setup 并选择 WhatsApp 即可获得引导式操作。

提示 — 两种 WhatsApp 集成方式

本页面介绍的是 Baileys 桥接器——设置快速，使用个人账户，无需公网 URL，存在封号风险。

如果你正在运行一个真正的商业机器人并希望获得稳定性，请参阅 WhatsApp Business Cloud API 指南。这是 Meta 官方支持的路径：无账户封禁风险，但需要 Meta Business 账户和公共 webhook URL。

如果你有需要，这两个适配器也可以针对不同的电话号码并行运行。

警告 — 非官方 API — 封号风险

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

  • 为机器人使用专用电话号码（不要用你的个人号码）
  • 不要发送批量/垃圾消息——保持对话式使用
  • 不要向未先给你发消息的人自动发送外发消息

警告 — WhatsApp Web 协议更新

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

两种模式

模式工作原理最佳适用场景
独立机器人号码（推荐）为机器人分配一个电话号码。人们直接向该号码发送消息。清晰的用户体验，多用户，较低的封号风险
个人自聊天使用你自己的 WhatsApp。你给自己发消息来与代理对话。快速设置，单用户，测试

前提条件

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

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

步骤 1：运行设置向导

bash
hermes whatsapp

该向导将：

  1. 询问你想要的模式（bot 或 self-chat）
  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（或使用双 SIM 卡的 WhatsApp Business 应用）
  2. 用新号码注册 WhatsApp
  3. 运行 hermes whatsapp 并从该 WhatsApp 账户扫描二维码

步骤 3：配置 Hermes

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

bash
## 必需
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 中的可选行为设置：

yaml
unauthorized_dm_behavior: pair

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

然后启动网关：

bash
hermes gateway              # 前台运行
hermes gateway install      # 安装为用户服务
sudo hermes gateway install --system   # 仅限 Linux：开机系统服务

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

会话持久化

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

  • 会话在重启后仍然存在 — 你无需每次都重新扫描二维码
  • 会话数据包括加密密钥和设备凭据
  • 不要共享或提交此会话目录 — 它授予对 WhatsApp 账户的完全访问权限

重新配对

如果会话中断（手机重置、WhatsApp 更新、手动取消链接），你会在网关日志中看到连接错误。要修复它：

bash
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 中自定义或禁用它：
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渲染效果
**bold***bold*粗体
~~strikethrough~~~strikethrough~删除线
# Heading*Heading*粗体文本（无原生标题）
[link text](url)link text (url)内联 URL

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

工具进度

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

消息批处理（防抖）

WhatsApp 会单独投递每条消息，因此快速爆发（转发批次、粘贴拆分、多行文本）本会导致每个片段触发一次独立的代理调用——浪费 token 并产生多个不连贯的回复。适配器会缓冲来自同一聊天的连续文本消息，并在短暂的静默期后（默认 5 秒，对于非常长的片段延长至 10 秒）将它们作为一个组合请求发送。通过 config.yaml 调整：

yaml
## ~/.hermes/config.yaml
gateway:
  platforms:
    whatsapp:
      extra:
        text_batch_delay_seconds: 5.0         # 刷新批次前的静默期
        text_batch_split_delay_seconds: 10.0  # 接近拆分阈值时的延长延迟

设置 text_batch_delay_seconds: 0 可立即投递每条消息（禁用批处理）。

故障排除

问题解决方案
二维码无法扫描确保终端宽度足够（60 列以上）。尝试不同的终端。确保你从正确的 WhatsApp 账户（机器人号码，而非个人号码）扫描。
二维码过期二维码大约每 20 秒刷新一次。如果超时，重新启动 hermes whatsapp。
会话未持久化检查 ~/.hermes/platforms/whatsapp/session 是否存在且可写。如果容器化，请将其挂载为持久卷。
意外登出WhatsApp 会在长时间不活动后取消链接设备。保持手机开机并连接网络，如有必要，使用 hermes whatsapp 重新配对。
桥接器崩溃或重连循环重启网关，更新 Hermes，如果会话因 WhatsApp 协议更改而失效，则重新配对。
WhatsApp 更新后机器人停止工作更新 Hermes 以获取最新的桥接器版本，然后重新配对。
macOS：显示 "Node.js not installed" 但 node 在终端中可用launchd 服务不会继承你的 shell PATH。运行 hermes gateway install 将当前 PATH 快照到 plist 中，然后运行 hermes gateway start。详情请参阅 Gateway Service 文档。
未收到消息验证 WHATSAPP_ALLOWED_USERS 是否包含发送者的号码（含国家代码，不带 + 或空格），或将其设置为 * 以允许所有人。在 .env 中设置 WHATSAPP_DEBUG=true 并重启网关，以在 bridge.log 中查看原始消息事件。
机器人用配对码回复陌生人如果你希望未授权的 DM 被静默忽略，请在 ~/.hermes/config.yaml 中设置 whatsapp.unauthorized_dm_behavior: ignore。

安全

警告

在投入使用前配置访问控制。使用特定电话号码（含国家代码，不带 +）设置 WHATSAPP_ALLOWED_USERS，使用 * 允许所有人，或设置 WHATSAPP_ALLOW_ALL_USERS=true。如果没有这些设置，网关会拒绝所有传入消息作为安全措施。

默认情况下，未授权的 DM 仍然会收到配对码回复。如果你希望一个私人的 WhatsApp 号码对陌生人完全保持静默，请设置：

yaml
whatsapp:
  unauthorized_dm_behavior: ignore
  • ~/.hermes/platforms/whatsapp/session 目录包含完整的会话凭据——像保护密码一样保护它
  • 设置文件权限：chmod 700 ~/.hermes/platforms/whatsapp/session
  • 为机器人使用专用电话号码，以隔离个人账户的风险
  • 如果你怀疑被入侵，请通过 WhatsApp → 设置 → 已链接设备取消链接设备
  • 日志中的电话号码会被部分遮盖，但请检查你的日志保留策略
AI 前沿
上一篇

hermes教程-模型提供者插件

下一篇

hermes教程-WhatsApp

分享: