梦行志AionUi 连接 Hermes 502 Bad Gateway：一个缺失的 Python 依赖包
排查日志里的一句 'ACP dependencies not installed'，让我追踪到 Hermes 与 AionUi 之间真正的通信链路
在 AionUi 里和 Hermes Agent 对话，页面直接弹窗：
Failed to send message. Please try again.
随后日志给出更详细的报错：
Failed to process: Message send failed: Bad gateway: Agent process exited before initialize handshake completed (exit code 1)
表面上看是"网关问题"，但真正的罪魁祸首，是一行被忽略的 pip install。
排查过程
第一步：检查 Hermes Gateway 是否在运行
hermes gateway status
→ ✗ Gateway is not runningGateway 没跑，先装服务、再启动，这是直觉反应：
echo -e "y\ny" | hermes gateway install
# 安装成功，服务已启动再次查看状态，服务已经正常监听 127.0.0.1:8642。到这里，第一直觉"Gateway 挂了"已经被排除。
第二步：查看 AionUi 日志，找到真正的错误
问题出现在这一步。翻看 ~/.config/AionUi/logs/2026-05-23.aioncore.log，发现关键报错：
Agent process exited before ACP handshake completed
stderr: ACP dependencies not installed.
Install them with: pip install -e '.[acp]'根因：Hermes 的 ACP（Agent Client Protocol）Python 依赖未安装。
AionUi 连接 Hermes 的方式有两种：
- OpenClaw WebSocket —
ws://127.0.0.1:18789（正常） - Hermes ACP 子进程 — 启动
hermes acp子进程通过 stdio/JSON-RPC 通信（失败）
AionUi 的 Hermes Agent 集成走的是 ACP 协议，不是 Gateway 的 HTTP API。这意味着即使 Gateway 正常运行，只要 ACP 依赖缺失，对话就会报 502。
第三步：安装 ACP 依赖
cd /home/oklife/.hermes/hermes-agent
.venv/bin/pip install -e ".[acp]"关键安装包：
agent-client-protocol==0.9.0（ACP 协议库）hermes-agent==0.14.0（可编辑模式重新安装）
注意： 不能用系统 pip（PEP 668 限制），必须用 Hermes 自己的 .venv。
第四步：重启并验证
systemctl --user restart hermes-gateway再次确认状态，AionUi 重新发送消息，Hermes Agent 正常响应。
关键知识点
ACP vs API Server vs OpenClaw WebSocket
| 协议 | 用途 | 通信方式 | 端口 |
|---|---|---|---|
| ACP | AionUi / VS Code / Zed 等编辑器集成 | stdio 子进程 + JSON-RPC | 无（stdio） |
| API Server | HTTP REST 接口，给其他程序调用 | HTTP | Gateway .env 中配置 |
| OpenClaw WebSocket | OpenClaw 网关通信 | WebSocket | 18789 |
AionUi 连接 Hermes Agent 必须装 ACP 依赖，否则子进程启动后立即退出（exit code 1），报 502 Bad Gateway。这是最容易踩的坑：看到 502 第一反应是查 Gateway，实际上 Gateway 根本没收到请求。
环境信息
- Hermes v0.14.0
- ACP 依赖：
agent-client-protocol==0.9.0 - Hermes venv：
/home/oklife/.hermes/hermes-agent/.venv - Gateway 端口：8642
- OpenClaw 端口：18789
- AionUi 配置目录：
~/.config/AionUi/
关联阅读
- [[AionUi上连接的你为什么没反应了？显示：Hermes Agent Hermes Agent 会话活跃中]]
- [[点venv环境配置]]
参考来源
–全文完–
“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”
转载请注明来自https://oklife.me。
