codex execの使い方｜非対話実行のフラグとCI運用の注意点

Codex CLIの codex exec は、対話画面を開かずにプロンプト1つを渡して実行し、結果を標準出力へ返す非対話モードです。基本形は codex exec "依頼文" で、スクリプトやCIから呼ぶために用意されています。OpenAI公式のCLIコマンドリファレンスにも、スクリプトやCI向けで人の操作なしに終わる実行に使うコマンドとして載っています（確認日 2026年10月16日）。

この記事は、codex exec だけに絞って、基本の書き方、モデル指定、サンドボックスと承認、出力の受け取り方、セッションの再開、認証とCIの注意を順に整理します。公式ページで当日確認できたコマンド名とフラグ名だけを使い、確認できなかった点はその旨を書きます。承認モード全体の考え方は承認モードとサンドボックスの記事、設定ファイルはconfig.tomlの記事に任せ、ここでは exec で何を指定するかに話を限ります。

codex execとは何か

codex exec は、Codex CLIを対話せずに1回の依頼として実行するコマンドで、短い形の codex e でも呼べます。

CLIリファレンスの説明では、スクリプトやCIのように人の確認を挟まず終わらせたい実行に使うコマンドです。普段の codex は画面の中で会話しながら進めますが、exec は依頼を渡すと作業して終了します。そのため、出力の形、権限、認証をあらかじめ指定しておく必要があります。以降の節は、この3点を順に決めていく構成です。

最小のコマンドと標準入力の使い方

最小の書き方は codex exec "依頼文" で、進行状況は標準エラー出力へ流れ、最終的なエージェントの返答だけが標準出力に出ます。

非対話モードのページには、プロンプトを渡して実行する例があり、進行状況はstderr、最終メッセージだけがstdoutへ出ると書かれています。この分かれ方のおかげで、codex exec "..." > result.txt のようにリダイレクトすると、返答だけがファイルに入ります。

依頼文は標準入力でも渡せます。同じ非対話モードのページによると、プロンプトの引数と標準入力の両方がある場合、引数が指示になり、パイプで流した内容は追加の文脈として扱われます。また、CLIリファレンスのPROMPT欄には、- を指定すると標準入力から読むと書かれています。

モデルを指定する（-m）

モデルは --model または短縮形の -m で、その1回の実行に限って設定済みのモデルを上書きして指定します。

CLIリファレンスのこのフラグの説明は、設定されているモデルをこの実行だけ上書きする、という趣旨です。Codexのモデルのページにも、起動時に --model か -m で選べること、同じ指定が非対話の実行でも使えることが書かれ、例として codex exec -m gpt-6.1-sol "Review the current changes" が載っています。

同ページで確認できたモデルIDは gpt-6-astra、gpt-6.1-sol、gpt-6-luna です。公式は、複雑なコーディングやエージェント的な作業にはアカウントとクライアントで使えるなら GPT-6.1 Sol を使うよう案内し、焦点の定まった繰り返しの作業には Luna を挙げています。GPT-Astra は、同じ公式情報で最も高性能なモデルと位置づけられています。選び方の目安を表にします。

右列は公式の位置づけを踏まえた編集部の当てはめで、公式がexecでの使い分けまで書いているわけではありません。提供状況はアカウントやクライアントで変わると公式が書いているため、スクリプトに固定する前に、手元で -m を付けた実行が通るかを一度試してください。モデル指定を毎回書かずに既定にしたい場合は、設定ファイルの model に書く方法があります。詳しくはconfig.tomlの記事を見てください。料金やプランごとの利用範囲はCodexの無料範囲を整理した記事で扱っています。

サンドボックスと承認の指定

codex exec のサンドボックスは --sandbox（短縮形 -s）で read-only、workspace-write、danger-full-access から選び、非対話モードのページは既定を読み取り専用と説明しています。

非対話モードのページは、既定では読み取り専用のサンドボックスで動くと説明し、編集を許すなら --sandbox workspace-write、より広い権限は --sandbox danger-full-access と書いています。後者は管理された環境でだけ使うよう注意されています。一方、CLIリファレンスの --sandbox の欄は、既定を設定に従うと書いています。2つのページの表現は同じではないので、スクリプトでは既定に頼らず、--sandbox を明示するのが安全です。

承認まわりのフラグも整理します。リファレンスには、自動の承認レビューを使い、承認を on-request、サンドボックスを workspace-write にする --approve-for-me（別名 --not-so-yolo）があります。このフラグは --sandbox や --yolo と併用できないと書かれています。承認とサンドボックスを丸ごと外す --dangerously-bypass-approvals-and-sandbox（別名 --yolo）は、隔離されたランナーの中だけで使うよう公式が警告しています。

