提供方

提供方是一个名称 → 配置的映射:一个新的上游只不过是又一个 [providers.<name>] 表 —— 无需改动代码。适配器类型如下:

• kind = "anthropic" —— 上游讲 Anthropic Messages API。shunt 将请求透传,可选择注入一个不同的 API 密钥。
• kind = "responses" —— 上游讲 OpenAI Responses API。shunt 在 Anthropic Messages ⇄ Responses 之间转换,含流式传输。
• kind = "cursor" —— 原生 Cursor 适配器。shunt 将 Cursor 的 ConnectRPC/protobuf AgentService 桥接到 Anthropic Messages API,含流式传输、推理(流式响应中)、原生工具调用与内联图像。由内置的 cursor 提供方使用。
• kind = "gemini" —— 原生的 Google Code Assist generateContent 适配器。
• kind = "antigravity" —— 通过 HTTP 连接 Google Antigravity 后端。
• kind = "antigravity_cli" —— 已废弃;调用本地的 Antigravity agy CLI。

内置提供方

每个名称都链接到对应提供方的专门页面,其中包含完整设置。shunt add upstream <name> 会为任意内置提供方打印分步操作蓝图 —— 将它通过管道传给编码 agent (shunt add upstream codex --print | claude),即可让 agent 为你完成配置。见 CLI 参考。

gemini 提供方的工具声明会经过与 antigravity 提供方相同的 schema 调整。两种传输共用同一个 Gemini 适配器,因此 Antigravity 提供方页面的适配器承载的内容中所述的元组折叠和无类型元素回退同样适用于 gemini 路由。

antigravity 提供方(Google Antigravity)

antigravity 提供方通过 HTTP 触达 Google Antigravity 后端。用 shunt login antigravity 认证:这是一个使用 Antigravity 自有 OAuth 客户端的 Google authorization-code 流程,它会申请两个 Gemini CLI 登录从不携带的 scope(cclog 和 experimentsandconfigs),因此两者的凭据在任一方向上都不可互换。登录还会解析 Code Assist 项目,并为首次使用的账号通过 onboardUser 完成开通,因此不会在请求前再做一次发现。

把每个本地别名映射到确切的 Antigravity 模型 slug:

[[models]]
id = "claude-gemini-3.6-flash-via-antigravity"
display_name = "[AGY ] Gemini-3.6-Flash"

[[routes]]
model = "claude-gemini-3.6-flash-via-antigravity"
provider = "antigravity"
upstream_model = "gemini-3.6-flash-medium"

Antigravity 把 Gemini 模型的 effort 写进 id 发布,并不提供不带后缀的 slug,而且有两种形态 —— -low / -medium / -high 后缀,或者把 effort 作为请求字段接收的单个 -tiered id。账号拿到哪种形态会随时间 变化,所以 shunt 会读取账号自己的目录,挑出它真正发布的 id:不带后缀的 gemini-* id 会依据 effort、 请求、否则按 medium 解析,而账号已不再发布的后缀会被重新解析而不是照原样发出。每种写法都能用。

完整设置 —— 登录与 scope、项目发现、模型 slug、thinking,以及适配器承载的内容 —— 见专门的 Antigravity 提供方页面。

已废弃的 antigravity_cli 传输

antigravity-cli 这条路径按每个请求以 agent 模式启动一个 agy CLI 子进程。agy 自己解析自己的工具调用,因此该适配器 永远无法返回 tool_use 块,真正要求调用工具的请求会被拒绝:非空的 tools 数组,或值为 any/tool 的 tool_choice, 会以指明这一限制的 400 invalid_request_error 拒绝。此类请求过去会被悄悄丢弃,返回 stop_reason: "end_turn" 的纯文本 200 —— 这是 agent 式调用方无法据以行动的响应,并且在直接违反 tool_choice: {"type": "any"} 的同时仍报告成功。有两种 形式不受此限制,因为它们都不强制调用工具:即使同时提供了 tools,tool_choice: {"type": "none"} 也不受限制;没有工具的 tool_choice: {"type": "auto"} 同样不受限制,它是许多客户端在每个请求中都会序列化的 Anthropic SDK 默认值。空的 tools: [] 同样不算工具请求。需要自行驱动工具循环的客户端应改用会转发工具的 antigravity 或 gemini 提供方。

