API Key 安全与轮换

这篇页面只讲 API Key 的安全管理：怎么安全保存、怎么把权限收窄到够用，以及发现泄漏后按什么顺序处理。

Key 的创建和字段说明见准备 API Key，令牌、额度等概念见概念说明，常见报错见常见问题。

平台差异

模型限制、IP 白名单、额度上限、过期时间、调用日志和吊销入口都由服务商控制台提供，名称和是否支持可能不同。本文给出通用做法；具体操作以服务商控制台为准。

安全保存

目标：Key 只存在于你信任的凭据存储和必要的运行环境中，不要出现在会被复制、同步、提交、截图或转发的地方。

推荐做法

• 密码管理器：保存完整 Key、服务地址、用途、创建日期和上次轮换日期。建议同时记录这把 Key 对应哪个工具、哪个环境。
• 系统凭据存储：如果工具支持，优先使用系统凭据存储，例如 Windows Credential Manager、macOS Keychain、Linux Secret Service/GNOME Keyring/KWallet。
• 环境变量或独立凭据文件：比把 Key 硬编码进项目配置好；但环境变量仍可能被同机进程、诊断输出或日志捕获，不要在共享机器上长期设置。
• CI/CD secret：把 Key 放在 CI 平台的加密 secret 中，并确认构建日志不会打印它。
• 按需注入：只在需要调用 API 的进程或工具里读取 Key；不要把它写进全局 shell profile、共享配置或默认启动脚本。

不要这样做

• 不要提交到 Git：包括 .env、settings.json、config.toml、opencode.json、CI 配置和任何会被同步到公开仓库的文件。
• 不要截图、录屏、发群、发公开 issue 或粘贴到聊天窗口。
• 不要写进多人共享的配置、共享终端历史或共享 CI 日志。
• 不要把 Key 放在会自动同步到云盘、备份或公开目录的文件夹。
• 不要把完整 Key 发给 AI。需要让 AI 帮你排查时，只提供变量名、用途或脱敏后的前缀。

权限最小化

一把 Key 只服务一个工具、一个环境或一个用途。能限制的字段都限制，泄漏后的损失才可控。

措施	建议	作用
按工具/环境建 Key	codex-local、claude-code-ci、opencode-laptop	独立吊销、对账和排障
模型限制	只允许这个 Key 调用确实需要的模型	缩小泄漏后的可用范围
IP 白名单	只允许家庭、办公室或 CI 出口 IP / CIDR（如果服务支持）	阻止其他来源使用
额度上限	关闭“无限配额”或设置明确的金额/token 上限	防止脚本跑飞或被盗刷
过期时间	CI 用短有效期；个人使用也建议设置合理有效期	让旧 Key 自动失效
命名可识别	在名称里写清工具和环境	日志和账单里更容易定位

创建或修改 Key 后，按这份清单核对：

• [ ] 这个 Key 只给一个工具或环境使用
• [ ] 已限制到必要模型
• [ ] 已设置额度上限
• [ ] 已设置过期时间
• [ ] 服务支持时已配置 IP 白名单
• [ ] 没有把完整 Key 写入项目文件或共享配置

无限配额不等于无限安全

“无限配额”通常只表示取消 Key 这一层的额度限制，账户余额、并发预扣和服务商风控仍然生效。不要因为它名字里有“无限”就把它当成安全设置。

发现泄漏后的处理顺序

确认或怀疑 Key 泄漏后，先止损，再排查。不要先删本地文件，也不要只改配置——文件删掉不等于 Key 失效。

1. 立即吊销

在服务商控制台删除、禁用或吊销泄漏的 Key。入口名称可能是“删除”“禁用”“吊销”或“Revoke”，以服务商控制台为准。

如果控制台暂时无法吊销，按服务商的安全事件流程处理，必要时先停用相关服务。

2. 新建替代 Key

新建一把 Key，重新按最小权限设置模型限制、额度、过期时间和 IP 白名单。不要复用旧 Key，也不要把旧 Key 继续留在任何地方。

3. 更新本地配置和环境变量

把新 Key 替换到所有会使用它的地方：

• 工具自己的凭据文件或系统凭据存储
• 本机环境变量和 shell profile
• CI/CD secrets、部署平台环境变量和容器 secret
• 服务器、NAS、定时任务或其他自动化脚本

替换后用 /v1/models 或服务商提供的验证方式确认新 Key 可用。不要在命令输出、日志或聊天里打印完整 Key。

4. 检查调用日志和账单

查看服务商的用量、调用日志和账单，重点看：

• 泄漏时间之后是否有异常请求
• 是否出现你没用过的模型、来源 IP 或调用时间
• 是否有异常并发、异常 token 量或异常费用

先保留脱敏后的证据，再联系服务商处理。不要为了排查继续使用旧 Key。

5. 清理泄漏源

按可能性逐个清理：

