为你的 Hermes Agent 套上最优雅的壳：Open WebUI 接入指南

写命令行工具很爽，用终端对话很硬核，但总有那么几天，你盯着漆黑的终端会觉得眼睛疼，或者你需要把强大的 Agent 分享给不懂命令行的麻瓜朋友。这时候，你需要一个体面的前端。

Open WebUI (126k★) 就是目前开源界最能打的自托管对话界面。今天我们来聊聊，怎么把底层生猛的 Hermes Agent 接入到 Open WebUI，让它看起来像个正经的商业 SaaS。

核心架构：套皮，但不只套皮

原理很简单：Open WebUI 把自己当客户端，Hermes Agent 把自己伪装成一个兼容 OpenAI 格式的 API Server。

当你在网页里敲字时，Open WebUI 发送标准的 /v1/chat/completions 请求；Hermes 在后台接单，该跑脚本跑脚本，该查网页查网页，忙活完之后把结果流式推回前端。

划重点： 这种服务器对服务器的通信，你不需要去折腾烦人的 API_SERVER_CORS_ORIGINS，省了一步踩坑。

极速上手：能 Docker 解决的绝不手敲

Step 1. 开启 Hermes 的 API 模式
在你的 ~/.hermes/.env 里塞入：

1
2

API_SERVER_ENABLED=true
API_SERVER_KEY=你要的密码随便填

Step 2. 启动网关

1

hermes gateway

看到 [API Server] API server listening on http://127.0.0.1:8642 就说明起飞了。

Step 3. 部署 Open WebUI
如果你用 Docker，直接一条命令干就完了（注意看 --add-host 参数，别怪我没提醒你）：

1
2
3
4
5
6
7
8

docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
  -e OPENAI_API_KEY=你要的密码随便填 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

如果你有代码洁癖，必须用 docker-compose.yml，那格式自己抄官方文档，重点也是配置好 OPENAI_API_BASE_URL 和 extra_hosts。

Step 4. 浏览器见
打开 http://localhost:3000，注册个管理员账号，在模型下拉框里选中 hermes-agent，享受你的图形界面吧。

常见弱智问题（Troubleshooting）

我知道你们肯定会遇到问题，提前把解药准备好了。如果看完这段你还是连不上，建议回去重修网络基础。

1. 模型列表空空如也？

   • 检查 URL 有没有带 /v1 后缀！必须是 http://.../v1，别给我省字符。
   • host.docker.internal 没配好。在 Linux 纯净环境下，Docker 默认不认这玩意儿，乖乖用 --network=host 模式，或者手动指定网桥 IP (172.17.0.1)。

2. 响应巨慢无比？

   • 稳住，别砸键盘。Hermes Agent 在后台可能正在疯狂写代码、跑测试、查资料。它干实事需要时间，不要拿它和那种只会吐废话的单纯聊天机器人比速度。

3. 测试连接通过，但还是没模型？

   • 又是你忘了加 /v1。Open WebUI 的连通性测试有时候就像在逗你玩，只测 IP 活不活，不测 API 对不对。

把 Hermes 接到 Web 端后，你会发现 Agent 依然保留了流式输出工具执行状态的能力（比如 💻 ls -la 会闪现一下）。这感觉就像是你坐在高档餐厅里，透过开放式厨房看着大厨怎么颠勺一样，极度治愈。

就说这么多，赶紧去部署吧。如果连这几行命令都能跑报错，那可能是玄学问题，建议重启。

如果代码能一次编译通过，那一定是有鬼。

本文由 BOSH 的博客助手 HerMes 整理！ 原文链接：https://hermes-agent.nousresearch.com/docs/user-guide/messaging/open-webui