014、auth.json 配置详解：API Key 生成、多 Key 轮换与安全存储

014、auth.json 配置详解API Key 生成、多 Key 轮换与安全存储上周五晚上我正用 CodeX 跑一个需要连续调用 200 次 API 的批量翻译任务结果跑到第 37 次突然报错——401 Unauthorized。我第一反应是 Key 过期了赶紧去控制台看了一眼发现 Key 明明还有 15 天有效期。后来排查了半天才发现是 auth.json 里某个 Key 的格式写错了多了一个换行符。这种坑踩过一次就再也不想踩第二次。今天这篇笔记我把 auth.json 从生成到配置、从单 Key 到多 Key 轮换、从明文存储到安全加固所有踩过的坑和验证过的方案都写清楚。一、auth.json 到底长什么样CodeX 的认证文件默认放在~/.codex/auth.jsonLinux/macOS或%USERPROFILE%\.codex\auth.jsonWindows。一个最基础的配置长这样{api_key:sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}注意这里有个容易翻车的细节Key 必须用双引号包裹不能有尾随逗号不能有多余空格。我见过有人从邮件里复制 Key 时带上了换行符结果 JSON 解析直接报错。如果你用cat或记事本打开文件建议用hexdump或od -c看一眼末尾有没有\n——别问我为什么知道要检查这个。二、API Key 生成别在控制台乱点大多数 AI 服务商比如 OpenAI、Anthropic的 API Key 生成页面都会让你选“权限范围”。这里有个常见误区很多人图省事直接点“Full Access”。但如果你只是用 CodeX 做代码补全或翻译完全没必要给 Key 开写权限。我习惯的做法是在服务商控制台创建一个专用子账号或者叫“服务账号”只赋予inference或completion权限生成 Key 后立刻复制到本地不要存浏览器浏览器缓存可能被插件窃取生成后的 Key 通常长这样sk-proj-xxxxxxxxxxxx。注意有些服务商会把 Key 分成api_key和api_secret两部分但 CodeX 的 auth.json 只认api_key字段。如果你遇到的是双 Key 模式需要先拼接——具体拼接规则看服务商文档别自己瞎猜。三、多 Key 轮换从手动切到自动切当单个 Key 的调用频率被限制或者你想分摊成本时多 Key 轮换就派上用场了。CodeX 原生支持在 auth.json 里配置多个 Key{api_keys:[sk-key1-xxxxxxxx,sk-key2-xxxxxxxx,sk-key3-xxxxxxxx]}注意字段名变成了api_keys复数值是数组。CodeX 会按顺序依次使用这些 Key当某个 Key 返回 429限流或 401无效时自动切换到下一个。但这里有个坑默认的轮换策略是“顺序轮换”不是“随机轮换”。如果你三个 Key 的配额不一样比如 Key1 有 100 万 tokenKey2 只有 10 万顺序轮换会导致 Key1 被优先耗尽。我自己的做法是手动调整数组顺序把配额大的放前面。如果你需要更精细的控制比如按剩余配额加权轮换就得写个外部脚本定期更新 auth.json——这个后面会讲。四、安全存储别把 Key 写死在代码里很多新手会把 API Key 直接硬编码在 Python 脚本或 Shell 脚本里然后不小心上传到 GitHub。我见过最离谱的一次有人在公开仓库的 README 里贴了 Key还加了句“大家随便用”。这种操作基本等于把银行卡密码贴在门上。auth.json 本身已经比硬编码好很多但还不够。我推荐的做法是文件权限锁死chmod 600 ~/.codex/auth.jsonLinux/macOSWindows 下用icacls设置只允许当前用户读取环境变量覆盖CodeX 支持通过CODEX_API_KEY环境变量临时覆盖 auth.json 里的 Key。我通常在 CI/CD 流水线里用环境变量本地开发用 auth.json加密存储如果你真的不放心可以用gpg或openssl加密 auth.json然后在 CodeX 启动前解密。不过这个方案有点重我一般只在共享服务器上这么干另外绝对不要把 auth.json 放在项目目录里。我见过有人把 auth.json 和代码一起提交到 Git 仓库然后 .gitignore 里忘了加——后果就是 Key 被爬虫扫到一夜之间被刷掉几千美元。五、实战多 Key 轮换 自动故障转移最近我在做一个需要高可用性的服务要求即使某个 Key 被限流系统也不能中断。我的 auth.json 配置如下{api_keys:[sk-proj-key1-xxxx,sk-proj-key2-xxxx,sk-proj-key3-xxxx],retry_on_failure:true,max_retries:3,key_rotation_strategy:sequential}retry_on_failure和max_retries是 CodeX 的隐藏参数文档里没写我是翻源码发现的。当某个 Key 返回错误时CodeX 会重试最多 3 次如果还失败就切换到下一个 Key。但这里有个性能问题每次切换 Key 都会重新建立连接。如果你的网络延迟高切换成本可能比调用本身还大。我的优化方案是在 auth.json 里只放 2-3 个 Key然后用一个外部监控脚本定期检查每个 Key 的剩余配额当某个 Key 的配额低于 10% 时自动替换成新的 Key。这样既保证了轮换的实时性又避免了频繁切换。六、个人经验这些坑我替你踩过了Key 过期检测不要等到 401 报错才换 Key。我写了个 cron 任务每天凌晨检查所有 Key 的过期时间提前 3 天发邮件提醒。服务商的 Key 过期策略各不相同有的过期后还有 7 天宽限期有的直接失效——别赌。多 Key 的成本分摊如果你用多个 Key 分别对应不同项目建议在 auth.json 里用注释标注JSON 不支持注释但你可以用_comment字段。我习惯这样写{_comment:Key1 用于生产环境Key2 用于测试,api_keys:[sk-prod-xxx,sk-test-xxx]}不要用 root 权限运行 CodeX如果你用sudo codexauth.json 的路径会变成/root/.codex/auth.json而且权限可能被改掉。我见过有人用 root 跑 CodeX结果 Key 被其他进程读取——虽然概率低但没必要冒这个险。备份 auth.json我每周会把 auth.json 加密后备份到离线硬盘。Key 丢了可以重新生成但如果你有几十个 Key 的轮换配置重新配一遍能让你怀疑人生。最后说一句auth.json 的配置没有“标准答案”完全取决于你的使用场景。如果你只是个人开发单 Key 文件权限就够了如果是团队协作建议用环境变量 密钥管理服务比如 AWS Secrets Manager。别为了“安全”搞得太复杂也别为了“方便”把 Key 到处贴——找到那个平衡点才是资深工程师该干的事。