Open Interpreter 非交互模式完全指南：用 `interpreter exec` 在脚本、CI 与流水线中驱动编码 Agent

2026-09-06 19:18:39作者：翟江哲Frasier

interpreter exec 是 Open Interpreter 面向自动化场景提供的非交互执行入口：把一次完整的编码任务（分析 diff、修 bug、跑代码审查）以"单条命令 + 单次运行到结束"的方式交付，无需打开全屏 TUI。本文以仓库文档 docs/zh/exec.md 为主体骨架，结合 codex-rs/exec 的源码实现，讲解 exec 的输入方式、全部常用标志、JSON 事件协议、结构化输出、会话恢复、代码审查子命令，以及在 CI 中的落地模式。读完你可以在 shell 脚本、GitHub Actions 类流水线和本地自动化工具里稳定地驱动一个编码 Agent。

说明：本文命令按仓库中文文档统一写作 interpreter exec（如 docs/zh/cli-reference.md 所示），其底层实现位于本仓库 codex-rs/exec crate，对应命令的内部 usage 字符串仍保留 codex exec（见 exec 的 CLI 定义），两者指向同一套 exec 子命令。

一、什么是非交互模式

当你希望某个任务在不启动全屏 TUI 的情况下完整执行时，使用 interpreter exec：

interpreter exec "summarize the changes in the last commit"

这条命令会把"总结最近一次提交的变更"作为一个完整的回合交给 Agent 处理，进程在任务结束后自行退出。可读的最终答案会打印到 stdout；进度和诊断信息使用 stderr，除非你选择 JSON 输出。

这种 stdout/stderr 分离不是约定，而是被源码强制的契约。在 codex-rs/exec/src/lib.rs 顶部注释写得很明确：

在默认输出模式下，写入 stdout 的唯一内容必须是最终消息；在 --json 模式下，stdout 必须是合法的 JSONL（每行一个事件）；其余所有输出必须写到 stderr。

实现层面对应的约束是 crate 级 #![deny(clippy::print_stdout)]，并在 run_main 的启动逻辑中按是否开启 --json 选择两种事件处理器：默认的 EventProcessorWithHumanOutput（人类可读输出）与 EventProcessorWithJsonOutput（JSONL 输出）。诊断日志则交给 tracing 层写往 stderr，默认过滤级别为 error，可通过 RUST_LOG 环境变量调整（见 exec 的 stderr 过滤逻辑）。

这样的设计让 exec 天然适合被程序捕获：脚本只需要读取 stdout 拿到最终答案，把 stderr 当作旁路诊断。

二、prompt 的五种输入形态

interpreter exec 接收的提示文本来自多个来源，且支持组合。

1. 作为位置参数直接传入

interpreter exec "find one bug in src/parser.rs"

这是最直接的用法，适合命令较短、无需转义换行的场景。

2. 从 stdin 读取提示（`-` 哨兵）

cat task.md | interpreter exec -

显式使用 - 时，提示内容完全从 stdin 读取。对应源码中的 StdinPromptBehavior::Forced 分支，即"无条件把 stdin 当作 prompt"（见 codex-rs/exec/src/lib.rs）。

3. 把上下文通过管道并入提示

git diff | interpreter exec "explain this diff and flag risky changes"

当既提供了位置参数 prompt、stdin 又处于管道输入状态时，stdin 不会被当作独立的 prompt 覆盖，而是作为追加的上下文块合并进提示。CLI 参数注释把这一点写得很清楚：stdin 管道内容会作为 <stdin> 代码块追加（见 cli.rs 的 prompt 字段注释）。这是"给 Agent 喂 diff / 日志 / 报表"最常用的姿势，相当于把文本上下文交给模型后再下达指令。

4. 为第一个提示附加图片

interpreter exec -i screenshot.png "describe the UI problem"

-i/--image 是一个全局共享参数，支持一次传多张、并以逗号分隔（见共享 CLI 参数 SharedCliOptions）。图片会先于文本被组装进首条用户输入：源码中将图片路径映射为 UserInput::LocalImage，随后再 push 文本输入（见首条消息的组装逻辑）。

5. 恢复会话时继续追加输入

恢复（resume）子命令同样接受 prompt 与 -i 图片，见下文"恢复 Exec 工作"一节。

三、常用标志一览

以下是文档给出的常用标志总表（docs/zh/exec.md）：

标志	用途
`--json`	输出换行分隔的 JSON 事件。
`--output-schema <file>`	要求最终答案符合 JSON Schema。
`--output-last-message, -o <file>`	将最终的助手消息写入文件。
`--color always\|never\|auto`	控制 ANSI 颜色。
`--sandbox <mode>`	覆盖沙箱模式。
`--ask-for-approval <mode>`	覆盖批准策略。
`--profile <name>`	使用指定的配置文件。
`--ephemeral`	不持久化会话记录。
`--skip-git-repo-check`	允许在非 Git 仓库中运行。
`--ignore-user-config`	跳过本次运行的用户配置。
`--ignore-rules`	跳过 execpolicy 规则。
`--verify`	在退出前额外运行一次完成检查。
`--timeout <seconds>`	在运行期间发送剩余时间提醒。

