Open WebUI 集成

Open WebUI（126k★）是最受欢迎的 AI 自托管聊天界面。借助 Hermes Agent 内置的 API 服务器，您可以将 Open WebUI 作为 Agent 的精美 Web 前端 —— 完整支持对话管理、用户账号和现代化聊天界面。

架构

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

运行位置

API 服务器是一个 Hermes Agent 运行时，不是纯粹的 LLM 代理。对于每个请求，Hermes 在 API 服务器所在主机上创建一个服务器端 AIAgent。工具调用在该 API 服务器运行的位置执行。

例如，如果笔记本电脑将 Open WebUI 或其他 OpenAI 兼容客户端指向远程机器上的 Hermes API 服务器，pwd、文件工具、浏览器工具、本地 MCP 工具和其他工作区工具都在远程 API 服务器主机上运行，而不是在笔记本电脑上。

Open WebUI 以服务器到服务器的方式与 Hermes 通信，因此此集成不需要配置 API_SERVER_CORS_ORIGINS。

快速配置

一键本地启动（macOS/Linux，无需 Docker）

如果您想在本地将 Hermes 与 Open WebUI 连接并使用可复用的启动器，运行：

cd ~/.hermes/hermes-agent
bash scripts/setup_open_webui.sh

脚本执行内容：

确保 ~/.hermes/.env 包含 API_SERVER_ENABLED、API_SERVER_HOST、API_SERVER_KEY、API_SERVER_PORT 和 API_SERVER_MODEL_NAME
重启 Hermes 网关以启动 API 服务器
将 Open WebUI 安装到 ~/.local/open-webui-venv
在 ~/.local/bin/start-open-webui-hermes.sh 写入启动器
在 macOS 上安装 launchd 用户服务；在有 systemd --user 的 Linux 上安装用户服务

默认值：

Hermes API：http://127.0.0.1:8642/v1
Open WebUI：http://127.0.0.1:8080
向 Open WebUI 展示的模型名称：Hermes Agent

有用的覆盖参数：

OPEN_WEBUI_NAME='My Hermes UI' \
OPEN_WEBUI_ENABLE_SIGNUP=true \
HERMES_API_MODEL_NAME='My Hermes Agent' \
bash scripts/setup_open_webui.sh

在 Linux 上，自动后台服务安装需要正常运行的 systemd --user 会话。如果您在无头 SSH 服务器上想跳过服务安装，运行：

OPEN_WEBUI_ENABLE_SERVICE=false bash scripts/setup_open_webui.sh

1. 启用 API 服务器

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

hermes config set 自动将配置项路由到 config.yaml，将密钥路由到 ~/.hermes/.env。如果网关已经在运行，重启以使更改生效：

hermes gateway stop && hermes gateway

2. 启动 Hermes Agent 网关

hermes gateway

您应该看到：

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

3. 验证 API 服务器可访问

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 失败，说明网关未获取到 API_SERVER_ENABLED=true —— 请重启网关。如果 /v1/models 返回 401，说明 Authorization 请求头与 API_SERVER_KEY 不匹配。

4. 启动 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 \
  -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 后端，否则它会显示为空并占据模型选择器。如果您实际上也在运行 Ollama，可以省略此参数。

首次启动需要 15–30 秒：Open WebUI 首次启动时会下载 sentence-transformer 嵌入模型（约 150MB）。在打开 UI 前等待 docker logs open-webui 的输出稳定。

5. 打开界面

访问 http://localhost:3000。创建管理员账号（第一个用户成为管理员）。您应该在模型下拉菜单中看到您的 Agent（以您的配置文件命名，或默认配置文件显示为 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
      - ENABLE_OLLAMA_API=false
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: always

volumes:
  open-webui:

然后：

docker compose up -d

通过管理界面配置

如果您更喜欢通过界面而非环境变量配置连接：

登录 Open WebUI：http://localhost:3000
点击头像 → Admin Settings
进入 Connections
在 OpenAI API 下，点击扳手图标（Manage）
点击 + Add New Connection
填写：
- URL：http://host.docker.internal:8642/v1
- API Key：与 Hermes 中 API_SERVER_KEY 完全相同的值
点击对勾验证连接
保存

您的 Agent 模型现在应出现在模型下拉菜单中（以您的配置文件命名，默认配置文件显示为 hermes-agent）。

注意

环境变量只在 Open WebUI 首次启动时生效。之后，连接设置存储在其内部数据库中。要在之后修改，请使用管理界面，或删除 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 模式：

进入 Admin Settings → Connections → OpenAI → Manage
编辑您的 hermes-agent 连接
将 API Type 从"Chat Completions"改为 "Responses (Experimental)"
保存

