问题现象
用 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 --version2. 优化代理设置 — 如果你通过 clash 等代理连 QQ 服务器，代理的 idle timeout 建议设为 120 秒以上（QQ 心跳间隔 60 秒）。更好的做法是让 QQ API 流量走直连，不经过代理。
3. 配置自动重启 — 让进程挂掉后自动拉起：
systemd 方式：
[Service]
Restart=always
RestartSec=10Docker 方式：
restart: unless-stopped4. 手动恢复 — 出问题时快速重启：
hermes gateway restart进阶方案
5. 健康检查脚本 — 用 crontab 定期检测，断连自动重启：
*/5 * * * * curl -s http://localhost:16648/health || docker restart hermes6. 关注相关 Issue 进度：
#14539：重连耗尽后静默退出（已修复合并）
#15490：网络异常时适配器静默死亡（部分场景仍存在）
时间线
2026 年 3 月：社区用户报告 QQ Bot 静默断连问题（#14539）
2026 年 4 月：PR #14565 提交修复，重连耗尽时正确通知 Gateway 退出
-
2026 年 4 月 24 日：#15490 报告了网络中断导致适配器静默死亡的更深层问题
截至 2026 年 5 月：#15490 的修复尚未合并，网络波动场景下的静默死亡可能仍存在一句话总结Hermes QQ Bot 掉线不是你的锅，是已知 bug。最务实的做法：升级到最新版 + 配好自动重启 + 优化代理超时。
