ChatGPT ドキュメント
日本語
お問い合わせ goolvyouyou@gmail.com

非対話モード

スクリプトや CI で Codex を実行するには codex exec を使用します

非対話モードでは、対話型 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

セッションのロールアウトファイルをディスクに保存したくない場合は、--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 ランナーやコンテナなど）でのみ使用してください。

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

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

有効な MCP server に required = true を設定していて初期化に失敗した場合、codex exec はその server なしで処理を続行せず、エラーで終了します。

機械可読な出力にする

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

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 exec 呼び出しにだけ 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 でのみサポートされています。

API key の代わりに Codex ユーザーアカウントで CI/CD ジョブを実行する必要がある場合にお読みください。たとえば、信頼できるランナー上で ChatGPT が管理する Codex アクセスを使用する企業チームや、API key の使用量制限ではなく ChatGPT/Codex のレート制限を利用する必要があるユーザーが対象です。

API key はプロビジョニングとローテーションが容易なため、自動化では適切なデフォルトです。Codex アカウントとして実行する必要がある場合にのみ、この方法を使用してください。

公開リポジトリやオープンソースリポジトリでは、このワークフローを使用しないでください。ランナーで codex login を使用できない場合は、安全なストレージを介して auth.json を配置し、ランナー上で Codex を実行してファイルをその場で更新させ、更新されたファイルを実行間で永続化します。

CI/CD で Codex アカウント認証を維持する（上級者向け）を参照してください。

非対話セッションを再開する

以前の実行を続行する必要がある場合（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

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 ログから pull request のコメント案を作成する

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