Configuration Reference

概要

config.toml と requirements.toml のキーの索引。このページは公式リファレンスのうち日常的に使うキー群を抜き出したもので、全キーを網羅していない。 網羅的な一覧と最新の JSON スキーマは出典を参照する。

仕様

ファイルの位置

user レベル: ~/.codex/config.toml
project スコープの上書き: .codex/config.toml。trusted なプロジェクトのときにのみ読み込まれる
config profile ファイル: config.toml の隣に $CODEX_HOME/profile-name.config.toml として置き、--profile profile-name で選ぶ

project スコープの config が上書きできないキー

project-local の .codex/config.toml に書いても無視されるキー（machine-local なプロバイダ、auth、ホスト所有の app リクエストメタデータ、通知、config profile の選択、テレメトリ経路）:

openai_base_url、chatgpt_base_url、apps_mcp_product_sku、model_provider、model_providers、notify、profile、profiles、experimental_realtime_ws_base_url、otel

これらは user レベルの config に置く。

JSON スキーマ

config.toml の最新 JSON スキーマが公開されている。VS Code / Cursor で補完と診断を得るには Even Better TOML 拡張を入れ、config.toml の先頭に次を書く。

#:schema https://developers.openai.com/codex/config-schema.json

モデルとプロバイダ

キー	型	説明
`model`	string	使うモデル
`review_model`	string	`/review` が使うモデルの上書き。既定は現在のセッションのモデル
`model_provider`	string	`model_providers` のプロバイダ ID（既定 `openai`）
`openai_base_url`	string	組み込み `openai` プロバイダの base URL 上書き
`model_context_window`	number	有効なモデルが使えるコンテキストウィンドウのトークン数
`model_auto_compact_token_limit`	number	自動 compaction を起こすトークン閾値。未設定ならモデルの既定
`model_auto_compact_token_limit_scope`	`total` \| `body_after_prefix`	閾値を有効なコンテキスト全体で数えるか（`total`、既定）、引き継いだ compaction-window prefix より後の増分だけで数えるか
`model_catalog_json`	path	起動時に読み込む JSON モデルカタログ。選択した profile ファイルが profile ごとに上書きできる
`oss_provider`	`lmstudio` \| `ollama`	`--oss` 実行時の既定のローカルプロバイダ。未設定なら都度尋ねる
`model_reasoning_effort`	`minimal`\|`low`\|`medium`\|`high`\|`xhigh`	対応モデルの reasoning effort。Responses API のみ。`xhigh` はモデル依存
`plan_mode_reasoning_effort`	`none`\|`minimal`\|`low`\|`medium`\|`high`\|`xhigh`	Plan mode 専用の上書き。未設定なら Plan mode の組み込みプリセット既定
`model_reasoning_summary`	`auto`\|`concise`\|`detailed`\|`none`	reasoning summary の詳細度、または無効化
`model_verbosity`	`low`\|`medium`\|`high`	GPT-5 Responses API 向けの verbosity 上書き。未設定ならモデル／プリセットの既定
`model_supports_reasoning_summaries`	boolean	reasoning メタデータを送る／送らないを強制する
`personality`	`none`\|`friendly`\|`pragmatic`	`supportsPersonality` を宣言するモデルでの既定のコミュニケーションスタイル。スレッド／ターン単位や `/personality` で上書き可
`service_tier`	string	新しいターンで優先する service tier。`fast` または有効なモデルが宣言する tier。`fast` はリクエスト値 `priority` に対応づく

カスタムプロバイダ（model_providers.<id>）:

組み込みのプロバイダ ID（openai、ollama、lmstudio）は予約されており上書きできない
name、base_url、env_key、env_key_instructions、requires_openai_auth（既定 false）、query_params、http_headers、env_http_headers
experimental_bearer_token: 直接のベアラトークン。非推奨とされ、env_key の利用が案内されている
wire_api: responses が唯一のサポート値で、省略時の既定
request_max_retries（既定 4）、stream_max_retries（既定 5）、stream_idle_timeout_ms（既定 300000）
supports_websockets: Responses API の WebSocket transport に対応するか
supports_standalone_web_search（既定 false）: 互換の standalone web search エンドポイントへの対応を宣言する。standalone search は開発中で既定 off。プロバイダの互換性だけでは有効にならない
auth テーブル（コマンドでベアラトークンを取得）: command（トークンを stdout に出力する必要がある）、args、timeout_ms（既定 5000）、refresh_interval_ms（既定 300000。0 で認証リトライ後のみ更新）、cwd。env_key / experimental_bearer_token / requires_openai_auth と併用しない
model_providers.amazon-bedrock.aws.profile / .region: 組み込みの amazon-bedrock プロバイダ用

