codex exec の基本的な使い方
（非対話モード）

by
  • codex execはCodexエージェントを非対話モードで動かすコマンドで、CIパイプラインやスクリプトへの組み込みを前提に設計されています。
  • 実行権限はデフォルトで確認付きですが、--full-autoで確認を省略し、-sオプションでサンドボックスポリシーを細かく制御できます。
  • モデルや作業ディレクトリ、出力形式はオプションで柔軟に指定でき、JSONLによるログ出力やJSONスキーマによる構造化レスポンスにも対応しています。
  • セッションの保存と再開、画像添付、コードレビュー実行など、自動化ワークフローに必要な機能をひとつのコマンドで提供します。

関連記事

1. プロンプトを与える基本構文

codex exec はCodexエージェントを非対話モードで動かすサブコマンドです。
スクリプトやCIパイプラインに組み込むことを前提に設計されています1。

codex exec [OPTIONS] [PROMPT]
Code language: CSS (css)

プロンプトは引数として渡すか、- を指定してstdinから読み込みます2。

# 引数として渡す
codex exec "テストを全部実行してエラーを修正して"

# stdinから渡す
echo "READMEを英語に翻訳して" | codex exec -
Code language: PHP (php)

1.1. よく使う組み合わせパターン

CI環境でテスト修正を自動化する場合：

codex exec \
  --full-auto \
  --json \
  -o ci-summary.txt \
  -C ./src \
  "失敗しているテストを特定して修正して"
Code language: JavaScript (javascript)

ローカルで画像をもとにコード生成する場合：

codex exec \
  -m o3 \
  -i screenshot.png \
  -s workspace-write \
  "スクリーンショットのフォームをHTMLとCSSで実装して"
Code language: JavaScript (javascript)

1.2. 画像の添付

-i / --image で画像ファイルを初期プロンプトに添付します。

codex exec -i mockup.png "このデザインをReactコンポーネントで実装して"
Code language: JavaScript (javascript)

UIのスクリーンショットを渡してコードを生成させる使い方が典型です3。

2. 作業ディレクトリの指定

-C / --cd でエージェントの作業ルートを指定します。

リポジトリのサブディレクトリだけを触らせたいときに使います4。

codex exec -C ./backend "APIのエンドポイントにバリデーションを追加して"
Code language: JavaScript (javascript)

--add-dir は主ワークスペースに加えて書き込みを許可するディレクトリを追加します5。

codex exec --full-auto --add-dir ../shared "共有ライブラリを更新して"
Code language: JavaScript (javascript)

--skip-git-repo-check はGitリポジトリ外でも実行できます。バージョン管理外のディレクトリでスクリプト生成やドキュメント作業をするときに使います6。

2.1. セッション管理

--ephemeral はセッションファイルをディスクに保存しません。

セッション管理 –ephemeral 使い捨て セッションを ディスクに保存しない 機密データ処理に適する resume セッション再開 –last　最新セッションを再開 session-id　IDで再開 codex exec — セッション管理

使い捨ての処理や機密データを含む作業に向きます7。

codex exec --ephemeral --full-auto "環境変数の設定ファイルを生成して"
Code language: JavaScript (javascript)

resume サブコマンドで以前のセッションを再開できます8。

# 最新のセッションを再開
codex exec resume --last

# IDを指定して再開
codex exec resume <session-id>
Code language: PHP (php)

3. 実行権限の制御

codex execは、デフォルトではコマンド実行前に確認を求め、自動実行の範囲を広げるにはオプションで明示的に求める設計になっています9。

実行権限の制御 デフォルト 確認プロンプト 実行前に承認 を求める ▶ –full-auto 確認スキップ workspace内 書き込み許可 ▶ danger-full-access 制限なし 外部隔離済み 環境専用 codex exec — 実行権限の制御

--full-auto はワークスペース内のファイルへの書き込みを許可し、確認なしで実行します。ローカル開発で最もよく使うフラグです10。

codex exec --full-auto "依存パッケージを最新化してテストを通して"
Code language: JavaScript (javascript)

-s / --sandbox は実行環境のポリシーを細かく選べます。

# 読み取り専用（書き込みは不可）
codex exec -s read-only "このコードの問題点を列挙して"

# ワークスペース内のみ書き込み可
codex exec -s workspace-write "リファクタリングして"

