OmniRoute 教程：搭建本地 AI API 閘道器與多模型自動切換

OmniRoute 是一個本地執行的 AI API 閘道器，把不同模型供應商、訂閱賬號和免費額度放到統一介面後面。Codex、Claude Code、Cursor、Cline、OpenCode 等客戶端只需連線一個 OpenAI 相容地址，再由 OmniRoute 根據可用額度、成本、延遲和健康狀態選擇模型。

它適合同時使用多家模型服務、經常遇到限流，或者希望統一檢視呼叫量的開發者。需要注意的是，閘道器不會憑空產生免費額度：賬號註冊、API 價格、速率限制和可接受使用方式仍由各上游供應商決定。

快速答案

全域性安裝並啟動：

1
2


npm install -g omniroute
omniroute

預設地址：

1
2


Dashboard: http://localhost:20128
API:       http://localhost:20128/v1

進入 Dashboard 的 Providers 頁面連線至少一個模型供應商，再到 Endpoints 頁面複製本地 API Key。AI 客戶端使用：

1
2
3


Base URL: http://localhost:20128/v1
API Key:  Dashboard 中生成的 Key
Model:    auto

驗證模型列表：

1
2


curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

如果返回已連線的模型，說明閘道器基本可用。正式接入編碼 Agent 前，再分別測試普通對話、流式輸出、工具呼叫和長上下文，避免只憑模型列表判斷相容性。

OmniRoute 如何工作

客戶端不再直接連線每家模型 API，而是把請求傳送到本地 OmniRoute。閘道器讀取模型名和路由規則，選擇當前可用的 Provider，再把響應轉換為客戶端能夠理解的協議。

1
2
3
4
5
6
7
8
9


Codex / Claude Code / Cursor
              |
              v
 http://localhost:20128/v1
              |
              v
      OmniRoute 路由与回退
       /       |        \
   Provider A  B         C

這種架構帶來三個直接效果：

客戶端只維護一個 Base URL 和訪問金鑰；
某個 Provider 限流或故障時，可以切換到候選模型；
呼叫量、成本、延遲和錯誤集中到同一控制面觀察。

代價是 OmniRoute 成為請求路徑中的關鍵元件。它停機、配置錯誤或資料目錄損壞時，所有經它轉發的客戶端都會受影響，因此生產環境需要持久化、備份、訪問控制和明確的繞行方案。

環境要求與安裝

官方當前要求 Node.js 22 或 24 LTS，並推薦 Node.js 24 LTS。先檢查版本：

1
2


node --version
npm --version

使用 npm 安裝：

1

npm install -g omniroute

第一次執行可以進入引導流程：

1

omniroute setup

啟動閘道器與 Dashboard：

1

omniroute

互動式終端聊天：

1

omniroute chat

遇到 Provider、埠或原生依賴問題時執行診斷：

1

omniroute doctor

如果本機沒有適配的 better-sqlite3 預編譯檔案，專案會嘗試使用其他 SQLite 實現。安裝異常時應先看完整日誌，不要直接關閉所有安裝指令碼或用管理員許可權反覆重灌。

使用 Docker 執行

官方提供多架構 Docker 映象：

1
2
3
4
5
6
7


docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --stop-timeout 40 \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

檢查狀態和日誌：

1
2


docker ps --filter name=omniroute
docker logs -f omniroute

omniroute-data 儲存配置、資料庫和執行狀態，升級或重建容器時不要隨意刪除。生產環境還應把 latest 換成經過驗證的明確版本標籤，並在升級前備份卷。

上面的 -p 20128:20128 可能把埠釋出到宿主機所有網路介面。只在本機使用時，可以限制到環回地址：

1
2
3
4
5
6
7


docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --stop-timeout 40 \
  -p 127.0.0.1:20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

需要遠端訪問時，應使用 HTTPS、強認證、IP 限制或私有網路，不要把 Dashboard 和 API 裸露到網際網路。

連線模型供應商

啟動後開啟：

1

http://localhost:20128

進入 Providers 頁面，根據實際擁有的賬號或 API Key 新增 Provider。建議按以下順序操作：

