Codexのheadless実行入門｜codex execで非対話運用する方法

codex exec とは — 対話モードとの違い

codex exec（短縮形は codex e）は、Codex CLI の非対話実行サブコマンドだ。公式リファレンスは「スクリプトや CI 形式の実行で、人間の対話なしに完了する」ための実行形態と説明している（出典: https://developers.openai.com/codex/cli/reference ）。使い方は単純で、実行したいタスクをそのまま引数に渡す。

codex exec "失敗しているテストを調査して修正して"

プロンプト引数に - を指定すれば、標準入力からプロンプトをパイプで渡すこともできる。他のコマンドの出力を加工してそのまま Codex に流し込む、といった使い方がこれで可能になる（出典: https://developers.openai.com/codex/cli/reference ）。

通常の codex コマンドが対話画面を開き、ファイル変更やコマンド実行の場面で人の承認を挟みながら進むのに対し、exec は与えられたタスクを最後まで走り切る。この「人がその場で止められない」という一点が、対話モードとの本質的な違いであり、次節の安全設計がすべての前提になる理由でもある。なお --cd（-C）でワークスペースのルートを指定してから実行でき、-c key=value で設定を個別に上書きすることもできる。Codex CLI の機能全体は公式の機能ドキュメントにまとまっている（出典: https://developers.openai.com/codex/cli/features ）。

無人実行の安全設計 — サンドボックスと承認ポリシーを先に決める

headless 実行では、実行中の判断を人が肩代わりできない。そこで「どこまで任せるか」を実行前に 2 つの設定で決めておく。設定ファイル config.toml の sandbox_mode と approval_policy だ（出典: https://developers.openai.com/codex/config-reference ）。

sandbox_mode は、Codex が生成したコマンドのファイルシステム・ネットワークへのアクセス範囲を決める。read-only（読み取りのみ）、workspace-write（ワークスペース内への書き込みを許可）、danger-full-access（制限なし）の 3 段階があり、exec 実行時にも --sandbox（-s）フラグで同じ 3 値を指定できる。かつての --full-auto フラグは廃止予定とされ、--sandbox workspace-write の利用が推奨されている（出典: https://developers.openai.com/codex/cli/reference ）。サンドボックスは macOS では Seatbelt、Linux では bubblewrap といった OS 固有の仕組みで強制され、ネットワークアクセスは既定で制限される。書き込み先を広げたい場合も、サンドボックスを外すのではなく書き込み可能なルート（writable_roots）を広げる方法が推奨されている（出典: https://developers.openai.com/codex/concepts/sandboxing ）。動作の詳細はサンドボックスモードの記事で解説している。

approval_policy は、承認を求めるタイミングを決める。untrusted・on-request・never があり、公式リファレンスは on-request を対話実行用、never を非対話実行用と位置づけている（出典: https://developers.openai.com/codex/config-reference ）。つまり headless で走らせるなら承認を never にして自動化することになるが、その分の安全はサンドボックスで担保する——「承認を減らすほどサンドボックスを狭く」が基本の考え方だ。なお --dangerously-bypass-approvals-and-sandbox という承認とサンドボックスの両方を外すフラグも存在するが、名前が示すとおり無人実行での利用は危険であり、隔離された環境以外では避けたい（出典: https://developers.openai.com/codex/cli/reference ）。フラグの一覧はCLI オプションの記事を参照してほしい。

スクリプト・パイプラインへの組み込み

安全設計を決めたら、あとは通常のコマンドと同じようにシェルスクリプトや CI/CD パイプラインから呼び出せる。基本形はこうだ。

codex exec --sandbox workspace-write "CHANGELOG.md を最新のコミット履歴から更新して"

機械処理を前提にする場合は --json を付ける。整形済みテキストの代わりに、状態変化ごとに 1 件の改行区切り JSON イベントが出力されるため、進捗のログ化や後段ツールでの解析がしやすくなる。公式リファレンスは CI での利用について、--json と --output-last-message を組み合わせ、機械可読な進捗と最終的な自然言語サマリーの両方を取得する形を推奨している（出典: https://developers.openai.com/codex/cli/reference ）。Git リポジトリの外で実行したい場合は --skip-git-repo-check を付ける。

エージェントをパイプラインに組み込む流れは業界全体で進んでいる。2026 年 7 月 2 日には GitHub Copilot CLI が、GitHub のホストする CI/CD 環境からの利用で personal access token を不要にする認証の簡素化を発表し、同日にエージェントセッションをリアルタイムに観測できるストリーミングが public preview になった（出典: https://github.blog/changelog/label/copilot/ / https://github.blog/changelog/2026-07-02-copilot-agent-session-streaming-is-now-in-public-preview ）。「対話の外でエージェントを走らせ、成果だけ受け取る」使い方は、ツールを問わず標準になりつつある。

結果の受け取り — 出力と完了通知

headless 実行では結果の受け取り方も先に決めておきたい。出力は既定で整形済みテキストとして標準出力に流れ、前述の --json でイベントストリームに切り替えられる。最終的な回答だけが欲しい場合は --output-last-message（-o）でアシスタントの最終メッセージをファイルに書き出せるほか、--output-schema に JSON Schema ファイルを渡して最終応答の形を指定することもできる（出典: https://developers.openai.com/codex/cli/reference ）。

完了を待たずに別の作業へ移るなら、通知の仕組みが役に立つ。config.toml の notify に呼び出したいプログラムを設定しておくと、Codex が通知を発するタイミングでそのプログラムが実行され、JSON 形式の情報が渡される。これをデスクトップ通知やチャットへの投稿につなげれば、「走らせて、終わったら知らせてもらう」型が完成する（出典: https://developers.openai.com/codex/config-reference ）。

途中から人が引き継ぐ — exec resume

非対話で走らせた結果を見て、続きは人が対話で詰めたい——そんなときのために codex exec resume がある。セッション ID を指定して既存セッションを再開でき、--last を付ければ現在のディレクトリで最新のセッションを続行、--all で全ディレクトリのセッションを対象にできる。追いかけのプロンプトをそのまま渡すことも可能だ（出典: https://developers.openai.com/codex/cli/reference ）。セッション再開の詳しい使い方はresume の記事に、ローカルではなくクラウドでタスクを走らせる選択肢はCodex クラウドの記事にまとめている。

まとめ — 任せる範囲を設計してから走らせる

headless 実行の基本は、「任せる範囲を先に設計し、結果を受け取る仕組みを整えてから走らせる」ことに尽きる。サンドボックスと承認ポリシーで安全の枠を決め、--json や --output-last-message、notify で受け取りを仕組みにし、必要なら exec resume で人が引き継ぐ——いずれも公式機能の組み合わせで今日から始められる（出典: https://developers.openai.com/codex/cli/reference ）。エージェントが働く環境を設計する側に回るというハーネス設計の考え方の、最初の実践場面が非対話運用だ。