Switchyard 是什么？Rust 编写的 AI Gateway 完整指南（2026）

你遇到的症状通常是：Claude Code、Codex 和不同模型后端各用一套 API，工具调用或模型字段一变，请求就失败。

最快解法：本周先用 Switchyard AI Gateway 做单模型透传，确认协议转换可用后，再加入随机路由、分类器或 Rust server；不要把它误判成“整个项目都是 Rust 编写”。

适合阅读这篇文章的，是需要让 Claude Code 或 Codex 连接不同模型后端的开发者、正在建设统一 AI Gateway 的平台团队，以及需要评估 Python 与 Rust 服务部署差异的工程师。

最后更新于 2026 年 8 月 14 日。本文依据官方 README、安装文档、Rust server 说明和仓库结构重新核验；如果后续语言架构或 server 状态变化，应重新检查这一结论。相关信息可参考 Switchyard 官方仓库。

先看边界：Rust server 不等于整个项目纯 Rust

Switchyard 的核心角色，是放在客户端与模型后端之间的代理层。客户端继续发送自己熟悉的 OpenAI 或 Anthropic 格式，Switchyard 再选择后端、转换请求、转发响应，并收集路由与使用统计。官方 README 将项目描述为 Python proxy，同时也提供独立的 Rust switchyard-server。(官方 README)

因此，标题中的“Rust 编写”需要准确理解：

✅ Python 路线：主要代理、CLI、Agent Launcher 和 Python 集成入口。
✅ Rust 路线：独立的 switchyard-server，以及协议、翻译、路由算法等 Rust crate。
⚠️ 不能直接推断：仓库有 Cargo.toml，不代表所有 CLI、配置流程和代理行为都只由 Rust 实现。
⚠️ 不能混用配置：Python 代理配置与 Rust server 的 TOML schema 不是同一套文件格式。

官方安装文档也把 Python integrations 与 standalone Rust serving 分成不同安装包。Python 包可以承载部分原生实现，Rust server 则可以直接通过 Cargo 安装并单独运行。具体安装分支以官方安装文档为准。

客户端为什么不能直接连所有后端

Claude 与 OpenAI 接口的差异

Claude Code 常见的是 Anthropic Messages 语义，许多本地推理服务或代理则暴露 OpenAI Chat Completions。OpenAI Responses 又有独立的响应结构、工具调用字段和推理相关字段。

如果你让每个客户端直接连接每个后端，至少会出现 3 类隐性成本：

协议维护成本：每个客户端都要保存独立的 Base URL、API Key、模型名和请求格式。
能力兼容成本：普通文本请求成功，不代表工具调用、结构化输出、流式响应也成功。
故障定位成本：请求失败时，你很难判断问题来自客户端、代理、模型服务，还是字段转换。

Switchyard 的价值不是“让模型自动变强”，而是提供一个统一入口。官方资料列出 OpenAI Chat Completions、Anthropic Messages 和 OpenAI Responses 等协议路径，并支持连接 OpenAI-compatible 后端，例如 vLLM、Ollama 等。(官方协议与架构说明)

协议转换要按能力分层验收

你可以把支持能力分为 3 层：

已确认的协议路径：三类客户端请求格式之间的转换。
依赖后端兼容性的能力：工具调用、流式输出、结构化结果、模型特有参数。
需要单独测试的边界：MCP 工具名称、超长工具描述、上下文长度、错误重试和供应商专属字段。

一个请求能返回 200，只能说明基础链路通了。对 Claude Code 来说，至少还要测试工具调用、连续多轮会话、流式输出和异常重试。

单模型透传与多模型路由，应该先选哪一种

Switchyard 官方提供多种路由机制，包括单模型透传、随机路由、LLM 分类器路由、阶段路由和自定义路由。它们解决的问题不同，不应简单按“越智能越好”排序。具体路由字段和示例可查看 Rust server 配置说明。

单模型透传：最适合第一次验收

