OpenAI API Key 获取与安全管理

OpenAI API Key 的完整管理方法：在哪里创建、组织与项目怎么划分、为什么只显示一次、如何用环境变量注入、泄露后的处置顺序，以及 429 报错里限流与额度耗尽的区别。

密钥是凭证，不是配置

把 API Key 当成配置项，是后面所有问题的源头。它更接近一张绑定了付款方式的门禁卡：拿到它的人可以用你的账单发起调用，也能看到这些调用的内容。

这条认知决定了它该按什么标准保管——和数据库密码、支付凭证同一档，而不是和日志级别、超时时间同一档。

先规划项目，再创建密钥

控制台里的结构是「组织 → 项目 → 密钥」。多数人跳过中间那层直接建密钥，这会让后面的隔离和排查都变得很难做。

官方在生产实践建议里给的做法是：为预发布和生产分开建项目，用来隔离开发测试与线上流量，并限制谁能访问生产项目。落到实践上：

• 开发环境一个项目，密钥可以给到开发者本人。
• 测试 / 预发布一个项目，用于集成测试，用量单独可见。
• 生产一个项目，密钥只进部署系统，个人不持有。

这样做的直接好处是：某个环境出问题时，撤销一把密钥不会让线上一起停摆；用量异常时，能立刻看出是哪一层在烧钱。

创建、命名与保存

创建密钥时有两件事必须当场做完。

第一，起一个能定位的名字。 「后端服务-生产」「数据清洗脚本」比「key1」「测试」有用得多。三个月后看到用量曲线异常，名字就是你唯一的线索。

第二，立刻保存。 完整的密钥值只在创建时显示这一次，之后控制台只显示前后几位。关掉页面就找不回来，只能删掉重建。存进密码管理器或团队的密钥管理服务，不要贴进备忘录、聊天窗口或代码注释。

用环境变量注入

官方建议使用环境变量，并把变量名统一成 OPENAI_API_KEY——名字统一之后，团队之间共享代码不必附带密钥。

export OPENAI_API_KEY="你的密钥"

几条配套做法：

• 本地开发用 .env 文件，并确认 .env 已经在 .gitignore 里。加进忽略列表这件事要在写入密钥之前做，不是之后。
• CI/CD 用平台自带的机密存储（例如 GitHub Actions 的 secrets），不要写进工作流文件。
• 生产环境用部署平台的环境变量或密钥管理服务注入，密钥不落盘、不进镜像。

Windows 上在系统环境变量里新建后，要重开终端才会生效——这是本地排查时最常见的假故障。

前端永远不放密钥

官方说明写得很直接：在浏览器或移动应用这类客户端环境暴露密钥，会让人拿走它并以你的名义发起请求，可能导致意外费用与账号数据风险。

「编译进去了看不到」不成立，构建产物可以被读取；「加了混淆」也不成立，混淆只是提高了一点点成本。

唯一正确的结构是：客户端调用你自己的后端，后端持有密钥去调模型接口。 在这一层你还能顺手做三件在前端做不了的事——鉴权、限流、成本上限。

提交进仓库之后

把密钥提交进仓库是最常见的泄露路径，公开仓库尤其危险。处理顺序不能颠倒：

1. 立刻撤销这把密钥，并创建新的。
2. 更新所有使用方（部署环境、CI、本地开发）。
3. 再处理仓库历史。

第三步之所以排在最后，是因为它并不能挽回泄露——推送到公开仓库的内容可能在几分钟内就被自动抓取。只删提交记录而不撤销密钥，等于没有处理。

盯住用量

用量页面支持按密钥查看，较新创建的密钥都带使用追踪。养成两个习惯：

• 定期扫一眼按密钥拆分的花费。异常增长往往是泄露的第一个信号，也可能是自己的重试逻辑失控。
• 设置花费上限。它的价值不在于省钱，而在于把最坏情况限制成一个你能承受的数字。

429 不都是「太快了」

429 这个状态码同时承担两类完全不同的问题，处理方式相反：

情况	表现	该怎么做
速率超限	短时间内请求或 token 过多	指数退避后重试，参考响应头里的剩余量与重置时间
余额或上限耗尽	预付额度用尽、组织或项目花费上限触顶	重试无用，需要充值或调整上限

区分方法是读错误体里的具体错误码，而不是只看状态码。官方接口在响应头里会返回 x-ratelimit-remaining-requests、x-ratelimit-remaining-tokens、x-ratelimit-reset-* 以及 Retry-After，退避逻辑应该基于这些值而不是固定的睡眠时间。

用量层级本身是按累计付费额自动提升的，层级越高限额越宽——所以偶发 429 未必是代码问题，也可能只是当前层级的正常上限。

轮换：按事件，而不只按日历

固定周期轮换有价值，但真正重要的是事件触发。出现以下情况应立刻轮换：

• 有成员离开团队，或权限范围发生变化；
• 密钥可能出现在日志、截图、录屏、工单里；
• 有人在非受控环境（借用的电脑、共享终端）用过它；
• 使用的第三方服务发生安全事件。

轮换时顺手做一件事：删掉不再使用的旧密钥。控制台里躺着一堆用途不明的历史密钥，本身就是风险。

泄露处置顺序

顺序固定，先止损再复盘：

1. 撤销——在控制台删除该密钥，让它立即失效。
2. 重建——创建新密钥并更新所有使用方。
3. 查用量——确认泄露窗口内有没有异常调用，估算影响范围。
4. 复盘路径——它是怎么泄露出去的：进了仓库、进了日志、进了截图，还是通过聊天工具传递。不修掉这一步，同样的事会再来一次。

别家的密钥也适用

上面这套做法与厂商无关。Claude、Gemini 的密钥同样是「只显示一次、不进前端、不进仓库、按用途拆分、事件驱动轮换」。各家的获取路径与环境变量名不同，具体见 Anthropic Claude API 使用教程 与 Gemini API 使用教程。

要把密钥换到第三方兼容接口上时，先看 OpenAI 兼容接口怎么判断——那边签发的是另一套密钥，官方密钥在那里无效。

相关内容

• 第一次调用：OpenAI API 使用教程
• 提供方信息：OpenAI API
• 别家的密钥与调用：Anthropic Claude API 使用教程、Gemini API 使用教程
• 第三方接口的兼容性：OpenAI 兼容接口怎么判断、API 中转站是什么

参考资料

• API Key 安全最佳实践（OpenAI 官方帮助中心）
• 生产实践建议（OpenAI 官方文档）
• 限流、用量层级与响应头（OpenAI 官方文档）
• 错误码说明（OpenAI 官方文档）