Codex CLI オプション・フラグの種類と引数設定ガイド

Codex CLI の基本的な呼び出し構文

Codex CLI は npm でインストール後、ターミナルから codex コマンドとして呼び出す。基本的な構文は以下の形式をとる。

codex [options] [prompt]

prompt にはタスクの内容を自然言語で記述する。プロンプトを省略した場合は対話モードで起動し、画面に入力フィールドが表示される。オプション（options）はプロンプトの前に指定するのが標準的だが、一部のフラグはプロンプト内の指示より優先される点に注意が必要だ。

公式のインストール手順と最新のオプション一覧は OpenAI が GitHub 上で管理しているリポジトリ（https://github.com/openai/codex）で確認できる。CLIのバージョンが上がると引数の挙動が変わることがあるため、codex --version でバージョンを確認する習慣をつけておくとよい。

Step 1: ヘルプで全オプションを確認する

まず codex --help を実行すると、その時点のバージョンで使えるフラグの一覧が表示される。出力には各フラグの簡単な説明と、対応するデフォルト値が含まれる。アップデートを適用した直後や新しいリポジトリで作業を始める前に実行しておくと、想定外の動作を防ぎやすい。

codex --help

出力の中で特に確認したいのは、approval-mode のデフォルト値だ。バージョンによっては suggest になっているが、環境変数 CODEX_APPROVAL_MODE を設定している場合はそちらが優先されるため、.env ファイルや shell の設定も併せてチェックすると確実だ。

--approval-mode：承認レベルの制御

--approval-mode は Codex CLI の動作の「自律度」を決める最も重要なフラグだ。次の3つの値から選択する。

1. suggest — 提案を表示するだけで、実際のファイル編集やコマンド実行は人間が承認する
2. auto-edit — ファイルの読み書きは自動で行うが、シェルコマンドの実行は都度確認を求める
3. full-auto — すべての操作を自動で実行する（サンドボックス内での使用が前提）

codex --approval-mode auto-edit "コメントを英語から日本語に翻訳する"

suggest はレビューを重視する場合に向いており、Codex の提案差分を git diff の形式で確認してから適用できる。auto-edit は、テストの追加やコメントの整理など、ファイル操作が中心の作業に適している。full-auto はサンドボックス環境または CI 環境でのみ使うことが OpenAI の公式推奨だ（参照: https://openai.github.io/codex/）。

approval-mode の選び方

新しいリポジトリや本番コードに触れる場面では suggest から始め、AGENTS.md に「この種のスクリプトは安全」と明示した後に auto-edit へ昇格させるのが安全な進め方だ。チームで共有するリポジトリでは、AGENTS.md の [policy] セクションで承認モードのデフォルトを明示しておくと、メンバー間でのばらつきを防げる。

--model：使用モデルの指定

--model フラグでは Codex CLI が内部で呼び出すモデルを指定できる。2026年6月時点で選択可能な主なモデルは以下のとおりだ。

1. codex-1 — Codex CLI 向けに最適化されたクラウドモデル。複雑な設計変更や大規模リファクタリングに向く
2. o4-mini — 軽量・高速で、コスト効率が高い。単純な修正やドキュメント更新に適している
3. o3 — 高精度の推論が必要な場面向けのモデル

codex --model o4-mini "README の誤字を修正する"

同じタスクでも使用するモデルによってクレジット消費量が大きく異なる。OpenAI の料金ページ（https://openai.com/pricing）でモデルごとのトークン単価を確認し、タスクの複雑さに応じてモデルを使い分けることがコスト管理の基本になる。AGENTS.md に model = "o4-mini" と記述しておけば、フラグを省略したときのデフォルトを上書きできる。

Step 2: モデルを切り替える実践例

大量の小さなファイルを一括処理する場面では、次のようにモデルと承認モードを組み合わせて指定すると効率的だ。

codex --model o4-mini --approval-mode auto-edit \
  "src/components/ 以下のコンポーネントに JSDoc コメントを追加する"

複数のファイルを巡回しながらドキュメントを追加するような反復作業は o4-mini の得意領域だ。一方、アーキテクチャの変更を伴う作業では codex-1 を指定して精度を優先する。

--sandbox：サンドボックス設定のオプション

Codex CLI は起動時に自動的にサンドボックス環境を用意し、ファイルシステムへのアクセスを限定する。--sandbox 関連のフラグを使うと、この動作を細かく制御できる。

network_access は Codex がネットワークにアクセスできるかを制御するキーだ。パッケージのインストールや外部 API の呼び出しを Codex に任せる場合は true に設定する必要がある。逆に、ローカルのコードだけを操作させたいときは既定の false のままにしておくと、意図しない通信を防げる。

codex --sandbox network_access=true \
  --approval-mode auto-edit \
  "npm install して型エラーを修正する"

AGENTS.md の [sandbox] セクションに設定を書いておくと、毎回フラグを指定しなくて済む。サンドボックス設定の詳細は公式ドキュメント（https://openai.github.io/codex/sandbox）に記載されている。

--quiet と --verbose：出力量の制御

--quiet フラグを指定すると、Codex の実行ログや途中経過の出力が最小限に抑えられる。スクリプト内で Codex を呼び出して結果だけを取得したい場面に向いている。逆に、デバッグや動作確認が目的の場合は --verbose を使うとステップごとの詳細なログが表示される。

