AI Coding Agent 進入多模型時代：OmniRoute 如何用一個 API 接入 352 家 AI 服務商

多模型時代：Coding Agent 爲什麼不能綁死一家

Coding Agent 與聊天窗口的差別，不在商標，而在循環：讀文件、跑測試、改補丁、再觀察。循環越長，對可用性與成本越敏感。把 Agent 綁死在單一供應商，等於把整條流水線的 SLA 外包給對方的狀態頁。2026 年常見做法是「主模型 + 備用模型 + 便宜模型」：重推理走 Claude / GPT，批量改寫走 DeepSeek / 本地，視覺或搜索走另一家——但若每個 Agent 各自維護一套密鑰與 Base URL，運維成本會線性爆炸。

多模型不是「哪個更聰明」的選美，而是路由策略。你需要：統一的請求面（多數工具只懂 OpenAI Chat Completions 或 Anthropic Messages）、可觀測的失敗切換、以及不把業務契約綁在某一家的字段名上。Agent 循環裏真正貴的是 arguments / tool_result 形狀漂移——換模型時若 Schema 跟着變，聯調會比換密鑰更痛苦。工程定義見 AI Agent 是什麼。

因此「一個 API」的價值，首先是把供應商差異關在網關後面。IDE 與 CLI 只配置一次；換上游、加免費檔、做配額感知調度，都不改 Agent 側代碼。這與 MCP 解決「工具怎麼發現」是正交的：MCP 管 Agent 向下連 Tools，網關管模型請求往哪家發。對照 A2A vs MCP——多模型路由是第三條腿：模型層。

OmniRoute 是什麼：本地優先的 OpenAI 兼容網關

OmniRoute 是開源、MIT 許可的本地優先 AI 網關（亦稱 AI gateway / LLM proxy）。默認監聽 http://localhost:20128，對外提供 OpenAI 兼容的 /v1，對內維護服務商連接、模型目錄、Combo 策略、壓縮、MCP/A2A 與桌面/PWA 儀表盤。它不是「又一個雲上的模型超市」：流量默認出你的機器直連上游，密鑰與日誌留在本機（或你自己的 Docker 主機）。安裝可用 npm 全局包 omniroute，或 Docker 鏡像 diegosouzapw/omniroute。快速上手見官方 Quick Start。

產品承諾可以收成三句：Never stop coding（配額與宕機時自動換路）；一個端點接多種 Coding Agent；以及可選的 RTK + Caveman 壓縮，降低工具調用密集會話的 token 賬單。v3.8.50 一代把註冊服務商推到 352，聊天模型 ID 過千；後續版本繼續加模態橋接、免費檔雷達與配額感知調度（Quota-Share）。數字會隨目錄審計上下浮動——寫進方案時請引用當期 Provider Reference，而不是把 README 徽章當合同。

和「雲聚合 API」相比，本地網關的取捨是：你負責運行與升級，換來密鑰不出機、可接本地 Ollama、可給內網 CI 用同一端點。團隊若已有 LiteLLM / 自建 OpenAI 兼容代理，概念類似；OmniRoute 的差異化在 Coding Agent 一鍵 setup、免費檔目錄與壓縮棧。選型時問三件事：工具是否只認 OpenAI Base URL、是否需要自動降級、是否接受本機守護進程。

一個 API：/v1、auto 模型與協議翻譯

「一個 API」在 OmniRoute 裏通常指：把 IDE/CLI 的 Base URL 指到 http://localhost:20128/v1，API Key 用儀表盤簽發的網關密鑰（不是上游密鑰），Model 填 auto 或具體模型 ID。工具發出的仍是熟悉的 Chat Completions / Responses 形狀；網關再翻譯到 Claude、Gemini 等上游方言。對 Agent 作者而言，arguments 仍是 JSON object（常以字符串出現在 tool_calls 裏）——網關不替你改業務 Schema。

auto 不是玄學：它讓網關按 Combo / 策略在速度、成本、質量與可用性之間選路。配額打滿或上游 5xx 時，circuit breaker 與 fallback 鏈決定下一跳。你仍應在業務層處理「模型換了但 arguments 形狀必須不變」——否則降級成功、Schema 失敗，用戶只看到 Agent 卡住。Structured Output 與工具入參分文件的理由，見 AI Structured Output。

驗證端點是否活着，先打 GET /v1/models（帶 Bearer）。返回列表應反映你已連接的服務商，而不是全球 352 的全集——目錄是「可註冊」，連接是「你已授權」。日誌在儀表盤 Monitoring 裏可見：這對確認 Cursor / Claude Code 是否真打到網關、而不是繞開直連上游，極其有用。

352 家服務商：目錄、免費檔與配額調度

「352」是註冊目錄規模（chat、media、search、local、cloud-agent、system 等集合），不是你電腦上已連接的數量。其中約 150+ 帶有 hasFree: true 發現元數據；免費檔還有單獨的 token 池審計（多池去重後的月度 headline 會顯示在 Free Tiers 儀表盤）。分母不同是設計如此：寫文章或投標時，請分清「可發現服務商」「已連接」「有免費額度」。權威說明在倉庫的 Provider Reference 與 Free Tiers 文檔。

