如果你也在折腾自己的 AI Agent，本地命令行能跑起来只是第一步。
真正让它“可用”的关键，是把它接到一个顺手的 Web 界面里，让自己可以像用 ChatGPT 那样直接聊天。
今天我做的一件事，就是把 Hermes Agent 跑起来，再把它通过 OpenAI 兼容 API 接到 Open WebUI，最终实现：
- Hermes 负责后端 Agent 能力
- Open WebUI 负责前端聊天界面
- 浏览器里直接选模型，直接对话
中间踩了几轮坑，但最后通了。
这篇文章就把完整过程写下来，方便后来人少走弯路。
一、为什么选这套组合
先说结论，这套组合我觉得很合理：
- Hermes Agent 擅长做 Agent、工具调用、终端执行、工作流
- Open WebUI 擅长做可视化聊天入口
- Hermes 自带 OpenAI 兼容 API server
- Open WebUI 本身就支持接 OpenAI 兼容后端
也就是说，不需要自己再写一层适配器，Hermes 和 Open WebUI 天然就能接上。
这比“给 Hermes 单独找一个网页聊天前端”要稳得多。
二、当前环境情况
我这次是在一台 Linux 服务器上操作，核心目标是：
- 安装并跑起 Hermes Agent
- 启用 Hermes 的 API Server
- 用 Docker 拉起 Open WebUI
- 让 Open WebUI 正确连接 Hermes
- 在网页里看到可选模型并开始聊天
Hermes 这边最终用到的关键接口是：
- API Server 地址：
127.0.0.1:8642 - API Key：
wc-hermes-local-key
Open WebUI 连接的其实就是这个 OpenAI 兼容接口。
三、第一步，先确认 Hermes API Server 能跑
Hermes 不是只能跑在终端里，它还能暴露一个 OpenAI 兼容 API。
这是整个方案成立的前提。
我这边配置里关键环境变量大概是这样：
bashCopy
API_SERVER_ENABLED=true
API_SERVER_HOST=127.0.0.1
API_SERVER_PORT=8642
API_SERVER_KEY=wc-hermes-local-key也就是说，Hermes 会在本机监听：
bashCopy
127.0.0.1:8642如果它正常起来，理论上就应该能通过下面这个接口拿到模型列表：
bashCopy
curl http://127.0.0.1:8642/v1/models \
-H "Authorization: Bearer wc-hermes-local-key"这一点非常关键。
如果这一步不通，后面的 Open WebUI 一定也不通。
四、第二步，发现服务器上居然没装 Docker
一开始我想直接把 Open WebUI 拉起来，结果一查：
bashCopy
docker --version系统直接告诉我：
bashCopy
docker: command not found那就没什么好说的，先装 Docker。
Ubuntu 上直接执行：
bashCopy
apt update
apt install -y docker.io
systemctl enable --now docker
docker --version安装完成后再确认：
bashCopy
systemctl status docker --no-pager只要看到：
bashCopy
active (running)就说明 Docker 已经准备好了。
五、第三步，第一次拉起 Open WebUI
Docker 有了以后，先按最常见的桥接网络方式启动 Open WebUI：
bashCopy
docker run -d \
--name open-webui \
-p 3000:8080 \
-e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
-e OPENAI_API_KEY=wc-hermes-local-key \
--add-host=host.docker.internal:host-gateway \
-v open-webui:/app/backend/data \
--restart unless-stopped \
ghcr.io/open-webui/open-webui:main这个命令的思路是：
- 容器内部通过
host.docker.internal去访问宿主机上的 Hermes - 对外暴露网页端口
3000 - Open WebUI 把 Hermes 当作 OpenAI 兼容后端来连接
容器本身其实很快就起来了，而且健康检查也是通过的。
表面上看一切正常，但真正打开页面后，问题出现了。
六、第四步，页面能打开，但提示“未选择模型”
这一步特别迷惑，因为表面症状是：
- Open WebUI 页面可以打开
- 容器状态 healthy
- 但是网页里提示 未选择模型
这时候如果经验不足，很容易误以为是 Open WebUI 本身坏了，或者前端刷新有问题。
但真正去看日志后，就会发现根因在后端连接：
bashCopy
docker logs --tail 100 open-webui日志里出现了类似报错：
bashCopy
Cannot connect to host host.docker.internal:8642这说明不是“没有模型”，而是 Open WebUI 根本连不上 Hermes API。
七、第五步，定位根因，Hermes 只监听了 127.0.0.1
继续往下看，就能发现问题本质：
Hermes API Server 监听的是：
bashCopy
127.0.0.1:8642而 Docker bridge 网络下的容器，访问宿主机时并不能天然把这个地址当作自己的 localhost。
虽然配了 host.docker.internal，但 Hermes 只绑定在 127.0.0.1，导致容器侧访问失败。
这就是为什么：
- Open WebUI 页面能开
- 但模型列表拉不下来
- 最终表现成“未选择模型”
八、第六步，把 Open WebUI 改成 host 网络模式
最稳的处理方法，不是继续硬折腾 bridge 网络，而是直接把 Open WebUI 改成 host 网络模式。
先删掉旧容器：
bashCopy
docker rm -f open-webui然后重新启动：
bashCopy
docker run -d \
--name open-webui \
--network host \
-e OPENAI_API_BASE_URL=http://127.0.0.1:8642/v1 \
-e OPENAI_API_KEY=wc-hermes-local-key \
-v open-webui:/app/backend/data \
--restart unless-stopped \
ghcr.io/open-webui/open-webui:main这一步的意义很大：
- Open WebUI 容器直接共享宿主机网络
- 它访问
127.0.0.1:8642，就等于直接访问宿主机上的 Hermes API - 不再依赖
host.docker.internal - 连接路径一下子变简单了
这也是这次折腾里最关键的修正之一。
九、第七步，又踩到一个坑，Hermes API Server 根本没常驻
本来以为改成 host 网络模式就行了，结果一测：
bashCopy
curl http://127.0.0.1:8642/v1/models \
-H "Authorization: Bearer wc-hermes-local-key"返回的是：
bashCopy
curl: (7) Couldn't connect to server这就说明另一个更底层的问题：
Hermes API Server 当时根本没在运行。
也就是说，前面看起来像“容器连不上宿主机”，其实还有一层原因是：
- Hermes 并没有稳定常驻
- 8642 端口没有持续监听
于是就得回头先把 Hermes API Server 真正跑起来。
十、第八步，重新启动 Hermes API Server
Hermes 这边最后是用后台方式启动的。
进入目录：
bashCopy
cd ~/.hermes/hermes-agent
source .venv/bin/activate
mkdir -p ~/.hermes/logs
nohup python cli.py -g > ~/.hermes/logs/api-server.log 2>&1 &然后检查端口：
bashCopy
ss -ltnp | grep 8642看到类似输出：
bashCopy
LISTEN 0 128 127.0.0.1:8642 0.0.0.0:* users:(("python",pid=xxxx,fd=16))这就对了。
再测一次：
bashCopy
curl http://127.0.0.1:8642/v1/models \
-H "Authorization: Bearer wc-hermes-local-key"只要这一步不再报连接失败，说明 Hermes 端已经通了。
十一、第九步，Open WebUI 终于识别到了模型
Hermes API Server 跑起来之后，再回到 Open WebUI 页面刷新，就能看到模型出来了。
最终页面里能看到可选项：
hermes-agent
这就说明整条链路已经打通：
- Hermes API 正常返回模型
- Open WebUI 成功读取模型列表
结尾
今天这次折腾最大的感受是：
很多 AI 工具真正难的不是“能不能装”，而是“装完之后链路有没有全部打通”。
Hermes、Docker、Open WebUI，这三个东西单看都不难。
真正容易出问题的是它们之间的连接关系：
- API 是否常驻
- 端口是否可达
- 容器网络是否通
- 模型列表是否返回
一旦这些点理顺，体验其实挺顺的。
如果你也在折腾 Hermes + Open WebUI，这篇文章希望能帮你少踩几个坑。