逐个拆解其底层行为

结合 exec 的 clap 参数定义，这些标志大多是 global 全局参数，可放在 prompt 前后任意位置：

--json：把事件处理器切换为 JSONL 输出。该参数还有一个历史别名 --experimental-json（见 cli.rs），自动化代码中两种写法都兼容。
--output-schema <file>：指向一个 JSON Schema 文件路径，运行时解析后作为 output_schema 字段随 turn/start 请求一并发送，约束模型的最终响应结构。读取逻辑在 load_output_schema。
--output-last-message, -o <file>：最终助手消息会被写入指定文件。该文件句柄会注入两种事件处理器（human / JSONL），便于脚本在主流程之外稳定取到最终答复，不受 stdout/stderr 重定向影响。
--color：接受 always / never / auto 三值，枚举定义见 Color。auto（默认）会检测 stdout/stderr 各自是否接终端来决定是否输出 ANSI 颜色（见颜色判定逻辑）。
--sandbox <mode>：覆盖配置文件中的沙箱策略，例如 CI 里收敛为 read-only（见 SharedCliOptions 的 sandbox_mode）。
--ask-for-approval <mode>：覆盖批准策略。特别地，headless 模式默认会强制为"永不询问"（AskForApproval::Never），只在自动审查评审员（AutoReview）场景重建覆盖（见 overrides 组装）。
--profile <name>：把 $CODEX_HOME/<name>.config.toml 作为一层配置叠加到基础用户配置之上，实现不同任务（如 code review 与日常开发）使用不同参数集。
--ephemeral：本次会话不落盘，不会在会话存储中留下记录。
--skip-git-repo-check：默认情况下，若不在 Git 仓库内运行，exec 会直接报错退出（"Not inside a trusted directory and --skip-git-repo-check was not specified"，见 lib.rs 的仓库检查）。--dangerously-bypass-approvals-and-sandbox（别名 --yolo）开启时也会跳过该检查，因为它假定外部环境已自行沙箱化。
--ignore-user-config：跳过 $CODEX_HOME/config.toml 的加载，但认证信息仍从 CODEX_HOME 读取（见 cli.rs）。
--ignore-rules：不加载用户级与项目级的 execpolicy .rules 文件，适用于无需规则约束的纯受信任务。
--verify：在正常回合结束后再额外跑一次"完成检查"回合，用于长任务结束时核对结果是否达标。
--timeout <seconds>：为超长运行设置倒计时，期间 Agent 会周期性地收到"剩余时间"提醒，从而主动收敛到可在时限内交付的方案。

四、JSON 事件：把运行过程变成可消费的数据流

自动化场景请使用 --json：

interpreter exec --json "list the files this task would touch"

每一行都是一个 JSON 事件，表示进度、工具调用、文件更改、推理摘要或最终消息。由于 stdout 只承载 JSONL，配合 jq、流式解析器或按行读取即可在外部管道中重建整个执行过程。

事件协议类型

顶层事件是一个带 type 判别字段的枚举（见 exec_events.rs 的 ThreadEvent），当前实现包含：

type	含义
`thread.started`	新线程启动，携带 `thread_id`——该 ID 可用来在之后 `resume` 恢复这条线程。
`turn.started`	向模型发送新 prompt 后开启一个回合。
`turn.completed`	回合完成，通常紧跟助手最终回复，事件内含 token `usage`。
`turn.failed`	回合以错误结束，携带 `error` 信息。
`item.started` / `item.updated` / `item.completed`	线程条目（item）的生命周期事件。
`error`	事件流层面不可恢复的致命错误。

其中 turn.completed 携带的 usage 统计了 input_tokens、cached_input_tokens、cache_write_input_tokens、output_tokens 与 reasoning_output_tokens 等明细（见 Usage 结构），可用于成本核算与额度监控。

线程条目（item）通过内层 type 继续细分（ThreadItemDetails）：agent_message（自然语言答复，或结构化输出模式下的 JSON 字符串）、reasoning（推理摘要）、command_execution（Agent 发起的命令执行及其退出码）、file_change（补丁应用结果）、以及 MCP 工具调用等。

消费示例

interpreter exec --json "list the files this task would touch" > events.jsonl

# 仅查看最终助手消息
jq 'select(.type == "agent_message") | .item.text' events.jsonl

# 查看回合的 token 用量
jq 'select(.type == "turn.completed") | .usage' events.jsonl

五、结构化输出：约束最终答案必须符合 JSON Schema

配合 --output-schema 使用模式文件，可以让 Agent 的最终输出直接变成程序可解析的结构化数据。先用一个 schema 文件描述期望的字段：

{
  "type": "object",
  "properties": {
    "risk": { "type": "string" },
    "recommended_fix": { "type": "string" }
  },
  "required": ["risk", "recommended_fix"]
}

interpreter exec --output-schema schema.json \
  "inspect the current diff and return the highest risk"

