Codex CLIの主要コマンドと使いどころ — 実践的リファレンス

Codex CLIのコマンド体系と動作原理

Codex CLIの基本的な呼び出し形式は codex [サブコマンド] [オプション] [プロンプト] という構造になっている。サブコマンドを省略した場合はインタラクティブなTUI（テキストユーザーインターフェース）が起動し、ターミナル上でコードの生成・修正・実行を対話的に進めることができる。一方、execサブコマンドを指定すると非インタラクティブモードで動作し、プロンプトを引数として渡すだけでタスクを即時処理して終了する。この二つのモードは目的が異なるため、用途に応じた使い分けが重要だ。

インタラクティブモードはリアルタイムで会話を深めながら設計や実装を進めたい場面に向いており、非インタラクティブモードはCI環境やシェルスクリプトからの呼び出しに適している。どちらのモードも同じ設定体系を共有しており、設定の優先度は CLIフラグ > 環境変数 > config.toml の順に処理される。たとえば--modelフラグでモデルを明示した場合、config.tomlのmodel項目よりもフラグ側が優先される。環境変数CODEX_MODELを使えばシェルレベルでデフォルトモデルを切り替えることも可能だ。

config.tomlはユーザーホームディレクトリの~/.codex/config.toml（あるいはXDG_CONFIG_HOMEに従うパス）に置かれ、モデル、承認設定、プロファイルなどを記述できる。v0.134で--profileフラグが統一化されたことで、複数の設定プロファイルを切り替えながら異なるプロジェクトに対応する運用が整備された。公式リポジトリは https://github.com/openai/codex で公開されており、設定ファイルのスキーマやリリースノートを参照できる。公式ドキュメントについては https://platform.openai.com/docs/codex も合わせて確認しておきたい。

日常開発で使うコアコマンド

codex（インタラクティブ起動）

引数なしで codex を実行すると、TUIが起動してセッションが始まる。キーボードからプロンプトを入力すると、Codexがコードを生成・提案し、承認を得てからファイルやコマンドを操作する。このモードは、問題の探索や設計の相談など、複数ターンにわたる対話が必要な作業に特に適している。

よく使うオプションとして、-m（または--model）でモデルを明示指定できる。たとえば codex -m o4-mini のように使う。--cdオプションを使うと起動時の作業ディレクトリを変更でき、特定のプロジェクトルートを指定してそのまま作業に入ることができる。他にも --profile でプロファイルを切り替えたり、--config で設定ファイルのパスを明示したりすることが可能だ。

codex exec（非インタラクティブ実行）

codex exec はCI環境やシェルスクリプトでの利用を想定した非対話型の実行モードだ。プロンプトを文字列として渡すと、TUIを起動せずにタスクを処理して終了する。標準出力に結果を書き出すため、他のコマンドとのパイプ処理にも対応しやすい。

主要なオプションとして、--json を付けると結果をJSON形式で出力できる。--ephemeral はセッション履歴を保存しない使い捨てモードで、ステートレスな処理を繰り返したい場合に便利だ。--output-last-message を指定すると最後のアシスタントメッセージのみを標準出力に出力し、後続の処理へ渡しやすくなる。

実際の使用例は次のとおりだ。

codex exec "テストを修正してすべてパスさせてください"
codex exec --json --ephemeral "src/utils.ts のバグを特定してください"
codex exec --output-last-message "READMEの日本語要約を生成してください"

codex resume / fork / archive

セッション管理には3つのコマンドが用意されている。codex resume は直前または指定したセッションIDのセッションを再開する。長期にわたる作業を中断して再開するケースや、以前の会話コンテキストを維持しながら作業を続けたい場面で活用できる。

codex fork は現在のセッションを分岐させ、別の方向性を試すための新しいセッションを作成する。リファクタリング案AとBを並行して検討したいときなど、同じ起点から異なるアプローチを試したい場合に有効だ。

codex archive と codex unarchive はv0.136（2026年5月）で追加された。完了したセッションをアーカイブ状態にすることで、アクティブなセッション一覧をすっきり保ちつつ、過去の会話コンテキストは参照できる状態を維持できる。セッション数が増えてきたときの整理運用として活用したい。

codex resume                    # 直前のセッションを再開
codex resume <session-id>       # 指定セッションを再開
codex fork                      # 現在のセッションを分岐
codex archive <session-id>      # セッションをアーカイブ
codex unarchive <session-id>    # アーカイブを解除

サンドボックスと承認設定

Codex CLIがファイルやコマンドを操作する際、どの範囲まで自律実行を許可するかは --sandbox と --ask-for-approval の二つのオプションで制御する。これらはセキュリティと利便性のトレードオフに直接関わるため、用途に応じた設定が重要だ。

--sandbox オプションには read-only、workspace-write、danger-full-access の三段階がある。read-only はファイルの読み取りのみを許可し、書き込みやコマンド実行をすべてブロックする最も安全な設定だ。workspace-write はカレントディレクトリ配下への書き込みのみを許可し、その他のディレクトリへのアクセスは制限する。danger-full-access はファイルシステムへのフルアクセスを許可するモードで、名前が示すとおり慎重に使う必要がある。

--ask-for-approval オプションは untrusted（デフォルト）、on-request、never から選べる。untrusted の場合、リスクがあると判断されたすべての操作に対して確認が求められる。on-request は明示的に「承認が必要」とマークされた操作のみ確認を取る。never はすべての操作を確認なしで実行するモードだ。

--dangerously-bypass-approvals-and-sandbox（通称 --yolo）は、サンドボックスと承認確認をすべて無効化するフラグだ。名前にdangerouslyが入っているとおり、このフラグを使うとファイルの削除やシステムコマンドの実行が無確認で行われる可能性がある。信頼できるプロンプトを扱うことが確実な場合にのみ、十分な理解のうえで使用すること。本番環境やチーム共有のリポジトリでの使用は推奨しない。

