Claude apps gateway 支出限额

按日、周或月为每个开发者设置通过 Claude apps gateway 的支出上限：管理 API 设置上限、实时强制、如何计价、Postgres 可用性与 Claude Code 里的用量提示。

支出限额限制每个开发者在给定的一天、一周或一个月里通过你的 Claude apps gateway 能花多少。开发者超过上限后，网关在其下一个请求上返回 429 并阻止他，直到周期重置或管理员调整。默认情况下，Claude apps gateway 通过一个共享的上游凭据转发所有推理，所以你提供商的账单把一切归到那个凭据，而不是单个开发者；支出限额让你在网关层面按开发者设上限。

设置上限

在 gateway.yaml 里配置 admin: 块后，网关在 /v1/organizations/spend_limits 提供管理 API，并对每个推理请求实时强制上限。上限本身通过这个 API 设置，不在 gateway.yaml 里。为每个开发者设置组织范围默认的每月 500 美元：

curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
  -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": {"type": "organization"}, "amount": "50000", "period": "monthly"}'

在 contractors 组的每个成员上叠加更紧的每日 100 美元上限：

curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
  -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": {"type": "rbac_group", "rbac_group_id": "contractors"}, "amount": "10000", "period": "daily"}'

字段	取值	说明
`scope.type`	`user`、`rbac_group`、`organization`	`user` 按 OpenID Connect（OIDC）的 `sub`（IdP 分配的稳定用户 ID，作为 `scope.user_id` 传入）指定一个开发者；`rbac_group` 按名称指定 IdP 组；`organization` 是全组织默认
`amount`	以美分计的整数字符串，或 `null`	`null` 表示无限制；`"0"` 是零上限，阻止每个请求
`period`	`daily`、`weekly`、`monthly`	一个范围每个周期可以有一个上限，各自独立强制：超过任何一个开发者就被阻止

组或组织的上限是每个成员继承的「按席位默认值」，不是共享池。每个周期里，开发者的有效上限按此顺序解析：按用户的覆盖、然后是其所在组上限中最严格的、然后是组织默认值。

认证到管理 API：发送 x-api-key 头（匹配 admin.write_keys 里的密钥获得完全访问，匹配 admin.read_keys 获得仅 GET 访问；每个密钥带一个出现在审计日志里的 id，所以给 Terraform、CI 和每个自动化各自一个密钥），或带 groups 声明包含某个 admin.admin_groups 的网关 bearer 令牌（完全访问，审计记为 oidc:<sub>，对人类管理员优先用它）。

强制如何工作

在每个 /v1/messages 请求上，网关用一次 Postgres 查询取得开发者的上限和本周期至今的支出。超过任何一个上限的开发者得到带 error.type: billing_error 和头 x-should-retry: false 的 429。消息点明周期和重置时间，如 spend limit reached (daily; resets 2026-08-08 00:00 UTC)，后跟你设置的 admin.blocked_message。上限在 UTC 日历边界重置：每日 00:00 UTC，每周周一，每月 1 号。网关从不阻止 /v1/messages/count_tokens，因为 token 计数是免费的。

请求如何计价

每个响应之后，用量计量器读取 token 数并把成本加到每日、每周和每月计数器；它从不碰发给客户端的字节，所以计量失败不会破坏响应。金额是美元估算。计量器按此顺序选择每个请求的费率：为服务该请求的上游匹配的 pricing.overrides 行（需 v2.1.227 或更高）；上游模型 ID（网关发给提供商的字符串）在 Claude Code 成本表识别它时的标价；对不带模型名的上游字符串（如 Bedrock 应用推理配置文件 ARN 或 Foundry 部署名），你映射到该上游 ID 的 models[].id 的标价；未知模型档位每百万输入/输出 token 5 美元/25 美元，所以计量器无法定位的 ID 永不免费（网关在启动时和每个 ID 在运行时警告一次）。无论哪种费率，计量器再乘以 pricing.multiplier（默认 1）。客户端中止也计费：流在没有上游最终用量帧的情况下结束时，计量器按已发给客户端的文本、约每个输出 token 四个字符估算一个下限，所以提前中止请求无法规避上限。

Postgres 可用性

预检查以两秒超时查询 Postgres。存储不可达或超时时，强制默认放行（fail-open）：请求继续，网关记录警告，响应不带 anthropic-ratelimit-unified-* 头。只有在你的负载均衡器或编排器仍把流量路由到网关时放行才有帮助；store.readiness_grace_seconds 让副本在短暂中断期间继续通过就绪检查。

Claude Code 里的用量提示

Claude Code 在开发者接近上限时警告：利用率超过 75% 时一次，其最耗用的上限超过 95% 时再一次。网关阻止请求时，Claude Code 原样显示网关的 429 消息，包括你的 admin.blocked_message。警告依靠响应头：网关服务器 v2.1.225 或更高时，有上限的开发者的每个成功 /v1/messages 响应在 anthropic-ratelimit-unified-* 头里携带其自己的上限利用率和重置时间；开发者机器也是 v2.1.225 或更高时，Claude Code 读取这些头并显示警告。这些头始终描述开发者自己的上限：网关剥离描述你共享配额的上游提供商速率限制头，从不转发它们。开发者机器 v2.1.251 或更高时，Claude Code 还会在 /usage 里显示 Spend limit 条（已用上限百分比和重置时间），并向状态栏输入添加 rate_limits.spend_limit 对象。

管理 API 参考

端点在 /v1/organizations/spend_limits 下：GET 列出已配置的上限（可按 scope_type 过滤，查询参数 ?limit=&after_id=&before_id=&scope_type=）；POST 为 {scope, period} 创建或替换上限；另有删除上限的端点，详见官方原文。