承認・sandbox

キー	型	説明
`approval_policy`	`untrusted`\|`on-request`\|`never`\| `{ granular = {...} }`	コマンド実行前に停止するタイミング。`on-failure` は deprecated。対話実行なら `on-request`、非対話なら `never` を使う
`approval_policy.granular.sandbox_approval`	boolean	`true` で sandbox escalation の承認プロンプトを表示できる
`approval_policy.granular.rules`	boolean	`true` で execpolicy の `prompt` ルール由来の承認を表示できる
`approval_policy.granular.mcp_elicitations`	boolean	`true` で MCP の elicitation プロンプトを自動拒否せず表示できる
`approval_policy.granular.request_permissions`	boolean	`true` で `request_permissions` ツールのプロンプトを表示できる
`approval_policy.granular.skill_approval`	boolean	`true` で skill-script の承認プロンプトを表示できる
`approvals_reviewer`	`user`\|`auto_review`	`on-request` または granular ポリシーでのレビュー担当。既定 `user`。sandbox を変えず、sandbox 内で既に許可されたアクションのレビューもしない
`auto_review.policy`	string	自動レビュー用のローカル Markdown ポリシー。managed `guardian_policy_config` が優先。空値は無視される
`allow_login_shell`	boolean	shell 系ツールで login-shell セマンティクスを許す。既定 `true`。`false` のとき `login = true` の要求は拒否され、`login` 省略時は非 login シェルになる
`sandbox_mode`	`read-only`\|`workspace-write`\|`danger-full-access`	コマンド実行時のファイルシステム／ネットワークポリシー
`sandbox_workspace_write.writable_roots`	array<string>	`workspace-write` のときの追加の書き込み可能 root
`sandbox_workspace_write.network_access`	boolean	workspace-write sandbox 内で outbound を許す
`sandbox_workspace_write.exclude_tmpdir_env_var`	boolean	writable roots から `$TMPDIR` を外す
`sandbox_workspace_write.exclude_slash_tmp`	boolean	writable roots から `/tmp` を外す
`windows.sandbox`	`unelevated`\|`elevated`	Windows 専用。ネイティブ実行時のサンドボックスモード
`windows.sandbox_private_desktop`	boolean	Windows ネイティブで、最終的な sandbox 子プロセスを private desktop で動かす（既定）。旧来の `Winsta0\Default` 挙動との互換が必要なときだけ `false`
`projects.<path>.trust_level`	`"trusted"` \| `"untrusted"`	プロジェクトまたは worktree を trusted / untrusted としてマークする。untrusted なプロジェクトは project-local の config・hooks・rules を含む project スコープの `.codex/` レイヤーをスキップする
`forced_login_method`	`chatgpt`\|`api`	認証方法を限定する
`forced_chatgpt_workspace_id`	string (uuid)	ChatGPT ログインを特定ワークスペースに限定する

permission profile 関連のキー（default_permissions、[permissions.<name>.*]）は facts/codex/permissions.md を参照。Beta 扱い。

MCP サーバー

