企业官网建设流程全解析

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

【免费下载链接】openinterpreterA coding agent for open models like Kimi K3 and GLM 5.3项目地址: https://gitcode.com/GitHub_Trending/op/openinterpreter

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/execcrate，对应命令的内部 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）：

逐个拆解其底层行为

结合 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 会周期性地收到"剩余时间"提醒，从而主动收敛到可在时限内交付的方案。

更多共享参数（自动化高频搭配）

exec 还继承了整套共享 CLI 参数（定义于 shared_options.rs），包括：

• -m, --model <model>：指定本次使用的模型；
• --oss/--local-provider <lmstudio|ollama>：切换到开源本地推理提供商；
• -C, --cd <DIR>：指定工作根目录（等价于在目标目录下执行）；
• --add-dir <DIR>：在主工作区之外追加可写目录；
• --approve-for-me：把批准请求路由到自动评审（等价于使用workspace-write沙箱的自动审查，见 shared_options.rs）。

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

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

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

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

事件协议类型

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

其中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）：

对于自定义审查指令，可传入文本或使用-从 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

这条命令的要点拆解：

1. OPENAI_API_KEY环境变量：headless 运行不使用交互式登录，通过 API Key 完成认证。exec 进程内会启用enable_codex_api_key_env读取环境变量（见 lib.rs 的启动参数）。
2. --sandbox read-only：把模型可执行命令的沙箱收敛为只读。模型可以读源码、分析 diff，但无法写文件——在 CI 里，这是把"会写代码的 Agent"约束成"纯分析器"的关键开关。
3. < pr.diff > review.jsonl：把 PR diff 通过 stdin 作为<stdin>上下文喂给提示（对应前面讲的管道输入），同时把结构化事件流落到review.jsonl，供后续步骤解析或归档。
4. 退出码：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（或确认外部环境已沙箱化）。

interpreter exec与仓库其他部分配合紧密，可继续阅读：

• 命令行全貌与其余子命令：docs/zh/cli-reference.md
• exec 内部 CLI/参数/子命令实现：codex-rs/exec/src/cli.rs、codex-rs/exec/src/lib.rs
• JSON 事件与 item 类型定义：codex-rs/exec/src/exec_events.rs
• 共享全局参数（模型、OSS、沙箱、目录等）：codex-rs/utils/cli/src/shared_options.rs
• 沙箱模式与批准策略：docs/zh/sandbox.md、docs/zh/permissions.md
• execpolicy 规则（--ignore-rules影响的加载项）：docs/zh/execpolicy.md
• 会话持久化与resume/--ephemeral的行为边界：docs/zh/sessions.md
• 自动代码审查（交互式/review与 exec review 的关系）：docs/zh/auto-review.md
• GitHub Action 场景下的interpreter exec --json用法：docs/zh/github-action.md

【免费下载链接】openinterpreterA coding agent for open models like Kimi K3 and GLM 5.3项目地址: https://gitcode.com/GitHub_Trending/op/openinterpreter