开启结构化输出后，schema 会被封装进首回合请求（TurnStartParams.output_schema，见 lib.rs 的回合启动），模型的最终消息会以符合该 schema 的 JSON 字符串形式产出（agent_message 条目在结构化输出模式下承载 JSON，见 exec_events.rs 的注释说明）。

由于是纯 JSON Schema 约束而非代码层强校验，建议 schema 中的 required 字段设置完整、类型声明严格，并在下游使用 jq 或反序列化器做容错解析。若还需要把最终消息落盘供后续步骤读取，可与 -o/--output-last-message 组合使用。

六、恢复 Exec 工作：让长任务可以被续跑

非交互会话是持久化的，如果任务超时、中途中断，或你想让 Agent 在一个已理清上下文的会话里继续干活，可以用 resume 子命令（源码层面它经 thread/list + thread/resume 完成，见 lib.rs 的 resume 流程）。

继续最近的非交互会话：

interpreter exec resume --last "now apply the plan"

或恢复指定的会话 ID：

interpreter exec resume <SESSION_ID> "continue"

两个要点：

会话 ID 既可以是 UUID，也可以是线程名，UUID 优先级更高；省略 ID 时配合 --last 自动选择最近记录的会话（见 ResumeArgs 定义）。
--last 与位置参数存在特殊语义：当使用 --last 且没有显式 prompt 时，位置参数会被重新解释为 prompt 而不是会话 ID，因此 exec resume --last "now apply the plan" 中最后的字符串是下一步指令（该重解释逻辑在 cli.rs 的 From 实现中完成）。

添加 --all 可搜索当前工作目录之外的会话。默认情况下会话搜索会按当前工作目录（cwd）过滤，跨目录续跑旧任务时必须加 --all。

七、来自 Exec 的审查：无 TUI 的自动代码审查

在不打开 TUI 的情况下运行代码审查，是 exec 子命令中与 resume 并列的另一个一等公民操作：

interpreter exec review --uncommitted
interpreter exec review --base main
interpreter exec review --commit abc123

三种目标选择（见 ReviewArgs）：

参数	审查范围	互斥关系
`--uncommitted`	已暂存 + 未暂存 + 未跟踪的全部变更	与 `--base`、`--commit`、prompt 互斥
`--base <BRANCH>`	相对指定基准分支的全部变更	与 `--uncommitted`、`--commit`、prompt 互斥
`--commit <SHA>`	某一次提交引入的变更	与 `--uncommitted`、`--base`、prompt 互斥

对于自定义审查指令，可传入文本或使用 - 从 stdin 读取：

interpreter exec review --uncommitted "focus on concurrency bugs and API misuse"

审查同样支持 --json、--sandbox 等全局参数。底层它会构造 ReviewRequest 并走 app-server 的 review/start 请求（见 lib.rs 的 Review 分支），审查内容与可读输出均与文档 auto-review 描述的能力一致。

八、CI 模式：流水线里的标准姿势

exec 就是为无头环境设计的。推荐的 CI 模式是：使用 API Key 认证，并保持沙箱范围窄，防止模型在审查/分析过程中改动仓库内容。

- name: Review patch
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  run: |
    interpreter exec --json --sandbox read-only \
      "review this pull request diff for regressions" \
      < pr.diff > review.jsonl

这条命令的要点拆解：

OPENAI_API_KEY 环境变量：headless 运行不使用交互式登录，通过 API Key 完成认证。exec 进程内会启用 enable_codex_api_key_env 读取环境变量（见 lib.rs 的启动参数）。
--sandbox read-only：把模型可执行命令的沙箱收敛为只读。模型可以读源码、分析 diff，但无法写文件——在 CI 里，这是把"会写代码的 Agent"约束成"纯分析器"的关键开关。
< pr.diff > review.jsonl：把 PR diff 通过 stdin 作为 <stdin> 上下文喂给提示（对应前面讲的管道输入），同时把结构化事件流落到 review.jsonl，供后续步骤解析或归档。
退出码：exec 会跟踪服务端上报的致命错误并以非零码退出，为自动化提供"失败可感知"的信号（见 lib.rs 的注释）。

审查类任务跑完后，最稳妥的取值姿势是 -o review-result.json + --output-schema 组合：先让审查结论以固定 JSON 结构返回并落盘，再用 jq 提取风险等级与建议，决定流水线是否继续。

九、实战建议与相关文档

综合源码与文档，把 exec 用好还有几条经验：

确认最终答案只从 stdout 读取：默认模式 stdout 只有最终消息；--json 模式 stdout 是纯 JSONL。任何进程级日志都走 stderr，不会污染你的捕获结果。
长任务优先 --json + -o：JSONL 保证中途进度可观测，-o 保证最终消息在进程异常退出前也有副本落盘。
审查、编辑类任务主动收紧沙箱：read-only（纯分析）与 workspace-write（允许在工作区内改代码）分别对应"只读审查"与"允许修改"两类 CI 阶段。
resume 语义注意 --last 的位置参数重解释：--last 后跟的字符串会被当作新 prompt 而非会话 ID。
跨目录续跑加 --all；脱离 Git 仓库运行加 --skip-git-repo-check（或确认外部环境已沙箱化）。