codex --sandbox workspace-write --ask-for-approval untrusted
codex --sandbox danger-full-access --ask-for-approval never
codex --dangerously-bypass-approvals-and-sandbox exec "テストを実行して結果を返してください"

拡張機能を管理するcodex mcpとcodex plugin

codex mcp — MCPサーバー管理

MCP（Model Context Protocol）は、外部ツールやサービスをCodexに接続するための標準プロトコルだ。codex mcp コマンドを使うことで、MCPサーバーの追加・一覧表示・削除をCLIだけで完結できる。

codex mcp add でサーバーを追加する。stdioベースとHTTP streamableの両方の接続方式に対応している。stdioサーバーを追加する場合は以下のような形式になる。

codex mcp add myserver -- npx -y @myorg/mcp-server

ダッシュ以降がサーバー起動コマンドになる。HTTP streamableサーバーを追加する場合は --url オプションでエンドポイントを指定する。

codex mcp add remote-server --url https://example.com/mcp

codex mcp list では現在登録されているMCPサーバーの一覧を確認でき、codex mcp remove <name> で不要なサーバーを削除できる。MCPサーバーの接続状態はセッション内の /mcp スラッシュコマンドでも確認可能だ。

codex plugin — プラグイン管理

プラグインはCodexの機能を拡張するパッケージで、codex plugin コマンドから管理する。サブコマンドには list、add、upgrade、remove がある。

codex plugin list でマーケットプレイスに公開されているプラグインや導入済みプラグインを確認できる。codex plugin add <plugin-name> でインストールし、codex plugin upgrade <plugin-name> でアップデートする。不要になったプラグインは codex plugin remove <plugin-name> で削除する。プラグインの適用状態はセッション内の /plugins スラッシュコマンドでも確認できる。

インタラクティブセッションのスラッシュコマンド

TUIセッション中は / で始まるスラッシュコマンドを入力することで、追加の操作を実行できる。これらはプロンプトではなくセッション制御のためのコマンドであり、マウスを使わずにキーボードだけで多くの操作を完結させられる。

よく使う5つのスラッシュコマンドを紹介する。/plan はCodexにタスクの実行計画を立てさせ、実際に手を動かす前に方針を確認する。大きな変更を加える前にこれを使うことで、意図しない修正を防ぎやすくなる。/diff は現在の作業による変更差分を表示する。どのファイルが変更されたかをその場で確認できるため、コミット前の見直しに役立つ。/review は変更内容のコードレビューをCodexに依頼する。セッション内でそのまま修正を依頼することもできる。

/compact は会話の履歴を要約・圧縮し、コンテキストウィンドウの消費を抑えるコマンドだ。長期のセッションで応答が遅くなってきたと感じたときや、コンテキスト上限に近づいたときに使う。/fork は現在のセッションを分岐させる。codex fork コマンドと同等の操作をセッション内から行える。

その他のスラッシュコマンドとして、/model でセッション中にモデルを切り替えられる。/permissions は現在の承認設定を確認・変更する。/goal はセッションの目標を設定またはリセットする。/mcp はMCPサーバーの接続状態を確認し、/plugins は現在有効なプラグインを一覧表示する。/skills はCodexが使えるスキルの一覧を表示する。/side はサイドパネルの表示を切り替え、コード差分やファイルツリーを確認できる。

診断・更新・その他のユーティリティ

codex doctor — 環境診断

codex doctor はCLIの動作環境を診断するコマンドで、APIキーの有無、依存ツールのバージョン、設定ファイルの読み込み状態などをまとめて確認できる。インストール直後や挙動がおかしいと感じたときに最初に実行するとよい。

--json オプションを付けると診断結果をJSON形式で出力できる。

codex doctor
codex doctor --json

JSON出力はシェルスクリプトからの読み取りや、診断結果を記録しておきたい場合に便利だ。

codex update — CLIのセルフアップデート

codex update はCLI自身をアップデートするコマンドで、v0.128から導入された。実行すると最新バージョンの有無を確認し、利用可能な場合は自動的にダウンロードして置き換える。パッケージマネージャー経由でインストールしている場合はそちらのアップデートコマンドを使う必要があるが、バイナリ直接インストールの場合はこのコマンドだけで更新が完結する。

codex update

v0.137.0（2026年6月）のような新機能を利用したい場合は、このコマンドで最新版に更新してから使い始めるとよい。リリースノートの詳細は公式リポジトリ https://github.com/openai/codex のタグページで確認できる。

codex cloud — クラウドタスク連携（実験的）

codex cloud はクラウド上でエージェントタスクを実行するための実験的なサブコマンド群だ。ローカルマシンのリソースや接続を気にせずに、長時間のタスクをリモート環境で実行させたい場合に活用できる。

主なサブコマンドとして cloud exec、cloud list、codex apply がある。codex cloud exec はクラウド環境でタスクを実行する。codex cloud list は実行中または完了済みのクラウドタスクを一覧表示する。

codex cloud exec "依存パッケージをアップデートして互換性を確認してください"
codex cloud list

クラウドで行われた変更をローカルリポジトリに適用するには codex apply を使う。クラウドタスクの結果として生成された差分パッチをローカルに取り込む仕組みで、クラウド上の変更をローカルで確認してからマージするワークフローを実現できる。

codex apply <task-id>

この機能はv0.137でのマルチエージェントv2強化と合わせて進化しており、今後さらなる機能拡充が見込まれる。実験的機能であるため、挙動が変わる可能性がある点は念頭に置いておきたい。詳しい仕様は https://platform.openai.com/docs/codex を参照のこと。