實戰手冊 · Field Manual 2026 春季號
github.com/diegosouzapw/OmniRoute · 6.7k ★
O
第 01 期 · 開源 AI Gateway / LLM Router

一個端點,
接上 231 個
AI 供應商。

OmniRoute 是 MIT 授權的開源本機 AI gateway,把 231 個供應商(50+ 提供免費額度)收斂成單一 OpenAI 相容端點。Claude Code、Codex、Cursor、Cline、Copilot 等 16+ 工具只要指向 localhost:20128/v1 即可使用免費與低成本模型;額度用盡時自動 fallback 到下一個供應商,RTK + Caveman 堆疊壓縮再省下 15–95% token。本手冊涵蓋安裝、核心能力、官方設定要點與一段完整實戰示範。

231
AI 供應商
50+
含免費額度
95%
最高省 Token
MIT
開源授權
01
這是什麼

一個跑在本機的
AI 路由代理。

OmniRoute 由 Diego Souza 開源,核心是一個跑在你機器上的 本機 proxy:它對外暴露單一 OpenAI 相容端點 http://localhost:20128/v1,對內把請求轉發到 231 個 AI 供應商。任何 OpenAI / Claude / Gemini 格式的工具只要改一個 Base URL 就能接上,不需要改其他設定。請求不經過 OmniRoute 的雲端——你的 prompt 只會送到你自己選的供應商。

它解決的是一個具體問題:每個 AI 供應商各有 SDK、各有 rate limit、各有帳單。手動拼接十幾個免費額度幾乎不可行。OmniRoute 把這些供應商聚合到一個端點,並做三件事——格式翻譯(OpenAI ↔ Claude ↔ Gemini ↔ Responses API)、自動 fallback(額度或供應商失敗時毫秒級切換),以及 token 壓縮(請求送出前透明壓縮)。

架構上分成四層能力:路由(15 種策略 + 9 因子自動評分)、韌性(熔斷器、連線冷卻、模型鎖定三層獨立保護)、壓縮(9 引擎管線),以及協定(內建 MCP server 與 A2A,讓 agent 能直接驅動 gateway)。下面逐層拆解。

請求路徑 · 從工具到供應商
IDE / CLI→ localhost:20128/v1→ 壓縮→ 路由評分→ 供應商→ 失敗 fallback
一個端點,231 個供應商。
請求 100% 跑在你的硬體上,
OmniRoute 的雲端不在請求路徑裡。
— 依官方 README「Private & Local-First」段落
02
安裝與連接

兩行裝好,
把工具指向同一端點。

環境需求:Node.js ≥ 22。透過 npm 全域安裝後執行 omniroute,gateway 與儀表板會起在 port 20128。

# 1) 全域安裝並啟動 gateway + 儀表板 npm install -g omniroute omniroute # 儀表板:http://localhost:20128 · API:http://localhost:20128/v1

連一個免費供應商(不用註冊)

在儀表板 → Providers 連接 Kiro AI(免費 Claude)或 OpenCode Free(免認證)即可。然後把你的 coding 工具指向 OmniRoute,model 設為 auto 走零設定智慧路由:

# 把任何 OpenAI 相容工具指向 OmniRoute Base URL: http://localhost:20128/v1 API Key: [從 儀表板 → Endpoints 複製] Model: auto # 零設定智慧路由,或填 provider/model # 驗證連線:列出可用模型 curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"

Docker / 其他安裝方式

官方提供 multi-arch(AMD64 + ARM64)映像。也支援從源碼、pnpm、Arch(AUR)、Nix、Podman、Android Termux 與桌面版(Electron)安裝——詳見 README 的「Where OmniRoute Runs」表。

docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \ -p 20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
不能送自訂 header 的 client?OmniRoute 另外提供帶 token 的相容路徑,例如 http://localhost:20128/vscode/YOUR_KEY/chat/completions(OpenAI)與 /vscode/YOUR_KEY/api/chat(Ollama)。官方說明:這些只給無法附帶 Authorization: Bearer 的工具用,header 驗證仍是首選。
03
核心能力

