# codex exec 非交互运行手册

核验日期：2026-07-16

## 最小只读运行

```bash
codex exec --ephemeral --sandbox read-only \
  "总结仓库结构、验证命令和三个需要人工核实的风险区域；不要修改文件"
```

`--ephemeral` 不持久化本次 session rollout。只读是非交互审计的合理起点。

## 允许工作区修改

```bash
codex exec --sandbox workspace-write --ask-for-approval never \
  "只修复已存在测试覆盖的单一问题，运行相关测试并报告未验证项"
```

`never` 不会移除沙箱。越界操作可能失败，脚本必须把非零退出视为失败。

## 保存最终消息

```bash
codex exec --sandbox read-only \
  -o ./artifacts/codex-final.md \
  "审查当前分支差异，只报告有文件证据的问题"
```

`-o`/`--output-last-message` 写入最终消息，同时 stdout 仍会输出结果。

## JSONL 事件流

```bash
codex exec --json --sandbox read-only \
  "列出仓库验证入口" > ./artifacts/codex-events.jsonl
```

逐行解析。至少处理：

- `thread.started`
- `turn.started`
- `item.started` / `item.completed`
- `turn.completed`
- `turn.failed`
- `error`

不要把 JSONL 当作单个 JSON 文档，也不要只寻找最后一条 agent message 判断成功。

## JSON Schema 输出

`schema.json`：

```json
{
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "evidencePaths": {
      "type": "array",
      "items": { "type": "string" }
    },
    "needsVerification": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["summary", "evidencePaths", "needsVerification"],
  "additionalProperties": false
}
```

运行：

```bash
codex exec --ephemeral --sandbox read-only \
  --output-schema ./schema.json \
  -o ./artifacts/result.json \
  "审计当前仓库。所有确定性结论都给出仓库内证据路径。"
```

Schema 只保证结构。脚本仍要打开证据路径并验证事实。

## 恢复会话

```bash
codex exec resume --last "根据上一轮发现，只修复已经确认的 P1 问题"
```

恢复前再次确认工作目录、commit 和工作树。会话上下文可以保留，外部状态不会冻结。

## CI 安全边界

- 不把 `OPENAI_API_KEY` 或 `CODEX_API_KEY` 设为会运行不可信仓库代码的 job 级环境变量。
- GitHub Actions 优先使用官方 `openai/codex-action`。
- 生成 patch 的 job 使用只读仓库权限。
- 写仓库的后续 job 不接收 OpenAI API key。
- 不使用已弃用的 `--full-auto` 设计新脚本；显式选择 sandbox。

## 成功判定

- [ ] 进程退出码为 0。
- [ ] JSONL 中没有 `turn.failed` 或 `error`。
- [ ] 输出文件存在且能被对应 parser 读取。
- [ ] 实际 diff 在允许范围内。
- [ ] 仓库测试命令退出码为 0。
- [ ] 最终报告列出未验证项。

官方来源：

- https://learn.chatgpt.com/docs/non-interactive-mode
- https://learn.chatgpt.com/docs/agent-approvals-security