Codexの設定 - プロファイルのソースを表示

== 概要 ==
OpenAI Codex CLIのプロファイル (Profiles) は、名前付き設定セットを保存して切り替えるための仕組みである。<br>
<br>
プロファイルを使用することで、使用するモデル、承認ポリシー、サンドボックスモード、推論エフォート等の設定を1つのセットとして定義し、用途に応じて素早く切り替えることができる。<br>
<br>
プロファイルが特に有効な場面を以下に示す。<br>
* 開発環境と本番環境の使い分け
*: 開発時は承認ありで安全に作業し、本番確認時は読み取り専用に切り替える。
* 速度と品質のトレードオフ管理
*: 高速実行プロファイルと、深い検討を行うプロファイルを使い分ける。
* チームメンバーへの設定共有
*: プロジェクト固有の <u>.codex/config.toml</u> にプロファイルを定義して共有する。
<br>
2026年5月時点において、プロファイル機能は実験的機能として提供されている。<br>
将来的なバージョンで仕様が変更または削除される可能性があるため、本番環境への導入前に最新の公式ドキュメントを確認することを推奨する。<br>
<br>
また、プロファイル機能はCLIに対応しており、IDE Extension (VSCode等) は現時点では未対応である。<br>
<br><br>

== TOML構文 ==
プロファイルは、<u>~/.codex/config.toml</u> または <u>.codex/config.toml</u> のTOMLファイルに定義する。<br>
<br>
==== プロファイルの定義 ====
プロファイルは <code>[profiles.<名前>]</code> セクションとして定義する。<br>
セクション名に使用するプロファイル名は、任意の文字列を指定できる。<br>
<br>
複数のプロファイルを定義する例を以下に示す。<br>
<br>
 <syntaxhighlight lang="toml">
 # 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"
 </syntaxhighlight>
