Skip to main content

Open WebUI 集成

Open WebUI（126k 星标）是目前最受欢迎的自托管 AI 聊天界面。通过 Hermes Agent 内置的 API 服务器，你可以将 Open WebUI 用作你代理的精美网页前端——支持对话管理、用户账户以及现代化的聊天界面。

架构​

Open WebUI 与 Hermes Agent 的 API 服务器连接方式，就像它连接 OpenAI 一样。你的代理会使用其完整的工具集（终端、文件操作、网络搜索、记忆、技能等）处理请求，并返回最终响应。

Open WebUI 以服务间通信的方式与 Hermes 服务器对接，因此你无需 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，创建管理员账户（第一个用户将成为管理员）。你应该能在模型下拉菜单中看到你的代理，名称会显示为你的配置文件名，或默认显示为 hermes-agent。开始聊天吧！

Docker Compose 设置​

为了更持久的部署，创建一个 docker-compose.yml：

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

通过 Admin UI 配置​

如果你更倾向于通过图形界面而非环境变量来配置连接：

  1. 登录 Open WebUI，访问 http://localhost:3000
  2. 点击你的 个人头像 → Admin Settings（管理员设置）
  3. 进入 Connections（连接）
  4. 在 OpenAI API 下，点击 扳手图标（管理）
  5. 点击 + Add New Connection（添加新连接）
  6. 输入：
    • URL: http://host.docker.internal:8642/v1
    • API Key: 任意非空值（例如 not-needed），或你的密钥
  7. 点击 对勾 以验证连接
  8. 保存

此时，你的代理模型应出现在模型下拉菜单中（名称为你的配置文件名，或默认为 hermes-agent）。

warning

环境变量仅在 Open WebUI 首次启动时 生效。之后，连接设置将存储在其内部数据库中。若需后续修改，请使用 Admin UI 或删除 Docker 卷并重新启动。

API 类型：Chat Completions 与 Responses​

当连接后端时，Open WebUI 支持两种 API 模式：

模式格式使用场景
Chat Completions（默认）/v1/chat/completions推荐。开箱即用。
Responses（实验性）/v1/responses用于通过 previous_response_id 实现服务端对话状态管理。

使用 Chat Completions（推荐）​

这是默认模式，无需额外配置。Open WebUI 发送标准 OpenAI 格式的请求，Hermes Agent 会相应地作出回应。每次请求都包含完整的对话历史。

使用 Responses API​

要使用 Responses API 模式：

  1. 进入 Admin Settings → Connections → OpenAI → Manage
  2. 编辑你的 hermes-agent 连接
  3. 将 API Type 从 "Chat Completions" 更改为 "Responses (Experimental)"
  4. 保存

使用 Responses API 时，Open WebUI 以 Responses 格式发送请求（input 数组 + instructions），Hermes Agent 可通过 previous_response_id 保留跨轮次的完整工具调用历史。

note

目前，即使在 Responses 模式下，Open WebUI 仍由客户端管理对话历史——它在每个请求中发送完整的消息历史，而不是依赖 previous_response_id。该模式主要为未来前端演进提供兼容性支持。

工作原理​

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

  1. Open WebUI 发送一个 POST /v1/chat/completions 请求，包含你的消息和对话历史
  2. Hermes Agent 创建一个带有完整工具集的 AIAgent 实例
  3. 代理处理你的请求——可能调用工具（终端、文件操作、网络搜索等）
  4. 工具执行过程中，进度信息会实时流式传输到 UI，让你看到代理正在做什么（例如 `💻 ls -la`, `🔍 Python 3.12 发布`)
  5. 代理的最终文本响应流式返回至 Open WebUI
  6. Open WebUI 在聊天界面中显示响应

你的代理拥有与 CLI 或 Telegram 使用时相同的全部工具和能力——唯一的区别只是前端界面。

工具执行进度

启用流式传输（默认）后，你会看到工具运行时的简短内联提示——包括工具图标及其关键参数。这些提示会在代理最终回答之前出现在响应流中，让你清晰了解后台正在进行的操作。

配置参考​

Hermes Agent（API 服务器）​

变量默认值说明
API_SERVER_ENABLEDfalse启用 API 服务器
API_SERVER_PORT8642HTTP 服务器端口
API_SERVER_HOST127.0.0.1绑定地址
API_SERVER_KEY(必填)认证用的 Bearer Token。需与 OPENAI_API_KEY 匹配

Open WebUI​

变量说明
OPENAI_API_BASE_URLHermes Agent 的 API 地址（需包含 /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 网络问题：在容器内，localhost 指的是容器本身，而非宿主机。请使用 host.docker.internal 或 --network=host。

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

几乎总是因为缺少 /v1 后缀。Open WebUI 的连接测试仅是基础连通性检测——不验证模型列表是否正常工作。

响应耗时过长​

Hermes Agent 可能正在执行多个工具调用（读取文件、运行命令、网络搜索等），才会生成最终响应。对于复杂查询，这是正常现象。代理完成所有操作后，响应将一次性呈现。

“无效 API 密钥”错误​

确保你在 Open WebUI 中填写的 OPENAI_API_KEY 与 Hermes Agent 中的 API_SERVER_KEY 完全匹配。

多用户设置与配置文件​

如需为每位用户运行独立的 Hermes 实例——每个实例拥有自己的配置、记忆和技能——请使用 配置文件。每个配置文件会在不同端口上运行独立的 API 服务器，并自动将其配置文件名作为模型名称在 Open WebUI 中展示。

1. 创建配置文件并配置 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，为每个配置文件添加一条连接：

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

模型下拉菜单将显示 alice 和 bob 作为独立模型。你可通过管理员面板为 Open WebUI 用户分配模型，实现每位用户拥有独立隔离的 Hermes 代理。

自定义模型名称

模型名称默认为配置文件名。如需覆盖，请在配置文件的 .env 中设置 API_SERVER_MODEL_NAME：

hermes -p alice config set API_SERVER_MODEL_NAME "Alice's Agent"

Linux 上的 Docker（无 Docker Desktop）​

在没有 Docker Desktop 的 Linux 系统上，host.docker.internal 默认不会解析。解决方案如下：

# Option 1: Add host mapping
docker run --add-host=host.docker.internal:host-gateway ...

# Option 2: Use host networking
docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1 ...

# Option 3: Use Docker bridge IP
docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1 ...