控制 Hermes - 插件版
INFO
小智是一款实时语音交互助手，Hermes 是一个开源的 AI Agent 网关，支持接入多种智能体和工具。通过安装 xiaozhi-pro 插件，你可以用语音指挥小智调度 Hermes 上的智能体，让小智成为你的 AI 助手调度中心。
TIP
无需公网 IP，只需给 Hermes 安装 xiaozhi-pro 插件即可自动连接，消息实时双向推送，体验流畅。
1. 基本原理
小智设备与 Hermes 通过 WebSocket 长连接 通信，由 Hermes 端的插件主动连接到小智Pro服务端：
小智设备 ────> 小智Pro服务端 <──(WebSocket)──> Hermes (xiaozhi-pro 插件主动连入)
│ │
小智设备 <──── 小智Pro服务端 <──(WS 实时推送)────┘小智服务端和 Hermes 内部之间隔着一层插件，插件做双向翻译：
方向1：小智 → Hermes（用户发消息）
小智服务端 Hermes 小智插件 Hermes 内部
┌──────────┐ WS: ┌──────────────┐ ┌──────────┐
│ push_to │──{"type": │ WS client │ handle_ │ │
│ hermes │─ "message", │ 收到 │──inbound() 派发 │─ agent │
│ │ "text":"你好"} │ │ MessageEvent │ 处理 │
└──────────┘ └──────────────┘ └──────────┘
方向2：Hermes → 小智（agent 回复）
Hermes 内部 Hermes 小智插件 小智服务端
┌──────────┐ ┌──────────────┐ WS: ┌──────────┐
│ agent │──→ send() │ WS client │──{"type": │ _message_│
│ 回复 │ │ .send_json() │─ "response",...}│ loop 收到│
└──────────┘ └──────────────┘ └──────────┘1.1 连接建立
- 用户在小智Pro平台获取 API 密钥
- 在 Hermes 上配置 xiaozhi-pro 插件，填入 API 密钥
- 重启 Hermes 网关，插件自动通过 WebSocket 连接到小智Pro服务端
- 插件发送
auth消息完成认证，认证成功后进入双向通信
1.2 消息投递策略
插件发来的 response 消息有两种来源，通过 device_id 是否存在区分投递策略：
| 来源 | 触发场景 | device_id | 投递策略 |
|---|---|---|---|
| 回复（reply） | 用户发消息 → agent 回复 | ✅ 有值 | 精确投递到该设备 |
| 主动推送（push） | cron 定时任务、agent 主动发起 | ❌ 为空 | 广播该用户所有设备 |
1.3 关键设计
| 特性 | 说明 |
|---|---|
| 实时通信 | WebSocket 全双工长连接，消息即时推送，无轮询延迟 |
| 无需公网 | Hermes 主动连接服务端，无需暴露端口 |
| 心跳保活 | 30 秒心跳检测，60 秒无响应自动断开 |
| 自动重连 | 插件内置指数退避重连（3s → 6s → 12s → ... → 60s 上限） |
| 消息去重 | 适配器侧 dedup 保证幂等，重复推送自动跳过 |
| 精确投递 | 支持指定设备投递或广播所有设备 |
| 自动踢旧 | 同一账号新连接自动踢掉旧连接 |
2. 操作指南
太长不看版
让 Hermes 自己搞定插件安装和配置，把下面这段文字发给它：
请帮我安装并配置小智Pro Hermes插件，参考这个 GitHub 仓库的 README 操作：https://github.com/hougeai/xiaozhi-pro-hermes-plugin
2.1 获取 API 密钥
WARNING
API 密钥是插件连接小智Pro的唯一凭证，请勿泄露给他人。
2.2 安装插件
将插件下载到 Hermes 的平台插件目录（目录名必须为 xiaozhi_pro，下划线，不能用连字符）：
方式 A：git clone
git clone https://github.com/HougeAI/xiaozhi-pro-hermes-plugin.git ~/.hermes/hermes-agent/plugins/platforms/xiaozhi_pro方式 B：下载压缩包
- 从 GitHub Releases 下载最新版压缩包
- 解压到
~/.hermes/hermes-agent/plugins/platforms/xiaozhi_pro/
mkdir -p ~/.hermes/hermes-agent/plugins/platforms/xiaozhi_pro
unzip xiaozhi-pro-hermes-plugin-*.zip -d ~/.hermes/hermes-agent/plugins/platforms/xiaozhi_proWARNING
目录名必须是 xiaozhi_pro（Python 模块要求），否则 Hermes 无法加载插件。
2.3 配置连接
在 ~/.hermes/config.yaml 中添加：
platforms:
xiaozhi_pro:
extra:
token: '你的API密钥'- 本插件属于 bundled platform 插件，Hermes 会自动加载，无需在
plugins.enabled中声明 - 只要配置了
token，网关启动时就会自动连接 - 也可以通过环境变量
XIAOZHI_PRO_TOKEN设置 Token - 要禁用连接，注释掉或删除
token即可（同时确保XIAOZHI_PRO_TOKEN环境变量未设置）
2.4 重启 Hermes 网关
hermes gateway restart插件会自动连接小智Pro 服务端，发送 {"type":"auth","token":"..."} 完成认证后进入双向通信。
查看 Hermes 日志确认连接状态：
tail -f ~/.hermes/logs/gateway.log日志中应出现 [XiaoZhiPro] Connecting to ... 和 [XiaoZhiPro] Auth OK。
2.5 验证连接
- 进入小智Pro控制台，点击左侧菜单 设备端MCP → Hermes插件版
- 点击 检查连接 按钮
- 如果显示绿色"已连接"标签，说明插件已成功连接
2.6 测试发送消息
在 Hermes 插件版页面底部：
- 选择目标设备：从下拉框选择要接收回复的小智设备（留空则广播到所有设备）
- 输入消息内容：输入要发送给 Hermes 的消息
- 点击 发送 或按 Enter 键
发送成功后，稍等片刻点击 刷新 按钮查看 Hermes 的回复记录。
2.7 通过设备语音操控
配置好连接后，你可以直接对小智说：
- '问问爱马仕现在都有哪些定时任务'
- '让爱马仕给我的飞书发一条消息'
- '让爱马仕立刻完成今天的AI资讯整理任务'Hermes 回复后，服务端会自动推送到设备，设备随即播报回复内容。
2.8 首次连接配对
服务端首次通过 xiaozhi_pro 通道连接 Hermes 会生成一个配对码，需在终端执行配对命令。配对成功后适配器即可接收来自已配对设备的消息。例如：
Hi~ I don't recognize you yet!
Here's your pairing code: B8XWG5HE
Ask the bot owner to run: hermes pairing approve xiaozhi_pro B8XWG5HE
3. 常见问题
连接状态显示"未连接"？
- 确认插件已启用：
hermes plugins list查看platforms/xiaozhi_pro是否为 enabled - 检查
~/.hermes/config.yaml中platforms.xiaozhi_pro.extra.token是否配置了有效的 API 密钥 - 检查 Hermes 服务是否正常运行
- 检查网络是否正常
- 查看 Hermes 日志排查连接错误：
tail -f ~/.hermes/logs/gateway.log
插件连接后频繁断开？
- 检查网络稳定性
- 确认 Hermes 服务器时间同步（NTP）
- 插件内置自动重连机制（指数退避），短暂断开后会自动恢复
- 服务端 30 秒心跳检测，60 秒无 pong 响应会断开，插件会自动重连
设备端没有收到 Hermes 的回复？
- 确认设备已绑定到小智Pro账号
- 确认控制台显示"已连接"状态
- 如果设备正在说话，服务端会自动等待，最多等待 120 秒，消息最多缓存 1 天
启动时报 "No adapter available for xiaozhi_pro"？
- 确认插件目录名是
xiaozhi_pro（下划线，不是连字符） - 确认
config.yaml中platforms.xiaozhi_pro.extra.token已配置，或环境变量XIAOZHI_PRO_TOKEN已设置 - 确认已安装 aiohttp 依赖：
pip install aiohttp