Codex CLIのconfig.toml完全ガイド｜設定の優先順位と書き方

Codex CLIやIDE拡張でcodex --profileや-cオプションを試したものの、どの設定がどこで上書きされているのか分からなくなった経験はないだろうか。結論から言うと、Codexの挙動はconfig.tomlの読み込み場所と優先順位、approval_policyとsandbox_modeの組み合わせ、そしてbeta機能であるpermission profilesという3つの仕組みを理解すれば体系的に把握できる。

この記事では、OpenAIの公式ドキュメントに記載された設定項目を一つずつ確認しながら、Codex CLIのconfig.tomlをどう組み立てればよいかを実際のtoml例つきで整理する。仮の例として、レビュー用途は~/.codex/deep-review.config.tomlというprofileファイルに集約し、通常のコーディング用途は~/.codex/config.tomlにデフォルト値を置くという構成を想定しながら読み進めてほしい。

Codex自体の使い方の基本はOpenAI Codex 使い方｜料金・始め方・Claude Codeとの違いで解説している。この記事は、その先にある「設定ファイルをどう書くか」に絞った内容になる。

Codex CLIのconfig.tomlとは何か｜設置場所と読み込みの基本

config.tomlとは、Codexがモデル・承認ポリシー・サンドボックス・MCPサーバーなどの動作をまとめて定義するTOML形式の設定ファイルであり、ユーザー単位とプロジェクト単位の2階層で読み込まれる。

公式ドキュメントでは、Codexのユーザー単位の設定は~/.codex/config.tomlに保存され、特定のプロジェクトやサブフォルダだけに設定を絞り込みたい場合は、そのリポジトリ直下に.codex/config.tomlを追加すると説明されている。プロジェクト側の設定は、そのプロジェクトを信頼済みとして扱っている場合にだけ読み込まれる点が前提になる。

CLIとIDE拡張は同じ設定レイヤーを共有しており、IDE拡張側からは歯車アイコンから「Codex Settings > Open config.toml」を選ぶとユーザー設定ファイルを直接開ける。CLIとIDE拡張のどちらを使う場合でも編集対象は同じファイルになるため、提供形態ごとに別々の設定を管理する必要はない。提供形態そのものの違い(CLI・IDE拡張・クラウド・アプリ)はOpenAI Codexの提供形態の違い｜CLI・IDE・クラウド・アプリ比較で整理している。

仮の例として、個人用のPCでは~/.codex/config.tomlにモデルや承認方針のデフォルトを書いておき、チームで共有するリポジトリだけ.codex/config.tomlでsandbox設定を上書きする、という2階層構成が公式ドキュメントの想定する基本形になる。

設定の優先順位｜7階層のどれが勝つかを整理する

Codexの設定は、CLIフラグを最優先としてプロジェクト設定・profile・ユーザー設定・クラウド管理・システム設定・組み込みデフォルトの順に7階層で解決され、同じキーが複数箇所にあれば優先順位が高い層の値が勝つ。

公式ドキュメントが示す優先順位(数字が小さいほど優先度が高い)を表にまとめる。

優先順位	設定層	内容
1	CLIフラグ・–config上書き	実行のたびに指定する一時的な上書き
2	プロジェクト設定ファイル	.codex/config.toml。プロジェクトルートから作業ディレクトリに近いほど優先(信頼済みプロジェクトのみ)
3	profileファイル	–profile profile-nameで選択する~/.codex/profile-name.config.toml
4	ユーザー設定	~/.codex/config.toml
5	クラウド管理のデフォルト	サインイン中のワークスペースに配信されるconfig.tomlのデフォルト値
6	システム設定	Unix系の/etc/codex/config.toml(存在する場合)
7	組み込みデフォルト	Codex本体が持つ標準値

