codex execとは？使い方と権限・JSON出力・CIでの注意

codex execとは：対話なしでCodexに仕事を任せるコマンド

ふだんのcodexは、ターミナルの中に対話画面（TUI）を開き、やり取りしながら作業を進めます。codex execは、この対話画面を開かずに、依頼を1つ受け取って最後まで進め、結果を返して終了します。短い形のcodex eでも同じように動きます。

公式のNon-interactive mode資料は、次のような場面での利用を挙げています。

• CI、マージ前の確認、定期実行の仕事の一部として動かす
• リリースノートや要約など、ほかのツールに渡せる出力を作る
• ほかのコマンドの出力をCodexに渡し、Codexの出力をさらに次のツールへ渡す
• サンドボックスと承認の設定を先に決めておき、その条件で動かす

人が画面の前で相談しながら進める仕事は対話画面、手順が決まっていて結果だけ欲しい仕事はcodex exec、と分けると使いどころを決めやすくなります。Codex CLIをまだ入れていない方は、先にCodex CLIのインストール方法と初回設定を済ませてください。

codex execの基本の使い方

依頼文を1つ渡して実行する

いちばん簡単な使い方は、依頼文を1つの引数として渡す形です。指定できるオプションの一覧は、公式のCommand line optionsのcodex execの項にあります。

codex exec "このリポジトリの構成を要約し、注意が必要な箇所を5つ挙げて"

実行中の途中経過は、経過やエラーの表示用の出口（標準エラー出力）に流れ、通常の出力先（標準出力）には最後の返答だけが出ます。そのため、結果をそのままファイルに保存したり、次のコマンドへ渡したりできます。

codex exec "直近10件のコミットからリリースノートを作って" | tee release-notes.md

ほかのコマンドの出力を材料として渡す

依頼文を引数で渡しつつ、パイプで別の内容を流し込むと、Codexは、引数を指示として、流し込んだ内容を追加の材料として扱います。手元のcodex exec --helpでは、流し込んだ内容は<stdin>というまとまりとして依頼文の後ろに付け足される、と説明されています。テストの失敗ログを要約させる例は次のとおりです。

npm test 2>&1 | codex exec "失敗したテストを要約し、いちばん小さい修正案を出して" | tee test-summary.md

依頼文そのものをファイルやスクリプトで組み立てる場合は、引数の代わりに-を置くと、流し込んだ内容全体が依頼文になります。

cat prompt.txt | codex exec -

codex execを編集部で実行した結果

編集部は、わざと誤りを入れた1ファイルだけの練習用リポジトリを作り、Codex CLI 0.163.0で3回実行しました。calc.pyのadd関数が、足し算ではなく引き算を返す状態です。個人の設定の影響を避けるため、3回とも$CODEX_HOME/config.toml（既定は~/.codex/config.toml）を読み込まない--ignore-user-configと、セッションの記録をディスクに保存しない--ephemeralを付けています。

2回目と3回目の開始時、標準エラー出力には動作条件の一覧が出ました。権限を指定しなかった2回目は、approval: never（人に承認を求めない）とsandbox: read-only（読み取り専用）でした。workspace-writeを指定した3回目は、書き込める場所として作業フォルダーと/tmp、$TMPDIRが表示されました。2回目と3回目は、標準出力に出たのが最後の返答（2回目はJSON）だけでした。

--jsonを付けた1回目は、実行中の出来事（イベント）が1行に1つずつ標準出力に出ました。最後の返答は、-oで指定したファイルにも保存されています。7行の順番は次のとおりです。

{"type":"thread.started", ...}
{"type":"turn.started"}
{"type":"item.completed","item":{"type":"agent_message", ...}}
{"type":"item.started","item":{"type":"command_execution","command":"/bin/zsh -lc 'cat calc.py'", ...}}
{"type":"item.completed","item":{"type":"command_execution", ...}}
{"type":"item.completed","item":{"type":"agent_message","text":"`calc.py` の `add(a, b)` は加算ではなく `a - b` を返しているため、`a + b` にする必要があります。"}}
{"type":"turn.completed","usage":{"input_tokens":28517,"cached_input_tokens":26368,"output_tokens":91, ...}}

長い値は「...」で省略しています。トークン数は今回の1回分の記録で、依頼の内容やリポジトリの大きさで変わります。

codex execの権限：サンドボックスの3段階

公式資料によると、codex execは何も指定しなければ、読み取り専用のサンドボックス（Codexが触れる範囲を区切る仕組み）で動きます。自動で動かす時は、その仕事に必要な最小の権限だけを渡すのが基本です。

