Open WebUI 安裝與 OmniProxy 設定

Open WebUI 是一個可以自行部署的聊天介面，可安裝在自己的電腦或伺服器上，也能完全離線執行。它不綁定任何一家模型服務：既可以連線至 Ollama 這類在本機執行模型的工具，也可以連線至相容 OpenAI 格式的 API，也就是使用相同請求格式提供模型服務的位址。這樣一來，本機模型和雲端模型就能在同一個視窗中切換。

它適合團隊和組織長期使用。更新較快的功能會先出現在 Computer，也就是 Open WebUI 用來試驗新功能的產品中。

安裝前準備

Open WebUI 可在 macOS、Linux 和 Windows 上使用。你可以透過 Docker、Python 或 Kubernetes 安裝。Docker 會把應用程式和執行環境放在相對獨立的容器中，是建議使用的方式；沒有 Docker 時，也可以使用下方經過實際測試的 Python 指令。Kubernetes 是用來部署和管理容器的系統，相關步驟請參閱文末的 Quick Start。

官方建議

Docker

一行 docker run
在瀏覽器開啟 3000
資料位於資料卷中

只想聊天

slim 映像檔

下載大小更小
標籤改為 :slim
聊天功能仍然可用

本文不詳述

另外兩種方式

手動安裝 Python
部署 Kubernetes
請參閱官方 Quick Start

先安裝 Docker，再使用建議的指令啟動。若只透過 API 聊天，可以把映像檔標籤改成 slim。

開始前請準備好：

已安裝並可正常執行的 Docker。
一組僅供自己使用的金鑰字串。執行 openssl rand -hex 32 產生，然後填入 WEBUI_SECRET_KEY。這個值必須固定保存；如果重建容器時更換金鑰，已登入的使用者會被登出。
正在執行的 OmniProxy，以及它目前模型清單中的模型 ID。模型 ID 是選擇特定模型時使用的完整名稱。

安裝並首次啟動

開啟終端機，執行 Quick Start 中的指令。先將 your-secret-key 換成剛才產生的金鑰字串：

docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data -e WEBUI_SECRET_KEY=your-secret-key --name open-webui --restart always ghcr.io/open-webui/open-webui:main

這條指令中的各個項目分別負責：

-p 3000:8080：讓你透過這台電腦的 3000 連接埠開啟介面。如果 3000 已被占用，請修改左側的數字。
-v open-webui:/app/backend/data：將聊天、使用者和設定存放在資料卷中。資料卷是在容器之外長期保存資料的位置，更新容器後內容仍會保留，因此不要移除這個項目。
--add-host=host.docker.internal:host-gateway：讓容器可以存取這台電腦上執行的其他服務。
--restart always：電腦重新開機後，容器會再次啟動。

執行指令後，在瀏覽器開啟 http://localhost:3000，依照頁面提示建立第一個帳號。

如果只需要透過 API 聊天，可以將映像檔標籤從 :main 改成 :slim。slim 是體積較小的映像檔，不包含容器內的本機語音和嵌入模型，但聊天介面仍可使用。需要這些本機功能時，請繼續使用 :main。

更新時，手動操作方式是先執行 docker rm -f open-webui，再執行 docker pull ghcr.io/open-webui/open-webui:main，然後使用相同的 docker run 指令重新啟動。資料卷和 WEBUI_SECRET_KEY 都必須保持不變。

沒有 Docker 時

Quick Start 也提供 Python 安裝方式。2026-10-09 在 macOS 上使用下列指令安裝至 Open WebUI v0.11.4，並完成了一次對話。當時這台電腦並未安裝 Docker Desktop。

DATA_DIR=~/.open-webui uvx --python 3.11 open-webui@latest serve

啟動後，在瀏覽器開啟 http://localhost:8080。這是 Python 安裝方式使用的連接埠，不是 Docker 使用的 3000。

第一次啟動時會下載一個嵌入模型，可能需要幾分鐘。嵌入模型會將文字轉換成便於搜尋和比對的資料。請等登入頁面出現後再繼續；第一個註冊的帳號會成為管理員。介面語言會跟隨系統，這次顯示的是簡體中文。

DATA_DIR 必須指向一個會長期保留的目錄，用來存放 Open WebUI 的資料。如果未設定，資料可能會存放在暫存目錄中，關閉後便會遺失。未設定 WEBUI_SECRET_KEY 時，程式會在目前目錄寫入 .webui_secret_key。請從打算保留的目錄啟動，或自行設定這個變數。

從 OmniProxy 取得連線參數

從你自己的 OmniProxy 複製以下三項：

URL:      https://your-omniproxy-origin.example/v1
API Key:  <YOUR_OMNIPROXY_API_KEY>
Model ID: 從 OmniProxy 目前的模型清單複製

URL 是 Open WebUI 連線至 API 時使用的位址，必須以 /v1 結尾。不要在後面再加上 /chat/completions，這一段會由 Open WebUI 自動附加。

模型 ID 必須從 OmniProxy 目前的清單完整複製。如果 ID 包含來源前綴和斜線，也必須一併保留。下列兩個簡短名稱只是 2026-10-09 供應商文件中的對照；如果目前清單中沒有，請勿使用：

Claude Sonnet 5.5 的 Claude API ID：claude-sonnet-5-5
Gemini 3.8 Flash 的 API 名稱：gemini-3.8-flash