单模型透传把所有请求送到指定目标。它的优点是变量少，便于判断协议转换是否正确。

适合：

第一次接入 Claude Code 或 Codex。
你正在确认某个 OpenAI-compatible 后端是否支持工具调用。
你不希望分类器本身增加额外请求。
你需要稳定复现同一类错误。

随机路由：适合 A/B 与均衡分发

随机路由可以在多个 target 之间分配请求，还支持相对权重。权重不需要加总为 1，客户端发送的是 route 的 id，而不是直接指定某个后端模型。

但随机路由不会自动判断任务难度，也不会保证质量更高或成本更低。你需要用真实请求统计比较延迟、错误率、输出质量和 token 消耗。

分类器与阶段路由：更强，但验收更复杂

LLM classifier 会先让分类器判断任务，再决定发送到 weak target 还是 strong target。stage router 则依据工具结果和 Agent 进度信号，为不同轮次选择能力层级。

这类路由额外引入了：

分类器不可用时的回退行为。
阈值变化导致的流量比例变化。
多轮会话是否保持同一路由。
路由决策本身的延迟。
“便宜模型先处理”但任务质量下降的可能性。

所以更稳妥的顺序是：透传 → 随机路由 → 分类器或阶段路由。

第一步：先用 Launcher 连接 Claude Code 或 Codex

官方 CLI 提供 switchyard launch claude、switchyard launch codex 等启动方式。Launcher 会启动本地代理，把 Agent 指向代理，再在客户端退出后关闭代理。

可以按下面的顺序操作：

确认客户端已安装
Claude Code 或 Codex 必须已经在系统 PATH 中。Launcher 不会替你安装客户端。
准备后端凭据
把 API Key 放入环境变量，不要直接写进提交到 Git 的配置文件。
安装 CLI 路线
根据官方安装方式安装 nemo-switchyard[cli]，或使用源码环境进行本地测试。
先做单模型透传
使用 --model 指定一个后端模型。此时不要同时加入随机路由、分类器和会话亲和。
验证客户端请求
在 Agent 内测试普通文本、代码修改、工具调用和流式输出，而不是只执行一次简单问答。
再切换到路由配置
当单模型透传稳定后，再用 --routing-profiles 或 Rust server 的 TOML 配置加入多个 target。
记录失败样本
保存请求格式、客户端版本、后端模型、错误码和是否流式。否则后续无法判断是协议问题还是模型问题。

如果你在 Mac 上进行本地验证，可以先查看 Hashvps 的帮助中心，把端口、环境变量和远程会话管理这些基础问题先整理好。

Python proxy 与 Rust server 的部署差异

Python proxy 更适合快速试验和 Agent Launcher。它与 Python CLI、配置流程和开发环境衔接更直接。官方仓库提供从 PyPI 安装、源码安装以及独立 Python server 的方式。

Rust server 更适合你已经确定配置模型，并希望把代理作为独立长期进程运行的场景。它通过 TOML 明确定义 llm_clients、targets 和 routes，支持 OpenAI Chat、OpenAI Responses 和 Anthropic Messages 端点。

两条路线的关键区别，不只是启动命令：

Python 路线更适合快速改配置、调试 CLI 和本地 Agent。
Rust server 更强调显式配置、独立进程和服务化运行。
Rust server 支持 /health、/v1/stats、/metrics 等服务端端点。
API Key 可以通过环境变量名注入，TOML 不必直接保存密钥。
Rust server 默认会处理部分传输失败、超时、408、429 和 5xx 重试，但这不等于所有业务错误都会自动恢复。

FAQ：部署前最容易混淆的 5 个概念

它在 AI 请求链路中究竟扮演什么角色？

Switchyard AI Gateway 是一个位于 Agent 客户端和模型后端之间的开源流量代理。它可以转换 OpenAI 与 Anthropic 相关请求格式，也可以根据 route 选择不同 target，并记录延迟、token、错误和路由统计。它不是模型本身，也不保证路由后质量或成本一定改善。

