如何解决 Hermes Agent 中 QQ Bot “灵魂不在线”

问题现象

用 QQ Bot 连接 Hermes 时，经常收到“该机器人的'灵魂'不在线，请检查它的主机服务部署环境”的提示。意思很简单：QQ 端认为你的机器人掉线了，消息发不过去。

原因分析

这不是配置问题。Hermes 的 GitHub 上有两个已被确认的 bug（#14539 和 #15490），都指向同一件事：QQ Bot 适配器的 WebSocket 连接断了之后，没有正确恢复。

具体来说，有两层故障叠加：

第一层：网络波动时重连逻辑漏捕异常

QQ Bot 通过 WebSocket 长连接与腾讯服务器（wss://api.sgroup.qq.com/websocket）通信。当网络出现短暂中断，比如代理切换、Wi-Fi 闪断、VPN 重连，适配器的重连代码没有正确捕获 httpx.ConnectError、TLS 握手失败、代理 CONNECT 失败这类底层异常。结果是整个适配器任务直接退出，连一行错误日志都没有留下。

第二层：重连耗尽后静默退出

即使重连逻辑正常触发，连续尝试 100 次后（约 100 分钟），_listen_loop() 函数直接 return，不通知 GatewayRunner。这时候：

• Gateway 进程还活着，Telegram 等其他平台正常

• QQ 适配器已经死了，但状态文件还显示 qqbot: connected

• systemd 不会重启，因为进程没有退出

这样在 QQ 端看到的就是那句“该机器人的'灵魂'不在线，请检查它的主机服务部署环境”。

解决方案

1. 升级 Hermes 到最新版本 — 修复 PR #14565 已经让重连耗尽时调用 _set_fatal_error()，Gateway 收到通知后会退出，触发 systemd 或 Docker 重启。检查你当前版本：

hermes --version

2. 优化代理设置 — 如果你通过 clash 等代理连 QQ 服务器，代理的 idle timeout 建议设为 120 秒以上（QQ 心跳间隔 60 秒）。更好的做法是让 QQ API 流量走直连，不经过代理。

3. 配置自动重启 — 让进程挂掉后自动拉起：

systemd 方式：

[Service]
Restart=always
RestartSec=10

Docker 方式：

restart: unless-stopped

4. 手动恢复 — 出问题时快速重启：

hermes gateway restart

进阶方案

5. 健康检查脚本 — 用 crontab 定期检测，断连自动重启：

*/5 * * * * curl -s http://localhost:16648/health || docker restart hermes

6. 关注相关 Issue 进度：

• #14539：重连耗尽后静默退出（已修复合并）

• #15490：网络异常时适配器静默死亡（部分场景仍存在）

时间线

• 2026 年 3 月：社区用户报告 QQ Bot 静默断连问题（#14539）

• 2026 年 4 月：PR #14565 提交修复，重连耗尽时正确通知 Gateway 退出

• 2026 年 4 月 24 日：#15490 报告了网络中断导致适配器静默死亡的更深层问题

  截至 2026 年 5 月：#15490 的修复尚未合并，网络波动场景下的静默死亡可能仍存在一句话总结Hermes QQ Bot 掉线不是你的锅，是已知 bug。最务实的做法：升级到最新版 + 配好自动重启 + 优化代理超时。