跑非交互任务

基于官方 Codex non-interactive mode 教程，面向新手讲清 codex exec 适合什么自动化任务、权限怎么给、输出怎么验收。

Non-interactive mode 的核心是 codex exec：让 Codex 在脚本、CI、pre-merge check 或定时任务里运行，而不是打开交互式 TUI。

它不是“没有界面的聊天”。它解决的是自动化：给 Codex 一个明确任务，让它在预设 sandbox 和 approval settings 下执行，并把最终结果或事件流交给下游工具。

先理解：什么时候用 `codex exec`

适合用：

CI 失败后，总结失败原因或提出最小修复。
合并前检查 diff，输出风险报告。
定时生成 release notes、变更摘要、依赖风险摘要。
把日志、测试输出、扫描结果 pipe 给 Codex，让它生成结构化结论。
在固定权限下跑一次任务，并让脚本消费输出。

不适合用：

需要长时间来回沟通的新手学习场景。
还没定义清楚输入、输出和验收的任务。
需要用户实时判断很多文件改动的复杂重构。
没有 Git 仓库、没有隔离环境、也没有权限边界的目录。

新手第一步不要自动修复生产问题。先让 Codex 做只读总结，确认它能稳定识别失败原因，再逐步开放写权限。

怎么判断权限给多少

官方说明 codex exec 默认运行在 read-only sandbox。这个默认值是对新手有利的：它能先看代码和输出，但不能直接改文件。

如果任务只是总结、审查、分类、写报告，保持 read-only。

如果任务需要写文件，用 --sandbox workspace-write。这应该配合窄提示词，例如“只修改失败测试相关的最小文件，不做无关重构”。

danger-full-access 只适合受控环境，例如隔离 CI runner 或容器。不要在自己的主工作目录里随手给这个权限。

官方也保留了 --full-auto 兼容参数，但新脚本应使用明确的 sandbox 参数。

输出应该怎么设计

默认情况下，codex exec 会把进度输出到 stderr，把最终 agent message 输出到 stdout。这适合 shell 管道，因为下游只拿最终结论。

如果你要让程序消费全过程，用 --json。官方说明 JSONL 事件包括 thread.started、turn.started、turn.completed、turn.failed、item.* 和 error。这适合做平台集成、日志留存和失败诊断。

如果你只需要最终结构化结果，用 --output-schema。例如固定输出项目名、风险等级、受影响文件、建议动作。结构化输出比自然语言更适合 CI。

新手不要一开始就解析完整事件流。先固定最终输出字段，再决定是否需要 JSONL。

CI 认证怎么做

CI 里默认用 API key。官方推荐把 CODEX_API_KEY 放进 job 的 secret environment variable；它只支持 codex exec。

不要把 key 写进脚本、workflow 日志或仓库文件。

ChatGPT-managed auth 是高级路径。官方提醒要把 ~/.codex/auth.json 当密码处理，不要提交、粘贴到工单或聊天，也不要用于 public 或 open-source repository 的 CI。

对新手来说，API key 是默认答案。只有企业受控 runner 且明确需要 ChatGPT-managed Codex access 时，再考虑高级认证。

新手常见坑

任务太宽：让 Codex “修好项目”会导致大范围改动；应限定失败命令、目标目录和禁止事项。
权限太大：先 read-only，再 workspace-write，最后才考虑隔离环境里的 danger-full-access。
没有复跑测试：自动修复后必须运行同一组测试，否则无法证明修复有效。
没有结构化输出：CI 只能得到一段自然语言，后续不好判断成功或失败。
把认证文件放进 CI：公开仓库尤其危险。
忽略 Git 仓库要求：Codex 默认要求在 Git repo 中运行，用来降低破坏性改动风险。
随便用 --skip-git-repo-check：只有确认环境安全时才覆盖这个检查。

一个稳妥的自动修复流程

第一步，主 CI 失败后触发 follow-up job。不要在主 CI 里直接改代码。

第二步，checkout 失败的 commit，安装依赖，复现失败。

第三步，用 codex exec 和最小权限运行窄任务。提示词里写清楚只修导致测试失败的最小问题，不做重构。

第四步，复跑测试。测试不过就让 job 失败，并保留 Codex 输出。

第五步，只有测试通过时，才打开 PR 或生成 patch 供人审查。

这个流程的重点不是“全自动”，而是每一步都有可检查的边界。

怎么验收

只读任务的验收：Codex 能稳定输出失败原因、关键日志和下一步建议，不修改文件。

写入任务的验收：只改预期范围内的文件，diff 小，复跑测试通过。

结构化输出的验收：下游脚本能解析固定字段，并能在字段缺失时失败。

安全验收：CI 日志里没有 key、token、私有配置或完整认证文件。

流程验收：失败时不会静默吞掉错误，成功时能留下任务输入、输出、diff 和测试结果。