キー	型	説明
`mcp_servers.<id>.command` / `.args` / `.env` / `.cwd`	—	stdio サーバーの起動設定
`mcp_servers.<id>.env_vars`	array	stdio サーバー向けに許可する追加の環境変数。文字列エントリは既定で `source = "local"`。`source = "remote"` は executor ベースのリモート stdio でのみ使う
`mcp_servers.<id>.url`	string	streamable HTTP サーバーのエンドポイント
`mcp_servers.<id>.auth`	`oauth`\|`chatgpt`	設定済みのベアラトークンと Authorization ヘッダーの後に使う認証のフォールバック。`oauth`（既定）は保存済みの MCP OAuth 資格情報。`chatgpt` は信頼された first-party の ChatGPT オリジンに対して現在の ChatGPT セッションを使い、その後 OAuth にフォールバックする。どちらのモードも、資格情報が解決できなければ未認証で接続しうる
`mcp_servers.<id>.bearer_token_env_var`	string	ベアラトークンを供給する環境変数
`mcp_servers.<id>.http_headers` / `.env_http_headers`	map	HTTP ヘッダー
`mcp_servers.<id>.enabled`	boolean	設定を消さずに無効化する
`mcp_servers.<id>.required`	boolean	true で、有効なこのサーバーが初期化できないとき起動／resume を失敗させる
`mcp_servers.<id>.startup_timeout_sec`	number	既定 10 秒の起動タイムアウトを上書き
`mcp_servers.<id>.startup_timeout_ms`	number	`startup_timeout_sec` のミリ秒版エイリアス
`mcp_servers.<id>.tool_timeout_sec`	number	既定 60 秒のツール単位タイムアウトを上書き
`mcp_servers.<id>.enabled_tools`	array<string>	公開するツール名の allow list
`mcp_servers.<id>.disabled_tools`	array<string>	`enabled_tools` の後に適用される deny list
`mcp_servers.<id>.default_tools_approval_mode`	`auto`\|`prompt`\|`writes`\|`approve`	このサーバーの既定の承認挙動
`mcp_servers.<id>.tools.<tool>.approval_mode`	同上	ツール単位の上書き
`mcp_servers.<id>.scopes`	array<string>	認証時に要求する OAuth スコープ
`mcp_servers.<id>.oauth_resource`	string	MCP ログイン時に含める RFC 8707 の OAuth resource パラメータ
`mcp_servers.<id>.experimental_environment`	`local`\|`remote`	実験的な配置。`remote` はリモート executor 環境で stdio サーバーを起動する。streamable HTTP のリモート配置は未実装

subagent（`[agents]`）

agents.enabled（既定 true）、agents.max_concurrent_threads_per_session、agents.max_threads（legacy alias）、agents.default_subagent_model、agents.default_subagent_reasoning_effort、agents.interrupt_message（既定 true）
agents.<name>.description: その agent 型を選ぶときに Codex に見せる役割の説明
agents.<name>.config_file: その役割の TOML config レイヤーへのパス。相対パスは役割を宣言した config ファイルから解決される
スカラー設定名は予約されており、カスタムの役割名には使えない

Memories（`[memories]`）

features.memories は Experimental で既定 off。

キー	既定	制限	説明
`memories.generate_memories`	`true`	—	`false` で、新規スレッドをメモリ生成の入力として保存しない
`memories.use_memories`	`true`	—	`false` で、既存メモリを以後のセッションに注入しない
`memories.disable_on_external_context`	`false`	—	`true` で、MCP ツール呼び出し・web search・tool search など外部コンテキストを使ったスレッドをメモリ生成から外す。legacy alias: `memories.no_memories_if_mcp_or_web_search`
`memories.max_raw_memories_for_consolidation`	`256`	上限 `4096`	グローバル統合のために保持する直近の raw メモリ数
`memories.max_unused_days`	`30`	`0`–`365` に clamp	最後に使われてからこの日数を超えると統合の対象外になる
`memories.max_rollout_age_days`	`30`	`0`–`90` に clamp	メモリ生成の対象とするスレッドの最大経過日数
`memories.max_rollouts_per_startup`	`16`	上限 `128`	起動 1 回あたりに処理する rollout 候補の最大数
`memories.min_rollout_idle_hours`	`6`	`1`–`48` に clamp	メモリ生成の対象になるまでの最小アイドル時間
`memories.min_rate_limit_remaining_percent`	`25`	`0`–`100` に clamp	メモリ生成を始めるのに必要な rate-limit ウィンドウの残り割合
`memories.extract_model`	—	—	スレッド単位のメモリ抽出に使うモデルの上書き
`memories.consolidation_model`	—	—	グローバル統合に使うモデルの上書き

feature flags（`[features]`）

安定・既定 on とされるもの: apps、hooks（features.codex_hooks は deprecated alias）、unified_exec（Windows を除いて既定有効）、shell_snapshot、multi_agent（spawn_agent / send_input / resume_agent / wait_agent / close_agent）、goals、remote_plugin、personality、shell_tool、enable_request_compression、skill_mcp_dependency_install、fast_mode（有効なモデルが宣言する場合の Fast tier コマンドを含む）。

開発中・実験的・既定 off:

features.code_mode.enabled: 開発中で既定 off。excluded_tool_namespaces、direct_only_tool_namespaces を併せて持つ
features.rollout_budget.enabled: 開発中で既定 off。有効時は limit_tokens が必須。reminder_interval_tokens は既定で limit_tokens の 10%（最低 1 トークン）、sampling_token_weight と prefill_token_weight は既定 1.0
features.memories: 既定 off
features.network_proxy: experimental で既定 off。boolean またはテーブル形式
features.prevent_idle_sleep: experimental で既定 off。ターン実行中にマシンをスリープさせない
features.web_search / web_search_cached / web_search_request: すべて deprecated。トップレベルの web_search 設定を使う
suppress_unstable_features_warning: 開発中のフィーチャーフラグを有効にしたときの警告を抑止する

シェル環境ポリシー（`[shell_environment_policy]`）

キー	説明
`inherit`	`all` \| `core` \| `none`。サブプロセス起動時のベースラインの継承
`ignore_default_excludes`	既定 `true`。KEY / SECRET / TOKEN を含む変数を他のフィルタの前に保持する。`false` にすると自動のシークレット名除外が適用される
`filters`	`map<string, include \| exclude>`。正準の大小文字非依存パターンフィルタ。include エントリは allowlist を作り、除外された値を復活させられない。明示的な `set` の値は除外の後に適用される。同一レイヤーで legacy の `exclude` / `include_only` 配列と併用しない
`exclude`	legacy の除外パターン。新規設定では `filters` を使う
`include_only`	legacy の allowlist。新規設定では `filters` を使う
`set`	除外の後に注入する明示的な環境値。include フィルタはこれも取り除きうる
`experimental_use_profile`	サブプロセス起動時にユーザーのシェル profile を使う

プロジェクトの指示ファイルと履歴

キー	説明
`project_root_markers`	プロジェクトルート探索に使うマーカーファイル名の一覧
`project_doc_max_bytes`	プロジェクト指示を組み立てる際に `AGENTS.md` から読む最大バイト数
`project_doc_fallback_filenames`	`AGENTS.md` が無いときに試す追加のファイル名
`model_instructions_file`	`AGENTS.md` の代わりに組み込みの指示を置き換えるファイル。旧キー `experimental_instructions_file` は deprecated。新しい名前に更新すること
`instructions`	将来のために予約。`model_instructions_file` か `AGENTS.md` を使う
`developer_instructions`	セッションに注入する追加の developer instructions（任意）
`compact_prompt`	履歴 compaction プロンプトのインライン上書き
`experimental_compact_prompt_file`	experimental。compaction プロンプトの上書きをファイルから読む
`history.persistence`	`save-all` \| `none`。トランスクリプトを `history.jsonl` に保存するか
`history.max_bytes`	設定すると、古いエントリを落として履歴ファイルサイズを制限する
`tool_output_token_limit`	個々のツール／関数出力を履歴に保存するときのトークン予算
`background_terminal_max_timeout`	空の `write_stdin` ポーリングの最大ポーリング窓（ミリ秒）。既定 `300000`。旧キー `background_terminal_timeout` を置き換える

その他

