CLI

shunt run

启动网关。run 是默认子命令,因此裸的 shunt 也可以。

shunt run
shunt run --config /path/to/shunt.toml

启动时它会用绑定地址(默认 127.0.0.1:3001)记录 shunt listening。用 RUST_LOG 设置日志详细程度,例如 RUST_LOG=shunt=debug shunt run。

不带 --config 时,shunt 依次搜索 ./shunt.toml → ~/.config/shunt/shunt.toml → $HOMEBREW_PREFIX/etc/shunt.toml;带 --config 时,文件缺失即报错。见 配置。

shunt check

校验解析后的配置并退出(shunt --check 也可以):

shunt check
# -> config ok

报告具体错误:错误的 bind 地址、路由中的未知提供方、缺失的 api_key_env、错误的 base_url、错误的适配器/认证组合。

shunt init

在现有目录中创建 starter shunt.toml。该命令只写入这一个文件，不会安装任何内容或访问网络。

shunt init
shunt init --upstream codex --upstream kimi
shunt init --root /path/to/project
shunt init --force

不指定 upstream 时，starter 完全由注释组成，加载后使用 shunt 的默认 passthrough 配置。重复使用 --upstream 可按 failover 顺序添加 preset 条目；可用名称为 anthropic、codex、openai、xai、grok、kimi 和 cursor。Starter 不设置 server.default_provider，因此未映射流量仍使用默认 Anthropic passthrough。指定 preset 时，会在末尾自动追加一个 anthropic passthrough upstream（除非你自己指定了 anthropic），使生成的文件既能通过 shunt check，又能保留该 fallback。

Root 默认为当前目录，并且必须已经存在。如果其中已有 shunt.toml、shunt.yaml 或 shunt.yml，则不带 --force 时会停止且不写入任何内容。强制 init 只覆盖 shunt.toml；YAML variant 保持不变，config discovery 会优先使用新的 TOML 文件。

shunt add

获取面向编码 agent 的内置 Markdown blueprint。Blueprint 是实现指南，而不是安装程序：该命令不会修改文件、安装任何内容或访问网络。

shunt add                                      # 列出两种 blueprint kind
shunt add upstream                             # 列出具名 upstream 指南
shunt add upstream kimi --print                # 打印一份指南
shunt add upstream https://example.com/docs    # 调研兼容 endpoint
shunt add provider https://example.com/docs    # 调研源码集成

Kind 分为 upstream（配置已提供的 preset 或兼容 endpoint）和 provider（贡献新的 provider protocol 支持）。已知的 upstream slug 或 alias 会获取对应的具名指南。绝对 http:// 或 https:// URL 会注入该 kind 的通用 research 指南；相对路径会被拒绝。

Blueprint Markdown 始终输出到 stdout，以便直接输送给 agent。--print 明确表达这一意图并抑制交互式 stderr hint，但不会改变 stdout 内容。

shunt add upstream kimi --print | claude

shunt token

将一个 Claude 订阅 OAuth token 打印到 stdout(日志走 stderr),设计用来接入 Claude Code 的 apiKeyHelper。两种模式:

• 静态 —— 如果设置了 SHUNT_GATEWAY_TOKEN 或 CLAUDE_CODE_OAUTH_TOKEN,原样回显该值。把它指向一个 claude setup-token 值,则从不刷新任何东西。
• 自动刷新 —— 否则读取 ~/.claude/.credentials.json(用 CLAUDE_CREDENTIALS 覆盖路径),返回 claudeAiOauth 访问 token,并在它距 expiresAt 5 分钟以内时,针对 platform.claude.com/v1/oauth/token(与 Claude Code 使用的同一授权)刷新它,然后以 0600 原子写回新 token,保留其他所有字段。刷新只在实际过期时发生,以尊重该端点的速率限制。

// ~/.claude/settings.json
{
  "apiKeyHelper": "/path/to/shunt token"
}

何时需要它,见 连接 Claude Code。

shunt login claude

用以下三种模式之一创建一个由 shunt 管理的 Anthropic 池账户:

# Full OAuth: shunt 获取并存储一个新的可刷新登录(推荐)。
shunt login claude --name primary --mode oauth

# 导入当前可刷新的 Claude Code 登录。
shunt login claude --name imported --mode import

# 运行 Claude 的一年期、仅推理 setup-token 流程。
shunt login claude --name ci --mode setup-token

在 TTY 中省略 --mode 时,shunt 会提示选择 oauth、import 或 setup-token,并默认推荐 OAuth。非交互输入继续沿用原有的 import 默认值。--long-lived 保留为 --mode setup-token 的 deprecated alias。

--mode oauth 运行 shunt 的 full-scope PKCE 授权流程,并同时存储 access token 与 refresh token。默认情况下,shunt 在 127.0.0.1 上绑定一个临时 listener,打开授权 URL,并在浏览器返回 http://127.0.0.1:<port>/callback 时完成。如果无法打开浏览器、无法启动 listener,或 5 分钟内没有收到 callback,它会回退到隐藏输入的手动粘贴流程。通过 SSH 或在 headless 环境中可用 --manual 立即使用手动流程:

shunt login claude --name remote --mode oauth --manual

--mode import 将 ~/.claude/.credentials.json(或 CLAUDE_CREDENTIALS)复制到 ~/.shunt/accounts/claude/<name>.json。它保留 refresh token,关联 Claude Code 全局配置中的当前账户 UUID,而 shunt 刷新这份私有副本,不会修改 Claude Code 的源文件。

--mode setup-token 运行与 claude setup-token 相同的一年期、仅推理 PKCE 流程。在浏览器批准后,把显示的授权码粘贴到 shunt 的隐藏输入提示中。shunt 直接交换该代码,存储 opaque token 和签发账户 UUID,并且绝不打印 token。

在 Unix 上,文件以 0600 权限原子写入 0700 目录。SHUNT_CLAUDE_ACCOUNTS_DIR 可覆盖存储目录;复用名称会替换其文件。已有的外部 setup token 仍需要 token_env 加显式 uuid,因为签发后无法恢复其账户 UUID。

通过只带名称的池条目引用结果,或将 provider 的账户列表留空以扫描所有存储文件:

[[providers.anthropic.accounts]]
name = "primary"

shunt login xai

运行 xAI 的 device-code OAuth 流程并保存可刷新的 credential:

shunt login xai

Anthropic 账户池认证

对于 auth = "claude_oauth" 的 Anthropic provider,账户可以使用只带名称的存储条目、credentials = "~/.claude/.credentials.json" 或 token_env = "YOUR_ENV_NAME"。存储条目可由上面的 Full OAuth、Claude Code 登录导入或 setup-token 流程创建。完整配置和 failover 规则见 Anthropic 多账户。

环境变量