この優先順位は、共通のデフォルトはconfig.tomlに、環境ごとに変わる値だけprofileやプロジェクト設定に書くという設計指針の根拠になる。profileファイルは基準となるユーザー設定より上位のレイヤーであり、かつCLI・プロジェクト設定より下位に位置するため、「普段はprofileの値を使うが、その場限りで–configやプロジェクト設定があれば、そちらを優先する」という動きになる。

仮の例として、個人のユーザー設定でapproval_policy = "on-request"をデフォルトにしておき、CI環境のプロジェクト設定だけapproval_policy = "never"を書けば、CI実行時だけ自動的に非対話のポリシーに切り替わる。

まず触る基本設定6項目とtomlの書き方

config.tomlで最初に変更されることが多い基本設定は、デフォルトモデル・承認プロンプト・サンドボックスレベル・reasoning effort・コミュニケーションスタイル・ログ出力先の6項目である。

公式ドキュメント(Config basics)が「人々が最もよく変更するオプション」として挙げているのが次の6項目になる。

• デフォルトモデル: model = "gpt-5.6"
• 承認プロンプト: approval_policy = "on-request"
• サンドボックスレベル: sandbox_mode = "workspace-write"
• reasoning effort: model_reasoning_effort = "high"
• コミュニケーションスタイル: personality = "friendly"(pragmatic・noneも選択可)
• ログ出力先: log_dir = "/absolute/path/to/codex-logs"

仮の例として、日常のコーディング用途では次のようなconfig.tomlを~/.codex/config.tomlに置く構成が考えられる。

model = "gpt-5.6"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "high"
personality = "pragmatic"
log_dir = "/Users/you/.codex/logs"

デフォルトモデルの命名やモデルごとの違いは頻繁に更新されるため、modelキーに何を指定できるかは最新のモデル一覧を確認したほうが確実だ。現行モデルの位置づけはGPT-6 Astraとは｜GPT-5.6との違い・料金・使い分けを解説で解説している。

また、log_dirを明示すると、そのディレクトリにプレーンテキストのTUIログ(codex-tui.log)がオプトインで出力されるようになる点も公式ドキュメントの記載どおりで、指定しない限りこのログは生成されない。

profileで用途別に設定を切り替える

profileとは、–profile profile-nameで選択できる名前付きの設定レイヤーであり、~/.codex/config.tomlの上に~/.codex/profile-name.config.tomlを重ねて読み込む仕組みである。

公式ドキュメントのprofile名の付け方は、英数字・ハイフン・アンダースコアのみを使う。profile用のファイルは、通常のconfig.tomlと同じトップレベルのキーをそのまま書けばよく、[profiles.profile-name]のようにネストさせる必要はない。

仮の例として、レビュー専用のprofileを作る場合、以下の内容を~/.codex/deep-review.config.tomlとして保存する。

# ~/.codex/deep-review.config.toml
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

codex --profile deep-review
codex exec --profile deep-review "review this change"

profileファイルはベースのユーザー設定より上位のレイヤーになるため、ベース設定と異なる値だけを書けば足りる。profile側でmodel_catalog_jsonを指定すると、ユーザー設定側の値より優先される。

注意点として、Codex 0.134.0以降では--profile実行時にconfig.toml内の[profiles.profile-name]テーブルを読まなくなり、トップレベルのprofile = "profile-name"セレクターもサポートされなくなった。旧バージョンの設定を使っていた場合は、profile用の内容を~/.codex/profile-name.config.tomlへ移し、config.toml側の[profiles.profile-name]テーブルとprofile = "profile-name"指定は削除する必要がある。

モデルのラインアップは今後も更新が見込まれるため、profileで固定していたモデルIDが非推奨になるケースもある。モデルの切り替え判断についてはOpenAI モデル非推奨化戦略も参考になる。

codex execや–configによる1回限りの上書き

–configまたは-cフラグは、config.tomlを編集せずにその場限りで任意のキーを上書きできるCLIオプションであり、値はJSONではなくTOMLとして解釈される。

公式ドキュメントは、専用フラグ(--modelなど)がある場合はそちらを優先し、任意のキーを上書きしたい場合だけ-c/--configを使うことを勧めている。