先連線一個低風險測試賬號；
確認模型目錄和單次對話可用；
設定預算或額度限制；
再增加第二個 Provider 驗證回退；
最後才接入日常編碼客戶端。

不要在截圖、日誌或問題反饋中暴露 OAuth Token、API Key 或 Dashboard 訪問金鑰。倉庫說明憑據會在本地加密儲存，但本機被攻破、主金鑰洩露或惡意擴充套件讀取程序時，仍可能造成風險。

使用 `auto` 自動路由

最簡單的配置是把客戶端模型設為：

1

auto

OmniRoute 還提供面向不同目標的自動模型名：

模型名	路由側重點
`auto`	平衡選擇，並傾向最近成功路徑
`auto/coding`	優先程式碼生成質量
`auto/fast`	優先低延遲
`auto/cheap`	優先較低呼叫成本
`auto/offline`	優先剩餘額度或限流空間
`auto/smart`	質量優先，並保留少量探索流量

自動路由不保證不同模型的行為完全一致。工具呼叫格式、上下文視窗、推理能力和輸出風格可能變化。關鍵任務應固定模型或限定候選集合，避免在一次長任務中無提示地切換到能力明顯不同的模型。

自定義回退鏈與路由策略

OmniRoute 把一組模型回退目標稱為 combo。可以按優先順序、權重、成本、剩餘額度、延遲或最近成功狀態選擇目標。

常見策略包括：

priority：按固定順序使用，失敗後轉下一個；
round-robin：在目標間輪詢；
cost-optimized：傾向價格更低的可用模型；
headroom：傾向剩餘額度更多的連線；
context-optimized：按當前上下文大小選擇模型；
lkgp：保持在最近已驗證成功的路徑。

配置回退鏈時，不要只比較模型名稱。還要統一考慮輸入輸出價格、上下文限制、工具呼叫、圖片能力、資料區域和供應商條款。對必須保持模型一致的會話，應啟用合適的粘性策略或直接固定 Provider。

接入 OpenAI 相容客戶端

能自定義 OpenAI Base URL 的工具通常可以使用：

1

http://localhost:20128/v1

推薦透過請求頭傳遞訪問金鑰：

1

Authorization: Bearer YOUR_KEY

無法新增自定義 Header 的客戶端，可以使用帶 Token 的相容別名，但 URL 會包含金鑰，更容易進入瀏覽器歷史、代理日誌或截圖。只有確實無法使用 Header 認證時才使用該方式，並定期輪換金鑰。

驗證聊天介面時，可以傳送一個最小請求：

1
2
3
4


curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Reply with OK"}]}'

Windows PowerShell 中 curl 的別名和引號行為可能不同，建議使用 curl.exe 或按當前 PowerShell 版本構造請求。

MCP 接入與許可權風險

OmniRoute 不僅能轉發模型請求，還提供 MCP，讓 Agent 管理 Provider、路由、combo、快取、壓縮和其他閘道器功能。

stdio 模式：

1

omniroute --mcp

HTTP MCP 地址：

1

http://localhost:20128/api/mcp/stream

Claude Code 示例：

1
2
3


claude mcp add-server omniroute \
  --type http \
  --url http://localhost:20128/api/mcp/stream

MCP 許可權比普通模型呼叫更敏感，因為 Agent 可能修改路由或連線配置。接入前應使用最小 scope、獨立訪問 Token 和審計日誌；刪除 Provider、輪換金鑰或調整團隊配額等操作應保留人工確認。

Token 壓縮應該怎麼評估

倉庫提供多級壓縮和 RTK、Caveman 等處理管線，官方展示的節省比例範圍很大。實際效果取決於工具輸出、重複內容、上下文結構和壓縮檔位，不能把 README 中的比例直接當作每個專案的保證。

建議用固定任務做 A/B 測試：

儲存原始 Prompt、工具輸出和最終結果；
關閉壓縮執行一次；
使用標準或 RTK 配置再執行一次；
比較輸入 Token、延遲、成本和答案正確性；
對程式碼修改執行同一套測試或驗證命令。

壓縮可能刪除被判定為低相關的資訊。安全審計、長日誌診斷和精確程式碼評審不應只看 Token 節省，還要檢查遺漏率並保留檢視原始輸出的路徑。