# サンドボックスなし（外部で隔離済みの環境専用）
codex exec -s danger-full-access "..."
Code language: PHP (php)

--dangerously-bypass-approvals-and-sandbox は確認プロンプトとサンドボックスをすべて無効化します。Dockerなどで外部からすでに隔離されている環境専用です11。

3.1. –full-auto と -s workspace-write の違い

どちらもワークスペース内への書き込みを許可しますが、意味が異なります。-s workspace-write はサンドボックスのポリシーだけを設定するオプションで、確認プロンプトはそのまま残ります。--full-auto は -s workspace-write に加えて確認プロンプトも省略する、複数オプションをまとめた便利エイリアスです。「確認なしで動かしたい」なら --full-auto、「書き込みは許可するが実行前に確認したい」なら -s workspace-write を使い分けてください12。

3.2. –dangerously-bypass-approvals-and-sandbox と -s danger-full-access の違い

-s danger-full-access はサンドボックスを外しますが、確認プロンプトは残ります。--dangerously-bypass-approvals-and-sandbox は確認もサンドボックスも両方なくします。名前が長い分だけ、使う前に一拍置いて判断してほしいという意図が込められています13。

4. モデルと設定の指定

-m / --model で使用するモデルを切り替えます14。

モデルと設定の指定 -m / –model モデル切替 -m o3 セッション単位 -c / –config 一時上書き config.tomlを セッション内で上書き -p / –profile プロファイル読込 プロジェクトごとの 設定セットを適用 codex exec — モデルと設定の指定 
codex exec -m o3 "パフォーマンスを改善して"
Code language: JavaScript (javascript)

-c / --config は ~/.codex/config.toml の値を一時的に上書きします。ドット区切りでネストしたキーも指定できます15。

codex exec -c model="o3" -c 'sandbox_permissions=["disk-full-read-access"]' "..."
codex exec -c shell_environment_policy.inherit=all "..."
Code language: JavaScript (javascript)

-p / --profile は config.toml に定義したプロファイルを読み込みます。プロジェクトごとにモデルや権限をまとめておく使い方が向いています16。

codex exec -p ci-profile "テストを実行して"
Code language: JavaScript (javascript)

4.1. -c と -p の違い

-p はあらかじめ config.toml に書いておいたプロファイルを丸ごと読み込むオプションです。
-c はそのセッションだけに有効な個別の上書きで、-p で読み込んだ値にさらに重ねて使えます。
繰り返し使う設定はプロファイルにまとめ、一時的な調整に -c を使うのが自然な使い方です17。

5. 出力の制御

-o / --output-last-message はエージェントの最後のメッセージを指定ファイルに書き出します。

出力の制御 -o / –output 最終メッセージ ファイルに保存 人が読む要約向き ▶ –json 全イベント出力 JSONL形式 途中経過も取得 ▶ –output-schema 構造化出力 JSONスキーマ指定 形式を保証 -o ＝ 最終結果のみ保存　　–json ＝ 全ログをパース –output-schema ＝ 構造化データを確実に受け取る codex exec — 出力の制御

CIで結果をキャプチャするのに使えます18。

codex exec --full-auto -o result.txt "変更内容をまとめて"
Code language: JavaScript (javascript)

--json は実行イベントをJSONL形式でstdoutに出力します。ログ収集や後処理スクリプトと組み合わせるときに便利です19。

codex exec --json "..." | jq 'select(.type == "message")'
Code language: JavaScript (javascript)

--output-schema でモデルの最終応答の形式をJSONスキーマで指定できます。構造化データを確実に受け取りたい場合に使います20。

codex exec --output-schema schema.json "依存パッケージの一覧をJSONで出力して"
Code language: JavaScript (javascript)

5.1. -o と –json の違い

-o はエージェントが最後に出力したメッセージだけをファイルに書き出します。人が読む要約や最終回答を保存するのに向いています。--json はすべての実行イベントをJSONL形式でstdoutに流し続けます。処理の途中経過も含めてパースしたい場合に使うもので、-o とは取得する情報量がまったく異なります21。

6. コードレビュー

review サブコマンドは現在のリポジトリに対してコードレビューを実行します22。

