Open WebUI 整合——網頁聊天介面

這篇教學教你如何用 Open WebUI 給 Hermes Agent 配一個漂亮的網頁聊天介面，像用 ChatGPT 一樣跟你的智慧體對話。

---

為什麼需要 Open WebUI？

Open WebUI 是 GitHub 上 12.6 萬星的開源專案，相當於給 AI 裝了個「微信」。Hermes Agent 自帶 API 伺服器，兩者一接，你就能在瀏覽器裡聊天、管理會話、註冊帳號，介面現代又流暢。

打個比方：Hermes Agent 是大腦，Open WebUI 是臉面。大腦負責思考幹活，臉面負責讓你看得舒服。

架構原理

瀏覽器 (Open WebUI, 連接埠 3000)  →  Hermes Agent API 伺服器 (連接埠 8642)
        ↓ 發送請求                              ↓ 處理並串流返回

重要提醒：API 伺服器是智慧體執行環境，不是純模型代理。每次請求，Hermes 都會在伺服器上建立一個 AIAgent，工具呼叫（終端機、檔案、瀏覽器等）都在伺服器那台機器上執行。如果你的伺服器在遠端，工具就跑在遠端，不在你本地電腦上。

---

第 1 步：開啟 API 伺服器

打開終端機，執行：

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

第一條命令把開關寫進 config.yaml，第二條把金鑰存到 ~/.hermes/.env。如果閘道已在執行，重啟生效：

hermes gateway stop && hermes gateway

看到 API server listening on http://127.0.0.1:8642 就成功了。

第 2 步：驗證伺服器

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 失敗，表示閘道沒讀到設定，重啟一下。如果 /v1/models 回傳 401，檢查金鑰是否一致。

第 3 步：啟動 Open WebUI

用 Docker 一條命令搞定：

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 後端，免得模型清單裡多個空選項。首次啟動要 15–30 秒，因為要下載約 150MB 的嵌入模型，等 docker logs open-webui 安靜下來再打開介面。

第 4 步：打開網頁

瀏覽器訪問 **http://localhost:3000**，註冊第一個帳號（自動成為管理員）。在模型下拉框裡就能看到 hermes-agent，直接開聊！

---

進階：用管理介面設定

如果你不想用環境變數，也可以在網頁裡配：

1. 點右上角頭像 → 管理員設定
2. 進入連線 → OpenAI API → 點扳手圖示
3. 新增連線，填 URL http://host.docker.internal:8642/v1 和你的金鑰
4. 點對勾驗證，儲存即可

注意：環境變數只在 Open WebUI 首次啟動時生效，之後設定存在資料庫裡。要改就進管理介面，或者刪掉 Docker 磁碟區重來。

---

小總結

接好之後，你在網頁裡發訊息，Hermes 會帶著全套工具（終端機、檔案、搜尋、記憶）幹活，工具執行過程會以進度訊息串流顯示，比如 `💻 ls -la`、`🔍 Python 3.12 release`，最後把答案串流返回。就像有個透明的小助手，每一步都讓你看見。

下篇預告：訊息平台接入系列繼續，下一篇我們聊聊怎麼把 Hermes Agent 接進 Discord，讓你的智慧體在伺服器裡隨時待命。

---