项目实际采用了哪条编程语言路线？

答案是“两者并存，但组件边界不同”。官方资料将主要 proxy 与 CLI 路线描述为 Python，同时提供独立 Rust server 和 Rust 库。判断时应看你安装的是 nemo-switchyard、CLI，还是 switchyard-server，不要只看仓库根目录是否存在 Cargo 文件。

让 Claude Code 经过代理启动，最短路径是什么？

最短路径是安装 CLI 后使用 switchyard launch claude，通过 --model 指定单个后端；需要多模型时，再改用路由配置。你仍然要验证 API Key、模型名称、Base URL、工具调用和 MCP 行为。某些后端路径还可能受到工具名称长度或字段兼容性限制。

当前文档列出的协议范围有哪些？

官方资料列出 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages。后端若只提供 OpenAI-compatible 接口，也可以接入，但具体能力取决于后端是否正确实现工具调用、流式响应、结构化输出和错误格式。

能不能把它当成一个单独运行的代理进程？

可以。Python 路线可以启动独立代理，Rust 路线可以通过 switchyard-server --config routes.toml 运行。生产部署还需要补齐进程托管、密钥注入、健康检查、指标采集、日志留存、会话路由和优雅退出，不能把本地启动成功当成生产验收完成。

生产前检查：别只测“能不能返回内容”

先验证协议，再验证路由

建议你用一组固定测试请求，依次覆盖：

OpenAI Chat Completions。
Anthropic Messages。
OpenAI Responses。
普通文本与多轮上下文。
工具调用和工具结果回传。
流式响应中断与重试。
无效模型名、错误 API Key 和上游 429。

每项都记录客户端格式、Switchyard route、实际 target、HTTP 状态、响应耗时和输出是否完整。

再验证统计与会话

Rust server 提供 /v1/stats、/metrics 和路由日志能力。官方说明中，指标覆盖请求数、错误数、模型调用延迟、输入输出 token、缓存 token、推理 token 和路由开销等维度。

如果你的 Agent 是多轮任务，还要测试会话亲和。分类器路由可以在会话内复用第一次决策，但消息哈希回退可能让发送相同首条消息的不同调用共享同一分配，这对多租户环境需要谨慎处理。

[ ] 已确认客户端实际使用的协议格式。
[ ] 已确认每个 target 的模型 ID 和 Base URL。
[ ] 已确认 API Key 只通过环境变量或密钥系统注入。
[ ] 已测试工具调用、流式响应和多轮会话。
[ ] 已验证 4xx、5xx、超时和上游限流。
[ ] 已查看 /health、统计接口和 Prometheus 指标。
[ ] 已决定是否启用会话亲和。
[ ] 已记录 Python proxy 与 Rust server 的实际版本和配置文件。
[ ] 已为长期运行进程配置日志轮转、重启策略和权限边界。

试验环境与生产网关，不应使用同一验收标准

试验环境的目标，是在较短时间内确认协议能否转换、客户端能否启动、模型能否返回结果。此时 Python CLI 和本地 Launcher 通常更省事。

生产网关的目标，则是可重复、可观测、可回退。你需要明确：

谁可以访问代理端口。
哪些请求可以使用强模型。
哪些 API Key 能被哪个 target 使用。
路由失败时是否允许切换后端。
请求日志是否包含敏感内容。
指标是否按模型、路由和租户隔离。
重启时是否会中断正在生成的流式响应。

如果团队准备把 Switchyard 与远程开发环境结合，建议同时阅读 Hashvps 的服务说明，先区分临时测试主机、长期运行代理和需要本地 GUI 的开发场景。若你的工作流还包含其他 Agent，也可以参考 Hashvps 的 OpenClaw 相关页面了解远程运行时的环境准备思路。

部署路线对比：Python proxy 还是 Rust server

