Claude 应用网关消费限额

按日、周或月限制每位开发者通过 Claude 应用网关产生的支出。使用 Admin API 设置限额，网关会对每个请求进行实时强制执行。

消费限额用于限制每位开发者在一天、一周或一个月内通过 Claude 应用网关产生的支出。开发者超过限额后，网关会对其下一个请求返回 429 并予以阻止，直到新周期开始或管理员提高限额。使用消费限额，可以为每位开发者、每个群组或整个组织设置上限，即使所有人共享同一凭证也不例外。

Claude 应用网关会通过一个共享的上游凭证转发所有推理请求，因此，提供商账单会把全部支出归到该凭证，而不是各个开发者名下。如果没有按开发者设置的限额，一组失控的智能体就可能耗尽组织的全部承诺用量。消费限额在这份共享账单之上提供网关自己的开发者级视图和熔断机制。

设置限额

在 gateway.yaml 中配置 admin: 块后，网关会在 /v1/organizations/spend_limits 提供 Admin API，并对每个推理请求实时执行限额。限额本身通过该 API 设置，而不是在 gateway.yaml 中设置；每个 POST /v1/organizations/spend_limits 请求都会根据 {scope, amount, period} 创建或替换一项限额。该 API 采用与 Anthropic 公共 Admin API 消费限额端点相同的传输格式，因此，为该契约编写的 HTTP 客户端只需更改 base URL，即可改为连接网关。

以下请求为每位开发者设置每月 $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"}'

群组或组织限额是每位成员分别继承的默认值，而不是所有成员共用的资金池。对于每种周期，开发者的有效限额按以下顺序解析：用户级覆盖设置、其群组限额中最严格的一项、组织默认值，最后是不设限。设置 admin.group_limit_mode: max 后，多群组间的选择规则会改为采用最宽松的一项。

对 Admin API 进行身份验证

发送以下任一凭证：

• 一个 x-api-key 请求头：与 admin.write_keys 中的 key 匹配可获得完整访问权限；与 admin.read_keys 匹配则只有 GET 访问权限。每个 key 都有一个 id，会以 admin-key:<id> 的形式出现在审计日志中，因此，请为 Terraform、CI 和每项自动化任务分配各自的 key。
• 一个网关 bearer Token，其 groups claim 包含 admin.admin_groups 中的某一项。它拥有完整访问权限，并以 oidc:<sub> 的形式接受审计，因此更适合人类管理员。

执行机制

收到每个 /v1/messages 请求时，网关会通过一次 Postgres 查询解析开发者的限额和本周期累计支出。如果开发者超过任何限额，请求会返回 429，其中包含 error.type: billing_error 和请求头 x-should-retry: false。消息为 spend limit reached；如果设置了 admin.blocked_message，其内容会附在该消息之后。

/v1/messages/count_tokens 不受限额影响。Token 计数免费，因此无论限额状态如何都会运行。

每个响应结束后，用量计量器会在响应以流式方式发送给客户端的同时读取其中的 Token 数量，按照 USD 目录价计价，并递增 Postgres 中三个周期 bucket 的计数器。计量器是该数据流上的单一读取者，因此不会改动客户端收到的字节，计量失败也不会导致响应中断。

消费限额根据 Token 数量和 USD 目录价估算支出；它是熔断机制，而不是发票。如需权威账单数据，请与提供商自己的用量报告进行核对，例如 Anthropic Usage & Cost Admin API、Amazon Bedrock 调用日志或 Google Cloud 的 Cloud Monitoring。

计价所用表格与 Claude Code CLI 显示自身成本时使用的表格相同，并且对 Anthropic、Amazon Bedrock (us.anthropic.…-v1:0)、Google Cloud's Agent Platform (claude-…@date) 和 Microsoft Foundry 各种形式的 ID 采用相同的模型 ID 规范化方式。如果模型 ID 无法在表格中定位，例如 Microsoft Foundry 部署名称或推理配置文件 ARN，系统不会按零成本处理，而是采用未知模型默认档位：每百万输入/输出 Token 分别为 $5/$25；这样，无法识别的 ID 就不能因未计量而绕过限额。当模型通过回退方式计价时，网关会在启动时发出警告，并在运行时针对每个 ID 警告一次。

