使用手冊

第 01 期 · 本機 AI Gateway / LLM Router

OmniRoute 自動路由 AI Gateway

OmniRoute 是 MIT 授權的本機 AI Gateway，以單一相容端點整合 290+ 個供應商、500+ 個模型、19 種路由策略、三層韌性機制、CLI 整合、壓縮與 MCP/A2A。本文提供安裝、Codex 連接、路由選擇、驗證方式與正式環境注意事項。

OmniRoute 將 290+ 個供應商與 500+ 個模型整合到本機相容端點，讓 Codex、Claude Code 與其他 AI 工具共用一套連線設定。它提供 19 種路由策略、三層韌性機制、CLI 設定器、壓縮管線與逐請求決策資訊。

diegosouzapw/omniroute
星標
—
分支
—
授權
—
資料截至
—
閱讀時間
8 分
更新日期
開啟原始報告
GitHub Stars
34.9k
路由策略
19
韌性層級
3
開源授權
MIT
本頁章節

01系統定位

本機相容端點與上游路由層

OmniRoute 是執行於使用者環境的 AI Gateway。它對工具提供 http://localhost:20128/v1 等相容介面，並把請求送往已連接的上游供應商；OpenAI、Anthropic、Gemini 與 Responses API 格式可在閘道層轉換。

auto 不需要預先建立 combo。系統會根據目前已連接的供應商建立虛擬候選池，再依健康度、額度、成本、延遲與歷史表現等訊號選擇模型；若上游失敗，路由層可改選下一個可用候選。

回應中的 X-OmniRoute-Decision 可用來確認策略、供應商與路由延遲，其他 X-OmniRoute-* 標頭則提供成本與使用量資訊。這些標頭可驗證路由結果，補充儀表板的狀態資訊。

  1. IDE / CLI

  2. localhost:20128/v1

  3. Auto 候選池

  4. 韌性檢查

  5. 上游供應商

  6. 決策標頭

“No combo to create. Set your model to auto.”

— 官方 README · Combos

02安裝與連接

安裝、啟動與連線驗證

npm 套件要求 Node.js ≥ 22.22.2 且 < 23，或 ≥ 24 且 < 27。全域安裝後執行 omniroute，儀表板與 Gateway 會使用本機 port 20128。

bash
# 全域安裝並啟動 Gateway 與儀表板
npm install -g omniroute
omniroute

# 儀表板：http://localhost:20128
# OpenAI 相容 API：http://localhost:20128/v1

供應商與 API 驗證

先在儀表板的 Providers 頁面連接可用供應商，再從 Endpoints 取得 API key。模型可先設為 auto，並用模型清單端點確認授權與連線。

bash
# OpenAI 相容工具設定
Base URL: http://localhost:20128/v1
API Key:  [從儀表板 → Endpoints 複製]
Model:    auto

# 驗證授權並列出可用模型
curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"

Docker 與 Codex 啟動器

官方容器命令將服務只綁定到 loopback，資料則保留在命名 volume。Codex 可用 omniroute launch-codex 啟動；此類 launcher 不會改寫現有設定檔。

bash
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

# 以目前環境啟動 Codex，不寫入設定檔
omniroute launch-codex

03核心能力

十九種策略與周邊能力

19 種策略涵蓋固定順序、負載分散、成本、額度、context、快取、評分與多模型工作流。先以 auto 建立基準，再依可重現的需求改用明確策略。

Route · 01

priority · fill-first

固定順序與額度填滿

priority 依清單順序選擇；fill-first 先使用目前候選，達到條件後再移至下一個。

Route · 02

weighted · round-robin

權重與輪替

weighted 依設定權重分配；round-robin 逐一輪替候選，適合可預期的分流。

Route · 03

p2c · least-used

低負載選擇

p2c 比較兩個隨機候選；least-used 選擇近期使用量較低者。

Route · 04

random · strict-random

隨機分流

random 可在失敗時重選；strict-random 保持一次隨機決策的嚴格語意。

Route · 05

cost-optimized · headroom

成本與餘量

cost-optimized 優先考量單價；headroom 優先考量剩餘額度。

Route · 06

reset-window · reset-aware

額度重設時窗

兩種策略都把額度重設時間納入決策，適合週期性配額與多帳號連線。

Route · 07

context-relay · context-optimized

Context 管理

context-relay 在模型間接續長對話；context-optimized 依 context 條件選擇候選。

Route · 08

cache-optimized · lkgp

快取與歷史表現

cache-optimized 納入快取效益；lkgp 使用最近已知良好表現協助選擇。

Route · 09

auto · fusion · pipeline

評分與工作流

auto 動態評分；fusion 組合多模型結果；pipeline 依序執行多階段工作。

Resilience · 10

breaker · cooldown · lockout

三層故障隔離

供應商熔斷器、連線冷卻與模型鎖定分別處理不同失敗範圍；模型鎖定預設關閉。

Compression · 11

RTK + Caveman

請求壓縮

壓縮管線可降低送往模型的 token；正式採用前可在源碼 checkout 執行 npm run eval:compression 進行離線評估。

Protocol · 12

--mcp · A2A · connect

Agent 與遠端控制

omniroute --mcp 提供 MCP；A2A 支援 agent 互通；omniroute connect 連接遠端執行個體。

Auto 模型識別碼

