---
title: "跑非交互任务"
description: "基于官方 non-interactive mode，讲清 codex exec 适合什么自动化任务、权限怎么给、输出怎么验收。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

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

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

<Cards>
  <Card title="Non-interactive mode" href="https://developers.openai.com/codex/noninteractive">
    查看 `codex exec` 的官方自动化说明。
  </Card>
  <Card title="CLI options" href="/docs/codex/official/01-products/27-cli-args">
    需要脚本化运行时，先确认 flags 和 `--config` 覆盖方式。
  </Card>
  <Card title="Approvals and security" href="/docs/codex/official/02-config-security/07-approval-security">
    自动化任务必须先确定 sandbox、approval 和 Git 边界。
  </Card>
</Cards>

## 它适合什么

```mermaid
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 和测试结果。

## 官方资料

- [Non-interactive mode](https://developers.openai.com/codex/noninteractive)
- [Codex CLI options](https://developers.openai.com/codex/cli/options)
- [Agent approvals and security](https://developers.openai.com/codex/agent-approvals-security)