• Git：从工作区、暂存区和历史提交中移除明文 Key。先吊销再重写历史；普通删除不会让 Key 失效。
• 日志：应用日志、网关日志、CI 日志、终端输出和错误报告。
• Shell 历史：Bash/Zsh history、PowerShell PSReadLine 历史、临时脚本。
• CI secrets：更新 secret 值，并检查是否有构建步骤把它打印出来。
• 截图和聊天：删除含 Key 的截图、聊天记录、issue、PR 评论和工单附件。
• 临时文件和备份：下载目录、临时文件、编辑器备份、剪贴板历史和云盘历史版本。

给 AI 的排查提示词

如果 AI 工具有本机文件访问权限，可以把下面这段提示词交给它，让它先定位再修改。不要粘贴完整 Key，只提供变量名、用途或脱敏前缀。

我在本机轮换了 API Key。请帮我定位可能仍保存旧 Key 的位置，但不要输出完整 Key。

旧 Key 的变量名或脱敏前缀是：<例如 OPENAI_API_KEY、ANTHROPIC_AUTH_TOKEN、sk-abc...>

请检查：
1. 当前项目、用户目录和常见工具配置目录
2. .env、*.json、*.yaml、*.toml、*.ini、*.config、脚本、Docker 和 CI 配置
3. Git 已跟踪文件、暂存区、历史提交和 .gitignore 未覆盖的文件
4. Shell history、应用日志、临时文件和备份
5. CI/CD secrets、系统环境变量和系统凭据存储
6. Codex、Claude Code、OpenCode、Copilot 等工具的凭据文件

请先只列出命中位置，包括文件路径、行号、变量名和脱敏后的前后文；不要打印完整 Key，也不要修改文件。等我确认后再给出替换和清理步骤。

如果 AI 没有本机文件访问权限，它只能给你搜索命令，无法替你确认本机还有哪些残留。

定期轮换

轮换的完整流程是：新 Key 可用 → 切换配置 → 观察 → 吊销旧 Key。

建议周期

• 泄漏或怀疑泄漏：立即轮换，不等待周期。
• 团队和 CI：常见做法是 30–90 天轮换一次，或按公司安全政策执行。
• 个人本地使用：可以按 90 天或服务商建议周期轮换。
• 设备丢失、人员变动、工具卸载、服务商安全事件：立即轮换。
• 具体周期以服务商支持能力和你的安全要求为准。

安全轮换步骤

1. 新建一把权限相同或更小的 Key。
2. 先用 /v1/models 或服务商的验证方式确认新 Key 可用。
3. 更新所有配置、环境变量和 CI secrets，并做一次实际调用。
4. 计划内轮换时，可以短暂保留旧 Key 作为回滚窗口（例如 24–72 小时），观察日志确认没有遗漏。
5. 回滚窗口结束后吊销旧 Key。
6. 在密码管理器中记录轮换日期和旧 Key 已吊销。

泄漏时不要保留回滚窗口

如果 Key 已经泄漏，旧 Key 必须立即吊销。此时不要为了“方便回滚”继续保留它；回滚只能依赖新 Key。

如果服务商限制同时存在的 Key 数量，可能无法先建新再删旧。此时先按服务商文档规划短暂停机窗口，仍然不要长期保留已知泄漏的 Key。

常见错误

错误	为什么危险	正确做法
把 Key 写进会提交的文件	一次提交就可能永久留在 Git 历史	用环境变量、凭据文件或 secret 管理；提交前检查 diff
多个工具共用一个 Key	一个工具泄漏，全部工具都要重配；账单也分不清	按工具和环境分别建 Key
把“无限配额”当成无限安全	只取消 Key 级上限，账户余额仍可能被刷	设置账户和 Key 级预算，并监控用量
只删除文件，不吊销 Key	文件删了，Key 在服务端仍然有效	先吊销，再清理本地和远程残留
把 Key 发到聊天、issue 或截图	会被搜索、转发、缓存和备份	只发脱敏片段；需要共享时使用安全的 secret 共享方式
从不轮换、从不设过期	泄漏后可能长期无人发现	设置过期时间并按周期轮换

快速检查

创建 Key 时：

• [ ] 一把 Key 只对应一个工具或环境
• [ ] 已设置模型限制、额度上限和过期时间
• [ ] 服务支持时已配置 IP 白名单
• [ ] Key 已保存到密码管理器或系统凭据存储

发现泄漏时：

• [ ] 已立即吊销旧 Key
• [ ] 已创建并验证新 Key
• [ ] 已更新所有本地配置、环境变量和 CI secrets
• [ ] 已检查日志和账单
• [ ] 已清理 Git、日志、Shell 历史、CI secrets 和截图
• [ ] 已记录轮换日期和事件经过

接下来

• 准备 API Key
• 概念说明：API Key、分组与计费
• 常见问题