公式資料によると、workspace-writeでも既定ではネットワークを使えず、.gitなどのフォルダーは読み取り専用のまま守られます。編集部の3回目では、作業フォルダーのほかに/tmpと$TMPDIRも書き込める場所として表示されました。書き込める場所を足したい時は、danger-full-accessにするのではなく、--add-dirでフォルダーを追加します。

--full-autoは使えなくなった

古い記事でよく見かける--full-autoについて、現在の公式資料はサポートを終了したと書いています。編集部の0.163.0でも、--full-autoを付けると「unexpected argument」というエラーになり、Codexは動きませんでした。古いスクリプトは--sandbox workspace-writeに書き換えてください。承認が必要な場面を、人の代わりに自動のレビューへ回したい時は--approve-for-meを使います。こちらもworkspace-writeのサンドボックスで動きますが、--sandboxと同時には付けられません。自動のレビューにもAIモデルを使うため、その分だけ呼び出しの回数（利用量）が増えます。

個人の設定やルールを読み込ませない指定

自動化の結果が、実行する人の設定によって変わると困ることがあります。--ignore-user-configは$CODEX_HOME/config.tomlを読み込まずに動かします（ログイン情報は引き続きCODEX_HOMEのものを使います）。--ignore-rulesは、利用者とプロジェクトのコマンド実行ルール（.rulesファイル）を読み込みません。どちらも、管理された自動化の環境で、だれが動かしても同じ条件にしたい時の指定です。

名前にdangerouslyが付く危険な指定

手元の--helpでも、名前にdangerouslyが付く2つの指定には「DANGEROUS（危険）」と書かれています。ふだんの自動化では使いません。

• --dangerously-bypass-approvals-and-sandbox：確認とサンドボックスをすべて外します。ヘルプでも「EXTREMELY DANGEROUS」とされており、コンテナなどでCodexの外側から隔離した環境だけで使います。
• --dangerously-bypass-hook-trust：信頼確認をしていないhookも、その1回だけ動かします。この指定を使ってよいのは、hook（決まったタイミングで自動的に動くスクリプト）の出どころを別の方法で確認できている自動化だけです。環境を隔離していても、それだけでは条件を満たしません。コンテナやCIの中でも、確認していないhookが入ったリポジトリでは使いません。hookの信頼確認についてはCodex hooksの記事で解説しています。

安全の考え方の全体は、公式のAgent approvals & securityにまとまっています。

必須にしたMCPサーバーが起動しない時

MCPサーバー（Codexに外部のツールをつなぐ仕組み）を設定で有効にし、required = trueを付けている場合、そのサーバーの起動に失敗するとcodex execは処理を続けず、エラーで終了します。

codex execの出力をスクリプトで使う

--jsonで途中の出来事も受け取る

--jsonを付けると、標準出力が1行に1つのJSON（JSON Lines）の流れになり、実行中に起きた出来事を順に受け取れます。公式資料が挙げるイベントの種類はthread.started、turn.started、turn.completed、turn.failed、item.*、errorです。itemには、Codexの返答、考えた過程、コマンドの実行、ファイルの変更、MCPツールの呼び出し、Web検索、計画の更新が含まれます。

-oで最後の返答だけをファイルに残す

最後の返答だけが必要なら、-o <保存先>（--output-last-message）を使います。返答をファイルに書き出しつつ、標準出力にも同じ内容を出します。

--output-schemaで決まった形のJSONを受け取る

次の処理で使う項目が決まっている時は、--output-schemaでJSON Schema（JSONの形の決まり）を渡すと、最後の返答をその形に合わせるよう、Codexに指示できます。編集部の2回目で使った決まりは次のとおりです。

{
  "type": "object",
  "properties": {
    "file": { "type": "string" },
    "has_bug": { "type": "boolean" },
    "summary": { "type": "string" }
  },
  "required": ["file", "has_bug", "summary"],
  "additionalProperties": false
}

下は、編集部が実行したコマンドから一部の指定を省いた形です。実際には--ephemeralと--ignore-user-configも付け、保存先は練習用リポジトリの外にしました。

codex exec --output-schema ./schema.json -o ./result.json "calc.py を点検し、結果を返してください。ファイルは変更しないでください。"

保存されたresult.jsonは、{"file":"calc.py","has_bug":true,"summary":"add(a, b) が加算ではなく減算（a - b）を返しています。…"}という、指定した3項目だけのJSONでした。なお、公式のコマンド一覧のcodex execの項には、画像の添付、--output-schema、--output-last-message、--ephemeralを使う時は依頼文が必要と書かれています（forkの説明の直後にある記述で、どこまで当てはまるかは編集部では確かめていません）。

codex execで前回の続きを実行する方法

