跳到主要内容

Open WebUI

Open WebUI 是目前最流行的自托管 AI 聊天界面之一。借助 Hermes Agent 内置的 API Server，你可以把 Open WebUI 作为 Hermes 的网页前端，获得更完善的会话管理、用户账号和现代聊天界面。

架构​

Open WebUI 连接 Hermes Agent API Server 的方式与连接 OpenAI 完全相同。你的 agent 会用完整工具集处理请求，包括终端、文件操作、网页搜索、记忆和技能，然后返回最终响应。

快速设置​

1. 启用 API Server​

在 ~/.hermes/.env 中加入：

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key

2. 启动 Hermes Agent 网关​

hermes gateway

3. 启动 Open WebUI​

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

4. 打开界面​

访问 http://localhost:3000。创建管理员账号后，你会在模型下拉框中看到 agent（默认 profile 显示为 hermes-agent）。

API 类型：Chat Completions 与 Responses​

ModeFormatWhen to use
Chat Completions (default)/v1/chat/completions推荐，开箱即用
Responses (experimental)/v1/responses适合需要 previous_response_id 的场景

使用 Chat Completions（推荐）​

这是默认模式，不需要额外配置。Open WebUI 发送标准 OpenAI 格式请求，Hermes Agent 按同样格式返回。

使用 Responses API​

  1. 打开 Admin Settings → Connections → OpenAI → Manage
  2. 编辑 hermes-agent 连接
  3. 将 API Type 从 “Chat Completions” 改成 “Responses (Experimental)”
  4. 保存

工作流程​

  1. Open WebUI 向 POST /v1/chat/completions 发送请求
  2. Hermes Agent 创建一个带完整工具集的 AIAgent 实例
  3. agent 处理请求，期间可能调用工具
  4. 工具执行期间，进度消息会以内联形式流式显示在 UI 中
  5. 最终响应流式返回给 Open WebUI

配置参考​

Hermes Agent（API Server）​

VariableDefaultDescription
API_SERVER_ENABLEDfalse启用 API Server
API_SERVER_PORT8642HTTP 服务端口
API_SERVER_HOST127.0.0.1绑定地址
API_SERVER_KEY(required)Bearer Token，需与 OPENAI_API_KEY 一致

Open WebUI​

VariableDescription
OPENAI_API_BASE_URLHermes Agent API 地址（需包含 /v1）
OPENAI_API_KEY必须为非空；应与 API_SERVER_KEY 保持一致

故障排除​

  • 模型下拉框为空：检查 URL 是否包含 /v1，并确认 curl http://localhost:8642/v1/models 有返回
  • 连接测试通过但没有模型：通常还是因为少了 /v1
  • 响应较慢：复杂请求下，Hermes 可能需要执行多个工具调用，这属于正常现象
  • “Invalid API key”：确认 Open WebUI 中的 OPENAI_API_KEY 与 Hermes 中的 API_SERVER_KEY 一致