古い記事や手順では --full-auto が出てきますが、非対話モードのページは、現在は対応しておらず、代わりに --sandbox workspace-write か --approve-for-me を使うと書いています。手元のスクリプトに --full-auto が残っていないか確認してください。承認ポリシーとサンドボックスの組み合わせの考え方は承認モードとサンドボックスの記事にまとめてあります。なお、この記事では exec で --ask-for-approval がどう扱われるかまでは確認していません。

出力の受け取り方（標準出力・JSON・ファイル）

codex exec の出力は、標準出力の最終メッセージ、--json のイベント列、-o で書き出すファイルなどの形で受け取れます。

既定では最終メッセージだけが標準出力に出ます。イベントごとの記録が欲しいときは --json を付けます。非対話モードのページによると、標準出力にJSON Lines（1行1イベントのJSON）が出て、イベントの種類には thread.started、turn.completed、error などがあります。CLIリファレンスでは、フラグ名は --json、別名として --experimental-json が載っています。最終メッセージだけをファイルに残すなら -o パス（--output-last-message）で、同じページによれば返答は標準出力にも表示されます。

回答の形を固定する場合は --output-schema にJSON Schemaのファイルを渡します。非対話モードのページには codex exec "Extract project metadata" --output-schema ./schema.json -o ./project-metadata.json という使い方の例があり、リファレンスでは、期待する最終回答の形を表すJSON Schemaファイルと説明されています。

具体例を1つ置きます。次は、読み取り専用で差分を確認させ、結果をJSONファイルに保存する流れです。すべて仮の例で、ファイル名は読み替えてください。

git diff main...HEAD | codex exec \
  --sandbox read-only \
  --output-schema ./review-schema.json \
  -o ./review.json \
  "この差分で壊れそうな箇所を、review-schema.jsonの形で出して"

この例では、パイプの差分が文脈、引数が指示です。サンドボックスが読み取り専用なので、ファイルは書き換わりません。出力はスキーマに沿った形で review.json に入り、後続のスクリプトがそのまま読めます。

作業ディレクトリ・Git・設定まわりのフラグ

作業ディレクトリは --cd（-C）で指定し、Gitリポジトリの外で動かす場合だけ --skip-git-repo-check を付けます。

非対話モードのページは、破壊的な変更を防ぐため、コマンドはGitリポジトリの中で実行する必要があると説明し、環境が安全な場合に限って --skip-git-repo-check で上書きするよう案内しています。CLIリファレンスの説明は、作業の根を実行前に設定する --cd と、一時的なディレクトリで動かすのに便利とされる --skip-git-repo-check です。そのほかの主なフラグを表にします。

CIのログに色の制御文字が混ざるのが気になる場合は --color never が使えます。利用者ごとの設定に左右されたくない場面では --ignore-user-config と -c を組み合わせると、実行の再現性を保ちやすくなります。これは公式の説明を踏まえた編集部の整理です。また、非対話モードのページには、required = true のMCPサーバーが初期化に失敗すると exec がエラーで終了するとも書かれています。MCPの設定はMCP連携の記事で確認できます。リポジトリの指示ファイルを整える方法はAGENTS.mdの記事にあります。

セッションを再開する（exec resume）

直前の実行の続きから依頼するには codex exec resume --last "続きの依頼"、特定のセッションなら codex exec resume セッションID を使います。

CLIリファレンスのresumeの項では、セッションIDで再開するか、--last で現在の作業ディレクトリの直近のセッションを続けると説明されています。--all を付けると、直近のセッションを選ぶ範囲が現在のディレクトリの外にも広がります。続きの依頼文を後ろに付けると、再開と同時に送られます。

リファレンスのSESSION_IDの欄はUUIDまたはセッション名と記載されています。なお、前のセクションの --ephemeral を付けた実行は記録を残さないので、あとから再開する前提の作業には付けないでください。これは公式の説明からの編集部の推論です。再開時にモデルやサンドボックスの指定がどう引き継がれるかは、確認したページでは見つけられなかったため、再開側でも必要な指定を明示して動作を確かめることをおすすめします。

認証とAPIキーの扱い

codex exec は既定で保存済みのCLI認証を再利用し、1回の実行だけAPIキーを使いたい場合は CODEX_API_KEY をその実行に付けて渡します。