免費額度與供應商條款

OmniRoute 彙總多家供應商公開的免費層、試用額度和限流資訊。數字會隨供應商政策、地區、賬號型別和時間變化，因此文章不固定引用某個“每月免費 Token 總數”。應以 Dashboard 當前目錄和上游官方價格頁為準。

還要區分三類資源：

長期免費層；
註冊後一次性試用額度；
需要付費或訂閱才能解鎖的額外額度。

使用訂閱賬號、非標準 OAuth 流程或多個賬號聚合前，必須核對供應商服務條款。技術上能夠接入不代表供應商允許把個人訂閱共享給團隊、自動化呼叫或規避額度限制。

遠端部署注意事項

把 OmniRoute 部署到 VPS 後，所有客戶端 Prompt、程式碼上下文和模型響應都會經過該主機。至少需要：

使用 HTTPS，避免明文傳輸 Token 和 Prompt；
限制 Dashboard、API 與 MCP 的訪問來源；
為不同使用者或客戶端簽發不同 scope 的 Key；
備份資料目錄，同時加密備份；
設定日誌保留週期，避免長期儲存敏感程式碼；
監控呼叫成本、失敗率、延遲和異常登入。

不要把本地示例中的 http://localhost:20128 簡單替換成公網 IP 就投入使用。推薦先透過 Tailscale、WireGuard 或 SSH Tunnel 驗證，再決定是否配置反向代理和公開域名。

常見問題

Dashboard 打不開

執行診斷並檢查埠：

1

omniroute doctor

確認程序仍在執行，20128 沒有被其他應用佔用。Docker 使用者檢視容器日誌和埠對映。

`/v1/models` 返回 401

確認請求使用的是 Dashboard → Endpoints 生成的本地 Key，幷包含：

1

Authorization: Bearer YOUR_KEY

不要誤把上游 Provider Key 當作 OmniRoute Endpoint Key。

`auto` 選到了不合適的模型

先固定一個已驗證模型確認客戶端相容，再調整 combo 候選、策略、預算和上下文要求。關鍵工作流可以使用 auto/coding，但仍應限制不滿足工具呼叫或上下文要求的模型。

路由回退後回答風格突然變化

不同模型的系統指令遵循能力和工具格式存在差異。啟用會話粘性、縮小候選模型差距，並在切換時保留必要的任務狀態。對需要確定性的任務直接固定模型。

OmniRoute 能降低所有 AI 成本嗎？

不能保證。它可以依據定價和額度路由，並減少部分重複上下文，但閘道器本身無法改變上游計費規則。融合、流水線或多模型評審還可能增加總呼叫量。

OmniRoute 適合哪些場景

OmniRoute 適合同時維護多家模型賬號、需要統一 OpenAI 相容入口、希望在限流時自動回退，或想集中觀察成本和健康狀態的個人與團隊。對只使用一個穩定 Provider 的簡單專案，引入完整閘道器可能增加維護複雜度。

在團隊生產環境採用前，建議先完成四項驗證：客戶端協議相容、Provider 條款、金鑰與許可權隔離、閘道器故障時的降級路徑。

OmniRoute 遠端 VPS、Caddy HTTPS 與故障回退

OmniRoute 的這個教學只處理標題中的具體任務。遠端部署應讓 20128 只監聽回環位址，再由 Caddy 提供 TLS；Codex 使用受限端點令牌，自動回退需要可觀察而不能靜默換模型。

以下所有操作都先放在測試儲存庫、測試帳號或僅回環監聽的服務中。指令中的網域名稱、使用者名稱、路徑與金鑰是佔位符，執行前需要替換。

遠端網關的實際資料路徑

1

docker version

VPS 上準備 Docker 與持久性卷

1

docker volume create omniroute-data

讓 OmniRoute 只監聽 127.0.0.1

1

docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest

第一次讀取模型列表

1

curl.exe http://127.0.0.1:20128/v1/models -H 'Authorization: Bearer YOUR_KEY'

Caddy 反向代理的最小配置

1

caddy validate --config Caddyfile

簽發 HTTPS 後檢查憑證鏈

