Codex 非交互模式 | codex exec、CI 与脚本

非交互模式允许你在脚本里直接调用 Codex，例如 CI 任务，而不必打开交互式 TUI。入口命令是 codex exec。

如果你需要查看更细的 flag 说明，请直接点击 codex exec 查看。

何时使用 `codex exec`

当你希望 Codex：

作为流水线的一部分运行，例如 CI、预合并检查或定时任务
输出可继续传给其他工具处理的结果，例如 release notes 或摘要
自然嵌入 CLI 工作流，把命令输出传给 Codex，再把 Codex 输出交给其他命令
在一开始就显式固定沙箱和 approval 设置

就适合使用 codex exec。

基本用法

最简单的方式是把任务提示词作为单个参数传入：

codex exec "summarize the repository structure and list the top 5 risky areas"

执行期间，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"

如果同时提供了 prompt 参数，并且 stdin 里也有输入，Codex 会把命令行 prompt 当作指令，把 stdin 内容当作额外上下文。

这很适合“一个命令生成数据，直接交给 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 运行在只读沙箱中。

在自动化环境里，应始终只授予工作流所需的最小权限：

允许编辑：codex exec --full-auto "<task>"
允许更广访问：codex exec --sandbox danger-full-access "<task>"

danger-full-access 只适合在受控环境中使用，例如隔离的 CI runner 或单用途容器。

如果你把某个 MCP server 配置成 required = true，并且它初始化失败，codex exec 会直接报错退出，而不会在缺少这个 server 的情况下继续执行。

让输出可供机器读取

如果你要在脚本里消费 Codex 输出，推荐启用 JSON Lines：

codex exec --json "summarize the repo structure" | jq

启用 --json 后，stdout 会变成 JSONL 事件流，因此你可以捕获 Codex 运行期间发出的每个事件。常见事件类型包括 thread.started、turn.started、turn.completed、turn.failed、item.* 和 error。

常见 item 类型包括智能体消息、reasoning、command executions、file changes、MCP tool calls、web searches 和 plan updates。

示例 JSONL 输出如下：

{"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}}

如果你只需要最终消息，可以使用 -o <path> / --output-last-message <path> 把它写入文件。Codex 会把最终消息写入文件，同时仍然打印到 stdout（详见 codex exec）。

通过 Schema 生成结构化输出

如果你的下游步骤需要稳定的结构化数据，可以用 --output-schema 传入 JSON Schema，要求最终响应符合该结构。这很适合需要稳定字段的自动化工作流，例如任务摘要、风险报告或发布元数据。

schema.json

{
  "type": "object",
  "properties": {
    "project_name": { "type": "string" },
    "programming_languages": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["project_name", "programming_languages"],
  "additionalProperties": false
}

运行方式：

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

最终输出示例：

{
  "project_name": "Codex CLI",
  "programming_languages": ["Rust", "TypeScript", "Shell"]
}

在 CI 中认证

默认情况下，codex exec 会复用 CLI 已保存的认证状态。在 CI 中，更常见的做法是显式提供凭据。

使用 API key 认证（推荐）

把 CODEX_API_KEY 配置为 CI job 的 secret 环境变量
注意 prompt 和工具输出中可能包含敏感代码或数据

CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"

CODEX_API_KEY 只在 codex exec 中受支持。

在 CI/CD 中使用 ChatGPT 管理的认证（高级）

如果你需要在 CI/CD 作业中使用 Codex 用户账号而不是 API key 来运行，请阅读本节。例如，企业团队在受信任的 runner 上使用由 ChatGPT 管理的 Codex 访问，或需要使用 ChatGPT / Codex 的速率限制而不是 API key 配额的用户，都适合这种方式。

API key 仍然是自动化场景的默认首选，因为它更容易发放和轮换。只有在你明确需要以自己的 Codex 账号身份运行时，才应选择这条路径。

不要在公开仓库或开源仓库中使用这套流程。如果 runner 上无法执行 codex login，应通过安全存储预先注入 auth.json，再在 runner 上运行 Codex，让 Codex 就地刷新该文件，并在多次运行之间持久化更新后的文件。

详见在 CI/CD 中维护 Codex 账号认证（高级）。

恢复非交互会话

如果你要在一个多阶段流水线中继续上一次运行，可以使用 resume 子命令：

codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"

你也可以直接指定某个 session ID：

codex exec resume <SESSION_ID>

需要 Git 仓库

Codex 默认要求命令在 Git 仓库中执行，以减少破坏性改动的风险。如果你确认当前环境安全，可以使用 codex exec --skip-git-repo-check 跳过这项检查。

常见自动化模式

示例：在 GitHub Actions 中自动修复 CI 失败

你可以用 codex exec 在 CI 失败后自动提出修复建议。一个典型模式如下：

在主 CI 工作流失败后触发后续 workflow。
checkout 失败的 commit SHA。
安装依赖，并以最小权限运行 Codex。
重新执行测试命令。
以生成的 patch 创建 PR。

使用 Codex CLI 的最小工作流

下面的示例展示了最小闭环。你应按自己的技术栈调整安装和测试命令。

name: Codex auto-fix on CI failure

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

permissions:
  contents: write
  pull-requests: write

jobs:
  auto-fix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    env:
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      FAILED_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
      FAILED_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ env.FAILED_HEAD_SHA }}
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: |
          if [ -f package-lock.json ]; then npm ci; else npm i; fi

      - name: Install Codex
        run: npm i -g @openai/codex

      - name: Authenticate Codex
        run: codex login --api-key "$OPENAI_API_KEY"

      - name: Run Codex
        run: |
          codex exec --full-auto --sandbox workspace-write \
            "Read the repository, run the test suite, identify the minimal change needed to make all tests pass, implement only that change, and stop. Do not refactor unrelated files."

      - name: Verify tests
        run: npm test --silent

      - name: Create pull request
        if: success()
        uses: peter-evans/create-pull-request@v6
        with:
          branch: codex/auto-fix-${{ github.event.workflow_run.run_id }}
          base: ${{ env.FAILED_HEAD_BRANCH }}
          title: "Auto-fix failing CI via Codex"

