非交互模式 codex exec

codex exec（简写 codex e）不打开交互界面，执行完一轮任务就退出。运行过程输出到 stderr，最终回复单独输出到 stdout，方便重定向或接管道。

codex exec "总结仓库结构，列出风险最高的 5 个区域"
codex exec "根据最近 10 个提交生成发布说明" | tee release-notes.md

参数

codex exec 专有的参数：

与交互模式共用的参数：

codex exec 没有交互模式的 -a 和 --search；需要实时网页搜索时可以用 -c web_search="live"。

默认的沙箱与审批

• 审批：固定以 approval_policy = "never" 运行，需要批准的操作直接被拒绝，失败信息返回给模型。例外是有效配置中 approvals_reviewer = "auto_review"（如用了 --approve-for-me），此时沿用配置的审批策略，由自动审查代为裁决。
• 沙箱：依次取 --sandbox、配置中的 sandbox_mode。都没有时，config.toml 中有信任记录（trust_level）的项目默认 workspace-write，其他目录默认 read-only；未启用 Windows 沙箱的原生 Windows 一律为 read-only。官方文档笼统写作“默认只读”，在没有信任记录的 CI 环境中确实如此。
• Git 检查：默认必须在 Git 仓库内运行，否则报错退出；--skip-git-repo-check 或 --yolo 会跳过这一检查。
• 启动检查：规则文件加载失败，或 required = true 的 MCP 服务器初始化失败时，直接报错退出。

需要改文件用 --sandbox workspace-write；danger-full-access 只用于隔离的容器或虚拟机，详见 沙箱、审批与安全。

读取 stdin

stdin 须为 UTF-8 文本（带 BOM 的 UTF-16 也能识别），其他编码会报错退出。

# 指令 + 管道数据
npm test 2>&1 | codex exec "总结失败的测试，并给出最小的修复建议"

# stdin 就是完整指令
cat prompt.txt | codex exec -

输出与退出码

• stdout 被重定向或接管道时，只有最终回复写到 stdout，其余进度信息都在 stderr；直接在终端里运行时，最终回复和进度显示在一起。
• -o <FILE> 在本轮成功结束时把最终回复写入文件，stdout 照常输出；本轮失败或被中断时不写文件。
• 本轮失败、被中断，或者出现不再重试的错误时，以退出码 1 结束。

--json 事件流

加上 --json 后，stdout 每行是一个 JSON 对象，顶层的 type 字段表示事件类型：

条目的 item.type：

{"type":"thread.started","thread_id":"0199a213-81c0-7800-8aa1-bbab2a035a53"}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","command":"bash -lc ls","aggregated_output":"","exit_code":null,"status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_2","type":"agent_message","text":"仓库包含 docs、sdk 和 examples 三个目录。"}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"cache_write_input_tokens":0,"output_tokens":122,"reasoning_output_tokens":0}}

结构化输出

--output-schema 读取一个 JSON Schema 文件（必须是合法 JSON，否则直接退出），要求模型的最终回复符合这个结构；对 resume、fork 发送的后续指令同样有效。

{
  "type": "object",
  "properties": {
    "project_name": { "type": "string" },
    "programming_languages": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["project_name", "programming_languages"],
  "additionalProperties": false
}

codex exec "提取项目元数据" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

恢复与派生会话

多阶段流水线可以接着上一次的会话继续：

codex exec "检查这次改动有没有竞态条件"
codex exec resume --last "修复你刚才发现的竞态问题"

codex exec fork <SESSION_ID> [PROMPT] 先把指定会话复制成新会话，再发送 PROMPT；不带 PROMPT 时只做派生。SESSION_ID 也可以是会话名称，查找时不按当前目录过滤。附带图片、-o、--output-schema 或 --ephemeral 时必须提供 PROMPT。官方文档没有列出这个子命令；它支持 --worktree，而 codex exec resume 不支持。

codex exec review 等价于 codex review，见 代码审查。

在 CI 中使用

认证：默认复用本机已保存的登录。CI 中推荐用 API key，并只对这一条命令设置 CODEX_API_KEY：

CODEX_API_KEY=<api-key> codex exec --json "分析失败的测试"

• 不要把 OPENAI_API_KEY、CODEX_API_KEY 设为 job 级环境变量：同一个 job 里的构建脚本、测试和依赖的生命周期钩子都能读到它们。
• GitHub Actions 推荐用官方的 openai/codex-action：它安装 Codex 并通过 Responses API 代理减少密钥暴露，见 Codex Cloud、GitHub 与 IDE。
• 也可以用 workload identity federation 代替长期凭据；ChatGPT Enterprise 工作区还可以只给这条命令设置 Codex access token（CODEX_ACCESS_TOKEN，见 环境变量）；或在受信任的 runner 上以 ChatGPT 账号运行（需维护 ~/.codex/auth.json，它等同于密码，不要用于公开仓库）。

推荐参数：--json 保留机器可读的全过程，-o 单独拿到最终总结。

codex exec \
  --sandbox workspace-write \
  --json \
  -o codex-summary.md \
  "运行 npm test 复现失败，只做让测试通过的最小修改"

受控环境可再加 --ignore-user-config、--ignore-rules；在 Git 仓库外运行加 --skip-git-repo-check；无需事后恢复会话加 --ephemeral。