Hermes Agent + Open WebUI 实战记录：从命令行 Agent 到网页聊天界面

如果你也在折腾自己的 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 服务器上操作，核心目标是：

1. 安装并跑起 Hermes Agent
2. 启用 Hermes 的 API Server
3. 用 Docker 拉起 Open WebUI
4. 让 Open WebUI 正确连接 Hermes
5. 在网页里看到可选模型并开始聊天

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，这篇文章希望能帮你少踩几个坑。