路由、韌性、壓縮、
協定四層。

下表把 OmniRoute 的能力依四層分組。日常只需記住三件事:model 填 auto 走智慧路由、韌性三層預設啟用、壓縮預設管線是 RTK → Caveman。其餘能力(MCP、A2A、Remote mode)是進階場景才需要。

Route · 01
auto
零設定智慧路由
不用建 combo,從已連接供應商即時組出虛擬 combo,以 9 因子(健康度、額度、成本、延遲、成功率、新鮮度…)即時評分。
Route · 02
auto/coding · auto/cheap · auto/fast
情境變體
同一引擎的權重變體:coding 重品質、cheap 重單價、fast 重延遲、offline 重額度餘量、smart 多 10% 探索。
Route · 03
combo
15 種路由策略
priority、fill-first、round-robin、weighted、p2c、least-used、cost-optimized、context-relay、random… 也可串接 combo-ref。
Resilience · 04
circuit-breaker
熔斷器
作用於整個供應商:上游失敗時停止打,並自動探測恢復。
Resilience · 05
connection-cooldown · model-lockout
冷卻與鎖定
冷卻作用於單一帳號/金鑰,跳過被限速的 key;鎖定只隔離單一額度用盡的模型,不影響整條連線。
Compress · 06
RTK → Caveman
堆疊壓縮
9 引擎管線,可逐 combo 開關。預設 RTK→Caveman,工具密集 session 平均約 89%,範圍 15–95%。Code、URL、JSON 保留 byte-perfect。
Compress · 07
LLMLingua-2
ML 語意修剪
經 MobileBERT ONNX 做語意修剪,code-safe、非同步。另含 Session-Dedup、CCR、Headroom、Ultra 等引擎。
Protocol · 08
omniroute --mcp
MCP server
內建 87 工具、3 種傳輸(stdio / HTTP / SSE)、30 scopes、完整稽核軌跡。可讓 agent 控制路由、供應商、combo、快取、記憶。
Protocol · 09
/.well-known/agent.json
A2A 互通
Agent-to-agent 協定,JSON-RPC 2.0 + SSE,6 skills,讓外部 agent 自主驅動 gateway。
Protocol · 10
omniroute connect
Remote mode
OmniRoute 跑在 VPS,用同一套 CLI 從筆電驅動。scoped token 分 read/write/admin;會生程序的路由維持 loopback-only。
Security · 11
guardrails
防護與加密
prompt-injection guard(附 red-team 測試)、PII / 注入 / 視覺防護、API 金鑰與 OAuth token 以 AES-256-GCM 加密,預設零遙測。
Platform · 12
omniroute <cmd>
CLI 駕駛艙
60+ 指令:providers、keys、combo、models、cache、compression、cost、usage、quota、health、mcp、a2a、memory… 跨 Web/Desktop/Termux/PWA,42 語系。

該用哪個路由策略?一張表決定

你的目標 策略 / combo
榨乾訂閱額度再付費 priority · fill-first
多帳號分散負載 round-robin · weighted · p2c · least-used
永遠選最便宜可用的模型 cost-optimized · auto/cheap
長 context 在模型間接力 context-relay · context-optimized
隨機 / 隱私路由 random · strict-random
不想決定,讓它自己選 auto(9 因子評分)· lkgp
04
官方文件記載的設定要點

依官方文件,
這樣設定最省。

以下八條全部來自官方 README 與 docs/,不含社群傳聞或未驗證的數字。每張卡標注出處段落。

TIP 01

先用 auto,不用建 combo

model 直接填 auto,OmniRoute 會從你已連接的供應商即時組出虛擬 combo 並評分。需要時再用 auto/coding、auto/cheap 等變體微調權重。

來源 · 官方 README「Combos」段落
TIP 02

連免費供應商不需信用卡

儀表板 → Providers 連 Kiro AI(免費 Claude)或 OpenCode Free(免認證)即可開始。README 列出 11 個「永久免費」供應商。

