Codexの設定 - プランモード

概要

OpenAI Codex CLIのプランモードは、計画立案フェーズと実装フェーズを分離するための読み取り専用動作モードである。

プランモードでは、コードベースを探索・分析するが、ファイルの変更やコマンドの実行は行わない。
計画のみを提示してユーザの確認を得た後に、通常の実装モードへ移行する設計になっている。

プランモードが有効な場面を以下に示す。

複雑なタスク
影響ファイルが多く、手順が複数ステップにまたがる変更
曖昧な構想を具体化したいとき
要件が不明確な段階で、Codexに質問させながら計画を固める場合
スコープが広いタスク
アーキテクチャ変更、大規模リファクタリング、機能追加等
AIドリフト (requirements drift) を防止したい時
途中で意図とずれた実装が進むリスクを排除したい場合

プランモードを使用することにより、以下に示すメリットが得られる。

安全性の向上
コードを一切変更せず、読み取り専用でコードベースを探索できる。
計画の可視化
Codexが提示する計画をユーザがレビュー・修正してから実装に進める。
トークンの節約
不要な試行錯誤を避け、最初から正しい方向で実装を開始できる。
Git ロールバック対応
全てのアクションのトランスクリプトが表示されるため、変更の追跡と巻き戻しが容易

/plan スラッシュコマンド

/plan コマンドは、アクティブな会話をプランモードに切り替えるためのスラッシュコマンドである。

基本構文

/plan [インラインプロンプト]

インラインプロンプトは省略可能である。
省略した場合は、現在の会話の流れをそのままプランモードで継続する。

# 使用例 1
/plan Propose a migration plan for this service

# 使用例 2
/plan ユーザ認証モジュールをOAuth2に移行する計画を提案して

コンテンツのペーストと画像添付

プランモード開始時に、以下に示すコンテンツを添付できる。

テキストのペースト
要件定義書、仕様書、エラーログ等のテキストを貼り付けて文脈として提供できる。
画像添付
スクリーンショット、UI モックアップ、アーキテクチャ図等の画像ファイルを添付できる。

タスク実行中のTabキューイング

Codex CLIでは、タスクが実行中の状態でも次のコマンドを予約できるTabキューイング機能を持つ。

プランモードへの切り替えは、タスク実行中でも以下の操作で予約できる。

[Tab]キー
実行中のターンがある状態で次のプロンプトをキューに追加する。
[Shift] + [Tab]キー
プランモードを即時起動する。

Plan モードの動作

プランモードは読み取り専用で動作し、以下の制約が適用される。

ファイルの作成、編集、削除は行わない。
シェルコマンドの実行は行わない。
コードベースの探索・分析、ファイルの読み取りのみ実行できる。

プランモードの基本フローを以下に示す。

Codexがコードベースを読み取り専用で探索する。
計画 (手順・変更が必要なファイル・リスク等) を提示する。
ユーザが計画を確認し、フィードバックや追加質問を行う。
ユーザが承認すると、通常の実装モードへ移行して変更を実行する。

全てのアクションはトランスクリプトとして表示されるため、進行中の作業を随時確認できる。
また、変更に問題があった場合は、Gitを使用してロールバックできる。

他の操作モードとの関係

Codex CLIは複数の操作モードを持ち、/permissions コマンドで会話中に切り替えられる。

下表に、各モードの特徴を示す。

Codex CLI 操作モード比較
モード	概要	ファイル変更	コマンド実行	主な用途
Auto (デフォルト)	各操作前にユーザに確認を求める	確認後に実行	確認後に実行	通常の開発作業
Read-only	読み取り専用変更・実行は不可	不可	不可	コードレビュー、調査
Full Access	全ての操作を自動承認する	自動実行	自動実行	信頼できる自動化タスク
Plan Mode	計画のみ提示変更・実行は行わない	不可	不可	実装前の計画立案

/permissions コマンドを使用すると、会話中にこれらのモードを切り替えられる。

Reasoning Effort 設定

Codex CLI では、モデルの推論にかけるリソースを制御する Reasoning Effort (推論エフォート) を設定できる。

プランモードは複雑な分析を行うため、推論エフォートを高く設定することを推奨する。
一方、実行フェーズでは低い設定にすることにより、レイテンシとコストを削減できる。

設定値

下表に、利用可能な推論エフォートの設定値を示す。

Reasoning Effort 設定値一覧
設定値	概要	推奨用途
`none`	推論なし最速・最低コスト	単純な補完、テンプレート生成
`minimal`	最低限の推論のみ	軽微な変更、定型作業
`low`	軽度の推論	明確な手順がある実装タスク
`medium`	バランス型標準的な推論	一般的な開発作業
`high`	高度な推論	複雑な設計分析、プランモード
`xhigh`	最高品質レイテンシよりも品質優先	最重要なアーキテクチャ決定 (2026年新追加)

