非対話モード

非対話モードでは、対話型の TUI を開かずに、継続的インテグレーション（CI）のジョブなどでスクリプトから Codex を実行できます。 起動には codex exec を使います。

各フラグの詳細は codex exec を参照してください。

codex exec の用途

codex exec は、次のような場合に使います。

• CI、マージ前のチェック、定期実行ジョブなどのパイプラインに Codex を組み込みたい場合
• リリースノートや要約の生成などで、Codex の出力をパイプで他のツールに渡したい場合
• あるコマンドの出力を Codex に渡し、その結果をさらに別のツールに渡す CLI ワークフローを組みたい場合
• サンドボックスと承認の設定をあらかじめ明示して実行したい場合

基本的な使い方

タスクのプロンプトを 1 つの引数として渡します。

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

標準入力とパイプの詳しい使い方は、標準入力とパイプの応用を参照してください。

権限と安全性

デフォルトでは、codex exec は読み取り専用のサンドボックスで実行されます。自動化する際は、ワークフローに必要な最小限の権限を設定してください。

• 編集を許可する場合：codex exec --sandbox workspace-write "<task>"
• より広い範囲へのアクセスを許可する場合：codex exec --sandbox danger-full-access "<task>"

danger-full-access は、隔離された CI ランナーやコンテナなど、管理された環境でのみ使ってください。

--full-auto のサポートは終了しました。スクリプトでは --sandbox workspace-write に切り替えてください。workspace-write サンドボックスで承認リクエストを自動レビューに回す場合は、--approve-for-me を使ってください。

--ignore-user-config を使うと、$CODEX_HOME/config.toml を読み込まずに実行できます。管理された自動化環境では、--ignore-rules を使うと、ユーザーとプロジェクトの execpolicy の .rules ファイルを読み込まずに実行できます。

有効な MCP サーバーに required = true を設定している場合、そのサーバーの初期化に失敗すると、codex exec はエラーで終了します。

機械可読な出力

スクリプトで Codex の出力を処理するには、JSON Lines 形式で出力します。

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 ツールの呼び出し、ウェブ検索、計画の更新があります。

以下は JSON ストリームの例です。各行が 1 つの 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> でファイルに書き出します。この場合も、最後のメッセージは stdout に出力されます。詳細は codex exec を参照してください。

スキーマを使った構造化出力

後続の処理で構造化データが必要な場合は、--output-schema を指定して、JSON スキーマに準拠した最終応答を要求できます。 ジョブの要約、リスクレポート、リリースのメタデータなど、毎回同じフィールドを必要とする自動化ワークフローに適しています。

schema.json

{
  "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 はデフォルトで、CLI に保存されている認証情報を再利用します。CI では、認証情報を明示的に渡すのが一般的です。

API キーによる認証

GitHub Actions では、CLI を自分でインストールして認証する代わりに、Codex GitHub Action を使ってください。このアクションは、API キーが露出する機会を減らすために、Codex をインストールし、Responses API のプロキシを起動したうえで、設定可能な安全対策を適用して Codex を実行します。

リポジトリ内のコードをチェックアウトまたは実行するワークフローでは、OPENAI_API_KEY や CODEX_API_KEY をジョブ全体の環境変数に設定しないでください。同じジョブ内のビルドスクリプト、テスト、依存パッケージのライフサイクルフック、侵害されたアクションから、これらの環境変数を読み取ることができます。

その他の自動化環境では、CODEX_API_KEY はキーが必要な Codex の呼び出しに限って設定し、同じプロセス環境で信頼できないコードが実行されないようにしてください。

1 回の実行だけ別の API キーを使うには、コマンドと同じ行で CODEX_API_KEY を設定します。

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

CODEX_API_KEY は、codex exec、codex review、TypeScript SDK、codex exec-server --remote で使えます。

非対話セッションの再開

2 段階のパイプラインなどで前回の実行の続きを処理するには、resume サブコマンドを使います。

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

codex exec resume <SESSION_ID> で特定のセッション ID を指定することもできます。

Git リポジトリでの実行要件

Codex では、破壊的な変更を防ぐため、コマンドを Git リポジトリ内で実行する必要があります。環境が安全であると確信できる場合は、codex exec --skip-git-repo-check でこのチェックを省略できます。

一般的な自動化パターン

例：GitHub Actions での CI 失敗時の自動修正

GitHub Actions のワークフローでは、Codex を自分でインストールしてシェルのステップに API キーを渡す代わりに、openai/codex-action を使ってください。このアクションは、OpenAI API キーを安全に扱うためのプロキシを起動します。

CI ワークフローが失敗したときに、Codex で修正案を自動生成できます。手順は次のとおりです。

1. メインの CI ワークフローがエラーで終了したら、後続のワークフローを起動します。
2. リポジトリの読み取り権限だけで、CI が失敗したコミットをチェックアウトします。
3. Codex の実行前にセットアップコマンドを実行します。これらのステップから OpenAI API キーにアクセスできないようにしてください。
4. Codex GitHub Action を実行します。
5. Codex がローカルで加えた変更を、パッチとしてアーティファクトに保存します。
6. 別のジョブでパッチを適用し、pull request を作成します。

以下の例では、Codex を実行するジョブの権限は contents: read だけです。Codex の実行後、このジョブは差分をアーティファクトに書き出すだけです。open_pr ジョブにはリポジトリへの書き込み権限を付与しますが、OPENAI_API_KEY は渡しません。

この例は Node.js プロジェクトを想定しています。セットアップとテストのコマンドは、使用する技術に合わせて調整してください。

セキュリティに関する詳しいチェックリストは、Codex GitHub Action のセキュリティガイドを参照してください。

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 への入力を生成する場合は、指示をどこから渡すかに応じて標準入力の使い方を選びます。指示があらかじめ決まっていて、別のコマンドの出力をコンテキストとして渡す場合は、プロンプト引数と標準入力を併用します。標準入力をそのままプロンプト全体として使う場合は、codex exec - を使います。

プロンプト引数と標準入力の併用

Codex で調べたいデータを別のコマンドで出力できる場合は、プロンプト引数と標準入力の併用が便利です。指示は自分で書き、コマンドの出力はコンテキストとしてパイプで渡します。コマンドの出力やログ、生成したデータを扱う 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

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

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

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 - による標準入力からのプロンプトの読み込み

プロンプト引数を省略すると、Codex は標準入力からプロンプトを読み込みます。この動作を明示的に指定するには、codex exec - を使います。

標準入力を指定する - は、別のコマンドやスクリプトでプロンプト全体を動的に生成する場合に便利です。たとえば、ファイルに保存したプロンプトを読み込む場合や、シェルスクリプトでプロンプトを組み立てる場合、コマンドの最新の出力と指示を組み合わせてからプロンプト全体を 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