OpenRouter API Key 怎么管理：创建、限额、轮换与泄漏处置

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

OpenRouter 的 key 和大多数厂商的 key 不是一个东西——官方在鉴权文档里专门用一个警告框说明：OpenRouter 上的 API key 比直接用模型厂商的 key「更强」，因为它可以给应用设置额度上限，也可以走 OAuth 流程发放。这一句决定了整篇文章的结构：key 本身就是一个带预算、带生命周期、可以程序化批量管的对象。你要管的是四件事——创建时把 name、消费上限、重置周期、过期时间一次填对；运行中用 GET /api/v1/key 盯 limit_remaining；轮换时走「建新 key → 换应用 → 删旧 key」三步且全程两把 key 同时有效；泄漏时立刻去 key 设置页删掉重建。另外有个反直觉的点要先说清楚：官方明确讲了，多开账号或多开 key 并不会提高你的速率限制，因为容量是全局管控的——想分摊压力只能换用限流规则不同的模型。

创建一把 key 的时候，其实能一次定好很多事

网页端创建路径最简单：去 key 页面新建，给它起个名字，再可选地设一个额度上限。官方对手工创建的描述只有这么多——起名 + 可选的 credit limit。

真正的字段全集在 Management API 的创建接口里。按官方参数表，name 是唯一必填项，其余都可选，其中几个值得单独拎出来：

• limit：这把 key 的消费上限，是可空的。官方对它的描述是可选的消费上限，未设置时为 null 表示不限。
• limit_reset：限额的重置类型，官方给出的取值是 daily、weekly、monthly，或者 null 表示不重置。重置在 UTC 午夜自动发生，周的口径是周一到周日。这两句是流程规则，不是行情数字，可以放心按它设计自己的预算周期。
• expires_at：可选的 ISO 8601 UTC 过期时间戳。这里有个很容易踩的坑——官方写明必须带秒（YYYY-MM-DDTHH:MM:SSZ，允许小数秒），只精确到分钟的时间戳会被拒绝。
• include_byok_in_limit：是否把 BYOK（用自己的供应商 key）产生的用量算进这把 key 的限额里。
• workspace_id：这把 key 建在哪个工作区，不传就落到默认工作区。
• creator_user_id：可选的创建者用户 ID，官方注明只在组织持有的 key、且要标记是哪个成员创建时才有意义。
• external_api_key / external_user：这两个是合作方场景专用的。官方写得很死——只有用 Connect client secret 鉴权时才接受，拿管理密钥传这两个字段会被 403 拒掉；external_api_key 会以 SHA-256 哈希存储且永不返回。

创建成功后的响应里会带上 key 字符串本身，之后就再也拿不到明文了。所以创建那一刻就要把它写进你的密钥管理设施，这一点和站内讲的通用 API Key 安全管理是同一套逻辑。

单 key 的限额到底怎么生效：三个字段和一个查询接口

官方把限制拆成两类，别混：额度限制管「你能花多少」，速率限制管「你能发多少请求」。

额度限制又有两个来源。第一是账户余额。官方在这里的措辞要逐字看：如果账户余额为负，你可能会看到报错，包括免费模型也在内，把余额补到零以上就能重新使用这些模型。注意是「可能」不是「一定」，也注意免费模型并不豁免于账户级的负余额状态。第二是单个 key 上可选的消费上限，由 limit、limit_reset、limit_remaining 三个字段描述。

查这三个字段的办法是对 https://openrouter.ai/api/v1/key 发一个 GET 请求，带上这把 key 自己的 Bearer token。返回结构里除了上面三个，还有几个日常很有用的：

• usage、usage_daily、usage_weekly、usage_monthly：全时段、当前 UTC 日、当前 UTC 周（从周一起）、当前 UTC 月的用量。
• byok_usage 系列四个字段：同样的四档口径，但统计的是外部 BYOK 用量。
• include_byok_in_limit：布尔值，对应上面创建时那个开关。
• is_free_tier：官方注释写的是「用户此前是否付过费」。
• 还有一个 rate_limit 对象，官方在类型定义里直接标了 deprecated，写明可以安全忽略。别再拿它做判断。