未能送达的 send_message 交接不会让已完成的轮次失败。print 模式会暴露 agy 的全部交互式工具面(包括 send_message), 却不会注册任何收件箱。一条子 agent 式的提示(“把结果汇报给主 agent”)就足以让模型把回复交给 main、team-lead 或 user;该调用失败,agy 会在回答已经流式输出之后,以 recipient "<name>" not found 错误把本次运行标记为 ERROR。 只要已经流式输出了助手文本,shunt 就把这一轮正常结束(end_turn、HTTP 200);若什么都没有输出,则回复只存在于那条 未送达的消息里,shunt 仍按失败处理。其他所有晚到的失败依旧以 SSE error 结束轮次。这是一个依赖上游错误字符串的兼容性 处理,详见仓库中的 docs/notes/agy-print-mode-tool-surface.md。

由于非交互式运行无法回答权限提示,agy 会带 --dangerously-skip-permissions 运行,并且默认带 --sandbox,所以请把该 提供方视为以运行 shunt 的用户身份执行任意代码。

有两项设置对它加以约束。sandbox(默认 true)会传入 --sandbox,这才是真正约束该 agent 的机制 —— 关掉它就只剩下不受 限制的 shell 访问。workspace_roots(默认为空)只决定 agent 可以从哪里启动:解析顺序是 SHUNT_AGY_WORKSPACE,然后是 请求系统提示中的 Working directory: 行,最后是网关自身的目录。系统提示是由客户端控制的文本,因此只有当其中给出的路径 规范化后落在你配置的某个根目录内时才会被采纳;没有配置任何根目录时,取自提示的路径会被忽略。

[providers.antigravity-cli]
kind = "antigravity_cli"
base_url = "http://localhost"
auth = "none"
# 请求内容可以把 agent 指向的仓库。
workspace_roots = ["/Users/you/repos"]
# sandbox = false   # 仅在 agent 需要不受限制的终端访问时

workspace_roots 不是牢笼:在 sandbox = false 时,从允许的根目录启动的 agent 仍然可以操作提示中别处给出的路径。

当 sandbox = false 与非回环的 bind 组合时,shunt 会拒绝启动,并按启动时绑定的监听器对每个请求执行同样的规则。热重载 无法移动该监听器,因此重新加载一个回环 bind 并不能让你在公开监听器仍然存活时关闭沙箱。请保持沙箱开启,或以回环绑定 重启。不要在非回环绑定上把该提供方暴露给不受信任的客户端。

第三个设置 profile_dir 为每个条目提供独立的 HOME。agy 通过 HOME 解析包括凭据在内的整个状态树，因此不设置时 所有条目都共享网关主机上唯一的 ambient ~/.gemini 配置，最终只能服务一个 Google 账号。给每个条目指定各自的目录后， 它们会分别登录自己的账号，并可以同时池化多个账号。该目录按需创建并规范化为绝对路径，开头的 ~ 会被展开。每个目录都 需要各自执行一次 agy 登录。仅对使用了该设置的条目，子进程的 GOOGLE_* / GEMINI_* 环境变量会被剥离，这样主机自身 的配置就无法悄悄改变由哪个账号 —— 以及谁的账单 —— 来处理请求。不设置（默认）则与既有行为完全一致。有序 [[upstreams]] 条目同样支持该设置。

建议优先使用上面那个原生的 antigravity HTTP 提供方,它完全不需要这些。本节是精简版 —— 包含模型 / effort 矩阵在内的 完整文档在英文指南的 The deprecated antigravity-cli transport。

codex 提供方(ChatGPT 订阅)

用 Codex CLI 登录一次;shunt 会读取并自动刷新 ~/.codex/auth.json:

codex login

如果该文件缺失或过期,shunt 会返回一个 authentication_error,提示你运行 codex login。

完整设置 —— auth 文件处理、模型选择、力度以及上下文大小 —— 见专门的 ChatGPT / Codex 指南。

cursor 提供方(Cursor 订阅)

内置的 cursor 提供方通过 Cursor 自己的 ConnectRPC/protobuf AgentService 访问你的 Cursor 订阅 —— kind = "cursor" 原生适配器在其与 Anthropic Messages 之间双向转换,包括流式传输、 推理、原生工具调用和内联图像。

使用 shunt login cursor 登录一次,然后路由一个 cursor:* 模型 id(cursor:default、 cursor-plan:default、cursor-ask:default……)—— 该提供方默认已预置,因此无需配置表。

完整设置 —— 登录、agent 模式、wire 模型 id、适配器能力和覆盖项 —— 见专门的 Cursor 提供方页面。

xai / grok 提供方(Grok)