备选方案：使用 Codex GitHub Action

如果你不想自己安装 CLI，也可以通过 Codex GitHub Action 运行 codex exec，并把 prompt 作为 action 输入传入。

高级 stdin 管道模式

当另一个命令要把结果交给 Codex 时，应根据“指令来自哪里”来选择 stdin 模式。如果你已经知道指令，只是想把命令输出作为上下文传给 Codex，就用“prompt + stdin”；如果 stdin 本身就是完整 prompt，就用 codex exec -。

使用 prompt + stdin

这种模式适合上游命令已经生成了你想让 Codex 检查的数据，而你只需自己补充解释任务目标：

npm test 2>&1 \
  | codex exec "summarize the failing tests and propose the smallest likely fix" \
  | tee test-summary.md

更多 prompt + stdin 示例

汇总日志

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 的更新

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 日志起草 PR 评论

gh run view 123456 --log \
  | codex exec "summarize the failure in 5 bullets for the pull request thread" \
  | gh pr comment 789 --body-file -

当 stdin 本身就是完整 prompt 时使用 `codex exec -`

如果你不提供 prompt 参数，Codex 会从 stdin 读取完整 prompt。显式写成 codex exec - 可以强制采用这种行为。

这很适合把 prompt 存在文件里、用 shell 脚本拼装 prompt，或者把实时命令输出和说明拼接后整体交给 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

来源：https://developers.openai.com/codex/noninteractive

最近搜索

推荐搜索

非交互模式

何时使用 `codex exec`

基本用法

权限与安全

让输出可供机器读取

通过 Schema 生成结构化输出

在 CI 中认证

使用 API key 认证（推荐）

恢复非交互会话

需要 Git 仓库

常见自动化模式

示例：在 GitHub Actions 中自动修复 CI 失败

使用 Codex CLI 的最小工作流

备选方案：使用 Codex GitHub Action

高级 stdin 管道模式

使用 prompt + stdin

汇总日志

分析 TLS 或 HTTP 故障

生成可直接发到 Slack 的更新

根据 CI 日志起草 PR 评论

当 stdin 本身就是完整 prompt 时使用 `codex exec -`

何时使用 codex exec

基本用法

权限与安全

让输出可供机器读取

通过 Schema 生成结构化输出

在 CI 中认证

使用 API key 认证（推荐）

恢复非交互会话

需要 Git 仓库

常见自动化模式

示例：在 GitHub Actions 中自动修复 CI 失败

使用 Codex CLI 的最小工作流

备选方案：使用 Codex GitHub Action

高级 stdin 管道模式

使用 prompt + stdin

汇总日志

分析 TLS 或 HTTP 故障

生成可直接发到 Slack 的更新

根据 CI 日志起草 PR 评论

当 stdin 本身就是完整 prompt 时使用 codex exec -

何时使用 `codex exec`

当 stdin 本身就是完整 prompt 时使用 `codex exec -`