Codexの設定 - プロファイル

概要

OpenAI Codex CLIのプロファイル (Profiles) は、名前付き設定セットを保存して切り替えるための仕組みである。

プロファイルを使用することで、使用するモデル、承認ポリシー、サンドボックスモード、推論エフォート等の設定を1つのセットとして定義し、用途に応じて素早く切り替えることができる。

プロファイルが特に有効な場面を以下に示す。

開発環境と本番環境の使い分け
開発時は承認ありで安全に作業し、本番確認時は読み取り専用に切り替える。
速度と品質のトレードオフ管理
高速実行プロファイルと、深い検討を行うプロファイルを使い分ける。
チームメンバーへの設定共有
プロジェクト固有の .codex/config.toml にプロファイルを定義して共有する。

2026年5月時点において、プロファイル機能は実験的機能として提供されている。
将来的なバージョンで仕様が変更または削除される可能性があるため、本番環境への導入前に最新の公式ドキュメントを確認することを推奨する。

また、プロファイル機能はCLIに対応しており、IDE Extension (VSCode等) は現時点では未対応である。

TOML構文

プロファイルは、~/.codex/config.toml または .codex/config.toml のTOMLファイルに定義する。

プロファイルの定義

プロファイルは [profiles.<名前>] セクションとして定義する。
セクション名に使用するプロファイル名は、任意の文字列を指定できる。

複数のプロファイルを定義する例を以下に示す。

 # deep-review プロファイル: 深い検討用 (高品質・低速)
 [profiles.deep-review]
 model = "codex-1"
 model_reasoning_effort = "xhigh"
 approval_policy = "never"
 sandbox_mode = "read-only"
 
 # lightweight プロファイル: 高速実行用
 [profiles.lightweight]
 model = "codex-1-mini"
 model_reasoning_effort = "low"
 approval_policy = "on-request"
 sandbox_mode = "workspace-write"
 
 # workspace-write プロファイル: 通常開発用
 [profiles.workspace-write]
 model = "gpt-4.1"
 model_reasoning_effort = "medium"
 approval_policy = "on-request"
 sandbox_mode = "workspace-write"

各セクションに指定できる設定項目については、後述のオーバーライド可能な設定項目を参照すること。

デフォルトプロファイルの指定

起動時に自動的に適用するプロファイルは、設定ファイルのトップレベルで profile キーを使用して指定する。

 # デフォルトで workspace-write プロファイルを使用する
 profile = "workspace-write"
 
 [profiles.workspace-write]
 model = "gpt-4.1"
 model_reasoning_effort = "medium"
 approval_policy = "on-request"
 sandbox_mode = "workspace-write"

デフォルトプロファイルが指定されている場合でも、CLIフラグ --profile を使用することで起動時に上書きできる。

CLIでのプロファイル切替

プロファイルは --profile フラグを使用してコマンドライン上から切り替える。

--profile フラグ

--profile フラグは、Codex CLIの各コマンドで使用できる。

# インタラクティブセッションでプロファイルを指定して起動
codex --profile deep-review

# execコマンドでプロファイルを指定
codex exec --profile lightweight "テストを実行してください"

# featureフラグをプロファイルスコープで保存
codex features enable shell_snapshot --profile workspace-write

codex features enable <feature> --profile <name> を使用すると、機能フラグの有効化状態が指定したプロファイルのセクションに保存される。
詳細は、後述のfeature flagの保存先を参照すること。

動作

--profile フラグで指定したプロファイルの設定は、トップレベルの設定およびデフォルトプロファイルの設定を上書きする。

設定の適用順序については、後述の設定の優先順位を参照すること。

オーバーライド可能な設定項目

下表に、プロファイルセクション内で指定できる設定項目を示す。

プロファイルでオーバーライド可能な設定項目
設定項目	説明	設定値の例
`model`	使用するモデルを指定する。	"gpt-4.1" "ux-1" "gpt-4.1-mini"
`model_reasoning_effort`	モデルの推論にかけるリソースを制御する。	minimal low medium high xhigh
`model_verbosity`	モデルの出力の詳細度を制御する。	"low" "medium" "high"
`approval_policy`	ファイル操作・コマンド実行時の承認要求動作を指定する。	untrusted on-request never
`sandbox_mode`	サンドボックスの動作モードを指定する。	read-only workspace-write danger-full-access
`model_catalog_json`	カスタムモデルカタログのパスを指定する。起動時にのみ読み込まれる。	"~/.codex/models.json"
`plan_mode_reasoning_effort`	プランモード専用の推論エフォートを指定する。	minimal low medium high xhigh
`model_reasoning_summary`	推論プロセスの要約表示方法を制御する。	auto concise detailed none
`show_raw_agent_reasoning`	エージェントの生の推論内容をそのまま表示するかを指定する。	true false

