Switchyard 是什麼？Rust 編寫的 AI Gateway 完整指南（2026）

截至 2026 年 8 月 14 日，Switchyard 官方資料同時呈現 Python proxy／CLI 路線與獨立 Rust server；因此你應把它理解為「LLM 流量轉換、路由與統計工具」，而不是把整個專案簡化成純 Rust 伺服器。這週的建議是：先用 Launcher 驗證 Claude Code 或 Codex 的協議相容性，再決定是否部署獨立的 switchyard-server。

適合閱讀這篇文章的人有三類：需要讓 Claude Code 或 Codex 連接不同模型後端的開發者、正在建設統一 AI Gateway 的平台團隊，以及需要評估 Python CLI 和 Rust 伺服器部署差異的工程師。

先看元件邊界：Python 入口與 Rust server 不是同一條路

很多文章看到倉庫內有 Cargo.toml、crates 或 switchyard_rust，就直接寫成「Switchyard 全部由 Rust 編寫」。這個說法對部署決策不夠準確。

你可以先用下表區分三種使用方式：

因此，Switchyard AI Gateway 的準確理解是「一組可透過不同入口使用的協議與路由元件」。你若只需要本機測試，不必先編譯完整 Rust 服務；你若需要讓多個團隊共用，才應評估獨立 Rust server 的運維成本。

官方文件列出的獨立伺服器支援 3 種上游格式：openai_chat、openai_responses 和 anthropic_messages。這是協議邊界，不代表每個模型的工具呼叫、串流格式或結構化輸出都能無條件互換。可參考 官方協議說明 與 translation crate 文件。

協議轉換的價值：保留客戶端格式，改變後端請求

Claude Code、OpenAI 相容客戶端和自建模型服務，常見問題不是「沒有模型」，而是彼此說不同格式。

例如：

• Claude Code 主要以 Anthropic Messages 形式發送請求。
• OpenAI 相容服務通常期待 Chat Completions。
• 部分新式服務使用 Responses API。
• vLLM、Ollama、NVIDIA NIM 或其他自建端點，還可能在工具、串流和額外欄位上存在差異。

Switchyard 位於客戶端與模型後端之間。客戶端保留原本的 API 形式，代理依路由選擇上游，再把回應轉回客戶端可以理解的格式。這能減少你為每一個 Agent 重寫連線層的工作，但不能消除所有相容性問題。

注意：代理成功回傳一次文字，不等於 Claude Code 的工具呼叫、長對話、串流中斷與重試都已經通過驗收。AI Gateway 的測試至少要包含文字回應、工具呼叫、錯誤重試和長時間連線。

Switchyard AI Gateway 的路由方式：固定透傳與動態判斷要分開

Switchyard 提供的路由策略不是單一「智慧選模型」按鈕。官方文件列出幾種不同方向，使用目的也不同，可參考 Routing Overview。

• Passthrough：把一個模型註冊成一個路由 ID，不做額外判斷。最適合先驗證協議。
• Random：按權重或固定分流，把請求送往不同目標。適合 A/B 測試與基準比較。
• LLM classifier：由分類模型判斷請求該走較弱或較強的模型。
• Stage router：根據工具結果、錯誤或對話進度等訊號選擇下一個模型。
• Custom algorithm：由你自行撰寫或嵌入路由邏輯。

這裡有一個容易被誤解的地方：分類器或分層路由不必然降低成本，也不必然提高品質。它可能增加一次分類請求，也可能因錯誤判斷把複雜任務送到不適合的後端。你應先記錄任務類型、成功率、延遲與 token 使用量，再決定是否加入動態路由。

若你正在研究不同 AI Agent 的運作差異，可以先閱讀 2026 年 AI Coding Agent 排名，再回頭判斷哪些 Agent 值得接入統一閘道。

Switchyard 是用 Rust 還是 Python 編寫的？

最準確的回答是：依你使用的路徑而定，不能只回答其中一種語言。

主專案的 CLI、安裝與 Agent 啟動流程包含 Python 路線；同時，官方也提供獨立的 Rust server binary，以及可嵌入 Rust 應用程式的 library。這種架構對使用者有三個直接影響：

1. 本機快速體驗較容易：Launcher 可替你啟動代理，不必先建立完整常駐服務。
2. 長期部署邊界較清晰：獨立 switchyard-server 可以用 TOML 管理 client、target 和 route。
3. 維護責任不同：Rust server 能提供較明確的單一程序，但憑據、日誌、反向代理與升級仍由你負責。

截至本文核驗資料，官方 README 將專案描述與執行路徑分成 Launcher、Server、Library 三類；因此不要根據倉庫存在 Cargo 檔案，就推斷 Python proxy、CLI 和所有功能均已由 Rust 完全取代。

如何連接 Claude Code：先用 Launcher，再改成獨立代理

如果你的目標是讓 Claude Code 或 Codex 經由 Switchyard 連到指定模型，建議按以下順序操作。這套流程的重點不是先追求複雜路由，而是先確認最小可用鏈路。

1. 確認客戶端已安裝

先確認 Claude Code 或 Codex 可以在目前終端機直接執行：

claude --version
codex --version

若指令不存在，先完成 Agent 本身的安裝。Switchyard Launcher 不會替你安裝所有客戶端。

