Open WebUI 安裝與 OmniProxy 設定指南

Open WebUI 是一個自託管的聊天介面，可以安裝在您自己的電腦或伺服器上，也能完全離線執行。它不綁定任何單一模型供應商：它既能連線至 Ollama 等執行本地模型的工具，也能連線至 OpenAI 相容的端點（即使用相同請求格式提供模型服務的位址）。這讓您能在同一個視窗中切換使用本地與雲端模型。

它適合團隊與組織長期使用。Open WebUI 用於測試新功能的產品 Computer 中，會優先推出更新較快的功能。

開始之前

Open WebUI 支援 macOS、Linux 與 Windows。您可以使用 Docker、Python 或 Kubernetes 進行安裝。Docker 將應用程式及其執行環境封裝在相對隔離的容器中，是推薦的安裝方式。若無法使用 Docker，您也可以使用下方經過測試的 Python 指令。Kubernetes 是一種用於部署與管理容器的系統；請參閱本指南末尾連結的快速入門以了解對應步驟。

官方推薦

Docker

• 單一 docker run 指令
• 在瀏覽器開啟 3000 埠
• 資料儲存於 Volume 中

僅需聊天功能

slim 映像檔

• 下載體積更小
• 將標籤改為 :slim
• 聊天功能依然可用

此處不涵蓋

另外兩種選項

• 手動 Python 安裝
• Kubernetes 部署
• 參閱官方快速入門

開始前，請準備以下項目：

• 已安裝並執行 Docker。
• 一組僅供您使用的密鑰字串。執行 openssl rand -hex 32 產生一組，並將其輸入為 WEBUI_SECRET_KEY。請永久儲存此數值。若在重建容器時變更此值，已登入的使用者將會被登出。
• 一個執行中的 OmniProxy 實例，以及其當前模型清單中的模型 ID。模型 ID 是用於選擇特定模型的完整名稱。

首次安裝與啟動

開啟終端機並執行快速入門中的指令。首先將 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：將對話、使用者與設定儲存在資料卷（Volume）中。資料卷是容器外的一個位置，資料可長期保留，因此容器更新後內容依然存在。請勿移除此選項。
• --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

快速入門也提供了 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: Copy from the current OmniProxy model list

URL 是 Open WebUI 用於連線至端點的位址，且必須以 /v1 結尾。請勿在其後加入 /chat/completions；Open WebUI 會自動附加該部分。

從 OmniProxy 的當前清單中複製完整的模型 ID。若 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 容器中執行，請將 URL 中的 localhost 取代為 host.docker.internal。主機即直接執行 Docker 的電腦。若 OmniProxy 僅監聽此電腦，URL 可寫為 http://host.docker.internal:port/v1，並將 port 取代為 OmniProxy 實際使用的埠。

若 Open WebUI 是透過前述的 Python 指令在本地執行，且 OmniProxy 也在本地執行，請在位址中使用 127.0.0.1 或 localhost。在此情況下請勿使用 host.docker.internal。

輸入設定

在 2026-10-09 測試的 v0.11.4 簡體中文介面中，名稱與英文說明中的「Settings > Admin > Connections」有所不同。請依照下方翻譯後的測試介面選項操作：

1. 展開左側邊欄。
2. 點擊底部的使用者選單。
3. 點擊 Settings（設定）。
4. 在下方的管理員區塊中，點擊 External Connections（外部連線）。
5. 開啟 OpenAI API。
6. 點擊 Manage OpenAI API Connections（管理 OpenAI API 連線）右側的 +。
7. 在 Edit Connection（編輯連線）對話框中，輸入以 /v1 結尾的 URL。將 API 類型保持設定為 Chat Completions。
8. 將 Authentication Method（驗證方式）保持設定為 Key (Bearer)。Bearer 驗證會將 API 金鑰放入請求中以進行身分識別。若 OmniProxy 給了您金鑰，請輸入於 API Key。若閘道器不驗證金鑰，請將此欄位留空。在 2026-10-09 的測試中，將此欄位留空也能成功驗證並進行對話。
9. 點擊 URL 旁的 Verify Connection（驗證連線）。若 OmniProxy 提供 /models，此處將會擷取模型清單。
10. 開啟 Advanced（進階）。若 Model ID 留空，將會使用該位址下 /models 所回傳的所有模型。僅在驗證失敗時，才在 Add Model ID（新增模型 ID）下方輸入清單中的完整 ID，然後點擊 Add（新增）。每個 ID 僅新增一次；開頭與結尾的空格會被移除。
11. 點擊此視窗中的 Save（儲存），然後點擊「外部連線」頁面右下角的 Save（儲存）。

儲存設定並不等同於驗證。Verify Connection 會請求其他服務的 /models 端點，該端點會列出可用模型。部分服務不提供此端點，因此即使聊天功能正常，驗證仍可能回報錯誤。在這種情況下，請手動新增模型 ID。

驗證實際任務

回到聊天頁面，開啟輸入框旁模型選單，並選擇 OmniProxy 清單中的完整 ID。發送一則非常簡短的訊息，例如要求它只回覆一個字。聊天框中必須確實出現回應。

在 2026-10-09，此對話是使用 v0.11.4 的 Python 安裝方式完成的。Docker 依然是推薦方式，但測試未在 Docker 中重複進行。

接著，開啟 OmniProxy 的請求紀錄，確認此請求的來源與模型 ID。僅看到儲存成功，或僅在選單中看到模型，並不代表完成設定。

介面

模型可被選擇

• 連線已儲存
• 模型出現在清單中
• 發送簡短問題

回應

聊天框顯示答案

• 非空白訊息
• 非連線錯誤
• 嘗試使用其他模型

紀錄

在閘道器中可見

• 來源為此連線
• 模型 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 已變更。請使用首次產生時的密鑰重新啟動。
• Verify Connection 失敗：請先在 Advanced 下手動新增模型 ID，然後透過實際的一句對話進行確認。部分服務不提供 /models，因此即使驗證回報錯誤，聊天功能仍可能正常運作。
• 模型不存在：請從 OmniProxy 的當前清單中重新複製 ID，而非繼續使用過時的名稱。

官方參考

關於安裝指令，請參閱 Open WebUI 快速入門。關於連線步驟，請參閱 OpenAI 相容連線說明。關於範例中使用的模型 ID，請參閱 Claude 模型概覽 與 Gemini 模型清單。

將所有佔位符替換為您自己的 OmniProxy 配置值。切勿發布真實金鑰。

保存的結果或 HTTP 200 單獨存在並不證明完整的 Agent 相容性。請在 OmniProxy 的呼叫記錄中檢查來源與模型。

官方來源 · Open WebUI ↗