额度不足时会返回 402。官方给的处置顺序是三步：先充值把账户余额补到正数；再检查这把 key 的 limit_remaining 是不是耗尽了，耗尽就提高这把 key 的上限或者等 limit_reset 到点；最后是主动调 GET /api/v1/key 提前监控，别等请求开始失败才发现。想把余额和用量的几种查询口径搞清楚，可以配合看余额和用量怎么查那篇。

速率限制这边有个前面提过的关键说明：官方在 Limits 页顶部的提示框里讲，多建账号或多建 key 不会改变你的速率限制，因为容量是全局管控的；但不同模型的速率限制不同，所以要分摊负载可以从模型这一层去分。另外 Cloudflare 的 DDoS 防护会拦掉显著超出合理用量的请求，官方把它归在「不论账户状态都适用于某些类型请求」的那一类里。

用 Management API 把一堆 key 管起来

如果 key 的数量超过手工点得过来的规模——比如要给每个客户实例发一把独立 key——就得上 Management API。

第一步是去管理密钥页面创建一把 Management API key。这把 key 和普通 key 是两种东西：官方明说管理密钥不能用来调 OpenRouter 的补全端点，它只用于管理类操作。所以别指望一把 key 通吃。

所有 key 管理端点都在 /api/v1/keys 下面，Authorization 头里放管理密钥。官方示例覆盖了这几个动作：

• 列出最近的一批 key，用 offset 查询参数翻页；
• 创建 key（参数见上一节）；
• 按 hash 取单把 key 的详情；
• PATCH 更新，可改的字段包括 name、disabled、include_byok_in_limit、limit_reset；
• DELETE 删除。

这里最该记住的是 hash 和 label 的分工。hash 是你后续 get / update / delete 时的定位符，创建响应里会返回；label 官方在类型定义里没有给出文字说明，只标了它是字符串。官方在轮换教程里专门提了一句：把创建响应里的 key hash 存下来，后面删旧 key 要用它。

disabled 字段也值得单独说——它给了你一个「先停掉、别急着删」的中间态。官方在 Management API 的用例里列的第三个场景就是用量监控：追踪 key 的使用情况并对超限的 key 自动停用，同时提到限额可以按日/周/月重置。

轮换：官方推荐的三步零停机做法

官方把轮换的理由写得很直白——限制凭证泄漏后的暴露窗口、满足合规对凭证管理的要求、留下干净的使用审计轨迹、以及给离职成员或废弃系统撤销访问。

做法是三步：

1. 建新 key。用管理密钥调创建接口，官方示例里的名字带上了轮换日期（形如「Production Key - Rotated 年-月」），这是个值得抄的习惯。
2. 把新 key 推到应用里。官方说具体过程取决于你的基础设施，常见做法是改部署配置里的环境变量、在密钥管理服务（官方点名举例 AWS Secrets Manager、HashiCorp Vault 这类）里轮换、或者更新 CI/CD 的变量。关键在于过渡期内两把 key 都有效，所以可以灰度推，不用停服务。
3. 删旧 key。官方在提示框里加了一条硬要求：删之前一定要先确认新 key 在生产环境确实能用，否则就是自己给自己制造故障。

配套的最佳实践官方列了五条：key 名字里带上轮换日期或版本号；删旧 key 前去 Activity 页确认流量确实已经迁到新 key 上；给新 key 设消费上限以防意外开销；把轮换周期文档化并固定下来（官方举的例子是按季度）；先在非生产环境验证一遍轮换流程。

还有一个结构性的好处只有用 BYOK 的人才吃得到：官方说 BYOK 场景下你的供应商 key 是绑在 OpenRouter 账户上的，不是绑在某一把 OpenRouter key 上，所以你可以随便轮换 OpenRouter 这一侧的 key，完全不用动上游厂商的凭证。对有严格轮换制度的组织来说，这条等于把「轮换成本」从 N 个厂商压缩到了一处。

想再收紧一层，用 Guardrails 给 key 加约束

单 key 的 limit 只管钱。要管「这把 key 能用哪些模型、走哪些供应商、能不能碰敏感数据」，就得用 Guardrails。入口在设置里的 Privacy 页，往下滚到 Guardrails 区块新建；组织账户下必须是管理员才能建和管。