多模型時代的真實用法，往往是免費檔墊底 + 付費檔扛質量。官方 Quick Start 演示了 Kiro、OpenCode Free、Pollinations 等無需信用卡的連接路徑，用於先跑通 Agent 循環。生產上則應顯式配置主/備與預算：否則 auto 可能在低價池裏兜圈子，編碼質量抖動。Quota-Share 一類調度把「誰還剩額度」變成可觀測信號，而不是靠人手盯狀態頁。

目錄還會繼續漲（路線圖指向更多服務商）。工程上不要把「352」硬編碼進產品文案當永久承諾；應寫成「經 OmniRoute 目錄接入多家上游，數量以當期版本爲準」。對 JSONVue 讀者更重要的是：無論接了多少家，你發出的 chat/completions JSON 與工具 arguments Schema 應保持穩定——服務商數量是運維變量，契約是產品變量。

接到 Claude Code / Cursor / Codex 的實操

最小路徑：安裝 → 啓動 → 在儀表盤連接至少一個服務商 → 簽發網關 Key → 把工具 Base URL 指到 /v1。npm：npm install -g omniroute 後運行 omniroute；Docker：映射 20128 端口。許多 Coding Agent 可用 omniroute setup-* 或 omniroute run <cli> 一鍵改配置（claude、codex、aider、opencode、gemini 等）。細節以當期 CLI Integrations 文檔爲準。

以 Continue.dev / 任意 OpenAI 兼容插件爲例，配置形態如下：provider 選 openai，model 填 auto，apiBase 指向本地 /v1，apiKey 用網關 Key。Cursor、Cline、Copilot 同類：凡是允許自定義 OpenAI Base URL 的，都能掛上。AgentBridge 一類能力進一步覆蓋 IDE 側 MITM/映射（僅本機、有明確安全邊界）——那是進階項，首次接入不必上。

聯調清單建議固定三步：curl /v1/models 確認目錄；在 Agent 裏發一句無關緊要的補全，到 Monitoring 確認命中網關；再跑一條帶 tool_calls 的真實任務，抓 arguments 字符串做 parse。若工具仍直連 Anthropic/OpenAI 官方域名，說明配置未生效——這是最常見的「以爲接上了」事故。

下面是一份「客戶端視角」的請求信封示例（字段名示意）。真正業務 arguments 仍由你的 Agent Schema 決定；網關只負責把整包路由出去。

{
  "baseURL": "http://localhost:20128/v1",
  "apiKey": "omniroute_gateway_key",
  "model": "auto",
  "messages": [
    {
      "role": "user",
      "content": "Refactor auth middleware and keep the public JSON contract unchanged"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "applyPatch",
        "parameters": {
          "type": "object",
          "properties": {
            "path": { "type": "string" },
            "diff": { "type": "string" }
          },
          "required": ["path", "diff"],
          "additionalProperties": false
        }
      }
    }
  ]
}

{
  "requestId": "req_7c2a",
  "selected": {
    "provider": "anthropic",
    "model": "claude-sonnet-4",
    "reason": "quota_ok + latency"
  },
  "fallback": [
    { "provider": "openai", "model": "gpt-5" },
    { "provider": "deepseek", "model": "deepseek-chat" }
  ],
  "status": "routed"
}

JSON 契約、降級與 JSONVue 校驗

多模型路由放大了兩類故障：上游 HTTP 失敗（應由網關 fallback），以及成功返回但 JSON 不合契約（網關幫不了你）。第二類在換模型、換壓縮、換免費檔時更容易出現：數字變字符串、漏 required、tool 名與緩存清單不一致。分類法見 AI 生成 JSON 錯誤指南。每個 hop 仍是 parse → Schema → 業務規則。

1. 保存一份 canonical tools Schema；所有上游只生成外殼，不改鍵名與枚舉。
2. 降級演練：人爲斷開主服務商，確認 Agent 仍能用同一 arguments 形狀完成任務。
3. 對 /v1/models 與 chat 響應抽檢：用 Schema 卡住 id、choices、tool_calls 結構，避免靜默字段漂移。

瀏覽器裏：JSON 格式化看清響應樹；JSON Schema 校驗卡 arguments 與 fixture；JSON Diff對比主模型與備用模型返回的 tool_calls。固定 valid / missing-field / wrong-enum 三份夾具，CI 與手工共用。上下文窗口變大時，別忘了預算 JSON——見 1M Token 上下文。

延伸閱讀：AI Agent 是什麼、什麼是 MCP、MCP 與 JSON Schema、大模型宕機觀察。

常見問題 FAQ

總結與下一步

Coding Agent 的多模型時代，勝負手不在「又接入一家」，而在一個穩定請求面 + 可觀測降級 + 不變的 JSON 契約。OmniRoute 用本地 /v1 把 352 家目錄關在網關後，讓 Claude Code、Cursor、Codex 等只配置一次。

下一步：按 Quick Start 跑通 curl /v1/models；把一個日常 Agent 改到 localhost；準備三份 Schema 夾具做降級演練。協議與工具層讀 MCP/Agent 文；契約層用 JSONVue 盯緊 arguments。