两个内置提供方触达 xAI 的 Grok 模型,按凭据划分:grok 经由 OAuth 消费你的 SuperGrok / X Premium+ 订阅(shunt login xai,无按 token 计费),而 xai 用一个 XAI_API_KEY 对接计量的开发者 API。订阅 bearer 和 API 密钥 不可互换 —— 各自只对其自己的提供方有效。

要汇集多个 SuperGrok 账户,请用 shunt login xai --name <name> 分别登录每个账户。

完整设置 —— 登录、两个提供方块、模型 slug、选择性启用的力度旋钮,以及 授权方面的坑 —— 见专门的 xAI / Grok 指南。

添加一个兼容 Anthropic 的后端

大多数第三方“在 Claude Code 中使用 X”网关都兼容 Anthropic-Messages:kind = "anthropic" 搭配 auth = "api_key",仅在 base_url 和密钥环境变量上不同。开箱即用的 base(每个提供方都链接到包含完整设置的专门页面):

对于不在此表中的提供方,shunt add upstream <docs-url> 会打印一份研究蓝图, 引导编码 agent 根据该提供方自己的文档完成接入 (shunt add upstream https://docs.example.com --print | claude)。

上表中除一行外都使用 auth = "api_key"。Kimi Code 是例外:它是与上一行按量计费的 Moonshot API 不同的、订阅制计费的 Kimi 服务 —— 主机不同,且使用 OAuth 而非 API 密钥。它拥有专用的内置预设 kimi-code(kind = "anthropic"、base_url = "https://api.kimi.com/coding"、auth = "kimi_oauth"),因此在有序的 [[upstreams]] 形式下只需指定 provider = "kimi-code",无需手写 [providers.*] 表。你还需要一个已登录的账号:

shunt login kimi --name <account-name>   # RFC 8628 设备流程 -> ~/.shunt/accounts/kimi/<account-name>.json

# shunt.toml —— 路由到你的 Kimi Code 订阅
[[upstreams]]
name = "kimi-code"
provider = "kimi-code"
auth = { mode = "kimi_oauth", account = "<account-name>" }

# 声明 [[upstreams]] 会替换内置的提供方集合,因此要保留末尾的
# anthropic 透传条目 —— 否则 `shunt check` 会因默认的
# server.default_provider 找不到而报错。这与 `shunt init` 追加的条目相同。
[[upstreams]]
name = "anthropic"
provider = "anthropic"

[[routes]]
model = "<model-id-your-subscription-exposes>"
provider = "kimi-code"

kimi_oauth 和 claude_oauth/chatgpt_oauth 一样支持账号池 —— 用 accounts = [...] 代替 account,即可将负载分散到多个已保存的 Kimi 账号上。完整说明见 Kimi → Kimi Code(OAuth 订阅)。

例如,要通过 shunt 路由 Kimi(Moonshot)的模型:

[providers.kimi]
kind = "anthropic"
base_url = "https://api.moonshot.ai/anthropic"
auth = "api_key"
api_key_env = "MOONSHOT_API_KEY"

[[routes]]
model = "kimi-k3[1m]"
provider = "kimi"

[[routes]]
model = "kimi-k2.7-code"
provider = "kimi"

然后 export MOONSHOT_API_KEY=…,将 Claude Code 指向 shunt,并选择 kimi-k3[1m](通过 ANTHROPIC_CUSTOM_MODEL_OPTION 或 ANTHROPIC_MODEL)。运行 shunt check 校验 —— 它会报告路由中的未知提供方、缺失的 api_key_env 或错误的 base_url。

每个提供方键(kind、auth、api_key_header、count_tokens……)都在 配置参考 中有文档。

子 agent 插件

pleaseai/shunt 市场 提供了固定到各提供方模型的现成 Claude Code 子 agent —— 每个模型一个 agent。安装一个插件,然后用 @ 提及一个模型或设置 CLAUDE_CODE_SUBAGENT_MODEL。每个 agent 的 model: frontmatter 只让该子 agent 分流;主会话仍留在 Claude。

/plugin marketplace add pleaseai/shunt
/plugin install shunt-xai@shunt

每个插件仍需要在 shunt.toml 中路由其提供方(见上文各节)并导出匹配的凭据 —— 插件自己的 README 会列出确切的路由和环境变量。grok 模型可由任一 xAI 提供方提供:xai(API 密钥,按 token 计费)或 grok(通过 shunt login xai 使用 SuperGrok / X Premium+ 订阅;按等级设限 —— 遇到 403 时回退到 xai)。