一条 guardrail 可以任意组合这些设置：按日/周/月重置的预算上限（默认只统计 OpenRouter 额度消费，打开 Include BYOK spend 后 BYOK 推理消费也计入同一个上限）、模型白名单、供应商白名单、按模型组强制零数据保留、针对提示注入与越狱的正则检测、敏感信息检测与脱敏、以及自定义正则内容过滤。白名单留空表示不限制。

有三条机制特别容易理解错：

• 建了不等于生效。官方专门用警告框强调，guardrail 在被「分配」之前什么都不管；创建时传 workspace_id 只是把它归到那个工作区里做组织管理，并不会应用到该工作区的流量上。
• 一个对象只能直接绑一条。用户或 key 上只能直接分配一条 guardrail。而且组织成员创建的所有 key 都会隐式跟随该成员的分配，即便这把 key 自己另外还绑了更严的一条。
• 叠加时严的赢。供应商白名单和模型白名单在多条 guardrail 之间取交集，零数据保留按模型组取或逻辑，敏感信息过滤取并集且同一实体上 block 优先于 redact，预算则是每条独立检查。预算的计量是按用户和按 key 分别算的，不是所有人共用一个池子；一把 key 的消费会同时计入这把 key 的预算和它所属成员的预算。

自定义内容过滤有两种动作：redact 把命中片段替换成占位符再转发给模型，block 则在请求到达模型之前直接拒掉。被 guardrail 的运行时检查拦住时返回的是 HTTP 403，注意预算超限和白名单限制也会返回 403，只是只有运行时内容检查才会在 openrouter_metadata 里带上阶段细节。这一点和403 报错的排查思路是同一件事的两面。

正则本身也有限制：官方支持字符类、量词、交替、非捕获组、命名捕获组、锚点和转义，但明确不允许前瞻、后顾、反向引用，以及 (a+)+ 这类嵌套量词导致的过度回溯；不合规的 pattern 会在创建和更新时被 invalid_regex_pattern 错误直接拒绝。单条 pattern 的长度也有上限，具体数值以官方文档当前版本为准。

key 泄漏了怎么办

官方在鉴权文档末尾单开了一节讲这个，动作只有两步，但前提值得知道。

前提是：OpenRouter 是 GitHub 密钥扫描的合作伙伴，另外还有别的手段检测暴露的 key。如果平台判定你的 key 已经泄漏，你会收到邮件通知。

处置动作是：收到这类通知，或者你自己怀疑 key 已经暴露，立刻去 key 设置页删掉被泄的那把，然后新建一把。官方同时给了一条通用建议——用环境变量、别把 key 放进代码库。

还有一处细节藏在别的章节里：官方在讲把 key 写进 shell 配置文件时，自己给出了「密钥卫生」的提醒——那类文件很容易被误提交进 dotfiles 仓库或者贴进 gist，更好的做法是从操作系统的钥匙串里读，官方给的 macOS 示例是用 security find-generic-password 取值再 export；万一真的泄了，就去 key 设置页吊销并轮换。

顺带一提，authentication 这个 error_type 的官方含义是「key 缺失、无效或已被吊销」，所以你删掉一把 key 之后，还在用它的服务会以鉴权失败的形式表现出来，而不是别的症状——这也是401 排查那篇的起点。

最容易栽的坑

从官方文档这几处提示能看出来，这套机制上最容易出问题的不是接口本身，而是三个假设：

第一，以为多建几把 key 能绕开速率限制。官方讲得很清楚，容量是全局管的，多开 key 或多开账号不改变速率限制。

第二，以为 key 的 limit 到顶了就只是这把 key 停了。实际上账户余额和单 key 上限是两条独立的闸，402 出现时得两条都看一遍，别只盯着一条。

第三，轮换时先删旧 key 再验新 key。官方那条提示框存在的意义就是拦这个动作——两把 key 在过渡期是同时有效的，你完全没有理由抢那几分钟。

下一步建议先做一件小事：给你现在正在用的每把 key 补上 name 和 limit_reset，再把 GET /api/v1/key 接进你的监控。等到 402 打脸的时候再去补，成本要高得多。