非対話モード

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

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

codex exec を使用する場面

Codex で次のことを行う場合は、codex exec を使用します。

• パイプライン（CI、マージ前チェック、スケジュール済みジョブ）の一部として実行する。
• 他のツールへパイプできる出力を生成する（リリースノートや概要の生成など）。
• コマンド出力を Codex に渡し、Codex の出力を他のツールへ渡す CLI ワークフローへ自然に組み込む。
• 明示的に事前設定したサンドボックスと承認設定で実行する。

基本的な使い方

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

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

セッションの rollout ファイルをディスクに永続化しない場合は、--ephemeral を使用します。

codex exec --ephemeral "triage this repository and suggest next steps"

stdin をパイプし、さらにプロンプト引数も指定すると、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 は読み取り専用サンドボックスで実行されます。自動化では、ワークフローに必要な最小限の権限を設定してください。

• 編集を許可：codex exec --sandbox workspace-write "<task>"
• より広範なアクセスを許可：codex exec --sandbox danger-full-access "<task>"

danger-full-access は、管理された環境（分離された CI runner やコンテナなど）でのみ使用してください。

Codex は codex exec --full-auto を非推奨の互換性フラグとして維持し、警告を表示します。新しいスクリプトでは、明示的な --sandbox workspace-write フラグを使用してください。

$CODEX_HOME/config.toml を読み込まない実行が必要な場合は --ignore-user-config を使用し、管理された自動化環境でユーザーおよびプロジェクトの execpolicy .rules ファイルをスキップする必要がある場合は --ignore-rules を使用します。

required = true を指定して有効な MCP サーバーを設定している場合、その初期化に失敗すると、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 ツール呼び出し、Web 検索、計画の更新があります。

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 に準拠した最終レスポンスを要求します。 これは、安定したフィールドを必要とする自動化ワークフロー（ジョブの概要、リスクレポート、リリースメタデータなど）に役立ちます。

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

最終出力の例（stdout）。

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

自動化で認証する

デフォルトでは、codex exec は保存済みの CLI 認証を再利用します。CI では、認証情報を明示的に指定するのが一般的です。

API key 認証を使用する

GitHub Actions では、CLI を自分でインストールして認証する代わりに、Codex GitHub Actionを使用してください。このアクションは、Codex をインストールし、Responses API プロキシを起動し、設定可能な安全戦略で Codex を実行することで、API key の漏えいリスクを軽減するよう設計されています。

リポジトリによって制御されるコードをチェックアウトまたは実行するワークフローでは、OPENAI_API_KEY や CODEX_API_KEY をジョブレベルの環境変数として設定しないでください。同じジョブ内のビルドスクリプト、テスト、依存関係のライフサイクルフック、または侵害されたアクションが、それらの環境変数を読み取れる可能性があります。

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

1 回の実行で別の API key を使用するには、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 key をシェルステップへ渡す代わりに、openai/codex-actionを使用してください。このアクションは OpenAI API key 用の安全なプロキシを起動します。

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

1. メインの CI ワークフローがエラーで完了したときに、後続のワークフローを起動します。
2. リポジトリの読み取り権限のみを使用して、失敗したコミットをチェックアウトします。
3. OpenAI API key をそれらのステップへ公開せずに、Codex より前にセットアップコマンドを実行します。
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

高度な stdin パイプ

別のコマンドが Codex への入力を生成する場合は、指示の入力元に応じて stdin のパターンを選択します。指示がすでに決まっていて、パイプされた出力をコンテキストとして渡す場合は、プロンプト＋stdin を使用します。stdin 全体をプロンプトとして使用する場合は、codex exec - を使用します。

プロンプト＋stdin を使用する

プロンプト＋stdin は、別のコマンドが 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 -

stdin をプロンプトとして使用する場合は codex exec - を使用する

プロンプト引数を省略すると、Codex は stdin からプロンプトを読み取ります。その動作を明示的に強制するには、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