xhigh は2026年に追加された設定値であり、品質を最優先してレイテンシを無視する用途に使用する。

plan_mode_reasoning_effort

plan_mode_reasoning_effort は、プランモード専用の推論エフォートを設定するオプションである。

このオプションを設定することで、プランモード (計画フェーズ) と通常モード (実装フェーズ) で異なるエフォートを使い分けられる。

 # 設定例 (プランモードは高品質、実装フェーズは低コスト):
 
 [defaults]
 model = "codex-1"
 plan_mode_reasoning_effort = "high"
 model_reasoning_effort = "low"

model_reasoning_effort

model_reasoning_effort は、全体のデフォルト推論エフォートを設定するオプションである。

plan_mode_reasoning_effort が設定されていない場合は、model_reasoning_effort の値がプランモードにも適用される。

その他の関連設定

推論エフォートに関連する追加設定を以下に示す。

model_reasoning_summary
推論プロセスの要約表示方法を制御する。

設定値: auto / concise / detailed / none

auto は Codex が状況に応じて適切な詳細度を選択する。
show_raw_agent_reasoning
エージェントの生の推論内容をそのまま表示するかどうかを制御する。

設定値: true / false

デバッグや詳細な推論確認に使用する。

TOML設定例

plan_mode_reasoning_effort および関連設定のTOMLの設定例を以下に示す。

グローバル設定

全プロファイル共通のグローバル設定例を以下に示す。

設定ファイルのパス
~/.codex/config.toml

 [defaults]
 model = "codex-1"
 plan_mode_reasoning_effort = "high"
 model_reasoning_summary = "concise"

プロファイル別設定

用途に応じてプロファイルを分けて設定する例を以下に示す。

 # 分析・設計用プロファイル: プランモードはxhigh、実行はmedium
 [profiles.analysis]
 model = "codex-1"
 plan_mode_reasoning_effort = "xhigh"
 model_reasoning_effort = "medium"
 model_reasoning_summary = "detailed"
 show_raw_agent_reasoning = false
 
 # 高速実行用プロファイル: プランモードはlow、実行はminimal
 [profiles.fast-execution]
 model = "codex-1-mini"
 plan_mode_reasoning_effort = "low"
 model_reasoning_effort = "minimal"
 model_reasoning_summary = "none"

設定の優先順位

設定値が複数の場所に記述されている場合、以下の優先順位が適用される。

プロファイルスコープの設定 (高優先)
[profiles.プロファイル名] セクションの設定が優先される。
グローバルスコープの設定 (低優先)
[defaults] セクションの設定はプロファイルで上書きされる。

プロファイルを切り替えるには、セッション開始時に --profile フラグを指定する。

codex --profile analysis

モデル選択

現状 (2026年5月)

現在、プランモードはCodex CLIのbuilt-in Plan preset modelを使用する。

プランモード専用のモデルを明示的に指定するオプションは提供されておらず、グローバルモデル設定 (model) を継承して動作する。

 [defaults]
 # このモデルがプランモードにも適用される
 model = "codex-1"