# 専用フラグを使う場合
codex --model gpt-5.6-terra

# 任意キーを汎用オーバーライドする場合(値はTOMLとして解釈される)
codex --config model='"gpt-5.6-terra"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

ドット記法を使うとmcp_servers.context7.enabled=falseのようにネストした値も直接指定できる。--configの値はTOMLとしてパースされ、シェルが値をスペースで分割してしまわないよう、迷ったらクォートで囲むこと、そしてTOMLとして解釈できない値は文字列として扱われることも公式ドキュメント(Advanced Configuration)に明記されている。

仮の例として、普段はworkspace-writeでネットワークを遮断しているが、パッケージのインストールだけ一時的にネットワークを許可したい場合は、config.tomlを書き換えずにcodex --config sandbox_workspace_write.network_access=trueを1回だけ実行すればよい。

カスタムmodel providerを追加する｜Bedrock・Azure・ローカルLLM

model providerとは、Codexがモデルへ接続する方法(ベースURL・wire API・認証・HTTPヘッダー)を定義する設定単位であり、組み込みのopenai・ollama・lmstudio以外に独自のproviderを追加できる。

独自のproxyやAzure、ローカルLLMをCodexから使いたい場合、[model_providers.<id>]テーブルでproviderを定義し、model_providerキーでそれを指すという公式の手順が示されている。

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

Amazon Bedrockについては、独自のproviderを一から定義しなくても、Codexに組み込み済みのamazon-bedrock model providerを指定するだけで使える。組み込みprovider側はAWSのprofileとregionのネスト設定だけをサポートしており、profileを省略すると標準のAWS認証情報チェーンが使われる。

model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"
region = "eu-central-1"

ローカルのOSSモデルを使う場合は--ossフラグで起動し、oss_provider = "ollama"または"lmstudio"をデフォルトとして設定できる。Azureを使う場合は[model_providers.azure]にbase_urlとAPIバージョンなどを個別に設定する。いずれの方式でも、組み込みのopenaiプロバイダーのIDを再利用して[model_providers.openai]を新たに定義することはできない点は共通の制約になる。

Bedrock連携そのものについてはOpenAI Amazon Bedrockで背景情報を補足している。

approval_policyとsandbox_modeの主要な組み合わせ5パターン

approval_policyは承認を求めるタイミングを決め、sandbox_modeはファイル・ネットワークへのアクセス範囲を決める、独立した2つの設定軸であり、公式ドキュメントはこの2軸の代表的な組み合わせを5パターンで示している。

用途ごとの組み合わせを、公式ドキュメントの表に沿って整理する。

用途	フラグ・設定	挙動
Auto(標準プリセット)	フラグなし、または–sandbox workspace-write –ask-for-approval on-request	ワークスペース内の読み取り・編集・コマンド実行は可能。ワークスペース外の編集やネットワークアクセスには承認が必要
読み取り専用ブラウジング	–sandbox read-only –ask-for-approval on-request	read-onlyサンドボックス内でファイル閲覧とコマンド実行が可能。サンドボックス外の操作には承認が必要になりうる
読み取り専用の非対話(CI向け)	–sandbox read-only –ask-for-approval never	read-onlyサンドボックス内で実行し、承認は一切求めない
Auto-reviewモード	–ask-for-approval on-request -c approvals_reviewer=auto_review	サンドボックスの境界はon-requestと同じだが、承認対象のリクエストはユーザーではなくAuto-reviewが審査する
危険なフルアクセス	–dangerously-bypass-approvals-and-sandbox(エイリアス–yolo)	サンドボックスなし・承認なし(非推奨)

config.toml側でも同じ組み合わせをそのまま記述できる。

# 読み取り専用サンドボックスでの対話的承認
approval_policy = "on-request"
sandbox_mode    = "read-only"
allow_login_shell = false

# workspace-writeモードでネットワークだけ許可したい場合
[sandbox_workspace_write]
network_access = true

