WhatsApp 接入
Hermes 通过 WhatsApp Web 桥接技术实现 WhatsApp 接入，让你可以直接通过 WhatsApp 与 Agent 对话。
前置条件
- 已安装并运行 Hermes
- 拥有 WhatsApp 账号（手机号已注册）
- Node.js v22 或更高版本（WhatsApp 桥接依赖）
- 手机需保持联网（WhatsApp Web 桥接依赖手机连接）
安装 Node.js v22
bash
# 使用 nvm（推荐）
nvm install 22
nvm use 22
# 验证版本
node --version # 应显示 v22.x.x配置步骤
第一步：运行 WhatsApp 配置命令
bash
hermes whatsapp此命令会启动交互式配置向导，引导你完成 WhatsApp 配对流程。
第二步：扫描 QR 码配对
命令运行后，终端会显示一个 QR 码
在手机上打开 WhatsApp：
- iOS：设置 -> 已关联设备 -> 关联设备
- Android：右上角菜单 -> 已关联设备 -> 关联设备
用手机扫描终端中显示的 QR 码
扫描成功后，终端会显示配对完成的提示
第三步：配置授权用户
编辑 ~/.hermes/.env，添加允许使用的手机号（国际格式，不含 +）：
bash
# WhatsApp 允许的用户手机号（国际格式）
WHATSAPP_ALLOWED_USERS=8613800138000,8613900139000中国大陆手机号示例：86 + 手机号（去掉开头的 0），如 8613812345678。
第四步：启动网关
bash
hermes gateway start使用方式
配对成功后，直接向自己（或已授权用户向机器人账号）发送 WhatsApp 消息即可开始对话。
支持的功能
| 功能 | 说明 |
|---|---|
| 文字消息 | 完全支持 |
| 语音消息 | 自动转录为文字后处理 |
| 图片 | 支持图片分析（需使用视觉模型） |
| 文档 | 支持 PDF、文本等文件 |
| 聊天命令 | 支持 /new、/reset、/model、/help |
注意事项
关于 WhatsApp 使用条款
WhatsApp Web 桥接使用非官方 API，存在以下风险：
- WhatsApp 可能检测到自动化行为并限制账号
- 建议使用专用手机号（非主要个人账号）作为 Bot 账号
- 避免发送大量消息，以免触发 WhatsApp 的垃圾邮件检测
保持手机联网
WhatsApp Web 桥接依赖手机与 WhatsApp 服务器保持连接。如果手机断网或 WhatsApp 被杀后台，桥接可能中断，需要重新扫码配对。
QR 码过期
QR 码有效期约为 60 秒。如果未能及时扫描，重新运行 hermes whatsapp 获取新 QR 码。
重新配对
如果需要重新配对（如换手机或连接中断）：
bash
# 清除旧的会话数据
rm -rf ~/.hermes/whatsapp-session/
# 重新运行配置
hermes whatsapp常见问题
扫码后很快断开连接？
- 确认手机上的 WhatsApp 保持在前台或后台运行
- 检查手机网络连接是否稳定
- 部分 Android 手机的省电模式会杀掉 WhatsApp 后台，需关闭
提示 Node.js 版本不兼容？
- 确认 Node.js 版本为 v22 或更高：
node --version - 使用 nvm 切换版本：
nvm use 22
消息发送后没有回复？
- 检查你的手机号是否在
WHATSAPP_ALLOWED_USERS中 - 运行
hermes gateway status查看网关状态 - 运行
hermes doctor诊断问题