Non-interactive 模式允许您从脚本（例如，持续集成 (CI) 作业）运行 Codex，而无需打开交互式 TUI。您可以使用 codex exec 调用它。
有关 flag-level 详细信息，请参阅 codex exec 。
何时使用 codex exec
当您希望 Codex 执行以下操作时，请使用 codex exec：
作为管道的一部分运行（CI、pre-merge 检查、计划作业）。
生成可以通过管道传输到其他工具的输出（例如，生成发行说明或摘要）。
自然地融入 CLI 工作流程，将命令输出链接到 Codex 并将 Codex 输出传递给其他工具。
使用显式的 pre-set 沙箱和批准设置运行。
基本用法
将任务提示作为单个参数传递：
codex exec "summarize the repository structure and list the top 5 risky areas"当 codex exec 运行时，Codex 将进度流式传输到 stderr，并仅将最终代理消息打印到 stdout。这使得重定向或管道传输最终结果变得简单：
codex exec "generate release notes for the last 10 commits" | tee release-notes.md当您不想将会话部署文件保留到磁盘时，请使用 --ephemeral：
codex exec --ephemeral "triage this repository and suggest next steps"如果标准输入是通过管道传输的，并且您还提供了提示参数，则 Codex 会将提示视为指令，并将管道传输的内容视为附加上下文。
这样可以轻松地使用一个命令生成输入并将其直接传递给 Codex：
curl -s https://jsonplaceholder.typicode.com/comments \ | codex exec "format the top 20 items into a markdown table" \ > table.md有关更高级的 stdin 管道模式，请参阅高级 stdin 管道。
权限和安全
默认情况下，codex exec 在 read-only 沙箱中运行。在自动化中，设置工作流程所需的最少权限：
允许编辑：codex exec --sandbox workspace-write "<task>"
允许更广泛的访问：codex exec --sandbox danger-full-access "<task>"
仅在受控环境（例如，隔离的 CI 运行程序或容器）中使用 danger-full-access。
Codex keeps codex exec --full-auto as a deprecated compatibility flag and prints a warning. Prefer the explicit --sandbox workspace-write flag in new scripts.
当您需要不加载 $CODEX_HOME/config.toml 的运行时，请使用 --ignore-user-config；当您需要为受控自动化环境跳过用户和项目 execpolicy .rules 文件时，请使用 --ignore-rules。
如果您使用 required = true 配置已启用的 MCP 服务器并且它无法初始化，则 codex exec 将出现错误并退出，而不是在没有该服务器的情况下继续。
输出machine-readable
要在脚本中使用 Codex 输出，请使用 JSON 行输出：
codex exec --json "summarize the repo structure" | jq当您启用 --json 时，stdout 将成为 JSON Lines (JSONL) 流，因此您可以捕获 Codex 在运行时发出的每个事件。事件类型包括 thread.started、turn.started、turn.completed、turn.failed、item.* 和 error。
项目类型包括代理消息、推理、命令执行、文件更改、MCP 工具调用、Web 搜索和计划更新。
示例 JSON 流（每行都是一个 JSON 对象）：
{"type":"thread.started","thread_id":"0199a213-81c0-7800-8aa1-bbab2a035a53"} {"type":"turn.started"} {"type":"item.started","item":{"id":"item_1","type":"command_execution","command":"bash -lc ls","status":"in_progress"}} {"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"Repo contains docs, sdk, and examples directories."}} {"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122,"reasoning_output_tokens":0}}如果您只需要最终消息，请使用 -o <path>/--output-last-message <path> 将其写入文件。这会将最终消息写入文件并仍然将其打印到标准输出（有关详细信息，请参阅 codex exec ）。
使用架构创建结构化输出
如果下游步骤需要结构化数据，请使用 --output-schema 请求符合 JSON 架构的最终响应。这对于需要稳定字段（例如作业摘要、风险报告或发布元数据）的自动化工作流程非常有用。
CXSYNC0令牌
{ "type": "object", "properties": { "project_name": { "type": "string" }, "programming_languages": { "type": "array", "items": { "type": "string" } } }, "required": ["project_name", "programming_languages"], "additionalProperties": false }使用架构运行 Codex 并将最终 JSON 响应写入磁盘：
codex exec "Extract project metadata" \ --output-schema ./schema.json \ -o ./project-metadata.json最终输出示例（标准输出）：
{ "project_name": "Codex CLI", "programming_languages": ["Rust", "TypeScript", "Shell"] }自动化验证
codex exec reuses saved CLI authentication by default. In CI, it’s common to provide credentials explicitly:
使用 API 密钥身份验证
对于 GitHub Actions，请使用 Codex GitHub 操作，而不是自行安装和验证 CLI。该操作旨在通过安装 Codex、启动响应 API 代理以及使用可配置的安全策略运行 Codex 来减少 API 密钥暴露。
请勿在签出或运行 repository-controlled 代码的工作流中将 OPENAI_API_KEY 或 CODEX_API_KEY 设置为 job-level 环境变量。构建脚本、测试、依赖生命周期挂钩或同一作业中的受损操作可以读取这些环境变量。
对于其他自动化环境，仅针对单个 codex exec 调用设置 CODEX_API_KEY，并确保同一进程环境中没有运行不受信任的代码。
要在单次运行中使用不同的 API 密钥，请内联设置 CODEX_API_KEY：
CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"CODEX_API_KEY 仅在 codex exec 中受支持。
如果您需要使用 Codex 用户帐户而不是 API 密钥运行 CI/CD 作业，例如企业团队对受信任的运行者使用 ChatGPT-managed Codex 访问，或者需要 ChatGPT/Codex 速率限制而不是 API 密钥使用的用户，请阅读本文。
API 密钥是自动化的正确默认值，因为它们更易于配置和轮换。仅当您特别需要以 Codex 帐户运行时才使用此路径。
将 ~/.codex/auth.json 视为密码：它包含访问令牌。不要提交、粘贴到票证中或在聊天中分享。
请勿将此工作流程用于公共或 open-source 存储库。如果运行器上没有 Codex 登录选项，请通过安全存储播种 auth.json，在运行器上运行 Codex，以便 Codex 刷新它，并在运行之间保留更新的文件。
恢复 non-interactive 会话
如果您需要继续之前的运行（例如，two-stage 管道），请使用resume 子命令：
codex exec "review the change for race conditions" codex exec resume --last "fix the race conditions you found"您还可以使用 codex execresume <SESSION_ID> 定位特定会话 ID。
Git repository required
Codex requires commands to run inside a Git repository to prevent destructive changes. Override this check with codex exec --skip-git-repo-check if you’re sure the environment is safe.
常见的自动化模式
示例：自动修复 GitHub Actions 中的 CI 故障
对于 GitHub Actions 工作流程，请使用 openai/codex-action ，而不是安装 Codex 并将 API 密钥传递到 shell 步骤。该操作为 OpenAI API 密钥启动安全代理。
当 CI 工作流程失败时，您可以使用 Codex 自动提出修复建议。模式是：
当主 CI 工作流程完成但出现错误时，触发 follow-up 工作流程。
仅使用存储库读取权限检查失败的提交。
在 Codex 之前运行设置命令，而不会将您的 OpenAI API 密钥暴露给这些步骤。
运行 Codex GitHub 操作。
将 Codex 的本地更改保存为补丁工件。
在单独的作业中，应用补丁并打开拉取请求。
下面的 Codex 作业只有内容：读取。 Codex 运行后，它仅将差异序列化为工件。 open_pr 作业接收存储库写入权限，但不接收 OPENAI_API_KEY。
该示例假设有一个 Node.js 项目。调整设置和测试命令以匹配您的堆栈。
有关更深入的安全检查表，请参阅 Codex GitHub 操作安全指南。
name: Codex auto-fix on CI failure on: workflow_run: workflows: ["CI"] types: [completed] jobs: generate_fix: if: ${{ github.event.workflow_run.conclusion == 'failure' }} runs-on: ubuntu-latest permissions: contents: read outputs: has_patch: ${{ steps.diff.outputs.has_patch }} steps: - uses: actions/checkout@v5 with: ref: ${{ github.event.workflow_run.head_sha }} fetch-depth: 0 persist-credentials: false - uses: actions/setup-node@v4 with: node-version: "20" - name: Install dependencies run: | if [ -f package-lock.json ]; then npm ci; fi - name: Run Codex uses: openai/codex-action@v1 with: openai-api-key: ${{ secrets.OPENAI_API_KEY }} prompt: | The CI workflow "${{ github.event.workflow_run.name }}" failed for commit ${{ github.event.workflow_run.head_sha }}. Run `npm test --silent` to reproduce the failure. Identify the minimal change needed to make the tests pass, implement only that change, and run `npm test --silent` again. Do not refactor unrelated files. - name: Create patch artifact id: diff run: | git add -N . git diff --binary HEAD > codex.patch if [ -s codex.patch ]; then echo "has_patch=true" >> "$GITHUB_OUTPUT" else echo "has_patch=false" >> "$GITHUB_OUTPUT" fi - name: Upload patch artifact if: steps.diff.outputs.has_patch == 'true' uses: actions/upload-artifact@v4 with: name: codex-fix-patch path: codex.patch if-no-files-found: error open_pr: runs-on: ubuntu-latest needs: generate_fix if: needs.generate_fix.outputs.has_patch == 'true' permissions: contents: write pull-requests: write steps: - uses: actions/checkout@v5 with: ref: ${{ github.event.workflow_run.head_sha }} fetch-depth: 0 - uses: actions/download-artifact@v4 with: name: codex-fix-patch - name: Apply Codex patch run: git apply --index codex.patch - name: Open pull request env: GH_TOKEN: ${{ github.token }} FAILED_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }} FAILED_HEAD_SHA: ${{ github.event.workflow_run.head_sha }} RUN_ID: ${{ github.event.workflow_run.run_id }} run: | branch="codex/auto-fix-$RUN_ID" git config user.name "github-actions[bot]" git config user.email "41898282+github-actions[bot]@users.noreply.github.com" git switch -c "$branch" git commit -m "Auto-fix failing CI via Codex" git push origin "$branch" { echo "Codex generated this patch after CI failed for \`$FAILED_HEAD_SHA\`." echo echo "Review the changes before merging." } > pr-body.md gh pr create \ --base "$FAILED_HEAD_BRANCH" \ --head "$branch" \ --title "Auto-fix failing CI via Codex" \ --body-file pr-body.md高级标准输入管道
当另一个命令生成 Codex 的输入时，请根据指令的来源选择标准输入模式。当您已经知道指令并希望将管道输出作为上下文传递时，请使用 prompt-plus-stdin。使用 codex exec - 当 stdin 应该成为完整提示符时。
使用prompt-plus-stdin
当另一个命令已经生成您希望 Codex 检查的数据时，Prompt-plus-stdin 非常有用。在此模式下，您自己编写指令并将输出作为上下文通过管道传输，这使其非常适合围绕命令输出、日志和生成的数据构建的 CLI 工作流程。
npm test 2>&1 \ | codex exec "summarize the failing tests and propose the smallest likely fix" \ | tee test-summary.md总结日志
tail -n 200 app.log \ | codex exec "identify the likely root cause, cite the most important errors, and suggest the next three debugging steps" \ > log-triage.md检查 TLS 或 HTTP 问题
curl -vv https://api.example.com/health 2>&1 \ | codex exec "explain the TLS or HTTP failure and suggest the most likely fix" \ > tls-debug.md准备 Slack-ready 更新
gh run view 123456 --log \ | codex exec "write a concise Slack-ready update on the CI failure, including the likely cause and next step" \ | pbcopy从 CI 日志中起草拉取请求评论
gh run view 123456 --log \ | codex exec "summarize the failure in 5 bullets for the pull request thread" \ | gh pr comment 789 --body-file -使用 codex exec - 当 stdin 为提示符时
如果省略提示参数，Codex 将从 stdin 读取提示。使用 codex exec - 当您想显式强制该行为时。
当另一个命令或脚本动态生成整个提示时，- 标记非常有用。当您将提示存储在文件中、使用 shell 脚本组装提示或在将整个提示传递给 Codex 之前将实时命令输出与指令结合起来时，这非常适合。
cat prompt.txt | codex exec -printf "Summarize this error log in 3 bullets:\n\n%s\n" "$(tail -n 200 app.log)" \ | codex exec -generate_prompt.sh | codex exec - --json > result.jsonl