好奇心花园🪴

搜索

SearchSearch

最近的笔记

WhatsApp

2026年5月24日11分钟阅读

WhatsApp 设置

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

:::warning 非官方 API — 封号风险 WhatsApp 不官方支持 Business API 之外的第三方机器人。使用第三方桥接器存在账户受限的小风险。为最小化风险：

  • 为机器人使用专用电话号码（而非您的个人号码）
  • 不要发送批量/垃圾消息 — 保持对话式使用
  • 不要向未首先发送消息的人自动发送出站消息 :::

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

两种模式

模式工作原理最佳用途
独立机器人号码（推荐）将一个电话号码专用于机器人。人们直接向该号码发送消息。干净的 UX、多用户、较低的封号风险
个人自聊使用您自己的 WhatsApp。您给自己发消息与 agent 对话。快速设置、单用户、测试

前提条件

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

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

第 1 步：运行设置向导

hermes whatsapp

向导将：

  1. 询问您想要哪种模式（bot 或 self-chat）
  2. 如果需要，安装桥接器依赖
  3. 在终端中显示二维码
  4. 等待您扫描它

扫描二维码：

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

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

:::tip 如果二维码看起来乱码，确保您的终端至少 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            # 或设置此标志（与 * 效果相同）

:::tip 允许所有简写 设置 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 是全局默认值。未知的 DM 发送者会收到配对码。
  • whatsapp.unauthorized_dm_behavior: ignore 使 WhatsApp 对未授权的 DM 保持静默，这通常是私人号码的更好选择。

然后启动网关：

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 支持流式（渐进式）响应——机器人会实时编辑其消息，就像 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 原生支持三重反引号格式。

工具进度

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

故障排除

问题解决方案
二维码无法扫描确保终端足够宽（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。详情请参阅网关服务文档。
消息未收到验证 WHATSAPP_ALLOWED_USERS 包含发送者的号码（含国家代码，无 + 或空格），或将其设为 * 允许所有人。在 .env 中设置 WHATSAPP_DEBUG=true 并重启网关，查看 bridge.log 中的原始消息事件。
机器人用配对码回复陌生人如果您希望未授权的 DM 被静默忽略，请在 ~/.hermes/config.yaml 中设置 whatsapp.unauthorized_dm_behavior: ignore。

安全性

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

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

whatsapp:
  unauthorized_dm_behavior: ignore
  • ~/.hermes/platforms/whatsapp/session 目录包含完整的会话凭证——像保护密码一样保护它
  • 设置文件权限：chmod 700 ~/.hermes/platforms/whatsapp/session
  • 为机器人使用专用电话号码，将风险与您的个人账户隔离
  • 如果怀疑被入侵，从 WhatsApp → Settings → Linked Devices 取消链接设备
  • 日志中的电话号码会被部分遮蔽，但请审核您的日志保留策略

关系图谱

反向链接