企业官网建设流程全解析

codex-lb API密钥详解：Token、成本、时间窗、模型与账号绑定的5维限流

【免费下载链接】codex-lbCodex/ChatGPT multiple account load balancer & proxy with usage tracking, dashboard, and OpenCode-compatible endpoints项目地址: https://gitcode.com/gh_mirrors/co/codex-lb

codex-lb是一个面向 Codex/ChatGPT 多账号的负载均衡代理，其API密钥（API Key）不仅承担客户端认证，更是精细限流的核心抓手：你可以按Token 数量、美元成本、时间窗口、模型范围、绑定账号这 5 个维度组合出配额策略，实现"按预算管流量"。本文带你从新手视角完整看懂这套 5 维限流机制 🎯

一、API密钥是什么？如何启用与创建

codex-lb 的API Key 认证默认关闭。开启后，客户端必须携带密钥访问受保护代理路由（/v1/*、/backend-api/codex/*、/backend-api/transcribe）：

Authorization: Bearer sk-clb-...

开启路径：控制面板Settings → API Key Auth。详细文档见 api-keys.md。

创建密钥非常简单：Dashboard → API Keys → Create。需要注意两点：

• 🔑 完整密钥只在创建时展示一次，务必妥善保存；
• 密钥支持可选的过期时间（expires_at），到期后自动拒绝请求。

二、维度一：Token 限流（三种口径）

在 schemas.py 中可以看到，限流规则支持 5 种limit_type，其中 Token 类占 3 种：

实现上，请求进入时代理会先"预留"额度（reserve），再按上游实际用量结算（settle）。相关逻辑位于 service.py 的_reserve_budget_for_limit_type中，保证并发下不会超发额度。

三、维度二：成本限流（cost_usd）

cost_usd规则按美元设上限。系统内部以"微美元"（microdollar，1 美元 = 100 万单位）记账，按请求的模型价格 × Token 数预估扣减；若模型未知，则按保守的兜底单价估算（见 service.py 的_unknown_model_reserve_cost_budget_microdollars）。

💡 成本限流 + 未知模型兜底单价，意味着即使遇到新模型也没办法绕过预算"白嫖"——这是新手容易忽略的安全细节。

四、维度三：时间窗限流（5种窗口）

limit_window支持 5 种窗口，在 models.py 的LimitWindow枚举中定义：

• daily（每日重置）
• weekly（每周重置）
• monthly（每月重置）
• 5h/7d（对齐上游 Codex 的 5 小时 / 7 天额度节奏）

窗口重置采用惰性重置 + 推进策略：到期不主动清零，而是下次请求时自动把reset_at向前推进到第一个大于当前的重置点，实现见 limit_windows.py 的advance_limit_reset——省掉了定时任务，重启也不丢状态。

⚠️ 当current_value >= max_value时，请求会被直接拒绝并返回限流错误；每个窗口各自独立计数，互不干扰。

五、维度四：模型维度限流与模型管控

模型管控有两层：

1）密钥级模型策略

• allowed_models：密钥只允许调用列出的模型；
• enforced_model：强制把请求改写到指定模型，客户端写什么都会被覆盖；
• apply_to_codex_model：是否将上述策略应用到 Codex 模型。

2）限流规则的模型过滤

LimitRuleCreate中的model_filter字段让每条配额规则只针对特定模型生效，例如：

• "gpt-5 每周限 1000 万 Token"
• "其他模型不限"

判断逻辑在 service.py 的_limit_applies_for_request中：请求模型不匹配的规则会被跳过，实现分模型差异化配额。

六、维度五：账号绑定限流（只消耗指定账号额度）

这是最实用的维度——把密钥绑定到指定账号池（assigned_account_ids）后，该密钥只从被分配的账号中消耗配额，互不抢占。

典型用法：

• 团队 A 的生产密钥 → 绑定 2 个 Plus 账号；
• 团队 B 的测试密钥 → 绑定 1 个 Team 账号；
• 某个账号额度耗尽时，只影响绑定它的密钥，故障域被隔离。

七、配额组合实战：一个新手友好的配置清单

综合 5 个维度，一个"稳妥的生产密钥"通常这样配：

配置完成后可在密钥卡片上直接查看usage_summary（请求数、总 Token、缓存命中 Token、累计成本）与limits中每条规则的current_value/remaining_value/reset_at，数据模型定义见 schemas.py 的ApiKeyResponse。

八、常见问题（FAQ）

Q1：限流被触发会怎样？请求会收到明确的限流错误提示（含触发的是哪条规则），不会静默排队，便于定位是 Token、成本还是窗口规则触顶。

Q2：窗口到期后额度怎么恢复？惰性重置：下一次请求自动推进重置点并清零计数，无需重启服务。

Q3：能限制客户端的请求强度吗？可以。密钥还支持enforced_reasoning_effort（强制推理强度）和allowed_reasoning_efforts（允许列表），越界请求返回403 reasoning_effort_not_allowed，详见 api-keys.md 的 Reasoning effort policies 一节。

Q4：成本规则按什么价格算？按请求实际使用的模型 × Token 数估算扣减，未知模型走保守兜底单价，确保预算不被绕过。

总结

codex-lb 的API 密钥限流把"谁在用（账号绑定）、用什么（模型管控）、用多少（Token/成本）、多久重置（时间窗）"五个问题收敛到一张密钥卡片里。作为多账号负载均衡代理，这套5 维限流机制让团队配额管理像配置防火墙规则一样直观——上手只需在API Keys → Create中勾选几下，即可开始精细化控制每一次 Codex 调用的成本 🚀

【免费下载链接】codex-lbCodex/ChatGPT multiple account load balancer & proxy with usage tracking, dashboard, and OpenCode-compatible endpoints项目地址: https://gitcode.com/gh_mirrors/co/codex-lb