1

curl.exe -I https://ai.example.com/v1/models

為 Codex 建立專用存取令牌

1

curl.exe https://ai.example.com/v1/models -H 'Authorization: Bearer YOUR_KEY'

auto 路由與固定模型如何選擇

1

curl.exe http://127.0.0.1:20128/v1/chat/completions -H 'Content-Type: application/json' -d '{"model":"auto","messages":[{"role":"user","content":"ping"}]}'

Provider 限流時觀察回退

1

docker logs --since 10m omniroute

壓縮功能先離線評估

1

docker exec omniroute npm run eval:compression

備份 omniroute-data 而不是只備份鏡像

1

docker run --rm -v omniroute-data:/data -v ${PWD}:/backup alpine tar czf /backup/omniroute-data.tgz -C /data .

故障時讓 Codex 切回原端點

1

docker stop omniroute

從 Caddy 日誌區分網關和上游錯誤

1

caddy validate --config Caddyfile

限制遠端令牌可呼叫的模型

1

curl.exe https://ai.example.com/v1/models -H 'Authorization: Bearer YOUR_KEY'

模擬主 Provider 失效

1

docker logs --follow omniroute

升級鏡像時固定回滾標籤

1

docker image ls diegosouzapw/omniroute

部署驗收與回退

不要把「容器正在執行」當成部署完成。正式接入 Codex 前，完成一次固定模型請求、一次 auto 請求、一次主 Provider 故障和一次恢復演練，並保存時間戳、鏡像標籤、配置版本與脫敏日誌。

驗收項	通過標準	停止上線的訊號
網路邊界	`20128` 只繫結 `127.0.0.1`，公網只能透過 Caddy 的 HTTPS 網域訪問	VPS 公網 IP 可直接訪問 `20128`，或憑證鏈驗證失敗
令牌許可權	Codex 專用令牌只能列出和呼叫允許的模型	必須使用管理員令牌、上游完整金鑰，或能訪問未授權模型
路由可觀察性	固定模型與 `auto` 請求都成功；回退日誌能確認原 Provider、失敗原因和最終模型	模型靜默切換、無法判斷實際路由，或日誌洩露秘密值
資料與升級	`omniroute-data` 備份可解包，當前及上一穩定鏡像標籤均已記錄	只有 `latest` 且沒有可恢復的資料備份
Codex 回退	停止 OmniRoute 後能恢復原 API 端點，並完成一次最小請求	原端點、金鑰來源或恢復步驟不明確

驗收時每次只改變一個變數：先固定模型驗證端到端連線，再啟用 auto，最後模擬主 Provider 限流或不可用。若出現停止訊號，立即恢復 Codex 原端點；升級失敗則切回上一穩定鏡像，並從已驗證的 omniroute-data 備份恢復。不要為了讓測試通過而擴大令牌許可權、開放 20128 公網監聽或關閉日誌脫敏。

OmniRoute 常見問題

是否可以跳過測試環境，直接把 OmniRoute 用到正式專案？

不建議。至少先完成一次最小成功請求、一次故意失敗和一次恢復演練。

OmniRoute 指令能運作但結果不對，先查哪裡？

先查輸入範圍、實際生效的配置和上游響應，再查模型總結。進程正常不代表業務結果正確。

如何避免 OmniRoute 的金鑰或令牌進入 Git？

使用系統環境變數、Secret 管理或專案外設定文件，並在提交前搜尋 diff。發現洩漏後必須輪換密鑰。

升級 OmniRoute 時最容易漏掉什麼？

最容易漏掉配置格式、預設監聽位址、權限範圍和快取相容性。升級前儲存版本與驗證樣本。

總結

OmniRoute 用本地 http://localhost:20128/v1 把多個模型供應商接到統一 API 後面，透過 auto 和 combo 實現成本、速度、額度與健康狀態驅動的路由。npm 安裝適合本機體驗，Docker 適合持久執行；遠端部署時必須補齊 HTTPS、訪問控制、備份和審計。免費額度和壓縮比例都是動態指標，應結合上游條款和自己的基準測試評估。

專案地址：diegosouzapw/OmniRoute

官方網站：omniroute.online