HTTP 端点

/admin* 路由仅在配置了 [server.admin] 时存在;没有该表时,它们一个都不会注册。管理员凭据可通过配置的头部或 x-api-key 提交,read_keys 凭据可以通过上面的所有 GET,但在所有修改操作上会被 403 拒绝。它可以登录:POST /admin/login 会接受它并铸造一个 read 级别的会话,该会话的修改操作同样会被 403 拒绝。 该登录 POST 受 same-origin 保护:跨站表单提交会在检查凭据之前就被 403 拒绝,因此任何凭据持有者都无法用自己的会话 cookie 替换已登录运维人员的会话。脚本登录不受影响 —— 当 Sec-Fetch-Site 和 Origin 都不存在时,该检查会通过。但 SPA 外壳与前端包文件是例外:GET /admin(两种写法)、GET /admin/{*path} 与 GET /admin/assets/{*path} 无需管理员认证即可获取。这样是安全的,因为它们不包含任何运维数据,而 SPA 读取的一切都在 /admin/api/* 之后,后者对每个请求都做认证;其中两个通配符路由同样仅在配置了 [server.admin] 且二进制使用 --features ui 构建时才存在。GET /admin/api/observed 会自动发现网关主机上受支持的 Claude Code、Codex CLI、Gemini CLI、Kimi Code、Grok CLI 与 Cursor.app 凭据,且从不刷新或写入这些来源。设置 [server.admin].hide_observed 即可跳过这一发现:该路由仍会认证并返回 { "accounts": [] },GET /admin/api/session 报告 hide_observed: true,仪表盘则跳过该请求,只列出托管的池账户。

管理 SPA 包(--features ui)

/admin/assets/{*path} 与 /admin/{*path} SPA 回退仅存在于使用 --features ui 构建的二进制中,该构建会把 ui/ 包产出的前端包内嵌进二进制。默认的 cargo build 不需要 Node 工具链,不包含前端包,也不会注册这两个路由;预构建的发布二进制则启用了 该特性。

回退被限制在 /admin 挂载点之内:

• /admin/ 下未匹配任何路由的路径会以 200 和 text/html 返回 SPA 外壳,使客户端 深链接在刷新后依然可用;
• /admin/api/ 下未匹配的路径会以 Anthropic 错误结构返回 404 —— 该命名空间是 JSON 而不是 UI,用 HTML 作答会破坏客户端的错误处理;
• 挂载点之外的路径不受影响,仍然返回 404。

GET /admin 同样是外壳,GET /admin/ 也是。由于通配符段无法匹配空字符串,/admin/ 既不会命中精确路由,也不会命中回退,只会在仪表盘自己的根路径上返回一个没有响应体的 404,因此挂载点根路径的两种写法各自注册。

这两者是在两种构建中都注册、但响应取决于该特性的管理路径:启用时返回外壳,未启用时返回响应体中点明 --features ui 的 404。两种构建都保留注册,是为了让那个 404 带上这句说明 —— 若直接不注册,得到的是 axum 没有响应体的 404,运维人员无法将其与未配置 [server.admin] 区分开。

管理路径迁移

破坏性变更。 所有管理 JSON 路由与修改类路由都从 /admin/* 迁移到了 /admin/api/*。 旧路径已被移除,而不是保留为别名,任何请求都不会再到达 admin 处理器。

旧路径上返回什么取决于构建方式,因此不要把那里的 200 当作成功:

• 默认构建 —— 该路径未在任何位置注册,返回 404。
• --features ui(预构建的发布二进制即为此类)—— GET 会像挂载点下的其他深层链接一样 落到 /admin/{*path} SPA 回退,返回 200 text/html 的外壳;HEAD 同理。其余方法返回 405 并带上 Allow: GET,HEAD,因为该回退是用 get 而非 any 注册的。

因此仍停留在旧 GET URL 的脚本收到的是 HTML,而不是迁移信号。请迁移到 /admin/api/*; 响应的 Content-Type 是可靠的判别依据。

/admin 仍然是仪表盘外壳,/admin/login 和 /admin/oidc/callback 也保持原位 —— 它们是服务端 渲染的页面,不是 API 路由。其余全部迁移,是为了让仪表盘可以把 /admin/* 用作可浏览的深层链接: 一个路径不可能既是 JSON 端点又是客户端路由,所以没有保留任何兼容别名。

脚本调用方只需机械地改写一次 —— 路径只是在 /admin 之后多了一个 /api 段:

认证未变:仍是同一份管理员凭据,通过同样的头部或 x-api-key 提交,读/写分级也相同。

spend-limit 路由仅在启动时配置了 [server.spend] 的情况下存在;它们使用 [server.admin] 凭据认证,因此与 [server.gateway] 无关。请通过配置的管理员头部(默认 x-shunt-admin-token)或 x-api-key 发送该凭据 —— 两个槽位都被接受。write 凭据(write_keys 条目,或 tokens_env/tokens_file 对)可使用全部操作;read_keys 凭据只能使用 GET,在修改操作上会收到 403。POST 接受 user 和 organization scope、daily/weekly/monthly period、user scope 中 1–256 字节的 user_id，以及 1–19 位非负 USD 美分整数字符串或 null 的 amount，并按 (scope, period) 执行 upsert。列表分页接受 limit（1–1000，默认 20）、after_id、before_id 和 scope_type；两个游标不能同时使用。每个响应都包含 request-id，错误采用 Anthropic 错误形状。限制与修改审计记录一起保存到所配置的带版本 JSON 状态文件中,每次修改归属于 admin-key:<id> 或 admin-token:<name> —— 当两个槽位携带同一层级的不同凭据时，归属于配置的管理员头部那一个。GET /v1/organizations/spend_limits/effective(read 或 write 凭据)为每个主体、每个周期返回一行,包含生效的上限(amount、source、spend_limit_id)以及以美分计的 period_to_date_spend;支持 limit(1–1000,默认 20,按主体计数)、period[]、user_ids[](最多 100 个,不分页)、q、sort=spend_desc(须恰有一个 period[])和 page,输入无效时返回 400 invalid_request_error。period_to_date_spend 只反映计量器能够读取的计数器:持久化计数记录恢复失败的主体,在其 unavailable 标记解除之前,支出可能显示为 0 或只有一部分,日志中的恢复警告会记录该主体。限制作用于 /v1/messages,以及入站 Codex 端点的 Responses 路由和 /alpha/search 别名(超限的 Codex 回合收到 429 usage_limit_reached,见入站 Codex 端点);仅由 passthrough 或 type = "noop" 路由组成的链不适用;不公开 /audit。

/user/bootstrap 路由仅在启动时启用了 [server.gateway] 的情况下存在，并要求有效的网关 bearer JWT；静态 [server.auth] token 无法通过该端点的认证。它以 application/json 返回 [server.gateway.desktop_bootstrap] 的模板，字符串值中的 ${user.email}、${user.sub}、${user.name} 会被替换。包括错误和 304 在内的所有响应都带有 Cache-Control: no-store，该路由从不重定向。

没有 policy 时，所有已登录用户都有权获取；有 policy 时，用户被某条 policy 的 match.emails 列出，或存在 catch-all policy(无 match)，才有权获取。设备码端点接受没有 client_id 的请求(Claude Desktop 不发送)以及 client_id=claude-code 的请求，其他取值一律拒绝。对于没有 client_id 的请求，被拒绝的 refresh token 返回 400 {"error":"invalid_grant"}，而 claude-code 请求仍返回 401。参见连接 Claude Desktop。

GET /managed/settings 与 POST /v1/{metrics,logs,traces} 遥测接收路由仅在启动时启用了 [server.gateway] 的情况下存在,二者要求相同的网关 bearer JWT。接收路由接受托管 Claude Code 客户端 export 的 OTLP/HTTP 载荷([server.gateway.telemetry] 将这些 exporter 指向网关),并把请求字节原样中继到所有 opt-in 该 signal 的目标。入站的 content-type 与 content-encoding 会被保留,目标配置的 headers 应用在其上(配置的键会替换转发值,而不是重复该 header)。客户端的 Authorization 头永远不会被转发,中继也不跟随重定向。目标按 signal opt-in(metrics 默认开启,logs/traces 默认关闭),没有任何目标 opt-in 的 signal 会被接收后丢弃。中继是分离执行的,因此无论目标状态如何,响应始终是立即的 200,成功 body 依照 OTLP/HTTP 镜像请求协议(application/json 得到 {},其余得到空的 application/x-protobuf body)。超过 32 MiB 入站上限的 body 返回 413。

入站 Codex Responses、网页搜索、模型目录和分析路由仅在配置了 [server.codex_endpoint] 时存在。Responses 路由通过 HTTP/SSE（POST）或 WebSocket 升级（GET）逐字中继 OpenAI Responses 请求和响应，也可以通过 [[server.codex_endpoint.routes]] 按模型路由到其他兼容 Responses 的上游。Codex 专用的两个模型路径返回 {"models":[]}；共用 /v1/models 仅在查询包含 client_version 时返回该形状，否则保持现有 Anthropic 外观响应。所有目录变体都会先通过现用的模型发现认证门。两个分析路由采用相同的入站认证策略，不转发或保留客户端 payload，并在认证后对无效 JSON 或超大正文也返回 200 {}。只有净化后的事件名称会记录到 shunt.codex_client_events；未配置指标 sink 时，它们是纯丢弃 sink。三个网页搜索路径通过与 Responses 路径相同的账户池和入站认证策略，把 Codex CLI 的内置网页搜索逐字中继到后端的 /codex/alpha/search；它们只接受 POST，且从不遵循 [[server.codex_endpoint.routes]] 条目。

/usage 路由仅在配置 [server.usage] 时存在,且同样要求 [server.auth] 或 [server.gateway]。它使用与 GET /v1/messages 相同的客户端 token,或以 Authorization: Bearer 发送的网关登录访问 token(即 shunt gateway claude 启动的会话所发送的值)进行认证。有效的网关登录无需经过 [server.auth] 即被接受,因此 [[server.auth.jwt]] 密钥集不可达时也不会被拒之门外。它返回共享账户池按窗口的剩余余量(报告该窗口的未禁用账户的 mean(clamp(cap - utilization, 0, 1)),其中 cap 是该账户在该窗口上解析得到的 max_utilization 硬上限,没有适用上限时为 1.0,即在上限将账户排除之前整个池的总容量中仍可使用的比例;若某账户已被上限排除在该窗口所处理的请求之外,则在该窗口计为零,且 5h 或 7d 上限也会将其排除在 Fable 请求之外)、这些账户报告的最早重置时间(对因上限而计为零的账户,也包括该上限解除的时间),以及 ok/degraded/exhausted/capped 状态。它不会暴露账户身份、数量、优先级、disabled、阈值或账户级数值。只有在没有任何未禁用账户报告某个窗口时,该窗口才是 null。Codex 响应中的 x-codex-* 头部和可选的 wham/usage 轮询会填充已观测的 5 小时和共享每周窗口。在 WebSocket 传输上,流内的 codex.rate_limits 事件会在每一轮对话(包括复用连接)填充同样的窗口。Codex 没有 Fable 范围(7d_oi)的信号,但混合提供方池中的其他提供方可以提供聚合 Fable 值。pool 是所有参与池化的提供方的总体聚合;providers 以配置的提供方名称为键,为每个参与池化的提供方给出同样经过净化的聚合,使路由到某一提供方的客户端可以读取该提供方自身的余量和状态,而不是整个池的平均值。认证模式不参与池化的提供方会被省略。完整的响应形态见英文端点参考。 Claude Code 客户端无需 curl 即可读取:本仓库插件市场中的 shunt mod 会用这个端点回答 /shunt:usage,打印每个窗口的剩余余量和重置时间。它需要函数钩子(CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1),目前仍是早期访问。

池状态 capped 表示没有可用账户,且至少有一个已启用(非 disabled)且未暂停的账户被 max_utilization* 硬上限剔除(参见 [server.pool]);它不同于 exhausted。

即使启用了 [server.auth],GET / 和 GET /health 也保持开放(健康检查工具通常无法附带 token),并且不暴露任何敏感信息 —— 只有状态、版本以及已经公开的端点列表。 配置了 [[server.auth.jwt]] 条目时,Authorization: Bearer 中经过验证的外部 JWT 可以像客户端 token 一样认证同一批受控路由。没有任何条目能验证的 token 返回 401;没有任何条目验证通过、且与 token 的 issuer 匹配的条目中存在既无缓存 key set 又拉取失败的条目时,返回 503。

网关协议

shunt 实现官方的 Claude Code LLM 网关协议:正确的头部和正文字段转发、特性透传以及系统提示归属处理。网关自身产生的错误以 Anthropic 错误形状返回,上游上下文溢出错误被重写为 Anthropic 的 prompt is too long 措辞,以便触发 Claude Code 的 压缩并重试,而流式响应无缓冲地中继(带可选的 keepalive ping)。