跳到主要内容

Open WebUI 集成

Open WebUI（126k★）是最受欢迎的自托管 AI 聊天界面。通过 Hermes Agent 内置的 API 服务器，你可以将 Open WebUI 作为 agent 的精致 Web 前端 — 包括对话管理、用户账户和现代聊天界面。

架构​

Open WebUI (浏览器 UI, 端口 3000) → POST /v1/chat/completions → hermes-agent 网关 API 服务器 (端口 8642)
hermes-agent → SSE 流式响应 → Open WebUI

Open WebUI 连接到 Hermes Agent 的 API 服务器，就像连接 OpenAI 一样。你的 agent 使用其完整工具集处理请求 — 终端、文件操作、网络搜索、记忆、skills — 并返回最终响应。

Open WebUI 使用服务器到服务器通信，因此此集成不需要 API_SERVER_CORS_ORIGINS。

快速设置​

1. 启用 API 服务器​

添加到 ~/.hermes/.env：

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key

2. 启动 Hermes Agent 网关​

hermes gateway

你应该看到：

[API Server] API server listening on http://127.0.0.1:8642

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. 打开 UI​

访问 http://localhost:3000。创建你的管理员账户（第一个用户成为管理员）。你应该在模型下拉列表中看到你的 agent（以你的 profile 命名，或默认 profile 的 hermes-agent）。开始聊天！

Docker Compose 设置​

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1
      - OPENAI_API_KEY=your-secret-key
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: always

volumes:
  open-webui:

然后：

docker compose up -d

通过管理 UI 配置​

如果希望通过 UI 而非环境变量配置连接：

  1. 登录 Open WebUI（http://localhost:3000）
  2. 点击你的头像 → Admin Settings
  3. 进入 Connections
  4. 在 OpenAI API 下，点击扳手图标（Manage）
  5. 点击 + Add New Connection
  6. 输入：
    • URL：http://host.docker.internal:8642/v1
    • API Key：你的密钥或任何非空值
  7. 点击勾选验证连接
  8. 保存
注意

环境变量仅在 Open WebUI 首次启动时生效。之后，连接设置存储在其内部数据库中。如需更改，请使用管理 UI 或删除 Docker 卷重新开始。

工作原理​

当你在 Open WebUI 中发送消息时：

  1. Open WebUI 发送带有你的消息和对话历史的 POST /v1/chat/completions 请求
  2. Hermes Agent 创建带有完整工具集的 AIAgent 实例
  3. Agent 处理你的请求 — 可能调用工具（终端、文件操作、网络搜索等）
  4. 工具执行时，内联进度消息流式传输到 UI，你可以看到 agent 正在做什么
  5. Agent 的最终文本响应流式返回到 Open WebUI
  6. Open WebUI 在聊天界面中显示响应
工具进度

启用流式传输后（默认），你会在工具运行时看到简短的内联指示器 — 工具表情符号及其关键参数。这些出现在响应流中 agent 最终答案之前，让你了解幕后发生的事情。

配置参考​

Hermes Agent（API 服务器）​

变量默认值描述
API_SERVER_ENABLEDfalse启用 API 服务器
API_SERVER_PORT8642HTTP 服务器端口
API_SERVER_HOST127.0.0.1绑定地址
API_SERVER_KEY(必填)认证的 Bearer 令牌

Open WebUI​

变量描述
OPENAI_API_BASE_URLHermes Agent 的 API URL（包含 /v1）
OPENAI_API_KEY必须非空。与你的 API_SERVER_KEY 匹配

故障排除​

下拉列表中没有模型​

  • 检查 URL 有 /v1 后缀：http://host.docker.internal:8642/v1（不只是 :8642）
  • 验证网关正在运行：curl http://localhost:8642/health 应返回 {"status": "ok"}
  • 检查模型列表：curl http://localhost:8642/v1/models 应返回包含 hermes-agent 的列表
  • Docker 网络：在 Docker 内部，localhost 指的是容器而非你的主机。使用 host.docker.internal 或 --network=host

连接测试通过但没有模型加载​

这几乎总是缺少 /v1 后缀。Open WebUI 的连接测试是基本连接性检查 — 不验证模型列表是否有效。

响应花费很长时间​

Hermes Agent 可能在生成最终响应之前执行多个工具调用（读取文件、运行命令、搜索网络）。对于复杂查询这是正常的。

"Invalid API key" 错误​

确保 Open WebUI 中的 OPENAI_API_KEY 与 Hermes Agent 中的 API_SERVER_KEY 匹配。

使用 profiles 的多用户设置​

要为每个用户运行独立的 Hermes 实例 — 各自具有自己的配置、记忆和 skills — 使用 profiles。每个 profile 在不同端口上运行自己的 API 服务器，并自动在 Open WebUI 中将 profile 名称作为模型名称进行宣传。

1. 创建 profiles 并配置 API 服务器​

hermes profile create alice
hermes -p alice config set API_SERVER_ENABLED true
hermes -p alice config set API_SERVER_PORT 8643
hermes -p alice config set API_SERVER_KEY alice-secret

hermes profile create bob
hermes -p bob config set API_SERVER_ENABLED true
hermes -p bob config set API_SERVER_PORT 8644
hermes -p bob config set API_SERVER_KEY bob-secret

2. 启动每个网关​

hermes -p alice gateway &
hermes -p bob gateway &

3. 在 Open WebUI 中添加连接​

在 Admin Settings → Connections → OpenAI API → Manage 中，为每个 profile 添加一个连接：

连接URLAPI Key
Alicehttp://host.docker.internal:8643/v1alice-secret
Bobhttp://host.docker.internal:8644/v1bob-secret

模型下拉列表将显示 alice 和 bob 作为不同模型。你可以通过管理面板将模型分配给 Open WebUI 用户，为每个用户提供了独立的 Hermes agent。