使用 Responses API 时，Open WebUI 以 Responses 格式（input 数组 + instructions）发送请求，Hermes Agent 可以通过 previous_response_id 在多轮间保留完整的工具调用历史。当 stream: true 时，Hermes 还会以规范原生的 function_call 和 function_call_output 事件流式传输，支持客户端中自定义结构化工具调用 UI。

备注

Open WebUI 目前即使在 Responses 模式下也在客户端管理对话历史 —— 它在每次请求中发送完整的消息历史，而不使用 previous_response_id。Responses 模式今天的主要优势是结构化事件流：文本增量、function_call 和 function_call_output 以 OpenAI Responses SSE 事件形式到达，而非 Chat Completions 数据块。

工作原理

在 Open WebUI 中发送消息时：

Open WebUI 发送包含消息和对话历史的 POST /v1/chat/completions 请求
Hermes Agent 使用 API 服务器的配置文件、模型/提供商配置、记忆、技能和已配置的 API 服务器工具集，创建一个服务器端 AIAgent 实例
Agent 处理您的请求 —— 可能在 API 服务器主机上调用工具（终端、文件操作、网络搜索等）
工具执行时，内联进度消息流式传输到界面，让您看到 Agent 在做什么（例如 `💻 ls -la`、`🔍 Python 3.12 release`）
Agent 的最终文本响应流式传输回 Open WebUI
Open WebUI 在聊天界面中显示响应

您的 Agent 可以访问与该 API 服务器 Hermes 实例相同的工具和能力。如果 API 服务器在远程，那些工具也在远程运行。

如果您需要工具在本地工作区上运行，请在本地运行 Hermes 并将其指向纯粹的 LLM 提供商或纯粹的 OpenAI 兼容模型代理（例如 vLLM、LiteLLM、Ollama、llama.cpp、OpenAI、OpenRouter 等）。"远程大脑，本地双手"的拆分运行时模式正在 #18715 中跟踪；这不是当前 API 服务器的行为。

工具进度

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

配置参考

Hermes Agent（API 服务器）

变量	默认值	说明
`API_SERVER_ENABLED`	`false`	启用 API 服务器
`API_SERVER_PORT`	`8642`	HTTP 服务器端口
`API_SERVER_HOST`	`127.0.0.1`	绑定地址
`API_SERVER_KEY`	（必填）	用于认证的 Bearer Token。需与 `OPENAI_API_KEY` 匹配。

Open WebUI

变量	说明
`OPENAI_API_BASE_URL`	Hermes 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 -H "Authorization: Bearer your-secret-key" http://localhost:8642/v1/models 应返回包含 hermes-agent 的列表
Docker 网络：在 Docker 容器内，localhost 表示容器本身，而非宿主机。使用 host.docker.internal 或 --network=host。
空的 Ollama 后端遮盖选择器：如果省略了 ENABLE_OLLAMA_API=false，Open WebUI 会在 Hermes 模型上方显示空的 Ollama 区域。使用 -e ENABLE_OLLAMA_API=false 重启容器，或在 Admin Settings → Connections 中禁用 Ollama。

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

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

响应时间很长

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

"Invalid API key" 错误

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

注意

Open WebUI 首次启动后会将 OpenAI 兼容连接设置持久化到自己的数据库中。如果您在管理界面中保存了错误的密钥，仅修改环境变量是不够的 —— 请在 Admin Settings → Connections 中更新或删除已保存的连接，或重置 Open WebUI 数据目录/数据库。

多用户配置（使用配置文件）

要为每个用户运行独立的 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 中，为每个配置文件添加一个连接：

连接	URL	API Key
Alice	`http://host.docker.internal:8643/v1`	`alice-secret`
Bob	`http://host.docker.internal:8644/v1`	`bob-secret`

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

自定义模型名称

模型名称默认为配置文件名称。如需覆盖，在配置文件的 .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 默认不解析。选项：

# 选项 1：添加主机映射
docker run --add-host=host.docker.internal:host-gateway ...

# 选项 2：使用主机网络
docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1 ...

# 选项 3：使用 Docker 桥接 IP
docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1 ...

架构​

快速配置​

一键本地启动（macOS/Linux，无需 Docker）​

1. 启用 API 服务器​

2. 启动 Hermes Agent 网关​

3. 验证 API 服务器可访问​

4. 启动 Open WebUI​

5. 打开界面​

Docker Compose 配置​

通过管理界面配置​

API 类型：Chat Completions 与 Responses​

使用 Chat Completions（推荐）​

使用 Responses API​

工作原理​

配置参考​

Hermes Agent（API 服务器）​

Open WebUI​

故障排查​

模型下拉菜单中没有模型​

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

响应时间很长​

"Invalid API key" 错误​

多用户配置（使用配置文件）​

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

2. 启动各网关​

3. 在 Open WebUI 中添加连接​

Linux Docker（无 Docker Desktop）​

架构