模型識別碼主要取向
auto平衡預設，搭配最近已知良好表現
auto/coding程式任務的品質優先
auto/fast低延遲優先
auto/cheap低成本優先
auto/offline額度餘量優先
auto/smart品質評分並保留探索比例

04操作原則

可驗證的設定順序

設定原則依目前預設分支的 README 與官方文件整理，各項均附設定或驗證點。

TIP 01 · auto 基準設定

模型設為 auto 時，系統會從目前連線即時建立虛擬候選池，不需先寫入 combo。確認命中結果後，再改用情境變體或固定策略。

來源 · docs/routing/AUTO-COMBO.md

TIP 02 · 決策標頭與路由核對

讀取 X-OmniRoute-Decision，確認實際策略、供應商與路由延遲。成本與用量則由其他 X-OmniRoute-* 標頭補充。

來源 · 官方 README · Routing Decision

TIP 03 · 設定前的 dry run

setup-codex 會建立 ~/.codex/<name>.config.toml。先使用 --dry-run 檢查預定內容，避免覆蓋既有工作設定。

來源 · docs/guides/CODEX-CLI-CONFIGURATION.md

TIP 04 · 臨時整合的 launcher

omniroute launch-codex 與其他 launcher 會帶入目前環境所需值，但不寫入工具設定檔。可用於驗證單次工作階段。

來源 · docs/guides/CLI-INTEGRATIONS.md

TIP 05 · 三層韌性的作用範圍

供應商熔斷器、連線冷卻與模型鎖定處理不同失敗層級。模型鎖定預設關閉，不能把三層一概視為已啟用。

來源 · docs/architecture/RESILIENCE_GUIDE.md

TIP 06 · header 授權資訊

標準整合使用 Authorization: Bearer。只有 client 無法傳送自訂 header 時，才採用含 token 的相容路徑。

來源 · docs/guides/CLI-INTEGRATIONS.md

TIP 07 · 記憶功能的啟用條件

Memory 預設關閉。啟用後才會把相關資料保存在本機；處理敏感內容前，應先確認資料保留範圍與清除流程。

來源 · 官方 README · Memory

TIP 08 · 安全防護的逐項確認

Prompt injection guard 預設為警告模式；credential masker 則需主動啟用。正式環境不能把 guardrail 當成唯一安全邊界。

來源 · docs/security/GUARDRAILS.md

05實戰示範

Codex 連線與路由核對

下列終端內容是操作順序示意。命令來自官方 README 與 CLI 文件；方括號中的文字只說明應觀察的結果，不代表固定供應商、費用或延遲。

~/projects/app · OmniRoute 操作示意


$ npm install -g omniroute
$ omniroute


# [確認儀表板可由 http://localhost:20128 開啟]
# [在 Providers 連接供應商，並於 Endpoints 取得 key]


$ omniroute doctor
# [檢查 Gateway、連線與必要設定]


$ curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"
# [確認回應包含目前可用模型]


$ omniroute launch-codex
# [launcher 啟動 Codex，不寫入設定檔]


$ codex ›
  檢查這個專案的測試失敗原因。


# [request model=auto/coding]
# [由 X-OmniRoute-Decision 核對策略、供應商與延遲]
ok: [由 X-OmniRoute-* 核對成本與使用量]

“One config — http://localhost:20128/v1 — and every AI IDE or CLI runs on free & low-cost models.”

— 官方 README · Quick Start

驗證重點

啟動成功後仍需驗證路由。先確認模型清單，再以實際請求的 X-OmniRoute-Decision 檢查命中供應商與策略。若啟用壓縮，另讀取 X-OmniRoute-Compression，並以代表性工作負載比較輸出品質。

需要長期設定時，再執行 setup-codex --dry-run 檢查預定寫入內容。Codex 使用的 Base URL 是 /v1；其他協定的根路徑可能不同，不能直接複製同一值。

06邊界與限制

正式環境的限制清單

07進階路徑

從本機驗證到受控部署

完成本機連線後，依序建立健康檢查、策略基準、設定管理、遠端存取與可觀測性。每一步都應保留可重現的驗證結果。

導入路徑

**1. 建立本機健康基準。**完成安裝、Providers 與 Endpoints 設定後，執行 omniroute doctor、模型清單請求與一筆實際推論。

**2. 比較 Auto 變體。**以相同工作負載測試 auto、auto/coding、auto/fast 與 auto/cheap，記錄決策標頭、延遲、成本與任務品質。

**3. 固化設定與策略。**使用 setup-codex --dry-run 檢查持久設定；有固定順序、成本上限或 context 需求時，再建立持久 combo。

**4. 評估 Agent 與遠端介面。**需要 agent 控制時再啟用 MCP 或 A2A；遠端執行個體則使用 omniroute connect，並配置最小權限與受保護的網路端點。

**5. 納入可觀測性。**保存 X-OmniRoute-Decision、成本、使用量與壓縮標頭，並把供應商失敗、fallback 與配額事件接入既有監控流程。

三份延伸文件

① docs/routing/AUTO-COMBO.md：Auto 候選池、模型識別碼與評分流程。

② docs/guides/CLI-INTEGRATIONS.md：各工具的 setup 與 launcher 行為。

③ docs/architecture/RESILIENCE_GUIDE.md：熔斷器、冷卻與模型鎖定的範圍。

“Self-managing model chains with adaptive scoring + zero-config auto-routing.”

— docs/routing/AUTO-COMBO.md