Open WebUI 集成——网页聊天界面 | Easy Understand Hermes Agent

这篇教程教你如何用 Open WebUI 给 Hermes Agent 配一个漂亮的网页聊天界面，像用 ChatGPT 一样跟你的智能体对话。

为什么需要 Open WebUI？

Open WebUI 是 GitHub 上 12.6 万星的开源项目，相当于给 AI 装了个「微信」。Hermes Agent 自带 API 服务器，两者一接，你就能在浏览器里聊天、管理会话、注册账号，界面现代又流畅。

打个比方：Hermes Agent 是大脑，Open WebUI 是脸面。大脑负责思考干活，脸面负责让你看得舒服。

架构原理

浏览器 (Open WebUI, 端口 3000)  →  Hermes Agent API 服务器 (端口 8642)
        ↓ 发送请求                              ↓ 处理并流式返回

重要提醒：API 服务器是智能体运行时，不是纯模型代理。每次请求，Hermes 都会在服务器上创建一个 AIAgent，工具调用（终端、文件、浏览器等）都在服务器那台机器上执行。如果你的服务器在远程，工具就跑在远程，不在你本地电脑上。

第 1 步：开启 API 服务器

打开终端，执行：

hermes config set API_SERVER_ENABLED true
hermes config set API_SERVER_KEY your-secret-key

第一条命令把开关写进 config.yaml，第二条把密钥存到 ~/.hermes/.env。如果网关已在运行，重启生效：

hermes gateway stop && hermes gateway

看到 API server listening on http://127.0.0.1:8642 就成功了。

第 2 步：验证服务器

curl -s http://127.0.0.1:8642/health
# {"status": "ok", ...}

curl -s -H "Authorization: Bearer your-secret-key" http://127.0.0.1:8642/v1/models
# {"object":"list","data":[{"id":"hermes-agent", ...}]}

如果 /health 失败，说明网关没读到配置，重启一下。如果 /v1/models 返回 401，检查密钥是否一致。

第 3 步：启动 Open WebUI

用 Docker 一条命令搞定：

docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
  -e OPENAI_API_KEY=your-secret-key \
  -e ENABLE_OLLAMA_API=false \
  --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

ENABLE_OLLAMA_API=false 是关掉默认的 Ollama 后端，免得模型列表里多个空选项。首次启动要 15–30 秒，因为要下载约 150MB 的嵌入模型，等 docker logs open-webui 安静下来再打开界面。

第 4 步：打开网页

浏览器访问 **http://localhost:3000**，注册第一个账号（自动成为管理员）。在模型下拉框里就能看到 hermes-agent，直接开聊！

进阶：用管理界面配置

如果你不想用环境变量，也可以在网页里配：

点右上角头像 → 管理员设置
进入连接 → OpenAI API → 点扳手图标
添加新连接，填 URL http://host.docker.internal:8642/v1 和你的密钥
点对勾验证，保存即可

注意：环境变量只在 Open WebUI 首次启动时生效，之后配置存在数据库里。要改就进管理界面，或者删掉 Docker 卷重来。

小总结

接好之后，你在网页里发消息，Hermes 会带着全套工具（终端、文件、搜索、记忆）干活，工具执行过程会以进度消息流式显示，比如 `💻 ls -la`、`🔍 Python 3.12 release`，最后把答案流式返回。就像有个透明的小助手，每一步都让你看见。

下篇预告：消息平台接入系列继续，下一篇我们聊聊怎么把 Hermes Agent 接进 Discord，让你的智能体在服务器里随时待命。