<br>
各セクションに指定できる設定項目については、後述の[[#オーバーライド可能な設定項目|オーバーライド可能な設定項目]]を参照すること。<br>
<br>
==== デフォルトプロファイルの指定 ====
起動時に自動的に適用するプロファイルは、設定ファイルのトップレベルで <code>profile</code> キーを使用して指定する。<br>
<br>
 <syntaxhighlight lang="toml">
 # デフォルトで workspace-write プロファイルを使用する
 profile = "workspace-write"
 
 [profiles.workspace-write]
 model = "gpt-4.1"
 model_reasoning_effort = "medium"
 approval_policy = "on-request"
 sandbox_mode = "workspace-write"
 </syntaxhighlight>
<br>
デフォルトプロファイルが指定されている場合でも、CLIフラグ <code>--profile</code> を使用することで起動時に上書きできる。<br>
<br><br>

== CLIでのプロファイル切替 ==
プロファイルは <code>--profile</code> フラグを使用してコマンドライン上から切り替える。<br>
<br>
==== --profile フラグ ====
<code>--profile</code> フラグは、Codex CLIの各コマンドで使用できる。<br>
<br>
 # インタラクティブセッションでプロファイルを指定して起動
 codex --profile deep-review
 
 # execコマンドでプロファイルを指定
 codex exec --profile lightweight "テストを実行してください"
 
 # featureフラグをプロファイルスコープで保存
 codex features enable shell_snapshot --profile workspace-write
<br>
<code>codex features enable <feature> --profile <name></code> を使用すると、機能フラグの有効化状態が指定したプロファイルのセクションに保存される。<br>
詳細は、後述の[[#feature flagの保存先|feature flagの保存先]]を参照すること。<br>
<br>
==== 動作 ====
<code>--profile</code> フラグで指定したプロファイルの設定は、トップレベルの設定およびデフォルトプロファイルの設定を上書きする。<br>
<br>
設定の適用順序については、後述の[[#設定の優先順位|設定の優先順位]]を参照すること。<br>
<br><br>

== オーバーライド可能な設定項目 ==
下表に、プロファイルセクション内で指定できる設定項目を示す。<br>
<br>
<center>
{| class="wikitable"
|+ プロファイルでオーバーライド可能な設定項目
! 設定項目 !! 説明 !! 設定値の例
|-
| <code>model</code> || 使用するモデルを指定する。 || <u>"gpt-4.1"</u><br><u>"ux-1"</u><br><u>"gpt-4.1-mini"</u>
|-
| <code>model_reasoning_effort</code> || モデルの推論にかけるリソースを制御する。 || <u>minimal</u><br><u>low</u><br><u>medium</u><br><u>high</u><br><u>xhigh</u>
|-
| <code>model_verbosity</code> || モデルの出力の詳細度を制御する。 || <u>"low"</u><br><u>"medium"</u><br><u>"high"</u>
|-
| <code>approval_policy</code> || ファイル操作・コマンド実行時の承認要求動作を指定する。 || <u>untrusted</u><br><u>on-request</u><br><u>never</u>
|-
| <code>sandbox_mode</code> || サンドボックスの動作モードを指定する。 || <u>read-only</u><br><u>workspace-write</u><br><u>danger-full-access</u>
|-
| <code>model_catalog_json</code> || カスタムモデルカタログのパスを指定する。起動時にのみ読み込まれる。 || <u>"~/.codex/models.json"</u>
|-
| <code>plan_mode_reasoning_effort</code> || プランモード専用の推論エフォートを指定する。 || <u>minimal</u><br><u>low</u><br><u>medium</u><br><u>high</u><br><u>xhigh</u>
|-
| <code>model_reasoning_summary</code> || 推論プロセスの要約表示方法を制御する。 || <u>auto</u><br><u>concise</u><br><u>detailed</u><br><u>none</u>
|-
| <code>show_raw_agent_reasoning</code> || エージェントの生の推論内容をそのまま表示するかを指定する。 || <u>true</u><br><u>false</u>
|}
</center>
<br>
上記以外にも、設定ファイルのトップレベルで使用できる大半の設定項目をプロファイル内で上書きできる。<br>
ただし、一部の項目 (MCPサーバ構成等) はプロファイル内での設定に対応していない場合がある。<br>
<br><br>

== 設定の優先順位 ==
Codex CLIは複数の場所から設定を読み込み、以下の優先順位で適用する。<br>
優先度が高い設定が低い設定を上書きする。<br>
<br>
<center>
{| class="wikitable"
|+ 設定の優先順位
! 優先度 !! 設定元 !! 説明
|-
| 1 (最高) || CLIフラグ <code>-c key=value</code> || 起動時にインラインで指定した設定<br>全ての設定を上書きする。
|-
| 2 || プロファイル値 (<code>--profile</code>) || <code>--profile</code> フラグで指定したプロファイルセクションの設定
|-
| 3 || ユーザ設定トップレベル (<u>~/.codex/config.toml</u>) || 設定ファイルのトップレベルに記述されたデフォルト設定
|-
| 4 (最低) || システムデフォルト || Codex CLI が内部的に保持するデフォルト値。
|}
</center>
<br>
プロジェクト固有の設定ファイル (<u>.codex/config.toml</u>) は、信頼済みプロジェクトとして認識されている場合に読み込まれ、ユーザ設定と同等またはそれ以上の優先度で適用される。<br>
<br>
 # CLIフラグによる上書き (優先度1)
 codex -c model=gpt-4.1 --profile deep-review
 
 # 上記コマンドでは、deep-reviewプロファイルのmodel設定が
 # -cフラグのgpt-4.1で上書きされる。
<br><br>

== 設定ファイルの位置 ==
Codex CLIが参照する設定ファイルの種類と場所を以下に示す。<br>
<br>
<center>
{| class="wikitable"
|+ 設定ファイルの位置
! 種類 !! ファイルパス !! 説明
|-
| ユーザ全体設定 || <u>~/.codex/config.toml</u> || 全プロジェクトに適用されるユーザ固有の設定ファイル<br>プロファイル定義はここに記述することが多い。
|-
| プロジェクト設定 || <u>.codex/config.toml</u> || プロジェクトルートに配置するプロジェクト固有の設定ファイル<br>信頼済みプロジェクトとして認識された場合のみ読み込まれる。
|-
| 管理者強制設定 || <u>requirements.toml</u> || 組織の管理者が強制適用するポリシーファイル<br>プロファイルを使用しても上書きすることはできない。
|}
</center>
<br>
<u>requirements.toml</u> で設定された制約は、プロファイルによる上書きができない最高優先のポリシーである。<br>
組織のセキュリティポリシーを確実に適用するために使用される。<br>
<br><br>

== 代表的なプロファイル設計例 ==
実際の開発シナリオを想定した代表的なプロファイル設計例を以下に示す。<br>
<br>
==== 開発環境プロファイル ====
通常の開発作業向けのプロファイル設定例である。<br>
承認ありで安全に作業しながら、ワークスペース内のファイルは自動的に変更できる。<br>
<br>
 <syntaxhighlight lang="toml">
 [profiles.dev]
 model = "gpt-5.1-codex"
 model_reasoning_effort = "medium"
 approval_policy = "on-request"
 sandbox_mode = "workspace-write"
 </syntaxhighlight>
<br>
 # 開発環境プロファイルで起動
 codex --profile dev
<br>
==== 本番環境プロファイル ====
本番コードの確認・レビュー向けのプロファイル設定例である。<br>
ファイル変更を行わず読み取り専用で動作し、高い推論エフォートで精密な分析を行う。<br>
<br>
 <syntaxhighlight lang="toml">
 [profiles.production]
 model = "gpt-4.1"
 model_reasoning_effort = "high"
 approval_policy = "never"
 sandbox_mode = "read-only"
 </syntaxhighlight>
<br>
 # 本番環境プロファイルで起動
 codex --profile production
<br>
==== 深い検討用 (Plan Mode) プロファイル ====
アーキテクチャ設計や大規模リファクタリングの計画立案に特化したプロファイル設定例である。<br>
最高品質の推論エフォートを使用して、深い分析と計画を提示する。<br>
<br>
 <syntaxhighlight lang="toml">
 [profiles.deep-plan]
 model = "gpt-5-pro"
 model_reasoning_effort = "xhigh"
 plan_mode_reasoning_effort = "xhigh"
 approval_policy = "never"
 sandbox_mode = "read-only"
 </syntaxhighlight>
<br>
 # 深い検討用プロファイルでプランモードを起動
 codex --profile deep-plan
<br>
==== 高速実行プロファイル ====
CI/CDパイプラインや自動化スクリプトでの高速実行向けのプロファイル設定例である。<br>
軽量モデルと低い推論エフォートを組み合わせることにより、処理速度とコストを優先する。<br>
<br>
 <syntaxhighlight lang="toml">
 [profiles.fast]
 model = "gpt-4.1"
 model_reasoning_effort = "low"
 approval_policy = "untrusted"
 sandbox_mode = "workspace-write"
 </syntaxhighlight>
<br>
 # 高速実行プロファイルで非インタラクティブ実行
 codex exec --profile fast "テストを実行して結果を報告してください"
<br><br>

== feature flagの保存先 ==
<code>codex features enable</code> コマンドを使用して機能フラグを有効化する場合、保存先は <code>--profile</code> フラグの有無によって異なる。<br>
<br>
* <code>--profile</code> フラグを指定した場合
*: 指定したプロファイルのセクション (<code>[profiles.<名前>]</code>) に機能フラグが保存される。
*: そのプロファイルを使用する場合にのみ機能フラグが有効になる。
* <code>--profile</code> フラグを指定しない場合
*: 設定ファイルのトップレベルに機能フラグが保存される。
*: 全てのプロファイルに共通して機能フラグが有効になる。
<br>
 # dev プロファイルのみ shell_snapshot を有効化
 codex features enable shell_snapshot --profile dev
 
 # 全プロファイル共通で codex_hooks を有効化
 codex features enable codex_hooks
<br><br>

== permission profile との違い ==
Codex CLIには、<u>プロファイル (Profiles)</u> と <u>パーミッションプロファイル (permission profile)</u> の2種類のプロファイル機能がある。<br>
名前が似ているが、用途と制御対象が異なる。<br>
<br>
<center>
{| class="wikitable"
|+ プロファイルとパーミッションプロファイルの比較
! 項目 !! プロファイル (Profiles) !! パーミッションプロファイル (permission profile)
|-
| 目的 || 設定セット全体を名前付きで管理する。 || ファイルシステム・ネットワークアクセスの細粒度な権限を制御する。
|-
| 制御対象 || model, sandbox_mode, approval_policy, 推論エフォート等の動作設定 || 特定パスへの読み書き権限、特定ホストへのネットワークアクセス権限
|-
| 定義場所 || <code>[profiles.<名前>]</code> セクション || <code>[permissions.<名前>]</code> セクション
|-
| CLI指定方法 || <code>--profile <名前></code> || <code>--profile :<名前></code> (コロンプレフィックス)
|-
| ビルトイン設定 || なし (全てユーザ定義) || <code>:read-only</code> / <code>:workspace</code> / <code>:danger-no-sandbox</code>
|}
</center>
<br>
両者は組み合わせて使用できる。<br>
プロファイルで全体的な動作設定を指定しつつ、パーミッションプロファイルで細粒度のアクセス制御を追加できる。<br>
<br>
 # プロファイルとパーミッションプロファイルを同時に指定
 codex --profile dev --profile :read-only
<br><br>

== 制限事項 ==
プロファイル機能に関する制限事項を以下に示す。<br>
<br>
* 実験的機能
*: 2026年5月時点では実験的機能として提供されており、将来のバージョンで仕様が変更または削除される可能性がある。
*: <br>
* IDE Extension非対応
*: プロファイル機能はCLIに限定されており、VSCode等のIDE Extensionは現時点では対応していない。
*: <br>
* MCPサーバ構成
*: MCPサーバの構成 (<code>[mcp_servers]</code>) は、プロファイルセクション内での設定に対応していない。
*: MCPサーバの設定はトップレベルまたは <code>[defaults]</code> セクションで行う必要がある。
*: <br>
* requirements.tomlの制約
*: 管理者が設定した <u>requirements.toml</u> の制約は、プロファイルによる上書きができない。
*: 例えば、<code>deny_sandbox = ["danger-full-access"]</code> が設定されている場合、プロファイルで <code>sandbox_mode = "danger-full-access"</code> を指定しても適用されない。
<br><br>

== 統合的な設定例 ==
トップレベル設定、複数プロファイルの定義、デフォルトプロファイル指定をまとめた完全な <u>~/.codex/config.toml</u> の設定例を以下に示す。<br>
<br>
 <syntaxhighlight lang="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"
 </syntaxhighlight>
<br>
上記の設定ファイルを使用する場合の各プロファイルの起動コマンドを以下に示す。<br>
<br>
 # デフォルト (dev プロファイル) で起動
 codex
 
 # 本番確認モードで起動
 codex --profile production
 
 # 深い検討モードで起動
 codex --profile deep-plan
 
 # 高速実行モードで非インタラクティブ実行
 codex exec --profile fast "依存関係のセキュリティ脆弱性を確認してください"
 
 # CLIフラグでモデルをさらに上書き
 codex --profile dev -c model=gpt-4.1
<br><br>

== 関連ページ ==
* [[インストール - Codex]]
* [[Codexの設定 - 機能]]
* [[Codexの設定 - AGENTS.md]]
* [[Codexの設定 - プランモード]]
* [[Codexの設定 - 環境変数]]
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,Electric Circuit,Electric,pcb,Mathematics,AVR,TI,STMicro,AVR,ATmega,MSP430,STM,Arduino,Xilinx,FPGA,Verilog,HDL,PinePhone,Pine Phone,Raspberry,Raspberry Pi,C,C++,C#,Qt,Qml,MFC,Shell,Bash,Zsh,Fish,SUSE,SLE,Suse Enterprise,Suse Linux,openSUSE,open SUSE,Leap,Linux,uCLnux,電気回路,電子回路,基板,プリント基板
|description={{PAGENAME}} - 電子回路とSUSE Linuxに関する情報 | This page is {{PAGENAME}} in our wiki about electronic circuits and SUSE Linux
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:設定]]