Open WebUI 集成

Open WebUI（126k★）是目前最受歡迎的自託管 AI 聊天界面。通過 Hermes Agent 內置的 API 服務器，你可以使用 Open WebUI 作為你 Agent 的精美網頁前端——支持對話管理、用戶賬戶以及現代化的聊天界面。

架構

Open WebUI 與 Hermes Agent 的 API 服務器連接方式，就像連接 OpenAI 一樣。你的 Agent 會使用其完整的工具集（終端、文件操作、網絡搜索、記憶、技能等）處理請求，並返回最終響應。

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。創建你的管理員賬戶（第一個用戶將成為管理員）。你應該能在模型下拉菜單中看到你的 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
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: always

volumes:
  open-webui:

然後執行：

docker compose up -d

通過 Admin UI 配置

如果你更傾向於通過 UI 而非環境變量來配置連接：

登錄 Open WebUI，訪問 http://localhost:3000
點擊你的 個人資料頭像 → Admin Settings
進入 Connections
在 OpenAI API 下，點擊 扳手圖標（Manage）
點擊 + Add New Connection
輸入：
- URL: http://host.docker.internal:8642/v1
- API 密鑰: 你的密鑰或任意非空值（例如 not-needed）
點擊勾號以驗證連接
保存

此時，你的 Agent 模型應出現在模型下拉菜單中（名稱為你配置文件的名稱，或默認配置文件為 hermes-agent）。

注意

環境變量僅在 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 模式：

進入 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 保留跨輪次的完整工具調用歷史。

備註

目前，即使在 Responses 模式下，Open WebUI 仍由客戶端管理對話歷史——它在每次請求中發送完整的消息歷史，而非使用 previous_response_id。Responses API 模式主要為未來前端演進提供兼容性支持。

工作原理

當你在 Open WebUI 中發送一條消息時：

Open WebUI 發送 POST /v1/chat/completions 請求，包含你的消息和對話歷史
Hermes Agent 創建一個帶有完整工具集的 AIAgent 實例
Agent 處理你的請求——可能調用工具（終端、文件操作、網絡搜索等）
工具執行過程中，進度消息會實時流式傳輸到 UI，讓你可以查看 Agent 正在做什麼（例如 `💻 ls -la`, `🔍 Python 3.12 release`）
Agent 的最終文本響應流式返回 Open WebUI
Open WebUI 在其聊天界面中顯示響應

你的 Agent 擁有與 CLI 或 Telegram 使用時相同的全部工具和功能——唯一的區別只是前端界面。

工具進度

啟用流式傳輸（默認）後，你會看到工具運行時的簡短內聯指示——包含工具圖標和其關鍵參數。這些信息會在 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 地址（包含 `/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 可能在生成最終響應前執行多個工具調用（如讀取文件、運行命令、網絡搜索）。對於複雜查詢，這是正常現象。當 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 中添加連接

在 管理員設置 → 連接 → OpenAI API → 管理中，為每個配置文件添加一個連接：

連接	URL	API 密鑰
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 ...

架構​

快速設置​

1. 啟用 API 服務器​

2. 啟動 Hermes Agent 網關​

3. 啟動 Open WebUI​

4. 打開 UI​

Docker Compose 設置​

通過 Admin UI 配置​

API 類型：Chat Completions 與 Responses​

使用 Chat Completions（推薦）​

使用 Responses API​

工作原理​

配置參考​

Hermes Agent（API 服務器）​

Open WebUI​

故障排除​

下拉菜單中沒有顯示模型​

連接測試通過但模型未加載​

響應耗時過長​

“無效 API 密鑰”錯誤​

多用戶設置（使用配置文件）​

1. 創建配置文件並配置 API 服務器​

2. 啟動每個網關​

3. 在 Open WebUI 中添加連接​

Linux Docker（無 Docker Desktop）​

架構