作者：Lei阅读 --

codex exec 能控制什么：一张实测参数表读懂 agent 的自动化控制面

基于本机 codex-cli 0.144.6 的 --help 实测，把 codex exec 全部参数整理成五个控制面：输入、执行者、行为配置、权限边界、输出与会话，并给出可直接复制的自动化配方。

CodexAgent自动化

判断一个 agent CLI 是不是认真为自动化设计的，不用读营销文档，看它的非交互入口暴露了哪些参数就够了。codex exec 的参数表，本质上是一张”把 agent 当成 Unix 进程来编排”的控制面清单——你能控制它读什么、谁来干、怎么干、干到什么程度、结果怎么拿。

事实来源，先说清楚

本文所有参数均来自本机实测：codex-cli 0.144.6，逐条运行 codex exec --help、codex exec resume --help、codex exec review --help 得到的输出，未做任何猜测补充。官方对非交互模式的定位见 Non-interactive mode 文档：让 Codex 跑在脚本和 CI 里，不打开交互式 TUI。不同版本参数可能增减，照抄前请先跑一遍你本机的 --help。

codex exec 的完整形态是：

codex exec [OPTIONS] [PROMPT]
codex exec [OPTIONS] <COMMAND> [ARGS]   # 子命令：resume / review

下面把 20 多个参数按”控制面”归组——这比按字母表列一遍有用得多，因为每个控制面对应你在自动化里要回答的一个问题。

主线：五个控制面

控制面回答的问题核心参数
输入agent 读什么？[PROMPT]、stdin、-i/--image、-C/--cd、--add-dir
执行者谁来干？-m/--model、--oss、--local-provider
行为配置按什么规则干？-c、-p/--profile、--enable/--disable、--strict-config
权限边界允许干到什么程度？-s/--sandbox 三档、两个 --dangerously-*
输出与状态结果怎么拿、状态怎么管？--json、-o、--output-schema、--ephemeral、resume

控制面一：输入——prompt 不只是一个字符串

codex exec 接收输入的方式比想象中丰富：

  • 位置参数 [PROMPT]：最普通的用法，codex exec "修复失败的测试"。
  • stdin 作为 prompt：不给参数（或显式给 -）时从 stdin 读指令。
  • stdin 追加：这是帮助文本里一个容易被忽略的细节——如果 stdin 是管道输入且同时提供了 prompt，stdin 会作为 <stdin> 块追加。也就是说 git diff | codex exec "总结这些变更" 里，diff 内容会结构化地拼进指令，而不是被丢弃。
  • -i, --image <FILE>...：给初始 prompt 附图。截图驱动的 bug 修复可以脚本化了。
  • -C, --cd <DIR>：指定 agent 的工作根目录，不用先 cd 再调。
  • --add-dir <DIR>：在主工作区之外追加可写目录——monorepo 里跨包改动的关键开关。
  • --skip-git-repo-check：默认 Codex 拒绝在 Git 仓库外运行（这是个安全默认值：没有版本控制就没有后悔药），此开关显式放行。

控制面二：执行者——云端模型不是唯一选项

  • -m, --model <MODEL>：指定模型。
  • --oss：切到开源 provider。
  • --local-provider <OSS_PROVIDER>：帮助文本明确列出两个取值——lmstudio 或 ollama。

这意味着同一条流水线脚本，可以在 CI 上用云端模型、在离线环境用本地 Ollama 模型跑，只差一个开关。

控制面三：行为配置——三层覆盖体系

配置控制是 codex exec 参数里层次最深的部分，实际是一个三层覆盖体系：

  1. 基础层：~/.codex/config.toml（用户配置）。
  2. profile 层：-p, --profile <名字> 把 $CODEX_HOME/<名字>.config.toml 叠在基础配置之上——比如为 CI、为代码评审各留一套预设。
  3. 单次覆盖层：-c, --config <key=value> 用点路径覆盖任意嵌套配置项，value 按 TOML 解析（解析失败则当字面字符串）。帮助文本给的示例：-c model="o3"、-c 'sandbox_permissions=["disk-full-read-access"]'、-c shell_environment_policy.inherit=all。

围绕这个体系还有四个开关：

  • --enable <FEATURE> / --disable <FEATURE>：可重复使用的 feature 开关，等价于 -c features.<name>=true/false 的语法糖。
  • --strict-config：配置文件里出现当前版本不认识的字段时直接报错——CI 里防”配置写错了但静默生效”的保险丝。
  • --ignore-user-config：完全不加载用户的 config.toml（认证仍走 CODEX_HOME）——保证流水线行为不被某台机器上的个人配置污染。
  • --ignore-rules：不加载用户和项目的 execpolicy .rules 文件。

对自动化来说，--ignore-user-config + 显式 -c 覆盖是”可复现执行”的正确姿势：环境里有什么不重要，命令行里写了什么才算数。

控制面四：权限边界——三档沙箱和两个”危险”开关

-s, --sandbox <SANDBOX_MODE> 只有三个取值，构成一个清晰的权限阶梯：