客户端中止的请求也会计费。上游只在数据流的结束帧中报告输出 Token，因此，中止的数据流不会携带该数量。计量器会根据已流式传输的内容大小保留一个保守的最低估算值，约为每个 Token 四个字符，并且仅在缺少结束用量帧时按该估算值计费。完整的数据流始终使用上游报告的数量计费。如果没有这项机制，受到限额约束的开发者可以流式接收输出，并在每次请求即将结束前中止，从而不断产生支出却始终不被计量。

Postgres 可用性

预检查查询 Postgres 时的超时时间为两秒。如果存储无法访问或查询超时，执行机制默认采用故障开放：请求继续执行，网关记录警告。设置 enforcement.fail_closed_on_error: true 可以改为故障关闭，此时会返回相同的 429 billing_error，消息为 spend limit unavailable。故障开放可以避免存储中断升级为推理服务中断；故障关闭则保证不会产生未计量的支出。

Admin API 参考

以下端点均位于 /v1/organizations/spend_limits 下。

相关约定与 Anthropic Admin API 一致：

• 每个对象都有 type
• ID 以 spl_ 开头
• 金额采用表示 USD 美分整数的字符串；POST 会对任何其他 currency 返回 400
• 使用 {type: "error", error: {type, message}, request_id} 错误 envelope
• 每个 Admin API 响应（无论成功还是错误）都有 request-id 响应头，与正文中的 request_id 一致

每项变更都会在同一事务中向 admin_audit 写入更改前/后的记录，并归因到 admin-key:<id> 或 oidc:<sub>。

网关只提供消费限额端点。spend_limit_increase_requests 队列等其他 Admin API 功能不属于网关的 Admin API。

/effective

GET /v1/organizations/spend_limits/effective 返回 Anthropic 的 SpendSummary schema：每行代表一个 principal 在一个周期内的数据，包括已解析限额、本周期累计支出和 actor 对象。网关特有的差异如下：

• user_id 为 OIDC sub。
• 在 principal 首次通过网关发出推理请求之前，actor.name 和 actor.email_address 为 null。网关没有用户目录；它会记录每位用户自身会话 JWT 中最后一次出现的值。
• 每行还包含 groups 数组，即最后一次看到的 principal IdP 群组。这是网关扩展，便于管理员 UI 显示所有适用的限额层级；采用 Anthropic 格式的客户端会忽略它。
• 未使用 user_ids[] 筛选器时，只列出已有支出记录的 principal，因为网关无法枚举组织的所有成员。

来源为群组的限额会根据这些最后一次看到的群组进行解析，并使用与执行机制相同的 group_limit_mode 选择规则，因此，查看器显示的就是实际生效的限额。

/audit

返回消费限额变更记录：谁更改了哪项限额、更改前后的快照，以及可选的原因；结果按时间从新到旧排列。has_more 为精确值。此端点遵循本地 Admin API 约定，而不是第一方传输格式。

分页

原始列表使用 after_id 和 before_id 分页，二者互斥，值均为 spl_… ID；结果按创建时间排序，has_more 会反映遍历方向。/effective 使用作为 ?page= 传回的不透明 next_page Token 进行分页，并按 principal 升序排列，使支出记录不断写入时各页仍保持稳定。二者的 limit 都是 1–1000，默认值为 20。

数据生命周期

网关维护四张与支出相关的表；每小时清理任务会执行保留期限：

identity_retention_days 特意短于 spend_retention_months：身份被取消配置后不再刷新，并会随时间清除；其匿名支出计数器则会保留，以便生成同比报告。

开发者离开组织时，请通过 DELETE /v1/organizations/spend_limits/{id} 删除其用户级限额；其支出和身份记录会根据上述保留期限逐渐清除。要为离职流程或数据主体访问请求 (DSAR) 立即清除某个人，请直接在网关数据库上运行 DELETE FROM principal_emails WHERE principal = '<sub>'。这样会删除唯一保存其电子邮件、姓名和群组的表。spend 和 admin_audit 行只引用经过假名化处理的 OIDC sub，并会按各自的保留期限自行清除。

相关内容

• admin 和 enforcement 配置：启用 Admin API 和调整保留期限
• 部署指南：Postgres schema 与备份指南