Switchyard 是位於客戶端與模型後端之間的 AI Gateway，值得需要統一編碼 Agent 入口、模型協定轉換與分層路由的團隊評估；但你本週應先完成兼容性、串流與故障回退測試，再決定是否部署。它目前仍是早期軟體，不應因為採用 Rust 就直接推導出高效能或生產穩定性。
最後更新於 2026 年 8 月 14 日；資料核實自 Switchyard 官方 Architecture、Getting Started、Routing 文件與官方倉庫目前的成熟度說明。
這篇適合三類讀者：希望統一 Claude Code 等客戶端模型入口的開發者；需要在強弱模型之間實施路由策略的 AI 平台團隊；正在評估自託管 AI Gateway 的基礎設施負責人。
先用一張表確認 Switchyard 的位置
Switchyard 不直接取代你的編碼 Agent，也不是模型本身。它位於應用程式、CLI Agent 與一個或多個模型後端之間，主要負責四件事：
- 接收客戶端原生格式的請求。
- 根據路由規則選擇後端。
- 把請求與回應轉成對方需要的格式。
- 在後端失敗、被淘汰或需要升級時執行回退。
官方目前列出的協定範圍包括 OpenAI Chat Completions、OpenAI Responses 與 Anthropic Messages。完整架構可參考官方架構說明。
| 元件 | Switchyard 的作用 | 你要驗證的事項 |
|---|---|---|
| 客戶端 | 保留原本的 API 呼叫方式 | Base URL、模型 ID、認證是否正確 |
| 協定層 | 轉換 OpenAI、Anthropic 與 Responses 格式 | 工具呼叫、串流、結構化輸出是否一致 |
| 路由層 | 選擇弱模型、強模型或指定後端 | 分流條件是否可解釋 |
| 回退層 | 後端失敗或被淘汰時切換目標 | 是否保留錯誤原因與路由紀錄 |
| 後端 | 對接遠端或自託管模型服務 | 上游格式、上下文限制與工具能力 |
這個位置能消除多個客戶端各自維護模型設定的問題。但它也新增一層故障面：原本一次 API 呼叫，現在可能經過路由判斷、格式轉換、上游重試與模型回退。
第一步：先判斷你是否真的需要一個 Rust AI Gateway
你需要的通常不是「另一個模型代理」，而是可控的流量管理層。以下限制，是 Switchyard 比單純修改客戶端環境變數更有價值的地方。
第一，客戶端格式不一致。
不同 Agent 可能依賴不同訊息格式。你若把每個模型後端直接接到每個客戶端，就會出現多組 Base URL、金鑰、模型別名與工具格式。Switchyard 可以把這些差異集中到閘道層處理。
第二，強弱模型切換難以解釋。
單純以成本選模型，可能把需要工具操作、長上下文或複雜修正的任務錯分到弱模型。相反地，所有請求都送強模型，又會失去分層路由的意義。你需要把任務階段、工具結果、錯誤訊號與模型品質放在同一條觀測鏈中。
第三，協定轉換不是無損翻譯。
文字訊息通常容易轉換，但工具名稱、工具參數、結構化輸出、串流事件、推理欄位與停止原因，可能在不同 API 之間沒有一對一對應。官方也提醒，某些後端與工具組合會遇到特定限制；例如文件列出 Bedrock 路徑可能受工具名稱長度限制影響。(github.com)
第四，回退會改變輸出語義。
後端失敗後換模型，不只代表延遲增加。不同模型的工具選擇、格式遵循、上下文理解與程式碼風格都可能不同。如果你沒有記錄「原本選了誰、為何回退、最後用了誰」，團隊很難解釋同一個輸入為何產生不同結果。
第二步：用 Agent Launcher 接入編碼工作流
Switchyard 的 Agent Launcher 目標，是為支援的 CLI Agent 啟動本地代理，再把 Agent 指向指定的模型入口。官方 README 目前列出 Claude Code、Codex CLI 與 OpenClaw 的啟動路徑，並區分單一模型直通與路由設定檔兩種方式。
最小化驗證可以先從單模型直通開始：
switchyard launch claude --model <model-id>
完成單模型測試後，再切換到路由設定：
switchyard --routing-profiles routes.yaml -- launch claude
| 接入方式 | 適合用途 | 主要風險 | 建議評分 |
|---|---|---|---|
| 單一模型直通 | 驗證 Agent 能否連線 | 無法驗證路由與回退 | 3/5 |
| 本地 Launcher | 個人開發、快速試點 | 本機程序結束後代理也會停止 | 4/5 |
| 路由設定檔 | 強弱模型分層、A/B 測試 | 設定版本與憑證管理較複雜 | 4/5 |
| 共享閘道 | 多人共用統一入口 | 權限、日誌、端口暴露與隔離要求高 | 3/5 |
你要把「支援啟動」與「穩定支援所有功能」分開看。能啟動 Claude Code，不代表 MCP 工具、串流回應、模型選擇器與長上下文都已經通過驗收。官方文件的版本要求、參數名稱與已知問題，應以Agent Launcher 文件為準，而不是依照社群貼文複製指令。
第三步：理解模型分流，而不是只設定便宜模型
Switchyard 的模型分流可以按不同訊號工作。官方 README 目前列出以下幾種策略：LLM Classifier、Stage Router、Escalation Router、Random，以及不做決策的 Passthrough。
| 路由類型 | 判斷依據 | 適合情境 | 主要代價 |
|---|---|---|---|
| Random | 固定比例 | A/B 測試、基線比較 | 不理解任務難度 |
| LLM Classifier | 額外分類模型判斷 | 依請求內容分配強弱模型 | 增加一次模型判斷 |
| Stage Router | 工具結果、錯誤等流程訊號 | Agent 多階段工作流 | 需要設計可靠訊號 |
| Escalation | 先弱後強，再由判斷器升級 | 需要控制強模型使用率 | 可能重複處理請求 |
| Passthrough | 不路由 | 單後端代理或初期排錯 | 沒有分層能力 |
LLM 路由的正確做法，是先建立任務分類，再用真實請求驗證。
例如，你可以把「一般問答、簡單程式碼修改、需要多次工具呼叫、長上下文除錯」分成不同類型，再比較各模型的成功率、工具正確率、回應完整度與失敗比例。
不要只使用單次成本作為規則。一次便宜的錯誤分流，可能導致 Agent 重試、工具失敗或人工介入，最後成本反而更高。路由規則也要保留輸入訊號、分類結果、選定後端與回退原因，否則事後無法解釋輸出差異。
第四步：回歸模型協定轉換的四個邊界
模型協定轉換是 Switchyard 最容易被高估的功能。你應把以下四類測試列成獨立驗收項目。
1. 工具呼叫
檢查工具名稱、JSON Schema、必要參數、工具回傳與多輪工具鏈是否保持一致。尤其是 MCP 產生的工具名稱，不能只用一個短名稱測試。
2. 結構化輸出
測試模型是否仍會輸出有效 JSON、是否遵守欄位型別，以及轉換層遇到空值、額外欄位或截斷時如何回報。
3. 串流回應
不要只測試完整回應。你要檢查 SSE 事件順序、分段文字、工具事件、停止原因與中途錯誤。串流只要少一個事件，Agent 就可能把半成品當成完整輸出。
4. 推理與上下文欄位
不同後端對推理內容、token 使用量、上下文長度與停止條件的欄位命名可能不同。轉換成功不等於欄位語義完全相同，日誌與計費資料尤其要獨立核對。
官方將協定容器與轉換元件分開維護，可參考官方協定元件。
FAQ：先回答五個部署前問題
Switchyard AI Gateway 是做什麼的？
它在客戶端與模型後端之間提供統一入口，負責請求格式轉換、後端選擇、路由統計與部分回退邏輯。對編碼 Agent 而言，價值在於不必為每個後端重新修改客戶端設定，但你仍需逐項驗證工具呼叫、串流與結構化輸出。
Switchyard 是否支援 OpenAI 和 Anthropic 協定？
官方目前列出 OpenAI Chat Completions、OpenAI Responses 與 Anthropic Messages。這代表它有相應的協定處理路徑，不代表所有提供商擴充欄位都能無損互換。正式採用前，應以你的 Agent、工具與模型組合做回歸測試。
Switchyard 要怎樣連接 Claude Code？
官方提供 switchyard launch claude 的 Launcher 路徑。你可以先指定單一模型，確認 CLI 能正常啟動，再改用 --routing-profiles 載入路由設定。若工作流包含 MCP，必須另外測試工具名稱、工具參數與工具錯誤，不能只驗證一般文字對話。
路由規則會根據哪些訊號切換模型？
它可以透過隨機分流、分類器、Stage Router 或升級式策略選擇後端。路由輸入可以是請求內容、工具結果、錯誤與對話階段。你應保留每次路由決策的理由，並用任務成功率而非主觀感覺調整強弱模型比例。
Switchyard 適合生產環境嗎？
截至 2026 年 8 月 14 日，官方倉庫仍將 Switchyard 標示為 pre-alpha，並明確提醒在 v1.0 前 API 與演算法可能大幅變更。它比較適合可回滾的開發、內部測試或受控試點，不適合未經驗收就成為所有團隊流量的唯一入口。
第五步：處理失敗回退與上下文溢出
回退策略至少要區分三種失敗：
- 連線失敗： 後端不可達、認證失效或端口未開放。
- 格式失敗： 後端拒絕工具欄位、結構化輸出或訊息格式。
- 能力失敗： 模型能回應，但無法完成工具操作、長上下文或指定任務。
這三類錯誤不應共用同一個 fallback。連線失敗可以切換到備援後端；格式失敗則可能需要改用另一種協定配置；能力失敗則應記錄為模型品質問題，而不是靜默換模型後當成成功。
上下文溢出也要單獨處理。若切換到較大上下文模型，你要確認轉換層是否保留完整訊息；若切換到較小模型，則應明確執行摘要或裁剪，而不是讓上游隨機截斷。否則，Agent 可能在沒有完整上下文的情況下繼續修改程式碼。
第六步：評估本地代理、共享閘道與生產服務
本機代理最容易開始。它適合單人驗證，憑證也較容易隔離。但它的生命週期跟著開發機走，無法自然提供團隊級日誌、權限、審計與一致設定。
共享閘道比較適合多人使用。你需要處理：
- 每位開發者或每個 Agent 的憑證隔離。
- 日誌中的提示內容、工具參數與敏感資料遮罩。
- 只暴露必要端口，避免把管理介面直接公開。
- 路由設定檔的版本管理與審查。
- 升級前保留舊版本，確保能快速回滾。
- 對每次回退保留模型、原因與最終回應狀態。
如果你準備在遠端開發環境中提供共享入口，可以先閱讀VPSSpark 幫助中心，再按照實際使用者所在地評估美國東岸雲端環境或美國西岸雲端環境的連線路徑。這些選擇不能替代閘道本身的權限設計，但會影響開發者到共享服務的連線穩定性。
用這組條件決定是否試點
- 若你只需要一個模型入口，且沒有協定轉換需求： 先用原生客戶端配置，暫不引入 Switchyard。
- 若你需要讓多個編碼 Agent 共用後端，且要保留各自原生協定： 可以建立本地試點。
- 若你需要強弱模型路由： 先準備至少一組真實任務資料，記錄成功率、工具錯誤、延遲與回退原因，再設計規則。
- 若你需要 MCP、串流與結構化輸出同時工作： 先做協定回歸，不要直接連接團隊共享環境。
- 若你要求穩定 API、長期相容與成熟生產支援： 在 Switchyard 完成版本穩定與內部驗收前，回退到已經熟悉的閘道方案。
- 若你需要物理介面、固定硬體或本機模型服務： 網關無法解決硬體連線問題，應另外規劃本地或專用伺服器。
官方入門文件包含獨立伺服器、設定檔、健康檢查與啟動方式；你可以先依照官方 Getting Started 指南完成最小路徑，再進入路由測試。
目前方案與 Mac 方案，應該怎樣取捨
如果你現在把編碼 Agent 直接跑在個人 Windows 或 Linux 開發機上，常見缺點是環境差異大、憑證散落在本機、團隊難以重現同一組路由設定。若改用臨時雲端主機，又可能遇到端口暴露、共享權限、閒置成本與上下文日誌難以集中管理等問題。Hackintosh 類方案則增加硬體相容、更新與維護風險，不適合作為長期團隊基礎設施。
對需要短期測試 Switchyard、Claude Code 代理或多模型路由的團隊，租用 VPSSpark 的 Mac 開發環境通常更容易隔離測試節點、快速重建配置，也不必先購買一台只在驗證階段使用的實體 Mac。若你的工作是長期固定重負載、需要直接連接特殊硬體，或已經有穩定的本地機房，則自購 Mac 或既有伺服器仍可能更合理。真正適合租用的情境，是你需要一個可快速開通、可撤換、能讓團隊重複驗收的臨時算力與開發入口。
為 AI Gateway 部署準備穩定的遠端環境
透過 VPSSpark 租用雲端 Mac，為 Switchyard、編碼 Agent 與本地代理建立獨立的開發及測試環境。
無論是模型路由、API 協定轉換還是失敗回退，都能在遠端 Mac 上靈活配置與驗證。