档位含义适用场景
read-only只读代码分析、评审、生成报告
workspace-write工作区可写改代码、修测试
danger-full-access全盘访问名字已经在警告你了

阶梯之外还有两个显式命名为 “dangerously” 的开关：

  • --dangerously-bypass-approvals-and-sandbox：跳过所有确认且不沙箱化执行。帮助文本原话是 EXTREMELY DANGEROUS. Intended solely for running in environments that are externally sandboxed——只该出现在容器等外部已隔离的环境里。
  • --dangerously-bypass-hook-trust：跳过 hook 的持久化信任检查直接运行已启用的 hooks，intended only for automation that already vets hook sources。

值得注意的设计选择：危险操作没有被藏进配置文件，而是用又长又丑、自带 “dangerously” 前缀的旗标暴露在命令行上。你在 CI 脚本里写下它的那一刻，代码评审者一眼就能看见。把危险显式化，是比把危险禁止化更诚实的安全设计——毕竟外部沙箱里全速运行本来就是合理需求。

控制面五：输出与状态——给机器读的三个出口

交互式 agent 的输出给人看，非交互 agent 的输出给下游程序看。codex exec 提供了三个机器友好的出口：

  • stdout/stderr 分流：按官方文档，运行过程的进度流向 stderr，stdout 只打印最终消息。所以 codex exec "给最近 10 个提交写 release notes" | tee notes.md 拿到的是干净结果，不掺进度日志。
  • --json：把事件以 JSONL 逐行打到 stdout——要做审计、观测、或实时解析 agent 每一步动作时用。
  • -o, --output-last-message <FILE>：把最终消息写进文件，和管道输出解耦。
  • --output-schema <FILE>：给一个 JSON Schema 文件，约束最终响应的形状。这是整张参数表里对工程集成最有价值的一个——它把 agent 从”输出一段自然语言”变成”输出一个可校验的结构化对象”，下游才敢直接 jq 取字段。

状态管理则是一对互补开关：

  • --ephemeral：不落盘任何会话文件——一次性任务、或合规上不允许留痕的环境。
  • codex exec resume：反方向——恢复之前的会话继续执行。支持按 UUID 或线程名定位，--last 直接取最近一次（默认按当前目录过滤，--all 取消过滤），还能带上新 prompt 和新图片：
codex exec "第一步：分析这个模块的测试覆盖"
codex exec resume --last "第二步：给覆盖率最低的三个函数补测试"

多步流水线不再需要把上一步的全部上下文塞进下一步的 prompt。

内置子命令：review 是一条现成的流水线

codex exec review 说明 OpenAI 自己也把”代码评审”当作 exec 最高频的自动化场景，直接内置了三种 diff 选择方式：

  • --uncommitted：评审 staged + unstaged + untracked 的全部变更（提交前自查）；
  • --base <BRANCH>：对指定基线分支评审（PR 场景）；
  • --commit <SHA>:评审单个提交引入的变更；
  • 外加 --title <TITLE> 给评审摘要一个标题，[PROMPT] 位置参数传自定义评审指令。

三个可直接复制的配方

1. CI 里的只读评审（严格配置 + 干净环境）：

codex exec review --base main \
  --ignore-user-config --strict-config \
  -c model="o3" \
  -o review-result.md

2. 结构化产出接下游程序：

codex exec "扫描仓库,列出所有缺少错误处理的公共 API" \
  -s read-only \
  --output-schema api-report.schema.json \
  -o report.json
cat report.json | jq '.findings[].location'

3. 管道即上下文：

git log --oneline -20 | codex exec "根据这些提交写一段中文 changelog" > CHANGELOG.snippet.md

边界与注意

  • 参数会变。本文对应 0.144.6；不同版本的旗标集合有差异，脚本里依赖某个旗标前先在目标版本上验证。
  • exec 不是万能替代。需要人在环上做多轮澄清的探索式任务，交互式 codex 仍是正确工具；exec 的甜区是输入明确、产出可校验的任务。
  • CI 凭据要小心。官方文档明确警告：不要在会检出并运行仓库代码的 job 里把 OPENAI_API_KEY / CODEX_API_KEY 设为 job 级环境变量——构建脚本、测试、依赖生命周期钩子都读得到它。
  • 沙箱档位从最低开始给。评审类任务没有理由给 workspace-write；danger-full-access 和两个 --dangerously-* 只属于外部已隔离的执行环境。

收束：一个可复用的判断模型

回到开头的断言。评估任何 agent CLI 的自动化成熟度，可以拿这五个控制面当 checklist：输入能否管道化？执行者能否替换？配置能否单次覆盖且可复现？权限能否显式分级？输出能否结构化校验？ codex exec 在五项上都给出了具体答案——尤其是 --output-schema 和 stdout/stderr 分流这两个细节，说明它的设计者真的用它写过流水线。下次你评估别的 agent CLI（或者自己设计一个），这五问可以直接搬走。

参考来源