codex exec 非交互模式怎么用:脚本管道、沙箱参数、JSON 输出与 Schema 结构化返回

想在 Shell 脚本、定时任务或 CI 里不弹界面直接跑 Codex?按官方《Non-interactive mode》整理 codex exec 用法:stdin 管道拼接、只读与可写沙箱(--full-auto 已废弃)、--json 事件流与 --output-schema 强约束。

NNathaniel bigo··原创首发·AI 辅助撰写
10 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 Plus 账号

结论先说

  1. 非交互模式入口是 codex exec(简写 codex e),运行过程不打开全屏终端界面(TUI)。
  2. 输出天然分流:执行进度打往 stderr,最终回复只打往 stdout,直接用 > 或管道 | 就能拿到干净结果。
  3. 默认是只读沙箱,且旧参数 --full-auto 已废弃;需要让脚本改文件时,传 --sandbox workspace-write。
  4. 管道有两种接法:传了提示词参数时,管道进来的 stdin 当补充上下文;写成 codex exec - 时,stdin 直接当整条提示词。
  5. 自动化解析有两件利器:--json 把 stdout 变成逐行 JSONL 事件流,--output-schema 强制最终回复严格符合指定 JSON Schema。

用 codex exec 写自动化脚本的五步法

图:本站根据 Codex 官方文档:Non-interactive mode 整理的示意图

本文根据 Codex 官方文档《Non-interactive mode》与《Command line options》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。

适用于谁

  • 想在 Shell 脚本、预提交检查、定时巡检或 CI 流水线里无人值守调用 Codex 的开发者;
  • 需要把报错日志通过管道喂给 Codex,再把返回结果存盘或传给下游工具(如 jq、gh)的人;
  • 照旧教程写 --full-auto 报错,想知道最新非交互权限与 JSON 输出参数的人。

一、基础命令与两种 stdin 管道模式

最简单的单次调用,直接把任务指令作为参数传入:

bash
codex exec "总结当前仓库目录结构,列出最需要注意的 5 个风险点" > summary.md

因为运行日志走 stderr、最终结论走 stdout,summary.md 里只会写入最后的总结正文。如果临时跑批处理不想在 ~/.codex/sessions 留下会话文件,加上 --ephemeral。

当上游命令(比如单测、日志截取、curl)通过管道喂数据时,按指令来源选写法:

  • 模式 A:「指令 + 管道上下文」(命令带提示词参数,管道内容自动作为附加材料):
bash
npm test 2>&1 \
  | codex exec "汇总失败的测试用例,并给出改动最小的修复方案" \
  | tee test-triage.md
  • 模式 B:「管道即完整提示词」(省略提示词或显式写 -,适合由上游脚本动态拼好整段提示词):
bash
cat prompt.txt | codex exec -

需要注意,Codex 默认强制检查当前目录是不是 Git 仓库,以防误伤非版本控制目录;如果确定在安全的临时目录里跑纯文本处理,需显式加上 --skip-git-repo-check。

二、沙箱与项目信任设置(别再用 --full-auto)

codex exec 默认运行在只读(read-only)沙箱中,不能改代码。按官方最新说明,旧版 --full-auto 参数已停止支持,脚本里请按最小权限改写:

bash
# 允许在当前工作区改文件
codex exec --sandbox workspace-write "修复失败的单测并重新运行验证"

# 在工作区可写基础上,把越界审批请求交给自动安全审核处理
codex exec --sandbox workspace-write --approve-for-me "更新快照并跑通检查"

只有在完全隔离的容器或一次性 CI 虚拟机里,才考虑 --sandbox danger-full-access。沙箱与自动审核的完整规则见 Codex 权限与沙箱设置 与 Codex 命令被自动审核拒绝怎么办。

另外两条容易在脚本里踩坑的加载规则:

  • 未信任项目不加载 .codex/:即使开了可写沙箱,本地 codex exec 也只对受信任项目加载仓库内的 .codex/config.toml 和项目级 MCP 服务;首次在自动化目录运行可传 --trust 保存信任状态(不能与 --ignore-user-config 同用)。
  • 纯净环境隔离:不想受本机 ~/.codex/config.toml 干扰时加 --ignore-user-config;想跳过 .rules 规则文件时加 --ignore-rules。若某个启用的 MCP 服务配置了 required = true 但初始化失败,codex exec 会直接非零退出而不会静默跳过(MCP 配置见 Codex 怎么配置 MCP)。

三、机器可读输出:--json、-o 与 --output-schema

codex exec 四种输出控制参数对比

图:本站根据 Codex 官方文档:Non-interactive mode 整理的示意图

写流水线脚本时,纯自然语言不好给下一步解析,官方提供了三种输出控制参数:

1. 抓全量过程事件:--json

加上 --json 后,stdout 会变成每行一个 JSON 对象的 JSONL 流,包含 thread.started、turn.started、item.started、item.completed(涵盖命令执行、文件修改、MCP 调用、网页搜索等)以及带 token 统计的 turn.completed。若既想要 JSONL 流又想单独拿最终结论文本,搭配 -o(即 --output-last-message):

bash
codex exec --json -o last-message.txt "检查最近一次提交的潜在空指针问题" > events.jsonl