キー	説明
`log_dir`	ログ出力先。既定 `$CODEX_HOME/log`。明示設定すると opt-in の平文 TUI ログ `codex-tui.log` も有効になる
`sqlite_home`	agent job などの再開可能なランタイム状態に使う SQLite DB のディレクトリ
`notify`	通知に使うコマンド。Codex から JSON ペイロードを受け取る
`check_for_update_on_startup`	起動時の更新確認。更新が中央管理されている場合にのみ false にする
`feedback.enabled`	ローカルクライアントの `/feedback` 送信（既定 true）
`analytics.enabled`	このマシン／profile の analytics。未設定ならクライアントの既定
`file_opener`	`vscode`（既定）\| `vscode-insiders` \| `windsurf` \| `cursor` \| `none`。出力の引用を開く URI スキーム
`web_search`	web search のモード（`disabled` / `cached` / `indexed` / `live`）
`tools.web_search`	web search ツールの設定。旧来の真偽値形式も受け付けるが、オブジェクト形式では `context_size`（`low`/`medium`/`high`）、`allowed_domains`、おおよその `location` を設定できる
`tools.view_image`	ローカル画像の添付ツール `view_image` の有効化
`skills.config`	skill ごとの有効・無効の上書き。各要素は `path`（`SKILL.md` を含む skill フォルダ）と `enabled`
`hide_agent_reasoning`	TUI と `codex exec` の両方で reasoning イベントを抑止する
`show_raw_agent_reasoning`	有効なモデルが生の reasoning を出すとき、それを表示する
`experimental_use_unified_exec_tool`	unified exec を有効にする旧来の名前。`[features].unified_exec` または `codex --enable unified_exec` が推奨される
`computer_use.windows.always_allowed_app_ids`	Windows 向け。Computer Use が確認なしで開ける app 識別子。一覧に無い app は承認が要る
`[tui.*]`	通知、アニメーション、alternate screen、vim mode、テーマ、status line、terminal title、keymap など
`[desktop.custom_file_handlers.<id>]`	デスクトップのカスタムファイルハンドラ
`[plugins.<plugin>.mcp_servers.<server>.*]`	plugin がバンドルする MCP サーバーの有効化・ツール許可・承認モード
`[apps.*]`	app（connector）の有効化、`destructive_hint` / `open_world_hint` を宣言するツールの許可、承認モード、reviewer
`[tool_suggest]`	発見可能な connector / plugin のツール提案の許可・無効化
`[otel.*]`	OpenTelemetry の environment（既定 `dev`）、exporter、trace_exporter、metrics_exporter（既定 `statsig`）、`log_user_prompt`、エンドポイントと TLS
`[notice.*]`	各種警告の非表示設定
`cli_auth_credentials_store` / `mcp_oauth_credentials_store` / `mcp_oauth_callback_port` / `mcp_oauth_callback_url`	資格情報の保存先と OAuth コールバック

`requirements.toml`

管理者が強制する設定ファイル。ユーザーが上書きできないセキュリティ上重要な設定を制約する。

ChatGPT Business / Enterprise では、cloud から取得した requirements も適用されうる
[features] で config.toml と同じ正準キーを使ってランタイムのフィーチャーフラグを固定できる。app 専用のキーなど config.toml には属さない文書化されたキーも含みうる
省略したキーは制約されないまま
一部の managed requirements は allowlist ではなく厳密な値を強制する。強制されたパス、更新の設定、login-shell ポリシー、feedback 設定、Windows の private-desktop 設定はユーザーが上書きできない
managed の permission-profile allowlist には Codex 0.138.0 以降が必要。0.137.0 以前は allowed_permission_profiles と managed default_permissions を無視する
allowed_sandbox_modes は sandbox_mode と併せて使う。permission-profile 展開では allowed_permission_profiles を managed default_permissions と併せて使う
[models.new_thread] は managed の既定であって強制ではない。 専用の CLI フラグや --config の上書きによる明示的な起動時の選択が優先する。明示的な model または reasoning-effort の上書きは managed の両フィールドを飛ばす。service_tier は独立

主なキー群: allowed_approval_policies、allowed_approvals_reviewers、guardian_policy_config、allowed_permission_profiles、default_permissions、enforce_residency、[models.new_thread]、[permissions]、allowed_sandbox_modes、[windows]（allowed_sandbox_implementations、sandbox_private_desktop）、remote_sandbox_config（hostname_patterns、allowed_sandbox_modes）、allowed_web_search_modes、allow_managed_hooks_only、allow_appshots、allow_remote_control、[features]（plugin_sharing、in_app_updates、in_app_browser、browser_use、browser_use_external、browser_use_full_cdp_access、guardian_approval、computer_use、workspace_dependencies など）、[computer_use]、[experimental_network]、[hooks]（managed_dir、windows_managed_dir）、permissions.filesystem.deny_read、[mcp_servers.<id>.identity]、[plugins]、[marketplaces]、[apps]、[rules]。

requirements.toml の [rules]:

.rules ファイルとマージされる管理者強制のコマンドルール。requirements の rules は制限的でなければならない
rules.prefix_rules[] は pattern と decision を必須とする
pattern は token の配列で、各 token は token（リテラル 1 個）または any_of（その位置で許す代替 token の配列）のどちらかを設定する
decision は prompt または forbidden のみ。allow は指定できない
justification（任意）は承認プロンプトや拒否メッセージに表示される

制約・注意点

このページは全キーの網羅ではない。網羅的な一覧は出典の Configuration Reference を参照する
experimental_instructions_file は deprecated。model_instructions_file に改名すること