最初の実行で問題を見つけ、次の実行でそれを直す、のように段階を分けたい時はresumeを使います。--lastは今いるフォルダーで最も新しいセッションを選び、--allを足すとすべてのセッションから探します。特定のセッションを指定する時はcodex exec resume <セッションID>です。

codex exec "この変更に競合状態がないか確認して"
codex exec resume --last "見つかった競合状態を直して"

元のセッションを残したまま別の進め方を試したい時はcodex exec fork <セッションID>で複製できます。新しい実行や複製に--worktreeを付けると、Codexが用意するGitのworktree（作業用の別フォルダー）の中で動かせます。--worktreeはresume・review・--ephemeral・--ignore-user-configとは組み合わせられません。

編集部はresumeを試していません。--ephemeralを付けた実行はセッションが保存されないため、後から続きを頼む用途には向きません。また、0.163.0のcodex exec resume --helpには--sandboxが載っていません。続きの実行でファイルを直せるかどうかは、編集部では確かめていません。

codex execにGitリポジトリが必要な理由

Codexは、取り消しにくい変更を防ぐため、Gitリポジトリの中で動くことを前提にしています。編集部がGit管理していないフォルダーで実行すると、「Not inside a trusted directory and --skip-git-repo-check was not specified.」と表示され、終了コード1（処理が失敗したことを表す値）で止まりました。安全だと分かっている環境でだけ、--skip-git-repo-checkでこの確認を外せます。

CIでcodex execを使う時の注意

codex execは、保存済みのCLIのログイン情報をそのまま使います。CIでは認証情報を明示的に渡すことが多く、その渡し方に注意が必要です。

• GitHub Actionsでは公式のCodex GitHub Actionを使う。公式資料は、CLIを自分で入れて認証する代わりにopenai/codex-actionを勧めています。Codexの導入、Responses APIの中継（プロキシ）の起動、安全の設定を選んだうえでの実行をまとめて行うので、APIキーが漏れる機会を減らせます。
• APIキーをジョブ全体の環境変数にしない。リポジトリのコードを取り出して動かすワークフローで、OPENAI_API_KEYやCODEX_API_KEYをジョブ全体の環境変数にしないでください。同じジョブで動くビルドスクリプトやテスト、依存パッケージの処理からキーを読まれるおそれがあります。
• ほかの環境では、必要な1回の実行にだけキーを渡す。CODEX_API_KEY=<APIキー> codex exec --json "..."のように、その呼び出しにだけ設定し、信頼できないコードが同じ環境で動かないようにします。キーはコマンドに直接書かず、GitHubのSecretsのような秘密情報の保管場所から読み込みます。公式資料によると、CODEX_API_KEYが使えるのはcodex exec、codex review、TypeScript SDK、codex exec-server --remoteです。
• ChatGPTアカウントでの認証は、信頼できる実行環境だけで使う。自動化ではAPIキーを使うのが基本で、ChatGPTアカウントで動かす必要がある時だけこの方法を使います。~/.codex/auth.jsonにはアクセス用の情報が入っているので、パスワードと同じように扱います。公式資料は、公開リポジトリやオープンソースのリポジトリではこの方法を使わないよう求めています。

公式資料には、CIの失敗をきっかけにCodexへ修正案を作らせる例も載っています。Codexを動かすジョブには読み取り権限だけを与えて差分をファイルに保存し、書き込み権限を持つ別のジョブがその差分を当ててプルリクエストを作る、という分け方です。書き込み権限を持つ側にはAPIキーを渡しません。Codexにコードの変更を確認させる方法と、GitHub連携との違いは、Codexでコードレビューする方法で扱っています。

codex execがうまく動かない時に、症状別に確かめること

MCPサーバーの接続設定は、CodexのMCP設定で解説しています。

まとめ：codex execは読み取りから始める

codex execは、Codexに1回分の仕事を任せて結果だけを受け取るコマンドです。何も指定しなければ読み取り専用で動き、標準出力には最後の返答だけが出ます。この2点を押さえておけば、スクリプトに組み込んでも予想外の動きをしにくくなります。

始める時は、まず読み取りだけの点検や要約をcodex execで試し、出力を-oや--output-schemaで受け取る形を作りましょう。ファイルを直させるのはその後で、--sandbox workspace-writeを付けて範囲を限ります。CIに載せる時は、GitHub Actionsなら公式のopenai/codex-actionを使い、それ以外の環境ではAPIキーをCodexの1回の実行にだけ渡してください。

Codexの全体像から確かめたい方はCodexとは？使い方と仕事でできることを、毎回同じ決まりを守らせたい方はAGENTS.mdの書き方も読んでみてください。