OmniRoute 將 290+ 個供應商與 500+ 個模型收斂到本機相容端點，讓 Codex、Claude Code 與其他 AI 工具共用一套連線設定。它提供 19 種路由策略、三層韌性機制、CLI 設定器、壓縮管線與逐請求決策資訊。
OmniRoute 是執行於使用者環境的 AI Gateway。它對工具提供 http://localhost:20128/v1 等相容介面，並把請求送往已連接的上游供應商；OpenAI、Anthropic、Gemini 與 Responses API 格式可在閘道層轉換。
auto 不需要預先建立 combo。系統會根據目前已連接的供應商建立虛擬候選池，再依健康度、額度、成本、延遲與歷史表現等訊號選擇模型；若上游失敗，路由層可改選下一個可用候選。
回應中的 X-OmniRoute-Decision 可用來確認策略、供應商與路由延遲，其他 X-OmniRoute-* 標頭則提供成本與使用量資訊。這些資料讓路由結果可驗證，而不是只依賴儀表板狀態。
npm 套件要求 Node.js ≥ 22.22.2 且 < 23，或 ≥ 24 且 < 27。全域安裝後執行 omniroute，儀表板與 Gateway 會使用本機 port 20128。
先在儀表板的 Providers 頁面連接可用供應商，再從 Endpoints 取得 API key。模型可先設為 auto，並用模型清單端點確認授權與連線。
官方容器命令將服務只綁定到 loopback，資料則保留在命名 volume。Codex 可用 omniroute launch-codex 啟動；此類 launcher 不會改寫現有設定檔。
Authorization: Bearer 的 client。一般整合應使用標頭，避免 key 出現在 URL、記錄或瀏覽歷程。
19 種策略涵蓋固定順序、負載分散、成本、額度、context、快取、評分與多模型工作流。先以 auto 建立基準，再依可重現的需求改用明確策略。
priority 依清單順序選擇；fill-first 先使用目前候選，達到條件後再移至下一個。weighted 依設定權重分配；round-robin 逐一輪替候選，適合可預期的分流。p2c 比較兩個隨機候選；least-used 選擇近期使用量較低者。random 可在失敗時重選；strict-random 保持一次隨機決策的嚴格語意。cost-optimized 優先考量單價；headroom 優先考量剩餘額度。context-relay 在模型間接續長對話；context-optimized 依 context 條件選擇候選。cache-optimized 納入快取效益；lkgp 使用最近已知良好表現協助選擇。auto 動態評分；fusion 組合多模型結果；pipeline 依序執行多階段工作。npm run eval:compression 進行離線評估。omniroute --mcp 提供 MCP；A2A 支援 agent 互通；omniroute connect 連接遠端執行個體。| 模型識別碼 | 主要取向 |
|---|---|
auto |
平衡預設，搭配最近已知良好表現 |
auto/coding |
程式任務的品質優先 |
auto/fast |
低延遲優先 |
auto/cheap |
低成本優先 |
auto/offline |
額度餘量優先 |
auto/smart |
品質評分並保留探索比例 |
以下原則整理自目前預設分支的 README 與官方文件。每項都包含可觀察的設定或驗證點。
模型設為 auto 時，系統會從目前連線即時建立虛擬候選池，不需先寫入 combo。確認命中結果後，再改用情境變體或固定策略。
讀取 X-OmniRoute-Decision，確認實際策略、供應商與路由延遲。成本與用量則由其他 X-OmniRoute-* 標頭補充。
setup-codex 會建立 ~/.codex/<name>.config.toml。先使用 --dry-run 檢查預定內容，避免覆蓋既有工作設定。
omniroute launch-codex 與其他 launcher 會帶入目前環境所需值，但不寫入工具設定檔。這適合先驗證單次工作階段。
供應商熔斷器、連線冷卻與模型鎖定處理不同失敗層級。模型鎖定預設關閉，不能把三層一概視為已啟用。
來源 · docs/architecture/RESILIENCE_GUIDE.md標準整合使用 Authorization: Bearer。只有 client 無法傳送自訂 header 時，才採用含 token 的相容路徑。
Memory 預設關閉。啟用後才會把相關資料保存在本機；處理敏感內容前，應先確認資料保留範圍與清除流程。
來源 · 官方 README · MemoryPrompt injection guard 預設為警告模式；credential masker 則需主動啟用。正式環境不能把 guardrail 當成唯一安全邊界。
來源 · docs/security/GUARDRAILS.md下列終端內容是操作順序示意。命令來自官方 README 與 CLI 文件；方括號中的文字只說明應觀察的結果，不代表固定供應商、費用或延遲。
啟動成功不等於路由正確。先確認模型清單，再以實際請求的 X-OmniRoute-Decision 檢查命中供應商與策略。若啟用壓縮，另讀取 X-OmniRoute-Compression，並以代表性工作負載比較輸出品質。
需要長期設定時，再執行 setup-codex --dry-run 檢查預定寫入內容。Codex 使用的 Base URL 是 /v1；其他協定的根路徑可能不同，不能直接複製同一值。
npm run eval:compression 和代表性資料建立品質基準，再決定是否套用到正式流量。
setup-codex 可建立具名 TOML 設定。先使用 --dry-run，並保留原設定；只需臨時測試時使用 launch-codex。
Authorization: Bearer。
完成本機連線後，依序建立健康檢查、策略基準、設定管理、遠端存取與可觀測性。每一步都應保留可重現的驗證結果。
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——熔斷器、冷卻與模型鎖定的範圍。