2. 强制返回固定 JSON 结构:--output-schema

先准备一份标准 JSON Schema 文件(注意顶层对象的 additionalProperties 设为 false),例如 schema.json:

json
{
  "type": "object",
  "properties": {
    "risk_level": { "type": "string" },
    "affected_files": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["risk_level", "affected_files"],
  "additionalProperties": false
}

执行时传入 --output-schema 并用 -o 落盘:

bash
codex exec "评估当前未提交改动的风险范围" \
  --output-schema ./schema.json \
  -o ./risk-report.json

四、多步接续、工作树与自动化凭据

  • 两阶段流水线接续:第一步只审不改,第二步接着改,可用 codex exec resume --last "修复刚才找出的竞态条件"(或传指定 <SESSION_ID>,会话恢复详见 Codex 历史会话在哪、怎么恢复)。
  • 隔离工作树执行:加 --worktree(如 codex exec --worktree "实现下一步" 或 codex exec fork <SESSION_ID> --worktree)可在受管 Git 工作树中独立改代码,不污染主检出。
  • 凭据安全:codex exec 默认复用本机登录态;在无人值守环境推荐单条命令前注入 CODEX_API_KEY=<密钥> codex exec ...,不要在跑未知仓库构建或测试代码的整个 CI Job 顶层暴露 OPENAI_API_KEY,以防被第三方依赖钩子读取。计费区别见 Codex 怎么收费;本地个人交互与轻脚本若用订阅额度跑,可在本站查看 ChatGPT Plus 充值说明。

常见问题

问:codex exec 和 codex review 有什么区别?

答:codex review 是专门做非交互代码审查的子命令(支持 --uncommitted、--base、--commit),而 codex exec 是通用的非交互执行入口,查日志、改文件、抽结构化数据都能干。

问:为什么加了 --ephemeral 或 --output-schema 却报错缺提示词?

答:官方命令参考规定,使用 --image、--output-schema、--output-last-message 或 --ephemeral 时,必须提供提示词(可直接给字符串,或用 - 从 stdin 读入)。

问:能在公共开源仓库的 CI 里把本机 ~/.codex/auth.json 拷过去跑吗?

答:官方明确禁止在公共或开源仓库这样做。auth.json 内含账号访问令牌,等同密码;CI 自动化应使用可随时轮换的 API Key 或官方 GitHub Action。

相关教程

参考资料

  • Codex 官方文档:Non-interactive mode — https://learn.chatgpt.com/docs/non-interactive-mode
  • Codex 官方文档:Command line options — https://learn.chatgpt.com/docs/developer-commands

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    AutoGen 现在怎么样了?微软官方演进路线与 Microsoft Agent Framework 入门

    搜 AutoGen 新教程常被 0.2、0.4、社区分支和 Semantic Kernel 绕晕。按微软官方文档,微软已将 AutoGen 与 Semantic Kernel 两支团队合并推出统一的开源框架 Microsoft Agent Framework。本文讲清现状与 Python 快速上手。

    ChatGPT其他 AI 工具0
  2. 02

    多 Agent 的成本为什么翻倍、怎么控制:Token 膨胀根源与五项降本措施

    刚把单智能体拆成多 Agent,用量往往暴涨好几倍。Anthropic 工程报告统计单智能体约为聊天的 4 倍 Token,多智能体可达约 15 倍。本文拆解固定前缀重复加载、历史搬运、工具链定义与缓存失效四大根源,并给出五条实操控费办法。

    ChatGPTClaude0
  3. 03

    多 Agent 协同开发怎么落地:「一个写、一个审」双代理工作流搭建指南

    多 Agent 协同开发里投入产出比最高的模式就是「一个写、一个审」。本文依据 Anthropic 与 OpenAI 官方编码最佳实践,讲清为什么同会话自审容易漏问题,以及用只读子代理、跨模型交叉审查(Claude Code + Codex)和自动化闭环落地的具体方法。

    ClaudeCodex0
  4. 04

    多 Agent 编排模式详解:编排者-工作者、交接(Handoffs)、并行与评估循环怎么选

    搜「multi-agent orchestration 中文」会被各家框架的不同术语绕晕。本文对照 Anthropic《Building effective agents》与 OpenAI 智能体指南,把编排者-工作者、去中心化交接、并行分片投票与生成-评估循环四种标准编排拓扑讲透。

    ChatGPTClaude0
  5. 05

    多智能体(Multi-Agent)是什么、什么时候该用:Anthropic 与 OpenAI 官方判断标准

    多智能体不是代理越多越聪明。本文依据 Anthropic 研究系统架构文章与 OpenAI 官方智能体指南,讲清确定性工作流、单智能体与多智能体的区别,以及哪三类瓶颈才值得上多智能体协同。

    ChatGPTClaude0
  6. 06

    codebase-memory 类 MCP 是什么、怎么用:基于语法树图谱的本地代码索引原理与配置

    codebase-memory-mcp(DeusData/codebase-memory-mcp)是一类本地代码图谱 MCP 服务器:用 Tree-sitter 把仓库解析成函数与调用关系的 SQLite 图库,帮编码助手查调用链并省下读整份文件的额度。

    ClaudeCodex0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~