上記以外にも、設定ファイルのトップレベルで使用できる大半の設定項目をプロファイル内で上書きできる。
ただし、一部の項目 (MCPサーバ構成等) はプロファイル内での設定に対応していない場合がある。

設定の優先順位

Codex CLIは複数の場所から設定を読み込み、以下の優先順位で適用する。
優先度が高い設定が低い設定を上書きする。

設定の優先順位
優先度	設定元	説明
1 (最高)	CLIフラグ `-c key=value`	起動時にインラインで指定した設定全ての設定を上書きする。
2	プロファイル値 (`--profile`)	`--profile` フラグで指定したプロファイルセクションの設定
3	ユーザ設定トップレベル (~/.codex/config.toml)	設定ファイルのトップレベルに記述されたデフォルト設定
4 (最低)	システムデフォルト	Codex CLI が内部的に保持するデフォルト値。

プロジェクト固有の設定ファイル (.codex/config.toml) は、信頼済みプロジェクトとして認識されている場合に読み込まれ、ユーザ設定と同等またはそれ以上の優先度で適用される。

# CLIフラグによる上書き (優先度1)
codex -c model=gpt-4.1 --profile deep-review

# 上記コマンドでは、deep-reviewプロファイルのmodel設定が
# -cフラグのgpt-4.1で上書きされる。

設定ファイルの位置

Codex CLIが参照する設定ファイルの種類と場所を以下に示す。

設定ファイルの位置
種類	ファイルパス	説明
ユーザ全体設定	~/.codex/config.toml	全プロジェクトに適用されるユーザ固有の設定ファイルプロファイル定義はここに記述することが多い。
プロジェクト設定	.codex/config.toml	プロジェクトルートに配置するプロジェクト固有の設定ファイル信頼済みプロジェクトとして認識された場合のみ読み込まれる。
管理者強制設定	requirements.toml	組織の管理者が強制適用するポリシーファイルプロファイルを使用しても上書きすることはできない。

requirements.toml で設定された制約は、プロファイルによる上書きができない最高優先のポリシーである。
組織のセキュリティポリシーを確実に適用するために使用される。

代表的なプロファイル設計例

実際の開発シナリオを想定した代表的なプロファイル設計例を以下に示す。

開発環境プロファイル

通常の開発作業向けのプロファイル設定例である。
承認ありで安全に作業しながら、ワークスペース内のファイルは自動的に変更できる。

 [profiles.dev]
 model = "gpt-5.1-codex"
 model_reasoning_effort = "medium"
 approval_policy = "on-request"
 sandbox_mode = "workspace-write"

# 開発環境プロファイルで起動
codex --profile dev

本番環境プロファイル

本番コードの確認・レビュー向けのプロファイル設定例である。
ファイル変更を行わず読み取り専用で動作し、高い推論エフォートで精密な分析を行う。

 [profiles.production]
 model = "gpt-4.1"
 model_reasoning_effort = "high"
 approval_policy = "never"
 sandbox_mode = "read-only"

# 本番環境プロファイルで起動
codex --profile production

深い検討用 (Plan Mode) プロファイル

アーキテクチャ設計や大規模リファクタリングの計画立案に特化したプロファイル設定例である。
最高品質の推論エフォートを使用して、深い分析と計画を提示する。

 [profiles.deep-plan]
 model = "gpt-5-pro"
 model_reasoning_effort = "xhigh"
 plan_mode_reasoning_effort = "xhigh"
 approval_policy = "never"
 sandbox_mode = "read-only"

# 深い検討用プロファイルでプランモードを起動
codex --profile deep-plan

高速実行プロファイル

CI/CDパイプラインや自動化スクリプトでの高速実行向けのプロファイル設定例である。
軽量モデルと低い推論エフォートを組み合わせることにより、処理速度とコストを優先する。

 [profiles.fast]
 model = "gpt-4.1"
 model_reasoning_effort = "low"
 approval_policy = "untrusted"
 sandbox_mode = "workspace-write"

# 高速実行プロファイルで非インタラクティブ実行
codex exec --profile fast "テストを実行して結果を報告してください"

feature flagの保存先

codex features enable コマンドを使用して機能フラグを有効化する場合、保存先は --profile フラグの有無によって異なる。

--profile フラグを指定した場合
指定したプロファイルのセクション ([profiles.<名前>]) に機能フラグが保存される。