Feature Request (Issue #19343)

プランモードで使用するモデルを個別に指定するための plan_mode_model コンフィグオプションが、GitHub Issue #19343 にて要望されている。

このIssueでは、以下の設計が提案されている。

トップレベル ([defaults]) でのプランモードモデル指定
プロファイルレベル ([profiles.xxx]) でのプランモードモデル指定

提案されているサンプル設定を以下に示す。

 [defaults]
 # 通常の実行モデル
 model = "gpt-5.4"
 
 # プランモード専用モデル (提案中)
 plan_mode_model = "gpt-5.2"

2026年5月時点では、この機能は未実装であり、今後のバージョンで追加される予定となっている。

回避策

plan_mode_model が実装されるまでの間は、以下の回避策を使用する。

プロファイルを切り替えて対応する
プランモード用プロファイルと実行モード用プロファイルを個別に定義する

セッション開始時に適切なプロファイルを選択する

 # プランモード用プロファイル (高品質モデルを使用)
 [profiles.plan]
 model = "codex-1"
 plan_mode_reasoning_effort = "xhigh"
 
 # 実行用プロファイル (高速モデルを使用)
 [profiles.execute]
 model = "codex-1-mini"
 model_reasoning_effort = "low"

効果的な活用シーン

プランモードが特に効果を発揮するシーンを以下に示す。

Interview 手法 (曖昧な構想を具体化)

要件が曖昧な段階でプランモードを開始し、Codex に質問させることで構想を具体化できる。

# 使用例:
/plan ユーザ管理機能を改善したい。実装前に必要な情報を質問してほしい。

Codexが以下のような質問を投げかけることで要件が明確化される。

現在の認証方式は何ですか？
パスワードリセット機能は必要ですか？
ロールベースのアクセス制御 (RBAC) は必要ですか？
既存のユーザデータの移行は必要ですか？

PLANS.mdテンプレート (大規模タスク管理)

大規模または長時間かかるタスクでは、プランモードで生成した計画を PLANS.md ファイルとしてリポジトリに保存して管理する手法が有効である。

 # PLANS.md
 
 ## 認証システムのOAuth2移行計画
 
 ### フェーズ 1: 調査 (完了)
 - [x] 現在の認証システムの分析
 - [x] 影響ファイルのリストアップ
 
 ### フェーズ 2: 実装
 - [ ] OAuth2プロバイダの設定
 - [ ] トークンエンドポイントの実装
 - [ ] 既存ユーザの移行スクリプト作成
 
 ### フェーズ 3: テスト・デプロイ
 - [ ] ユニットテストの作成
 - [ ] 統合テストの実施
 - [ ] 本番環境へのデプロイ

この手法により、セッションをまたいで作業を継続しやすくなる。

その他の有効なシーン

複雑な機能追加
複数のファイルやモジュールにまたがる新機能の実装計画立案
バグ修正の前後分析
バグの根本原因を分析し、修正による影響範囲を事前に把握する。
大規模リファクタリング
アーキテクチャ変更やモジュール再設計の段階的な実装計画の作成

自動化での利用

Codex CLIのプランモードは、スクリプトや自動化ワークフローにも統合できる。

codex exec --planコマンド

codex exec コマンドに --plan フラグを指定することにより、非対話的にプランモードを実行できる。

# 使用例:
codex exec --plan "このサービスのマイグレーション計画を提案してください"

このコマンドはstdoutに計画と結果を出力するため、スクリプトでの処理やログへの記録に利用できる。

スクリプト統合

CI/CDパイプラインや定期実行スクリプトへの統合例を以下に示す。

 #!/usr/bin/env sh
 
 # プランモードを実行して計画をファイルに保存する
 codex exec --plan "このリポジトリの依存関係更新計画を提案してください" > migration_plan.md
 
 # 計画内容を確認する
 cat migration_plan.md

stdoutに計画と結果が出力されるため、変数への格納やファイルへのリダイレクトが容易である。

推奨事項

プランモードを効果的に使用するための推奨事項を以下に示す。

推論エフォートの組み合わせを活用する

計画段階と実行段階でそれぞれ適切な推論エフォートを設定することを推奨する。

計画フェーズ
high または xhigh

複雑な分析・設計に高品質な推論を適用する
実行フェーズ
low または medium

計画に基づいた明確な実装タスクでは低コストに処理する。

 [defaults]
 model = "codex-1"
 plan_mode_reasoning_effort = "high"
 model_reasoning_effort = "low"

プランモードを活用すべきタスクの判断

以下に示す基準でプランモードの使用を判断する。

スコープが大きいタスク
影響範囲が多くのファイルにまたがる場合
要件が曖昧なタスク
要件が不明確で、実装方法が複数考えられる場合
影響範囲が広いタスク
アーキテクチャや設計に関わる変更を伴う場合

一方、単純な変更や原因が明確なバグ修正では、プランモードを省略して直接実装する方が効率的である。

計画・確認・実行の3段階を維持する

プランモードを使用する時は、以下の3段階のフローを維持することを推奨する。

計画フェーズ
プランモードでCodexにコードベースを探索・分析させ、計画を立案させる。
確認フェーズ
提示された計画をレビューし、フィードバックや追加質問を行う。

必要に応じて計画の修正を依頼する。
実行フェーズ
計画を承認したら、通常モードへ切り替えて実装を開始する。

このフローを維持することで、意図とずれた実装 (AIドリフト) を防止できる。

既知の問題

プランモードに関連する既知の問題を以下に示す。

Codex Desktop バグ (Issue #18712)

Codex Desktopアプリでは、plan_mode_reasoning_effort の設定が正しく反映されないバグが報告されている。(Issue #18712)

この問題は、Codex Desktopに固有のものであり、CLI環境では正常に動作する。

回避策:

Codex CLI (ターミナル) を使用して plan_mode_reasoning_effort の設定を行う。
Codex Desktopでは、この設定が反映されるまで手動でモデルの推論エフォートを調整する。