codex --quiet "package.json のバージョンを 1.2.0 に更新する"

--verbose は初めて使う機能や、想定通りに動作しない場面でのトラブルシューティングに役立つ。特にサンドボックス内でのファイルアクセスや、モデルがどのツールを呼び出しているかを追跡するときは、--verbose の出力が診断の手掛かりになる。

Step 3: verbose で動作を追跡する

次のコマンドで Codex の挙動を詳しく観察できる。

codex --verbose --approval-mode suggest \
  "utils/format.ts の関数をすべてリストアップする"

出力には、Codex がどのファイルを読み込み、どのようなツールコールを発行したかが時系列で表示される。特に複雑な依存関係を持つリポジトリでは、この出力を見ながら AGENTS.md の記述を改善すると、次回以降の精度が上がる。

--no-project-doc：AGENTS.md の読み込みを無効化する

--no-project-doc フラグを指定すると、Codex はリポジトリ内の AGENTS.md を読み込まずに起動する。AGENTS.md の記述が原因でタスクがうまく動かない場合のデバッグや、AGENTS.md を持たない外部リポジトリで一時的に作業する場合に便利だ。

codex --no-project-doc "このリポジトリの構造を説明する"

ただし、AGENTS.md を無効化すると、リポジトリ固有のルールや禁止コマンドも適用されなくなるため、本番リポジトリでの利用は避けること。あくまでデバッグや調査目的で一時的に使うフラグと位置づけるのが適切だ。

--dangerously-auto-approve-everything：完全自動モードの特殊フラグ

このフラグは名前が示す通り、すべての操作を確認なしに実行する最も強力な自律モードだ。full-auto との違いは、サンドボックスの制限すら無視して動作する点にある。CI/CD パイプラインのテスト環境や完全に隔離されたコンテナ内でのみ使用が想定されており、ローカルの開発環境で実行するのは推奨されない。

OpenAI の公式ガイドライン（https://openai.github.io/codex/safety）では、このフラグを本番環境や重要なデータを扱うリポジトリで使わないよう明記している。誤って実行した場合、git 管理外のファイルが上書きされるリスクがあるため、使用前には必ずリポジトリのバックアップまたはクリーンな git 状態を確認することが必要だ。

環境変数によるデフォルト設定の上書き

フラグを毎回指定するのが手間な場合は、環境変数でデフォルト値を設定できる。主な環境変数は以下のとおりだ。

1. CODEX_APPROVAL_MODE — --approval-mode のデフォルト値を設定する
2. CODEX_MODEL — --model のデフォルト値を設定する
3. OPENAI_API_KEY — API キーを渡すための標準的な環境変数

export CODEX_APPROVAL_MODE=auto-edit
export CODEX_MODEL=o4-mini

これらを .bashrc や .zshrc に記述しておくと、毎回のコマンドが短くなる。ただし、プロジェクトごとに異なる設定が必要な場合は、ディレクトリ単位の .env ファイルと direnv（https://direnv.net/）を組み合わせると、切り替えを自動化できる。

AGENTS.md でオプションを永続化する

CLI フラグと環境変数に加えて、AGENTS.md の [config] セクションにオプションを記述すると、リポジトリ単位の設定としてチーム全体で共有できる。

[config]
model = "codex-1"
approval_mode = "auto-edit"

[sandbox]
network_access = false

この記述があると、Codex CLI はリポジトリを開いたときに自動的にこれらの設定を読み込む。環境変数よりも AGENTS.md の設定が優先されるケースとそうでないケースがあるため、優先順位（CLI フラグ > 環境変数 > AGENTS.md）を把握しておくとトラブルを防ぎやすい。AGENTS.md の仕様詳細は公式リポジトリの Wiki（https://github.com/openai/codex/wiki/AGENTS.md）に記載されている。

Step 4: チームで使うリポジトリへの適用例

チーム開発リポジトリで Codex を導入する場合、次のような AGENTS.md テンプレートから始めると安全性と利便性のバランスが取りやすい。

[config]
model = "codex-1"
approval_mode = "auto-edit"

[sandbox]
network_access = false

[policy]
disallowed_commands = ["git push --force", "rm -rf /"]

disallowed_commands には、Codex に実行させたくないコマンドを列挙しておく。これにより、誤ったプロンプトや想定外の推論でリポジトリの歴史が書き換わるリスクを下げられる。

よく使うフラグの組み合わせパターン

実務では、目的に応じて複数のフラグを組み合わせて使う場面が多い。代表的なパターンを整理しておく。

安全確認重視のレビュー用途:

codex --model codex-1 --approval-mode suggest \
  --verbose "このリポジトリのセキュリティ上の問題点を洗い出す"

高速・低コストの一括処理用途:

codex --model o4-mini --approval-mode auto-edit \
  --quiet "src/ 以下のすべての .ts ファイルに型アノテーションを補完する"

デバッグ・動作確認用途:

codex --no-project-doc --verbose --approval-mode suggest \
  "AGENTS.md なしでリポジトリを読んだときの動作を確認する"

これらのパターンをシェルのエイリアスや npm scripts に登録しておくと、チーム全体での利用が標準化しやすい。Codex CLI の引数設計は今後のバージョンアップで変更される可能性があるため、リリースノート（https://github.com/openai/codex/releases）を定期的に確認する習慣が継続的な活用には欠かせない。