AI工具

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

介紹 OmniRoute 本地 AI 閘道器的安裝與配置，涵蓋 OpenAI 相容介面、Provider 接入、auto 模型路由、故障回退、Docker 部署及 MCP 安全。

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

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

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

代價是 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。建議按以下順序操作：

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

不要在截圖、日誌或問題反饋中暴露 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 測試：

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

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

免費額度與供應商條款

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

還要區分三類資源：

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

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

專案地址：diegosouzapw/OmniRoute

官方網站：omniroute.online