配置 | shunt

shunt 按优先级递增的顺序从以下来源加载配置:

内置默认值 —— 每个提供方(anthropic、openai、codex……)都已预配置。
一个 TOML 文件。使用 --config <path> 时会使用该确切文件(文件缺失即报错)。否则 shunt 取以下位置中找到的第一个文件:
- ./shunt.toml
- $XDG_CONFIG_HOME/shunt/shunt.toml(默认为 ~/.config/shunt/shunt.toml)
- $HOMEBREW_PREFIX/etc/shunt.toml(默认为 /opt/homebrew 和 /usr/local 前缀)
启动日志会报告加载了哪个文件,或者正在使用默认值。
以 SHUNT_ 为前缀的环境变量,用 __ 表示嵌套键 —— 例如 SHUNT_SERVER__BIND=0.0.0.0:3001。

由于默认值已经定义了每个提供方,你的 shunt.toml 只需包含你想改动的部分。从 shunt.toml.example 开始。

带注释的示例

[server]
bind = "127.0.0.1:3001"        # shunt 监听的地址
default_provider = "anthropic" # 面向任何无路由匹配的模型的提供方(透传)

# 每个提供方都是一个 [providers.<name>] 表。
[providers.anthropic]
kind = "anthropic"             # 原样转发 Claude Code 自己的凭据
base_url = "https://api.anthropic.com"

[providers.openai]
kind = "responses"             # 将 Anthropic Messages 转换为 OpenAI Responses
base_url = "https://api.openai.com/v1"
auth = "api_key"
api_key_env = "OPENAI_API_KEY" # 读取 OpenAI 密钥的环境变量
# effort = "high"              # 该提供方可选的默认推理力度

[providers.codex]
kind = "responses"
base_url = "https://chatgpt.com/backend-api"
auth = "chatgpt_oauth"         # 复用 ~/.codex/auth.json
# effort = "high"

# --- 路由:请求的 `model` id 如何选取提供方 ---

# 匹配的 [models.upstream_model] 条目最先胜出。[[routes]] 是随后检查的旧版精确匹配形式。
[[routes]]
model = "gpt-5.6-sol"
provider = "codex"
# upstream_model = "gpt-5.6-sol"
# effort = "high"

# 然后是前缀匹配。
[[route_prefixes]]
prefix = "gpt-"
provider = "openai"

# 可选:通过发现在 /model 选择器中暴露 Claude 命名的别名。
# id 必须以 "claude" 或 "anthropic" 开头,否则 Claude Code 会忽略它。
# [[models]]
# id = "claude-opus-via-codex"
# display_name = "Opus (via Codex)"

路由优先级

与请求的 model id 匹配的 [models.upstream_model] 条目。
对请求的 model id 的精确 [[routes]] 匹配。
[[route_prefixes]] 前缀匹配。
server.default_provider —— 默认为 anthropic,因此无匹配的模型会原样透传给 Anthropic。

一条路由可以按模型覆盖转发的模型 id(upstream_model)和推理力度(effort)。

部分覆盖

配置映射是深度合并的,因此对内置提供方的部分覆盖会保留其余默认值:

# 只提高 codex 的默认力度;其他一切保持内置值。
[providers.codex]
effort = "high"

校验

shunt check
# -> 打印 "config ok",或一个具体错误(错误的 bind 地址、未知提供方……)

每个键见配置参考,添加新后端见提供方。