跑非交互任务

📖 本篇术语速查表

英文 / 缩写	中文	一句话解释
非交互	non-interactive	不进交互、一次跑完的任务方式。
CI 认证边界	CI auth scope	自动化环境里的认证和权限边界。
自动修复	auto-fix	让 Codex 自动修复并验证的流程。

不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你设计一个稳妥的非交互/自动化 Codex 任务。

你是 Codex 非交互任务顾问，帮我设计一个稳妥的非交互 / 自动化任务，做到不需人盯也不出事。

【角色】
你熟悉非交互任务适合什么、权限怎么给、输出怎么设计、CI 认证边界、稳妥的自动修复流程。

【输入】
- 我要自动化的任务：___
- 运行环境（本地脚本 / CI）：___
- 是只读检查还是会写改动：___
- 输出要给谁 / 怎么用：___

【工作流程】
1. 判断任务适不适合非交互（不需越界才适合）
2. 按最小必要给权限和认证
3. 设计可解析、可判断成败的输出
4. 若自动修复，给稳妥流程和兜底

【输出规范】
▌一、是否适合非交互
▌二、权限与认证配置
▌三、输出设计
▌四、自动修复流程 + 兜底

【硬约束】
- 非交互任务必须设计成不需越界审批
- 自动修复要有验证和失败兜底，不盲改
- 凭据走 secret，不明文
- 写改动的自动化任务限定范围
- 不确定的机制标注需查官方文档

Non-interactive mode 的入口是 codex exec：给 Codex 一个明确任务，让它在预设权限里跑完，并把结果交给脚本、CI 或下游系统。

非交互不是“无人值守万能修复”。输入、权限、输出和验收都不清楚时，先用交互模式把任务收窄。

Non-interactive mode

查看 codex exec 的官方自动化说明。

CLI options

需要脚本化运行时，先确认 flags 和 --config 覆盖方式。

Approvals and security

自动化任务必须先确定 sandbox、approval 和 Git 边界。

它适合什么

flowchart LR
    Input["明确输入"] --> Exec["codex exec"]
    Exec --> Policy["sandbox / approval"]
    Policy --> Run["一次性执行"]
    Run --> Output["stdout / JSONL / schema"]
    Output --> Downstream["CI / 脚本 / PR"]

适合：

CI 失败后总结原因。
合并前审查 diff 风险。
定时生成 release notes。
把日志、测试输出、扫描结果转成报告。
在固定权限下运行一次小修复，并由脚本消费结果。

不适合：

新手学习和长轮次沟通。
目标还没有拆清楚的重构。
需要人实时判断大量文件改动的任务。
没有 Git、没有隔离环境、没有权限边界的目录。

新脚本的默认起点应是只读总结。只有当总结稳定、验证清楚、写入范围可控时，再开放写权限。

权限怎么给

官方文档把 codex exec 放在自动化场景里使用。实际配置时按任务风险分层：

只读审查：保持 read-only sandbox。
小范围修复：使用 workspace-write，并在提示词里限制文件范围。
全自动 runner：只放在隔离 CI、容器或临时工作区里。
高危目录：不要用 danger-full-access 直接跑主工作目录。

提示词要写清三件事：

只允许做什么。
明确不能做什么。
完成后必须跑什么验证。

不要靠“请小心”控制风险。自动化依赖的是权限和验收，不是语气。

输出怎么设计

默认输出适合人读：进度通常走 stderr，最终 agent message 走 stdout。这让 shell 管道可以只消费最终结论。

需要程序消费全过程时，用 --json。官方说明 JSONL 事件会覆盖 thread、turn、item、error 等运行过程，适合日志留存、平台集成和失败诊断。

只需要最终结构化结果时，用 --output-schema。例如固定输出：

项目名。
失败原因。
风险等级。
受影响文件。
建议动作。

结构化输出比自然语言更适合 CI。脚本应在字段缺失、JSON 解析失败或风险等级缺失时直接失败。

CI 认证边界

CI 里优先使用受保护的 secret 环境变量，不把 key、token 或认证文件写进仓库、日志、artifact、issue comment。

auth.json、API key、access token 都按密码处理。公开仓库和第三方 runner 里不要复制本机登录态。需要企业级自动化时，先确认 runner、仓库权限、日志脱敏和 secret rotation，而不是先把本机配置搬过去。

稳妥自动修复流程

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

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

第三步，用 codex exec 跑窄任务，提示词限制目标文件、禁止重构、要求复跑同一测试。

第四步，测试不过就失败并保留 Codex 输出；测试通过才生成 patch、PR 或人工审查材料。

第五步，记录输入、输出、diff、测试结果和运行权限，方便追溯。

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

常见坑

让 Codex “修好项目”，没有失败命令和范围。
一开始就给写权限或全权限。
CI 只看自然语言输出，无法程序化判断成功失败。
自动修复后不复跑测试。
把本机认证文件带进 CI。
忽略 Git 仓库检查或随手跳过安全检查。

验收清单

只读任务没有文件 diff。
写入任务只改预期范围。
结构化输出能被下游解析。
失败时 job 明确失败，不静默吞错。
日志里没有 key、token、私有路径或完整认证文件。
成功时留下任务输入、最终输出、diff 和测试结果。