在 CI/CD 中维护认证
基于官方 Codex CI/CD 认证教程，面向新手讲清 API key 默认路线、ChatGPT-managed auth 高级路线和 auth.json 的安全边界。
Codex 自动化认证的默认答案是 API key。官方 CI/CD auth 文档说得很明确：只有当你确实需要让 workflow 以你的 Codex account 身份运行时，才使用 ChatGPT-managed auth 的高级方案。
新手不要从 auth.json 开始。那是可信私有 runner 上的高级维护方案，不适合公开仓库，也不适合随手复制到 GitHub-hosted runner。
先理解：两条认证路线
API key 路线：把 CODEX_API_KEY 或 Action 需要的 OpenAI key 放进 CI secret，由 job 注入。它更容易发放、轮换和撤销，是大多数自动化的默认选择。
ChatGPT-managed auth 路线：先在可信机器上 codex login 生成 auth.json，把它放到可信 runner，让 Codex 在运行中自动 refresh，并把更新后的 auth.json 留给下一次 run。
第二条路线的核心不是“自己调用 refresh API”。官方推荐的是运行 Codex，让 Codex 使用内置 refresh flow，然后持久化刷新后的文件。
怎么判断该用哪条
用 API key：
- 普通 CI/CD。
- 公开仓库或开源仓库。
- GitHub Actions、GitLab CI、Jenkins 等常规自动化。
- 你只需要跑
codex exec或 Codex GitHub Action。 - 你希望凭据容易轮换。
考虑 ChatGPT-managed auth：
- 你必须以 Codex account 身份运行，而不是 API key。
- runner 是可信私有基础设施。
- 远程 runner 不能运行 browser login。
- 你能在 runs 之间保存刷新后的
auth.json。 - 同一个
auth.json不会被并发 job 或多台机器同时使用。
如果这些条件有一个不满足，就不要用 auth.json 方案。
auth.json 为什么危险
官方要求把 ~/.codex/auth.json 当密码处理，因为它包含 access tokens。
不要 commit，不要贴到 ticket，不要发到 chat，不要放进 public artifact，不要写进日志，不要用于 public 或 open-source repository。
它也不适合多机共享。一个 runner 或一个串行 workflow stream 使用一份独立 copy。并发使用会导致 token refresh 互相覆盖，最终出现 401 或无法刷新。
可信 runner 的正确心智
Self-hosted runner 最适合这个高级方案，因为它能在 jobs 之间保留 CODEX_HOME。第一次缺文件时 seed auth.json，后续不要每次用原始 secret 覆盖它。
Ephemeral runner 也能做，但必须实现 restore、run、persist 的闭环：每次 job 从安全存储恢复当前 auth.json，运行 Codex，再把本次可能刷新过的文件写回安全存储。
关键点是写回“刷新后的文件”，不是写回原始 seed。
新手常见坑
- 在公开仓库里用 ChatGPT-managed auth：官方明确不建议。
- 把
auth.json当普通配置文件：它是密码级凭据。 - 每次 run 都覆盖原文件：会丢掉 Codex 刷新的 token。
- 多个并发 job 共享同一份
auth.json：refresh 状态会互相踩。 - 以为需要自己调用 OAuth refresh：官方推荐让 Codex 自己刷新。
- 忘记重新 seed：refresh token 被 revoke、expired 或被别的机器旋转后，需要重新登录生成新文件。
- 把完整
auth.json上传 artifact：这等于泄露账号凭据。
出问题时怎么判断
如果开始出现 401，先判断 runner 是否能读取当前 auth.json，以及它是否被旧 secret 覆盖。
再看是否有并发 job 使用同一份文件。
再看 secure storage 的 restore / persist 是否成功，尤其是 persist 步骤是否写回了本次运行后的文件。
如果仍然失败，不要手写 refresh 请求。回到可信机器重新 codex login，生成新的 auth.json，重新 seed runner。
怎么验收
API key 路线的验收：key 只存在 CI secret 中，日志没有打印，job 能运行 codex exec，失败时能轮换 key。
ChatGPT-managed auth 路线的验收：runner 是可信私有环境；auth.json 权限收紧；没有进入仓库、日志和 artifact；每次 run 后能保留刷新后的文件。
并发验收：同一份 auth.json 不会被两个 job 同时使用。
恢复验收：删除 runner 上的 cached file 后，可以从安全存储恢复；恢复后运行 Codex；运行后把更新文件写回。
事故验收：一旦怀疑泄露，立即重新登录、替换 secret、撤销旧凭据。