不要將供應商金鑰填入 Open WebUI。如果閘道不驗證金鑰，API 金鑰可以留空，不要另外編造一組金鑰。

瀏覽器

本機 3000

開啟聊天頁面
先完成註冊
再進入設定

容器內

Open WebUI

不要填寫 localhost
改用主機名稱
URL 以 /v1 結尾

同一台電腦

OmniProxy

金鑰保留在閘道
模型清單以閘道為準
再查看呼叫記錄

當 Open WebUI 位於 Docker 中，而 OmniProxy 位於主機上時，不要將位址寫成容器內的 localhost。

如果模型服務在主機上執行，而 Open WebUI 在 Docker 容器中執行，請將 URL 中的 localhost 換成 host.docker.internal。主機就是直接執行 Docker 的這台電腦。如果 OmniProxy 只監聽這台電腦，URL 可以寫成 http://host.docker.internal:連接埠/v1，其中的連接埠必須換成 OmniProxy 實際使用的連接埠。

如果 Open WebUI 透過上一節的 Python 指令在本機執行，而 OmniProxy 也在本機，位址請使用 127.0.0.1 或 localhost。此時不要寫成 host.docker.internal。

填寫工具設定

2026-10-09 的 v0.11.4 簡體中文介面，與英文說明中的 Settings > Admin > Connections 名稱不同。請依照實際看到的中文選項操作：

展開左側邊欄。
按一下底部的使用者選單。
按一下設定。
在下方的管理員群組中按一下 外部連線。
開啟 OpenAI 介面。
在 管理 OpenAI 介面連線 右側按一下 +。
在彈出的 編輯連線 中，填入以 /v1 結尾的 URL。介面類型保持為 Chat Completions。
驗證方式保持為 金鑰（Bearer）。Bearer 是將 API 金鑰放入請求中進行身分驗證的方式。OmniProxy 提供金鑰時，請將它填入 API 金鑰。如果閘道不驗證金鑰，這個欄位請留空。2026-10-09 留空後，連線驗證和一次對話都成功完成。
按一下 URL 旁邊的 驗證連線。如果 OmniProxy 提供 /models，這裡會取得模型清單。
開啟進階。模型 ID 留空時，會使用該位址的 /models 所傳回的全部模型。只有在驗證失敗時，才需要在 新增模型 ID 中填入清單裡的完整 ID，再按一下新增。每個 ID 只需新增一次，前後空白會被移除。
按一下這個視窗中的儲存，再按一下外部連線頁面右下角的儲存。

只儲存設定不能取代驗證。驗證連線會向對方的 /models 發出請求，也就是用來列出可用模型的 API。有些服務沒有這個 API，驗證會顯示錯誤，但聊天仍可能可以使用。此時再手動新增模型 ID。

驗證一項實際任務

回到聊天頁面，開啟輸入框旁邊的模型選單，選擇 OmniProxy 清單中的完整 ID。傳送一句很短的訊息，例如要求它只回覆一個詞。聊天框中必須實際出現回覆。

2026-10-09 使用 v0.11.4 的 Python 安裝方式完成了這次對話。Docker 仍是建議使用的方式，但這次並未在 Docker 中重新測試。

接著開啟 OmniProxy 的呼叫記錄，確認這次請求的來源和模型 ID。只看到設定儲存成功，或只看到模型出現在選單中，都還不算完成。

介面

可以選擇模型

Connections 已儲存
模型出現在清單中
傳送一句簡短問題

回覆

聊天框中有答案

不是空白訊息
不是連線錯誤
換一個模型再試一次

記錄

閘道看得到

來源是這次連線
模型 ID 一致
沒有金鑰進入頁面

三處都相符，才表示這條連線可用。

常見錯誤

在容器中填寫 localhost 或 127.0.0.1：這兩個位址指向容器本身，而不是主機。請改成 host.docker.internal，並確認啟動指令中包含 --add-host=host.docker.internal:host-gateway。如果 Open WebUI 不在容器中，情況則相反，應使用本機位址。
瀏覽器無法開啟：Docker 請檢查 3000，Python 請檢查 8080。第一次啟動時，必須等待嵌入模型下載完成。可以使用 docker ps 確認容器是否正在執行。如果 3000 已被占用，請修改 -p 左側的連接埠。
模型選單中的 ID 比供應商的簡短名稱更長：請使用選單中的完整 ID，包括其中的斜線。
更新後所有人都被登出：WEBUI_SECRET_KEY 已變更。請使用第一次產生的金鑰字串重新啟動。
驗證連線失敗：先在進階中手動新增模型 ID，再透過一句實際聊天訊息確認。有些服務沒有 /models，即使驗證顯示錯誤，聊天仍可能可以使用。
模型不存在：請從 OmniProxy 目前的清單重新複製 ID，不要繼續使用已過期的名稱。

官方參考資料

安裝指令請參閱 Open WebUI Quick Start。連線步驟請參閱 OpenAI-compatible 連線說明。範例中使用的模型 ID 請參閱 Claude 模型總覽和 Gemini 模型清單。

用你自己的 OmniProxy 設定取代每個佔位符。不要發布真實金鑰。

儲存成功或 HTTP 200 不單獨代表完整 Agent 相容性。請在 OmniProxy 呼叫記錄中確認來源和模型。

官方來源 · Open WebUI ↗