この5パターンはprofileとしても保存できる。仮の例として、非対話CI向けにはread-only+neverの組み合わせを~/.codex/readonly_quiet.config.tomlとして保存しておけば、codex --profile readonly_quietだけで同じ構成を再現できる。

# ~/.codex/full_auto.config.toml
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

# ~/.codex/readonly_quiet.config.toml
approval_policy = "never"
sandbox_mode    = "read-only"

「untrusted」承認ポリシー廃止への移行手順

approval_policy = “untrusted”は廃止済みの設定であり、Codex・ChatGPT Workのどちらでも指定するとクライアントが起動できなくなるため、既存設定から取り除いたうえで代替設定へ移行する必要がある。

公式ドキュメントは、ユーザー設定・プロジェクト設定・profileファイル・起動スクリプト・管理者側のデフォルト設定のすべてからuntrusted指定を取り除くよう案内している。対話的な読み取り専用用途としての代替は次のとおりだ。

sandbox_mode = "read-only"
approval_policy = "on-request"

CLIから直接指定する場合はcodex --sandbox read-only --ask-for-approval on-requestを実行すればよい。on-requestでは、サンドボックスが許可しているコマンドは承認なしで実行され、アクセス可能なファイルの読み取りやネットワークアクセス(有効化されている場合)も承認なしで進む。

従来のuntrustedが持っていた「より厳格にコマンド単位の承認を必須にする」挙動を残したい場合は、approval_policyを明示せず、代わりにユーザー設定側でプロジェクトごとに信頼レベルを指定する。

[projects."/path/to/project"]
trust_level = "untrusted"

この設定にすると、実行ポリシーのルールで許可されない限りコマンドには承認が必要になる。ただし、approval_policyを明示的にon-requestにすると、このプロジェクト由来のポリシーより優先されてしまう点、また管理設定側でallowed_approval_policiesにuntrustedを含めていないとこの設定自体が許可されない点は、移行時に見落としやすい。

granular approval policyでカテゴリ単位に制御する

granular approval policyとは、approval_policy = { granular = { … } }という形式で、プロンプトのカテゴリごとに承認を求めるか自動で拒否するかを個別に設定できるapproval_policyの一種である。

公式ドキュメント(Approval policies and sandbox modes)のコメント付きサンプルには、次の5つのカテゴリがtrue/falseで設定できる例として示されている。

• sandbox_approval
• rules
• mcp_elicitations
• request_permissions
• skill_approval

# Example granular approval policy:
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

この仕組みは、「通常のケースでは対話的な承認を残しつつ、request_permissionsやskill関連のプロンプトだけは自動的にfail closed(拒否)にしたい」というように、一部のカテゴリだけ挙動を変えたい場合に使う設定として案内されている。あわせてapprovals_reviewer = "auto_review"を設定すると、対象となる対話的承認リクエストの審査者を自動レビューに切り替えられる。これは承認の境界(サンドボックス)そのものを変えるのではなく、誰がレビューするかを変える設定である点に注意したい。

仮の例として、通常のファイル編集やコマンド実行はsandbox_approvalとrulesをtrueにして対話的に確認しつつ、MCP経由の権限昇格要求(request_permissions)だけはfalseにして自動拒否する、という構成が考えられる。

permission profiles(beta)とsandbox設定は併用できない

permission profilesはファイルシステムとネットワークのルールを1つの名前付きポリシーにまとめるbeta機能であり、公式ドキュメントは従来のsandbox_mode / sandbox_workspace_writeとの併用を明示的に禁止している。

公式ドキュメント(Permissions)によると、Codexには3つの組み込みpermission profileが用意されている。

• :read-only — ローカルコマンド実行を読み取り専用に保つ
• :workspace — アクティブなワークスペースのルートとシステムの一時ディレクトリ内での書き込みを許可する
• :danger-full-access — ローカルのサンドボックス制限を取り払う。意図的に広い権限が必要な場合だけ使う

