非対話モード¶
非対話モードを使うと、インタラクティブな TUI を開かずに、スクリプト（たとえば継続的インテグレーション（CI）ジョブ）から Codex を実行できます。
codex exec で呼び出します。
フラグの詳細については、codex exec を参照してください。
codex exec を使用する場合¶
次のような処理を Codex に実行させたい場合は、codex exec を使用します。
- パイプライン（CI、マージ前チェック、スケジュールされたジョブ）の一部として実行する。
- 他のツールにパイプできる出力を生成する（たとえば、リリースノートや要約を生成する）。
- コマンドの出力を Codex に渡し、Codex の出力を他のツールに渡す CLI ワークフローに自然に組み込む。
- サンドボックスと承認の設定を明示的かつ事前に指定して実行する。
基本的な使い方¶
タスクのプロンプトを単一の引数として渡します。
codex exec の実行中、Codex は進行状況を stderr にストリーミングし、最終的なエージェントメッセージだけを stdout に出力します。これにより、最終結果を簡単にリダイレクトまたはパイプできます。
セッションのロールアウトファイルをディスクに保存したくない場合は、--ephemeral を使用します。
標準入力がパイプされていて、さらにプロンプト引数も指定した場合、Codex はプロンプトを指示として扱い、パイプされた内容を追加のコンテキストとして扱います。
これにより、1 つのコマンドで入力を生成し、それを直接 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 ランナーやコンテナ）でのみ使用してください。
Codex は codex exec --full-auto を非推奨の互換性フラグとして引き続き保持し、警告を出力します。新しいスクリプトでは、明示的な --sandbox workspace-write フラグを優先してください。
--ignore-user-config は、$CODEX_HOME/config.toml を読み込まない実行が必要な場合に使用し、管理された自動化環境でユーザーおよびプロジェクトの execpolicy .rules ファイルをスキップする必要がある場合は --ignore-rules を使用します。
有効化された MCP サーバーを required = true で設定し、その初期化に失敗した場合、codex exec はそのサーバーなしで続行せず、エラー終了します。
出力を機械可読にする¶
スクリプトで Codex の出力を利用するには、JSON Lines 出力を使用します。
--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> を使ってファイルに書き込めます。これにより最終メッセージがファイルに書き込まれ、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 は、デフォルトで保存済みの CLI 認証を再利用します。CI では、認証情報を明示的に指定するのが一般的です。
API キー認証を使用する¶
GitHub Actions では、CLI を自分でインストールして認証する代わりに、Codex GitHub Action を使用してください。この Action は、Codex のインストール、Responses API プロキシの起動、設定可能な安全性戦略による Codex の実行を行うことで、API キーの露出を抑えるように設計されています。
リポジトリ管理下のコードをチェックアウトまたは実行するワークフローでは、OPENAI_API_KEY または CODEX_API_KEY をジョブレベルの環境変数として設定しないでください。同じジョブ内のビルドスクリプト、テスト、依存関係のライフサイクルフック、または侵害された Action が、これらの環境変数を読み取る可能性があります。
その他の自動化環境では、CODEX_API_KEY を単一の codex exec 呼び出しに対してのみ設定し、同じプロセス環境で信頼できないコードが実行されないようにしてください。
1 回の実行で別の API キーを使用するには、CODEX_API_KEY をインラインで設定します。
CODEX_API_KEY は codex exec でのみサポートされます。
API キーは、プロビジョニングとローテーションが簡単なため、自動化における適切なデフォルトです。Codex アカウントとして実行する必要が明確にある場合にのみ、この方法を使用してください。
~/.codex/auth.json はパスワードと同じように扱ってください。アクセス トークンが含まれています。コミットしたり、チケットに貼り付けたり、チャットで共有したりしないでください。
公開リポジトリやオープンソースリポジトリでは、このワークフローを使用しないでください。ランナーで codex login が利用できない場合は、安全なストレージを通じて auth.json を用意し、ランナー上で Codex を実行して 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 キーをシェルステップに渡す代わりに、openai/codex-action を使用してください。この Action は OpenAI API キー用の安全なプロキシを起動します。
Codex を使って、CI ワークフローが失敗したときに修正を自動的に提案できます。パターンは次のとおりです。
- メイン CI ワークフローがエラーで完了したときに、後続のワークフローをトリガーします。
- リポジトリの読み取り権限のみを使用して、失敗したコミットをチェックアウトします。
- Codex の前にセットアップコマンドを実行します。その際、それらのステップに OpenAI API キーを公開しないでください。
- Codex GitHub Action を実行します。
- Codex によるローカル変更をパッチアーティファクトとして保存します。
- 別のジョブでパッチを適用し、プルリクエストを作成します。
以下の 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
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 ログからプルリクエストのコメントの下書きを作成する¶
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 に渡す場合に適しています。