选择	更适合的任务	主要优点	需要特别验收
Python proxy / CLI	本地试验、快速连接 Claude Code、调试路由	启动快，靠近 Python 配置与 Agent 工作流	Python 环境、CLI 依赖、进程生命周期
Python 独立服务	小团队内部统一入口	配置修改灵活，便于快速迭代	进程托管、权限、日志和请求隔离
Rust server	长期运行的独立代理	TOML 配置明确，提供健康、统计和指标接口	Rust 版本、配置 schema、密钥注入
直接调用后端	单模型、低复杂度应用	链路最短，排错简单	多客户端重复配置，缺少统一路由与统计

路由方式	能解决什么问题	不应承诺什么	推荐顺序
Passthrough	固定模型验证协议和能力	不会自动故障转移	第 1 阶段
Random	多 target 分流、A/B 测试	不会自动判断任务质量	第 2 阶段
LLM Classifier	按任务能力选择强弱模型	不保证降低成本，且会增加判断环节	稳定后使用
Stage Router	按 Agent 过程信号切换层级	配置和观测复杂，需大量真实样本	平台化后使用
Custom Router	适配团队自有规则	维护成本由你承担	有明确规则再使用

结论：先确认边界，再决定是否长期运行

如果你只需要把 Claude Code 或 Codex 临时接到一个模型，直接使用 Python CLI 和单模型透传，通常是最短路径。如果你需要统一多个客户端、多个协议和多个后端，再考虑路由配置；如果还要独立进程、健康检查、指标和长期运行，Rust server 才值得进入评估范围。

你当前的本地电脑或普通临时云主机，常见问题是开发环境与网关进程互相干扰、断开 SSH 后服务退出、密钥权限边界不清，以及长期日志和监控没有固定位置。需要临时测试、远程验证或短期运行 AI Gateway 时，租用 Hashvps 的 Mac 环境可以把主机准备、远程连接和测试任务分开；但如果你要持续承载稳定的大规模请求，仍应优先建设专门的生产网关、密钥系统和监控方案，而不是把租赁环境当成永久替代。

本周建议动作很简单：先用单模型透传完成一组 Claude Code 或 Codex 请求验收，再决定是继续 Python proxy，还是切换到独立 Rust server。只有当协议、工具调用、路由回退和观测指标都通过测试后，才值得把 Switchyard 放进长期运行链路。

FAQ

Switchyard AI Gateway 主要解决什么问题？

它位于 Claude Code、Codex 或其他客户端与模型后端之间，负责在 OpenAI Chat、OpenAI Responses 和 Anthropic Messages 等请求格式之间转换，并按配置选择后端、执行回退和记录请求统计。它适合需要统一入口，而不是只调用单一模型的团队。

Switchyard 到底是用 Rust 还是 Python 编写的？

两种组件都存在。官方项目仍将主要代理与 CLI 描述为 Python 路线，同时仓库提供独立的 switchyard-server Rust 服务及相关库。你不能因为仓库存在 Cargo 文件，就把所有功能概括成纯 Rust；部署前应先确认你使用的是哪一个入口。

Switchyard 如何让 Claude Code 连接其他模型？

最直接的方式是使用 switchyard launch claude。你先准备后端 API Key 和 Base URL，再用 --model 做单模型透传，或通过 routing profiles 指定路由集合。工具调用、模型字段、流式响应和 MCP 兼容性仍要按具体后端单独验收。

Switchyard 支持哪些模型协议？

官方文档列出 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages 三类格式。后端可以是对应协议服务，也可以是兼容 OpenAI 接口的 vLLM、Ollama 或其他服务。能否完整工作，还取决于工具调用、结构化输出和流式响应是否被后端正确实现。

Switchyard 能部署成独立代理服务吗？

可以。Python 路线能够通过配置文件启动独立代理，Rust 路线则使用 switchyard-server 和独立 TOML 配置。独立服务部署时，你还需要处理 API Key 注入、进程托管、日志、健康检查、指标采集、会话亲和和优雅退出，不能只验证一次 curl 请求。