來源 · 官方 README「Quick Start」
TIP 03

一鍵設定每個 coding tool

專用的 setup-* 指令會把各工具設定成走 OmniRoute(Claude Code、Codex、Cline、Cursor、Aider、Gemini CLI…);omniroute launch 是零設定啟動器。

來源 · 官方 docs/guides/CLI-INTEGRATIONS.md
TIP 04

把 OmniRoute 放 VPS,用 Remote mode

omniroute connect <host> 以密碼換取 scoped token,之後每個指令都打遠端。tokens create --scope read 可為其他機器簽發更窄的 token。

來源 · 官方 docs/guides/REMOTE-MODE.md
TIP 05

壓縮預設管線是 RTK → Caveman

9 引擎可逐 combo 指派,並有 Lite / Standard / Aggressive / Ultra / Stacked 等一鍵預設。Code、URL、JSON、結構化資料一律 byte-perfect 保留。

來源 · 官方 docs/compression/COMPRESSION_ENGINES.md
TIP 06

記憶體預設關閉,且可逐請求控制

Memory 預設 off;開啟後支援 int8 向量量化(Qdrant + sqlite-vec)。單一請求可加 x-omniroute-no-memory header 跳過記憶。

來源 · 官方 docs/frameworks/MEMORY.md
TIP 07

每個 endpoint 都有成本遙測 header

回應帶 X-OmniRoute-* cost/usage header(含媒體端點),快取命中時帶 X-OmniRoute-Cost-Saved,也可為每把 key 設 USD 花費上限。

來源 · 官方 docs/reference/API_REFERENCE.md
TIP 08

把整個 gateway 交給 agent 控制

用 claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream,Claude Code 即取得 87 個 MCP 工具,可自主管理路由與供應商。

來源 · 官方 README「Full CLI + A2A & MCP」
05
實戰示範

從安裝到
第一次 自動 fallback。

以下示範一條最短路徑:安裝 OmniRoute、連一個免費供應商、把 Claude Code 指向本機端點、用 auto 跑一輪,並觀察免費額度用盡時自動切到下一個供應商。指令均取自官方 README。

~/projects/app · omniroute v3.8.x
$ npm install -g omniroute && omniroute
[OmniRoute] gateway listening on http://localhost:20128 [OmniRoute] dashboard http://localhost:20128 [OmniRoute] api http://localhost:20128/v1
# 在儀表板 → Providers 連接 Kiro AI(免費 Claude)+ OpenCode Free
$ curl http://localhost:20128/v1/models -H "Authorization: Bearer $OMNI_KEY"
{ "data": [ { "id": "auto" }, { "id": "kr/claude-sonnet-4.5" }, { "id": "oc/gpt-5.1" } ] }
# 把 Claude Code 指向 OmniRoute(一鍵設定) $ omniroute setup claude-code [setup] wrote base_url = http://localhost:20128/v1 · model = auto ✓
claude › 重構這個檔案,把 callback 改成 async/await。
[route] model=auto · strategy=lkgp · 9-factor score [route] → kr/claude-sonnet-4.5 (free · health 1.0 · quota 88%) [compress] RTK → Caveman · 6,410 → 1,180 tok (saved 81.6%) [ok] 200 · X-OmniRoute-Cost: $0.00 · X-OmniRoute-Cost-Saved: $0.031
claude › 再跑一次,順便補單元測試。
[route] → kr/claude-sonnet-4.5 [quota] kr/claude-sonnet-4.5 額度用盡 → model lockout(只鎖這個模型) [route] fallback → oc/gpt-5.1 (free · 毫秒級切換) [ok] 200 · 沒有中斷 · combo 自動接手 ✓
額度用盡的是單一模型,
被鎖定的也只有那個模型——
連線不斷,下一個供應商接手。
— 對應官方 README「Resilience」的三層保護

這段示範的重點

全程沒有改 client 程式,只改了一個 Base URL。壓縮在請求送出前透明發生,client 不需要知道;fallback 由 combo 自動處理,額度用盡不會讓對話中斷。成本 header 讓你能逐請求看到實際花費與省下的金額。