重要なのは、default_permissionsと[permissions]を使う設定と、sandbox_mode / sandbox_workspace_writeを使う従来設定は同時に組み合わせられないという制約だ。読み込まれた設定ファイルのどこかにsandbox_modeがあったり、--sandboxフラグを渡したり、選択したconfig profileがsandbox_modeを設定していたりすると、Codexはpermission profilesではなく従来のsandbox設定を優先して使う。

例外は管理者側のallowed_permission_profilesで、これが設定されるとCodexはpermission profilesを使う側に切り替わる。この管理設定をデプロイする前には、sandbox_modeや[sandbox_workspace_write]といった旧設定を取り除いておく必要がある。

企業導入でpermission profilesの許可リストを展開する場合の全体像はOpenAI Codex企業導入ガイドも参考になる。

カスタムpermission profileの作り方

カスタムpermission profileとは、[permissions.<name>]テーブルの下にworkspace_rootsとfilesystemルールを書いて定義する、組み込み3種以外の独自ポリシーである。

named profileを作るには、[permissions.<name>]の下にプロファイルを定義し、トップレベルのdefault_permissionsキーをそのprofile名か、組み込みのいずれかに設定する。カスタムprofileでは次の2つの概念を使う。

• [permissions.<name>.workspace_roots] — そのprofileのワークスペースルートとして扱う具体的なディレクトリを追加する
• [permissions.<name>.filesystem.":workspace_roots"] — セッションのランタイムワークスペースルートと、上記で追加したルートを合わせた「実効ワークスペースルート」の内側に適用するファイルシステムルールを定義する

profileは通常のconfig層モデルに従うため、組織レベルの設定とユーザーレベルの設定が、同じprofile名を個別に拡張できる。

# /etc/codex/config.toml (組織レベル)
[permissions.server.workspace_roots]
"~/code/server" = true

# ~/.codex/config.toml (ユーザーレベル)
[permissions.server.workspace_roots]
"~/code/mobile-app" = true

ネットワークに関しては注意が必要で、profileのnetwork.enabled = trueはコマンドのネットワークアクセス自体を許可するだけであり、ネットワークプロキシを起動するわけではない。profileが定義するドメインルールを実際に強制するには、config.toml側でfeatures.network_proxy = trueを設定するか、管理者が有効化した[experimental_network]要件を使う必要がある。プロキシが動いていない状態では、profileのドメインルールは直接のネットワークアクセスを制限しない。

仮の例として、サーバーリポジトリ用にserverというカスタムprofileを組織側で定義し、開発者ごとにworkspace_rootsだけをユーザー設定側で追加していく、という運用が考えられる。

shell_environment_policyで環境変数を絞り込む

shell_environment_policyとは、Codexが実行するコマンドへどの環境変数を引き渡すかを制御する設定であり、inheritの初期値とfiltersによる除外・許可の組み合わせで決まる。

何もかも引き継ぐのではなく、inherit = "none"で空の環境から始めるか、inherit = "core"で絞り込んだ最小限の環境を引き継ぐところから設定を始める、というのが公式ドキュメントの推奨する考え方だ。

[shell_environment_policy]
inherit = "core"
set = { MY_FLAG = "1" }
ignore_default_excludes = false