codex exec review
codex exec -m o3 review
  1. Codex CLIはRustで書かれたオープンソースのコーディングエージェントです。npmでインストールして使えます。ChatGPT Plus・Pro・Business・Edu・Enterpriseプランに含まれています。 – Codex CLI
  2. codex exec は codex e と短縮できます。非対話型で完結する処理向けに設計されており、TUI（ターミナルUI）は起動しません。 – Non-interactive mode
  3. 対応フォーマットはPNGとJPEGです。複数ファイルはカンマ区切りか -i を繰り返して指定できます。 – Codex CLI features
  4. workspace-write モードでは .git、.codex、.agents ディレクトリが書き込みから保護されます。これらのパスは再帰的に読み取り専用として扱われます。 – Security
  5. フラグは複数回繰り返せます。例：--add-dir ../shared --add-dir ../config のように指定できます。 – Command line options
  6. Codexはデフォルトでリポジトリ外での実行を拒否します。これは破壊的な変更を防ぐための意図的な制約です。 – Non-interactive mode
  7. 通常のセッションファイルは $CODEX_HOME（デフォルトは ~/.codex）以下に保存されます。環境変数 CODEX_HOME で保存先を変更できます。 – Advanced Configuration
  8. resume はフォローアッププロンプトも受け取れます。例：codex exec resume --last "見つけた問題を修正して"。会話コンテキストは引き継がれますが、フラグ（モデルやサンドボックス設定など）は再指定が必要です。 – Non-interactive mode
  9. デフォルトの codex exec は読み取り専用サンドボックスで動きます。ファイルへの書き込みを許可するには -s workspace-write か --full-auto を明示する必要があります。 – Non-interactive mode
  10. --full-auto は workspace-write サンドボックスと on-request 承認ポリシーを同時に設定するエイリアスです。確認プロンプトを省略する never 承認が組み合わさっています。 – Command line options
  11. このフラグは --yolo という別名でも指定できます。社内ガイドラインなどで管理者が requirements.toml で sandbox_mode = "danger-full-access" を禁止している環境では動作しません。 – Security
  12. workspace-write モードでもデフォルトはネットワークアクセスが無効です。外部APIへのアクセスが必要な場合は config.toml の [sandbox_workspace_write] セクションで network_access = true を設定します。 – Advanced Configuration
  13. 公式ドキュメントでは --full-auto と --dangerously-bypass-approvals-and-sandbox を同時に使うことを明示的に非推奨としています。外部でサンドボックス済みのVM内でのみ組み合わせてください。 – Command line options
  14. モデル名は model キーとして config.toml にデフォルト値を書いておけます。-m は1回の実行だけに有効な上書きです。 – Config basics
  15. -c の値はTOML形式でパースされます。JSONではない点に注意が必要です。パースできない場合はリテラル文字列として扱われます。 – Advanced Configuration
  16. プロファイル機能は現時点で試験的（experimental）な扱いです。将来変更・廃止される可能性があり、Codex IDEエクステンションでは未対応です。 – Advanced Configuration
  17. 設定の優先順位は「コマンドラインの -c」が最も高く、次に「プロファイル値」、その下に「ユーザー設定 (~/.codex/config.toml)」、さらにその下に「プロジェクト設定 (.codex/config.toml)」と続きます。 – Config basics
  18. シェルのリダイレクト（>）でも同じことができますが、-o はその実行専用のオプションです。--output-schema と組み合わせると、最終的なJSON出力だけをファイルに保存できます。 – Non-interactive mode (docs.onlinetool.cc)
  19. --json で出力されるイベントタイプには thread.started、turn.started、turn.completed、turn.failed、item.*、error があります。アイテムタイプにはエージェントメッセージ、推論、コマンド実行、ファイル変更、MCPツール呼び出し、ウェブ検索、プラン更新が含まれます。 – Non-interactive mode
  20. Codexは出力をスキーマに対して検証します。-o と組み合わせると最終JSONだけをファイルに保存できます。JSON SchemaはDraft 7に準拠したファイルを指定します。 – Non-interactive mode (docs.onlinetool.cc)
  21. セッションのJSONLログは --ephemeral を指定しない限り $CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl に自動保存されます。--json のstdout出力とは別物です。 – GitHub Issue #2288
  22. review には --uncommitted（未コミットの変更）、--base <branch>（ベースブランチとの差分）、--commit <hash>（特定コミット）などのオプションがあります。カスタム指示を追加することもできます。例：codex exec review --uncommitted "セキュリティの問題に絞って"。 – Smithery Codex Skill