要強調的是:示範中的 token 數、節省比例與供應商命中是說明性數值,實際結果取決於你連接哪些供應商、開了哪些壓縮引擎,以及各供應商當下的額度狀態。

06
邊界與限制

先了解限制,
再接上 production。

  • 免費額度數字是聚合估算,會變動。README 的「~1.6B 免費 token/月」是把 40+ 供應商的文件記載免費 tier 去重後加總,並非 OmniRoute 發給你的額度。各供應商可隨時調整或關閉免費方案,儀表板對每個供應商標有 terms flag。
  • 多供應商等於多份服務條款。同時使用多個免費 / 訂閱帳號時,務必確認各供應商的 ToS 是否允許這種用法。OmniRoute 只負責路由,合規責任在你。
  • 壓縮對散文是有損的。Code、URL、JSON、結構化資料保留 byte-perfect,但 Caveman / LLMLingua-2 對一般 prose 是語意壓縮。高精度需求的純文字任務,建議降到 Lite 或關閉壓縮。
  • MITM / TPROXY 需要安裝 CA 憑證。要攔截忽略 proxy 環境變數的 CLI 流量,需把 OmniRoute 的憑證裝進系統信任庫。理解這代表的信任範圍再啟用,不要在共用機器上隨意開。
  • 需要 Node.js ≥ 22。低於此版本無法啟動。容器化部署請用官方 multi-arch 映像,避免本機 Node 版本問題。
  • 會生程序的路由維持 loopback-only。Remote mode 下,process-spawning 路由不對遠端開放;token 分 read / write / admin,給其他機器時請簽發最窄 scope。
  • 記憶體預設關閉是刻意的。開啟 memory 會把對話內容寫入本機向量庫。需要隱私時保持預設關閉,或對單一請求加 x-omniroute-no-memory header。
  • 數字以發布版本為準。本手冊數據對應 README 當前狀態(v3.8.x 區間)。供應商數量、工具數、引擎數會隨版本變動,以 repo README 與 CHANGELOG.md 為準。
07
進階路徑

把 OmniRoute
接成你的基礎設施。

裝好、跑通 auto 之後,下面五步把 OmniRoute 從「個人省錢工具」推進到「團隊 / agent 基礎設施」。

進階玩法地圖

1. 自訂 combo 與壓縮 profile。用 omniroute combo 建你自己的 fallback 鏈(訂閱 → API → 便宜 → 免費),並逐 combo 指派壓縮管線。tool-heavy 的 session 用 Stacked(RTK → Caveman),高精度任務用 Lite。

2. 把 gateway 交給 agent。透過 MCP(omniroute --mcp 或 HTTP /api/mcp/stream)讓 Claude Code 取得 87 個工具自主管理路由;或用 A2A(/.well-known/agent.json)讓外部 agent 互通。

3. 部署到永遠在線的地方。用 Docker(multi-arch)或 Android Termux 讓 OmniRoute 24/7 運行,再用 Remote mode(omniroute connect)從任何機器以 scoped token 驅動。

4. 接更多供應商與 cloud agent。從 docs/reference/PROVIDER_REFERENCE.md 的機器可讀目錄擴充供應商;cloud agent 支援 Codex、Devin、Jules、Cursor Cloud Agent。

5. 收斂成本可觀測性。用 X-OmniRoute-* header 與 omniroute cost / usage 指令把每把 key 的花費拉出來,設 USD 上限,讓免費與付費的界線可監控。

最該讀的三份延伸閱讀

① docs/reference/FREE_TIERS.md——免費額度的計算方法、去重邏輯與各供應商條款。
② docs/routing/AUTO-COMBO.md——9 因子自動評分引擎與 combo 語法。
③ docs/compression/COMPRESSION_ENGINES.md——9 引擎管線、保留規則與省 token 計算。

本機 proxy、MIT 授權、源碼全開。
你可以逐行審查,然後永久自架。
— 依官方 README「Private & Local-First」段落