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.json（Linux/macOS）或%USERPROFILE%\.codex\auth.json（Windows）。一个最基础的配置长这样：

{"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 万 token，Key2 只有 10 万），顺序轮换会导致 Key1 被优先耗尽。我自己的做法是手动调整数组顺序，把配额大的放前面。如果你需要更精细的控制（比如按剩余配额加权轮换），就得写个外部脚本定期更新 auth.json——这个后面会讲。

四、安全存储：别把 Key 写死在代码里

很多新手会把 API Key 直接硬编码在 Python 脚本或 Shell 脚本里，然后不小心上传到 GitHub。我见过最离谱的一次，有人在公开仓库的 README 里贴了 Key，还加了句“大家随便用”。这种操作基本等于把银行卡密码贴在门上。

auth.json 本身已经比硬编码好很多，但还不够。我推荐的做法是：

文件权限锁死：chmod 600 ~/.codex/auth.json（Linux/macOS），Windows 下用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 codex，auth.json 的路径会变成/root/.codex/auth.json，而且权限可能被改掉。我见过有人用 root 跑 CodeX，结果 Key 被其他进程读取——虽然概率低，但没必要冒这个险。
备份 auth.json：我每周会把 auth.json 加密后备份到离线硬盘。Key 丢了可以重新生成，但如果你有几十个 Key 的轮换配置，重新配一遍能让你怀疑人生。

最后说一句：auth.json 的配置没有“标准答案”，完全取决于你的使用场景。如果你只是个人开发，单 Key + 文件权限就够了；如果是团队协作，建议用环境变量 + 密钥管理服务（比如 AWS Secrets Manager）。别为了“安全”搞得太复杂，也别为了“方便”把 Key 到处贴——找到那个平衡点，才是资深工程师该干的事。