2. 安裝 CLI 與必要套件

官方 Getting Started 以 uv 安裝 Python 發佈的 CLI：

uv tool install --python 3.10 "nemo-switchyard[cli]"

不同版本的安裝要求可能改變，發佈前應查看 官方安裝文件 或 Getting Started，而不是複製過時指令。

3. 設定 API Key

把密鑰放在環境變數，不要直接寫進公開的 TOML、Shell script 或 CI 設定檔：

export OPENROUTER_API_KEY="你的金鑰"

若使用其他供應商，就依該供應商的 base URL、API 格式和密鑰環境變數調整。

4. 先做單模型透傳

先不要立刻啟用分類器：

switchyard launch claude --model switchyard

或使用自訂配置：

switchyard launch claude \
  --model my-route \
  --config routes.toml

單模型透傳能先排除路由判斷造成的干擾。

5. 驗證文字、串流與工具呼叫

至少測試以下四項：

• 一般文字問答是否回傳。
• 串流是否能正常完成。
• Claude Code 是否能讀取檔案、執行工具或使用 MCP。
• 後端回傳 4xx、429 或 5xx 時，Agent 是否得到可理解的錯誤。

官方文件也提醒，特定 Bedrock 路線可能遇到工具名稱長度限制。這說明「API 格式相同」不代表工具層一定相容，應把工具呼叫列為獨立驗收項目。

6. 需要共用時再部署 Rust server

安裝獨立的 Rust server：

cargo install --locked switchyard-server
switchyard-server --help

啟動前先做配置檢查：

switchyard-server --config routes.toml --dry-run
switchyard-server --config routes.toml \
  --host 127.0.0.1 \
  --port 4000

再確認健康狀態：

curl http://localhost:4000/health
curl http://localhost:4000/v1/models

官方配置使用 api_key_env 指向環境變數，TOML 本身不應保存密鑰。獨立伺服器也能設定重試、路由日誌與結構化終端事件；相關欄位可查看 switchyard-server 官方說明。

從試驗環境到生產網關：驗收項目完全不同

本機 Launcher 的驗收目標是「Agent 能否通」。長期運行的 AI Gateway 則要回答「出問題時能否定位、恢復與追責」。

試驗環境

適合個人開發者或短期模型比較：

• 使用單模型透傳。
• API Key 由本機環境變數提供。
• 只監看終端輸出與基本錯誤。
• 先驗證 Claude Code、Codex 的工具呼叫。
• 不把本機代理直接暴露到公網。

長期運行環境

適合平台團隊或多個專案共用：

• 以獨立 switchyard-server 服務運行。
• 使用反向代理、TLS、存取控制與密鑰輪替。
• 記錄請求延遲、錯誤、token、路由結果和上游回應狀態。
• 為多輪 Agent 設計 session affinity，避免同一工作流頻繁跳到不一致的模型。
• 設定優雅關閉、健康檢查與自動重啟。
• 對每個模型後端建立工具呼叫和串流回歸測試。

部署前可勾選清單

• [ ] 已確認 Claude Code 或 Codex 的實際 API 格式。
• [ ] 已用單模型透傳完成文字與串流測試。
• [ ] 已用至少一個真實工具呼叫測試 Agent。
• [ ] 已確認每個 target 的模型 ID、base URL 與協議格式。
• [ ] 已用 --dry-run 驗證 TOML、環境變數與路由引用。
• [ ] 已確認 API Key 不會出現在版本控制、日誌或錯誤訊息。
• [ ] 已定義 429、5xx、逾時和串流中斷的處理方式。
• [ ] 已決定是否需要 session affinity 與路由紀錄。
• [ ] 已建立健康檢查、重啟和升級回退方案。
• [ ] 已用實際 Agent 工作流，而不是單次 curl，完成最後驗收。

如果你還在整理 Claude Code 的操作層，可以參考 Claude Code Skills 框架整理。它能協助你把「模型能否連線」進一步拆成技能、工具與工作流的驗收項目。

你應該現在採用 Switchyard 嗎？

若你的問題是「我想讓 Claude Code 或 Codex 先接上多個後端，並保留原本的 OpenAI 或 Anthropic 介面」，Switchyard 值得在隔離環境中測試。它的優勢是協議轉換、路由策略和 Agent Launcher 集中在同一個開源專案內。

但若你需要已經高度穩定、版本變更風險低的生產服務，就不要只看 Rust server 的啟動速度或倉庫結構。官方文件仍要求你自行處理模型相容性、工具呼叫、憑據、監控與長期運行；路由演算法也不應在沒有基準資料時直接宣稱省錢或提高品質。

相較於把代理長期跑在你的個人電腦上，現有方案常見的缺點是：電腦休眠會中斷請求、網路出口不固定、密鑰容易散落在本機環境，而且多人共用時缺少一致的日誌與權限邊界。若你只是需要短期測試 Claude Code、Codex 或 AI Gateway，不想先購買和維護一台長期在線的 Mac，租用 Hashvps 的 Mac 環境會更適合做隔離測試與臨時部署；但若你需要固定的實體介面、長期滿載運行或完全自主管理硬體，仍應比較自購設備與其他雲端方案。