そのプロファイルを使用する場合にのみ機能フラグが有効になる。
--profile フラグを指定しない場合
設定ファイルのトップレベルに機能フラグが保存される。

全てのプロファイルに共通して機能フラグが有効になる。

# dev プロファイルのみ shell_snapshot を有効化
codex features enable shell_snapshot --profile dev

# 全プロファイル共通で codex_hooks を有効化
codex features enable codex_hooks

permission profile との違い

Codex CLIには、プロファイル (Profiles) とパーミッションプロファイル (permission profile) の2種類のプロファイル機能がある。
名前が似ているが、用途と制御対象が異なる。

プロファイルとパーミッションプロファイルの比較
項目	プロファイル (Profiles)	パーミッションプロファイル (permission profile)
目的	設定セット全体を名前付きで管理する。	ファイルシステム・ネットワークアクセスの細粒度な権限を制御する。
制御対象	model, sandbox_mode, approval_policy, 推論エフォート等の動作設定	特定パスへの読み書き権限、特定ホストへのネットワークアクセス権限
定義場所	`[profiles.<名前>]` セクション	`[permissions.<名前>]` セクション
CLI指定方法	`--profile <名前>`	`--profile :<名前>` (コロンプレフィックス)
ビルトイン設定	なし (全てユーザ定義)	`:read-only` / `:workspace` / `:danger-no-sandbox`

両者は組み合わせて使用できる。
プロファイルで全体的な動作設定を指定しつつ、パーミッションプロファイルで細粒度のアクセス制御を追加できる。

# プロファイルとパーミッションプロファイルを同時に指定
codex --profile dev --profile :read-only

制限事項

プロファイル機能に関する制限事項を以下に示す。

実験的機能
2026年5月時点では実験的機能として提供されており、将来のバージョンで仕様が変更または削除される可能性がある。
IDE Extension非対応
プロファイル機能はCLIに限定されており、VSCode等のIDE Extensionは現時点では対応していない。
MCPサーバ構成
MCPサーバの構成 ([mcp_servers]) は、プロファイルセクション内での設定に対応していない。

MCPサーバの設定はトップレベルまたは [defaults] セクションで行う必要がある。
requirements.tomlの制約
管理者が設定した requirements.toml の制約は、プロファイルによる上書きができない。

例えば、deny_sandbox = ["danger-full-access"] が設定されている場合、プロファイルで sandbox_mode = "danger-full-access" を指定しても適用されない。

統合的な設定例

トップレベル設定、複数プロファイルの定義、デフォルトプロファイル指定をまとめた完全な ~/.codex/config.toml の設定例を以下に示す。

 # ~/.codex/config.toml
 
 # デフォルトで使用するプロファイルを指定
 profile = "dev"
 
 # トップレベルのデフォルト設定 (プロファイルで上書きされる)
 model = "gpt-4.1"
 model_reasoning_effort = "medium"
 approval_policy = "on-request"
 sandbox_mode = "workspace-write"
 
 # 全プロファイル共通の機能フラグ
 [features]
 streaming_diff = true
 
 # --- プロファイル定義 ---
 
 # 通常開発用プロファイル
 [profiles.dev]
 model = "gpt-5.1-codex"
 model_reasoning_effort = "medium"
 approval_policy = "on-request"
 sandbox_mode = "workspace-write"
 
 # 本番確認用プロファイル
 [profiles.production]
 model = "gpt-4.1"
 model_reasoning_effort = "high"
 approval_policy = "never"
 sandbox_mode = "read-only"
 
 # 深い検討用プロファイル (Plan Mode 向け)
 [profiles.deep-plan]
 model = "gpt-5-pro"
 model_reasoning_effort = "xhigh"
 plan_mode_reasoning_effort = "xhigh"
 approval_policy = "never"
 sandbox_mode = "read-only"
 model_reasoning_summary = "detailed"
 
 # 高速実行プロファイル (CI/CD 向け)
 [profiles.fast]
 model = "gpt-4.1"
 model_reasoning_effort = "low"
 approval_policy = "untrusted"
 sandbox_mode = "workspace-write"
 model_reasoning_summary = "none"

上記の設定ファイルを使用する場合の各プロファイルの起動コマンドを以下に示す。

# デフォルト (dev プロファイル) で起動
codex

# 本番確認モードで起動
codex --profile production

# 深い検討モードで起動
codex --profile deep-plan

# 高速実行モードで非インタラクティブ実行
codex exec --profile fast "依存関係のセキュリティ脆弱性を確認してください"

# CLIフラグでモデルをさらに上書き
codex --profile dev -c model=gpt-4.1