非対話モードのページによると、CODEX_API_KEY は1回の実行に限ってインラインで設定でき、codex review やTypeScript SDKにも使えます。CIのような自動実行では、人がログインできないため、この認証をどう用意するかが最初の決めごとです。ChatGPTの管理下の認証をCIで使う方法は、信頼できるランナー向けの上級者向けの選択肢とされ、公開リポジトリやオープンソースのリポジトリでは使わないよう書かれています。

表の「履歴にキーが残らない書き方」は編集部の注意で、公式が書いた手順ではありません。キーそのものをコマンドの文字列やリポジトリに書き込まないことが基本です。無料枠やAPIキー利用時の課金の違いは、このサイトのCodexの無料範囲の記事に整理してあります。

CIで使う時の権限と秘密情報の注意

CIで codex exec を使うときは、読み取り専用の実行と書き込みの権限を別のジョブに分け、APIキーをリポジトリ内のコードを動かすジョブへ渡さない構成が、公式の例に沿った考え方です。

非対話モードのページは、リポジトリで管理されたコードを動かすワークフローで、OPENAI_API_KEY や CODEX_API_KEY をジョブ全体の環境変数として設定しないよう警告しています。GitHub Actionsでは、CLIを自分でインストールしてAPIキーをシェルのステップへ渡すより、openai/codex-action を使うことを勧めています。さらに、自動修正の例として、読み取り専用のCodexのジョブがパッチをアーティファクトとして出し、別の書き込み権限のあるジョブがAPIキーを受け取らずにプルリクエストを開く構成が載っています。

この表は、公式の自動修正の例の構成を、役割ごとに並べ直した編集部の整理です。ポイントは、書き込み権限を持つジョブにはAIの実行もキーも置かず、AIを動かすジョブには書き込み権限を渡さないことです。権限と秘密情報を同じ場所に集めないことが、設計の軸になります。

運用に入る前の確認項目として、次の点を手元で試してください。1つ目は --sandbox を明示しているか。2つ目は --full-auto のような古いフラグが残っていないか。3つ目は --yolo を隔離されていない環境で使っていないか。4つ目はAPIキーがログやジョブ全体の環境変数に出ていないか。コードレビューの自動化を考えている場合はCodexのコードレビューの記事も参考になります。

目的別の組み合わせ早見表

codex exec のフラグは、やりたいことから逆引きすると決めやすく、調査・修正・データ抽出・隔離環境での作業で組み合わせが変わります。

ここまでのフラグを、場面ごとの組み合わせとして並べます。いずれもCLIリファレンスのフラグ名を使った編集部の組み合わせ例で、公式がこの組み合わせを推奨しているわけではありません。

よくある質問（FAQ）

Q1. codex exec と普通の codex は何が違いますか。

対話画面を開かずに、依頼を1回渡して終わるかどうかです。公式のリファレンスは、人の操作なしで終わらせたいスクリプトやCI向けの実行と説明しています。詳細はCLIリファレンスを見てください。

Q2. exec は既定でファイルを書き換えますか。

非対話モードのページは、既定では読み取り専用のサンドボックスで動くと書いています。ただしCLIリファレンスは既定を設定に従うと書いているので、書き換えを許すかどうかは --sandbox で明示してください。

Q3. モデルは設定ファイルと -m のどちらが優先されますか。

リファレンスは、-m を設定済みのモデルを、その実行に限って上書きするものと説明しています。設定ファイルの model は既定の指定として使えます。

Q4. 出力をほかのプログラムで処理するには。

イベントを追うなら --json、最終回答だけなら -o、回答の形を決めたいなら --output-schema を使います。組み合わせの例は「出力の受け取り方」の節にあります。

Q5. Gitリポジトリの外で実行できますか。

公式は、破壊的な変更を防ぐため既定ではGitリポジトリの中での実行を求めており、環境が安全な場合に限って --skip-git-repo-check で上書きできると案内しています。

Q6. 以前の手順にあった --full-auto は使えますか。

非対話モードのページは、現在は対応していないと書いています。--sandbox workspace-write か --approve-for-me に置き換えてください。

Q7. CIでAPIキーをどう扱えばよいですか。

公式は、リポジトリのコードを動かすワークフローでキーをジョブ全体の環境変数にしないよう警告し、GitHub Actionsでは openai/codex-action を勧めています。構成の例は「CIで使う時の権限と秘密情報の注意」の節にあります。

まとめ

codex exec を安全に使う要点は、依頼を渡す形、権限、出力、認証を、実行のたびに明示することです。確認日は2026年10月16日で、フラグの名前や既定は更新されることがあるため、実際に組み込む前に非対話モードのページとCLIリファレンスを開いて見比べてください。対話での使い方はスラッシュコマンドの記事、全体像は提供形態の違いの記事にあります。