Open WebUI 集成#
Open WebUI(126k★)是最受欢迎的自托管 AI 聊天界面。借助 Hermes Agent 内置的 API 服务器,你可以将 Open WebUI 用作 agent 的精美 Web 前端——完整支持对话管理、用户账户和现代聊天界面。Open WebUI 连接 Hermes Agent 的 API 服务器,方式与连接 OpenAI 完全相同。Hermes 使用其完整工具集——终端、文件操作、网络搜索、记忆、技能——处理请求并返回最终响应。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 连接并使用可复用的启动器,请运行:确保 ~/.hermes/.env 包含 API_SERVER_ENABLED、API_SERVER_HOST、API_SERVER_KEY、API_SERVER_PORT 和 API_SERVER_MODEL_NAME
重启 Hermes gateway 以启动 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
在 Linux 上,自动后台服务设置需要可用的 systemd --user 会话。如果你在无头 SSH 机器上并希望跳过服务安装,请运行:1. 启用 API 服务器#
hermes config set 会自动将标志路由到 config.yaml,将密钥路由到 ~/.hermes/.env。如果 gateway 已在运行,请重启以使更改生效:2. 启动 Hermes Agent gateway#
[API Server] API server listening on http://127.0.0.1:8642
3. 验证 API 服务器可访问#
如果 /health 失败,说明 gateway 未加载 API_SERVER_ENABLED=true——重启它。如果 /v1/models 返回 401,说明你的 Authorization 头与 API_SERVER_KEY 不匹配。4. 启动 Open WebUI#
ENABLE_OLLAMA_API=false 会禁用默认的 Ollama 后端,否则它会显示为空并干扰模型选择器。如果你确实在同时运行 Ollama,可以省略此参数。首次启动需要 15–30 秒:Open WebUI 在第一次启动时会下载 sentence-transformer embedding(嵌入)模型(约 150MB)。请等待 docker logs open-webui 输出稳定后再打开 UI。5. 打开 UI#
访问 http://localhost:3000 。创建管理员账户(第一个用户将成为管理员)。你应该能在模型下拉列表中看到你的 agent(以你的 profile 命名,默认 profile 则显示为 hermes-agent)。开始聊天吧!Docker Compose 设置#
如需更持久的设置,创建 docker-compose.yml:通过管理员 UI 配置#
4.
在 OpenAI API 下,点击扳手图标(Manage)
6.
URL:http://host.docker.internal:8642/v1
API Key:与 Hermes 中 API_SERVER_KEY 完全相同的值
你的 agent 模型现在应出现在模型下拉列表中(以你的 profile 命名,默认 profile 则显示为 hermes-agent)。环境变量仅在 Open WebUI 首次启动时生效。此后,连接设置存储在其内部数据库中。如需后续修改,请使用管理员 UI,或删除 Docker 卷后重新启动。
API 类型:Chat Completions 与 Responses#
Open WebUI 连接后端时支持两种 API 模式:| 模式 | 格式 | 使用场景 |
|---|
| Chat Completions(默认) | /v1/chat/completions | 推荐。开箱即用。 |
| Responses |