Section: Messaging Platforms · URL: https://hermesbible.com/docs/user-guide/messaging/open-webui

Open WebUI 整合

Open WebUI（126k★）是目前最熱門的自架式 AI 聊天介面。透過 Hermes Agent 內建的 API 伺服器，你可以將 Open WebUI 作為你 Agent 的精美 Web 前端——支援完整的對話管理、使用者帳號以及現代化的聊天介面。

架構

flowchart LR
    A["Open WebUI<br/>browser UI<br/>port 3000"]
    B["hermes-agent<br/>gateway API server<br/>port 8642"]
    A -->|POST /v1/chat/completions| B
    B -->|SSE streaming response| A

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 串接起來，並使用可重複使用的啟動腳本，執行：

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）。請等待 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

透過管理介面設定

如果你偏好透過介面而非環境變數來設定連線：

在 http://localhost:3000 登入 Open WebUI
點選你的個人頭像 → 管理設定
前往連線
在 OpenAI API 下方，點選扳手圖示（管理）
點選 + 新增連線
輸入：
- URL：http://host.docker.internal:8642/v1
- API Key：與 Hermes 中 API_SERVER_KEY 完全相同的值
點選勾選圖示以驗證連線
儲存

你的 Agent 模型現在應該會出現在模型下拉選單中（以你的設定檔命名，或使用預設設定檔的 hermes-agent）。

警告

環境變數僅在 Open WebUI 首次啟動時生效。之後，連線設定會儲存在其內部資料庫中。若日後需要變更，請使用管理介面，或刪除 Docker volume 後重新開始。

API 類型：Chat Completions vs 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 模式：

前往管理設定 → 連線 → OpenAI → 管理
編輯你的 hermes-agent 連線
將 API 類型 從 "Chat Completions" 改為 "Responses（實驗性）"
儲存

使用 Responses API 時，Open WebUI 會以 Responses 格式（input 陣列 + instructions）發送請求，而 Hermes Agent 可透過 previous_response_id 在多輪對話中保留完整的工具呼叫歷史。當啟用 stream: true 時，Hermes 也會串流原生規格的 function_call 和 function_call_output 項目，這使得支援 Responses 事件的用戶端能夠實現自訂的結構化工具呼叫介面。

注意

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 網址（需包含 `/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 重啟容器，或在管理設定 → 連線中停用 Ollama。

連線測試通過但模型無法載入

這幾乎總是因為缺少 /v1 後綴。Open WebUI 的連線測試僅進行基本連線檢查——它不會驗證模型列表功能是否正常。

回應耗時過長

Hermes Agent 可能在產生最終回應之前執行了多次工具呼叫（讀取檔案、執行命令、搜尋網路）。這對於複雜查詢是正常的。Agent 完成後，回應會一次呈現。

"Invalid API key" 錯誤

請確認你在 Open WebUI 中的 OPENAI_API_KEY 與 Hermes Agent 中的 API_SERVER_KEY 一致。

警告

Open WebUI 在首次啟動後會將 OpenAI 相容的連線設定儲存在其自己的資料庫中。如果你不小心在管理介面中儲存了錯誤的金鑰，僅修改環境變數是不夠的——請在管理設定 → 連線中更新或刪除已儲存的連線，或重設 Open WebUI 的資料目錄/資料庫。

多使用者設定與設定檔

若要為每位使用者執行獨立的 Hermes 實例——各自擁有獨立的設定、記憶體和技能——請使用設定檔。每個設定檔會在不同的連接埠上運行自己的 API 伺服器，並自動將設定檔名稱作為模型名稱向 Open WebUI 公告。

1. 建立設定檔並設定 API 伺服器

API_SERVER_* 是環境變數，而非 YAML 設定鍵，因此請將它們寫入每個設定檔的 .env 檔案。請選擇預設平台範圍之外的連接埠（8644 是 webhook 適配器，8650 是 wecom-callback，8651 是 msgraph-webhook），例如 8650+：

hermes profile create alice
cat >> ~/.hermes/profiles/alice/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8650
API_SERVER_KEY=alice-secret
EOF

hermes profile create bob
cat >> ~/.hermes/profiles/bob/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8651
API_SERVER_KEY=bob-secret
EOF

2. 啟動每個閘道器

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

3. 在 Open WebUI 中新增連線

在管理設定 → 連線 → OpenAI API → 管理中，為每個設定檔新增一條連線：

連線	URL	API Key
Alice	`http://host.docker.internal:8650/v1`	`alice-secret`
Bob	`http://host.docker.internal:8651/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 ...