[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"

フィルターパターンは大文字小文字を区別せず、*と?のワイルドカードに対応する。"exclude"を使うとマッチした変数を除外し、どれか1つでも"include"パターンを使うと、Codexはincludeパターンにマッチする変数だけを残す。includeはすでに除外された変数を復元しない点、フィルターのキーは設定レイヤーをまたいで大文字小文字を区別せずマージされる点も明記されている。

ignore_default_excludesのデフォルトはtrueで、この場合CodexはKEY・SECRET・TOKENという文字列を含む変数名を自動的には除外しない。これらの自動除外を有効にしたい場合は明示的にfalseを設定する必要がある。Codexは自動除外(有効化されている場合)→カスタムのexclude→setの値→includeパターンによる許可リスト、の順で処理を適用するため、setは除外より後に実行されて一度除外した変数を復元しうる点、そのあとにincludeパターンの許可リストがあれば、復元した値を再び取り除ける点も押さえておきたい。

旧来のexclude・include_only配列も既存設定との互換のために引き続きサポートされているが、同じ設定レイヤー内で配列と[shell_environment_policy.filters]を組み合わせることはできず、組み合わせるとCodexはその設定を拒否する。

feature flagsで実験的機能をON/OFFする

feature flagsとは、config.tomlの[features]テーブルで個別にON/OFFできる実験的・段階公開中の機能群であり、公式ドキュメントは主要なものとして14種類のフラグを一覧で示している。

公式ドキュメント(Config basics)の一覧表に基づく、主なfeature flagsとデフォルト値・成熟度・説明は次のとおりだ。

キー	デフォルト	成熟度	説明
apps	true	Stable	アプリ(コネクタ)連携を有効化
goals	true	Stable	永続化されたゴールと自動継続を有効化
hooks	true	Stable	hooks.jsonまたはインラインの[hooks]によるライフサイクルフックを有効化
fast_mode	true	Stable	Fast modeの選択とservice_tier = “fast”の経路を有効化
memories	false	Experimental	Memories機能を有効化
multi_agent	true	Stable	サブエージェントによる協調ツールを有効化
personality	true	Stable	personality選択のコントロールを有効化
remote_plugin	true	Stable	リモートプラグインカタログを有効化
shell_snapshot	true	Stable	シェル環境をスナップショットして繰り返しコマンドを高速化
shell_tool	true	Stable	デフォルトのshellツールを有効化
unified_exec	true(Windows除く)	Stable	統合されたPTYベースのexecツールを使用
web_search	true	Deprecated	レガシーな切り替え。トップレベルのweb_search設定を優先
web_search_cached	false	Deprecated	未設定時にweb_search = “cached”へ対応付くレガシー切り替え
web_search_request	false	Deprecated	未設定時にweb_search = “live”へ対応付くレガシー切り替え

featureを有効にする方法は3つあり、config.tomlの[features]にfeature_name = trueを追記する、CLIからcodex --enable feature_nameを実行する、複数まとめて有効化したい場合はcodex --enable feature_a --enable feature_bのように--enableを重ねる、のいずれかを使う。無効化したい場合はconfig.toml側で該当キーをfalseにすればよい。キーを省略した項目はデフォルト値のまま扱われる。

web_search関連はレガシーな真偽値の[features]キーよりも、トップレベルのweb_search設定("cached"・"indexed"・"live"・"disabled"の4種類)を使うことが推奨されている。仮の例として、社内ネットワークからの利用でライブのWebアクセスを避けたい場合はweb_search = "cached"のまま維持し、最新情報が必要な調査タスクの回だけcodex --config web_search=liveのように一時的に切り替える運用が考えられる。

MCPサーバー接続とOTelによる可観測性設定

config.tomlはモデルやサンドボックスだけでなく、外部ツールをつなぐMCPサーバー設定と、Codexの実行ログを外部へ送るOpenTelemetry(OTel)連携の設定も担う。

MCPサーバーの追加・認証・有効/無効の切り替えはconfig.toml側から行うが、キーの詳細は専用のMCPドキュメントにまとまっているため、この記事では設定ファイル内の位置づけだけを押さえておく。--configによる一時的な上書きの章で触れたとおり、mcp_servers.context7.enabled=falseのようにドット記法で個別のMCPサーバーだけを1回のセッション限定で無効化することもできる。MCPサーバー経由での外部ツール呼び出しという発想自体は、OpenAI APIのFunction callingとも近い考え方であり、モデルに外部の関数やツールを呼ばせる仕組み全般を理解したい場合はOpenAI APIのFunction callingの使い方と設計手順もあわせて参考になる。

可観測性については、OpenTelemetry(OTel)によるログエクスポートで、APIリクエスト・SSE/イベント・プロンプト・ツール承認や実行結果といったCodexの実行内容を追跡できる。この機能はデフォルトで無効になっており、[otel]テーブルでオプトインする。

[otel]
environment = "staging"   # 未指定時は"dev"
exporter = "none"         # otlp-httpまたはotlp-grpcに設定するとイベントを送信
log_user_prompt = false   # 明示的に有効化しない限りユーザープロンプトは記録から除外

仮の例として、ステージング環境の動作検証だけOTelを有効化してユーザープロンプトは記録せず、本番相当の環境ではexporterを未設定のままにして送信自体を止める、という切り分けが考えられる。model_verbosityのように、内部的にResponses API系のproviderにしか効かない設定もあり、Chat Completions系のproviderはその値を無視する。Responses APIとChat Completionsの違いそのものはResponses APIとChat Completionsの違いと使い分けで解説している。

よくある質問(FAQ)

Q1. config.tomlはユーザー単位とプロジェクト単位のどちらに置くべきか

普段から使うモデルや承認方針といった共通のデフォルトは~/.codex/config.tomlに置き、特定のリポジトリだけサンドボックス設定を変えたい場合に.codex/config.tomlを追加する、という2段構えが公式ドキュメントの想定する基本形だ。プロジェクト側の設定は、そのプロジェクトを信頼済みとして扱っている場合にだけ読み込まれる。

Q2. profileと–configはどちらを使えばよいか

繰り返し使う設定の組み合わせ(レビュー用・CI用など)はprofileファイルにまとめ、--profile profile-nameで切り替える。今この1回の実行だけ値を変えたい場合は-c/--configで一時的に上書きする方が管理が煩雑にならない。

Q3. approval_policy = “untrusted”は今も指定できるか

指定できない。Codex・ChatGPT Workのどちらでもこの設定は廃止されており、指定するとクライアントが起動できなくなる。対話的な読み取り専用用途への移行先としてはsandbox_mode = "read-only"とapproval_policy = "on-request"の組み合わせが案内されている。

Q4. permission profilesとsandbox_modeは同時に設定できるか

できない。公式ドキュメントは、default_permissionsと[permissions]を使う設定と、sandbox_mode/sandbox_workspace_writeを使う従来設定のどちらか一方だけを使うよう明記している。sandbox_modeが読み込まれた設定のどこかにあれば、Codexは従来設定を優先する。

Q5. shell_environment_policyを何も設定しないとどうなるか

明示的な指定がない場合でも、ignore_default_excludesのデフォルトはtrueであり、この状態ではCodexはKEY・SECRET・TOKENを含む変数名の自動除外を行わない。この自動除外を有効にしたい場合はignore_default_excludes = falseを明示する必要がある。

Q6. feature flagsはCLIからも切り替えられるか

切り替えられる。config.tomlの[features]に書く方法に加えて、codex --enable feature_nameで1つずつ、または--enableを複数回重ねて有効化できる。無効化はconfig.toml側でキーをfalseにする方法が案内されている。

まとめ

Codex CLIのconfig.tomlは、単独のファイルではなくCLIフラグからシステム設定までの7階層として動いている。まずは~/.codex/config.tomlにモデル・承認・サンドボックスなど基本の6項目を書き、用途ごとの差分だけをprofileファイルへ切り出し、その場限りの調整は--configで済ませる、という順番で組み立てると管理しやすい。

承認まわりはapproval_policyとsandbox_modeの組み合わせ、あるいはbeta機能であるpermission profilesのどちらかに寄せて設計し、両者を混在させないことが公式ドキュメント上の前提になる。granular approval policyやshell_environment_policy、feature flagsは、必要になったときに個別に調整すれば十分で、最初からすべてを作り込む必要はない。

モデルの選び方やCodexの提供形態そのものについては、ChatGPT最新モデルの違いと使い分けもあわせて確認しておくと、config.toml側のmodel設定を決める判断材料になる。