config-reference.md Codex Docs, 2026-02-24 00:33 UTC → 2026-03-18 00:36 UTC

6 6 

7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.

8 8 

9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).

10 10 

11| Key | Type / Values | Details |11| Key | Type / Values | Details |

12| --- | --- | --- |12| --- | --- | --- |

13| `agents.<name>.config_file` | `string (path)` | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |13| `agents.<name>.config_file` | `string (path)` | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |

14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |

15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |

16| `agents.job_max_runtime_seconds` | `number` | Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker. |

15| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |

16| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |

17| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |19| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |

20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |

18| `approval_policy` | `untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |21| `approval_policy` | `untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |

19| `approval_policy.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |22| `approval_policy.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |

20| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |23| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |

33| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |36| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |

34| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |37| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |

35| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |38| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |

39| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |

36| `compact_prompt` | `string` | Inline override for the history compaction prompt. |40| `compact_prompt` | `string` | Inline override for the history compaction prompt. |

37| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |41| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |

38| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |42| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |

39| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |43| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |

40| `experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`. |

41| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |44| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |

42| `features.apply_patch_freeform` | `boolean` | Expose the freeform `apply_patch` tool (experimental). |

43| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |45| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |

44| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |46| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |

47| `features.artifact` | `boolean` | Enable native artifact tools such as slides and spreadsheets (under development). |

45| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |48| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |

46| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |49| `features.collaboration_modes` | `boolean` | Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key. |

47| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |50| `features.default_mode_request_user_input` | `boolean` | Allow `request_user_input` in default collaboration mode (under development; off by default). |

48| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |51| `features.elevated_windows_sandbox` | `boolean` | Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it. |

49| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

53| `features.experimental_windows_sandbox` | `boolean` | Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it. |

54| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |

55| `features.image_detail_original` | `boolean` | Allow image outputs with `detail = "original"` on supported models (under development). |

56| `features.image_generation` | `boolean` | Enable the built-in image generation tool (under development). |

50| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |57| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |

51| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |58| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere. |

52| `features.remote_models` | `boolean` | Refresh remote model list before showing readiness (experimental). |59| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |

53| `features.request_rule` | `boolean` | Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default). |60| `features.remote_models` | `boolean` | Legacy toggle for an older remote-model readiness flow. Current builds do not use it. |

61| `features.request_rule` | `boolean` | Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset. |

62| `features.responses_websockets` | `boolean` | Prefer the Responses API WebSocket transport for supported providers (under development). |

63| `features.responses_websockets_v2` | `boolean` | Enable Responses API WebSocket v2 mode (under development). |

54| `features.runtime_metrics` | `boolean` | Show runtime metrics summary in TUI turn separators (experimental). |64| `features.runtime_metrics` | `boolean` | Show runtime metrics summary in TUI turn separators (experimental). |

55| `features.search_tool` | `boolean` | Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental). |65| `features.search_tool` | `boolean` | Legacy toggle for an older Apps discovery flow. Current builds do not use it. |

56| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (beta). |66| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |

57| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |67| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |

58| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (beta). |68| `features.skill_env_var_dependency_prompt` | `boolean` | Prompt for missing skill environment-variable dependencies (under development). |

69| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |

70| `features.sqlite` | `boolean` | Enable SQLite-backed state persistence (stable; on by default). |

71| `features.steer` | `boolean` | Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior. |

72| `features.undo` | `boolean` | Enable undo support (stable; off by default). |

73| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (stable; enabled by default except on Windows). |

59| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |74| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |

60| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |75| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |

61| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |76| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |

67| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |82| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |

68| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |83| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |

69| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |84| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |

70| `include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |

71| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |85| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |

72| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |86| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |

73| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |87| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |

84| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |98| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |

85| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |99| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |

86| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |100| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |

101| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |

87| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |102| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |

103| `mcp_servers.<id>.scopes` | `array<string>` | OAuth scopes to request when authenticating to that MCP server. |

88| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |104| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |

89| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |105| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |

90| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |106| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |

107| `model_providers.<id>.requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). |123| `model_providers.<id>.requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). |

108| `model_providers.<id>.stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). |124| `model_providers.<id>.stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). |

109| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |125| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |

110| `model_providers.<id>.wire_api` | `chat | responses` | Protocol used by the provider (defaults to `chat` if omitted). |126| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

127| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |

111| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |128| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |

112| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |129| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |

113| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |130| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |

114| `model_verbosity` | `low | medium | high` | Control GPT-5 Responses API verbosity (defaults to `medium`). |131| `model_verbosity` | `low | medium | high` | Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used. |

115| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |132| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |

116| `notice.hide_gpt-5.1-codex-max_migration_prompt` | `boolean` | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |133| `notice.hide_gpt-5.1-codex-max_migration_prompt` | `boolean` | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |

117| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |134| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |

129| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |146| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |

130| `otel.exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL exporter TLS. |147| `otel.exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL exporter TLS. |

131| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |148| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |

149| `otel.metrics_exporter` | `none | statsig | otlp-http | otlp-grpc` | Select the OpenTelemetry metrics exporter (defaults to `statsig`). |

132| `otel.trace_exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |150| `otel.trace_exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |

133| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |151| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |

134| `otel.trace_exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL trace exporter requests. |152| `otel.trace_exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL trace exporter requests. |

136| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |154| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |

137| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |155| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |

138| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |156| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |

157| `permissions.network.admin_url` | `string` | Admin endpoint for the managed network proxy. |

158| `permissions.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

159| `permissions.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |

160| `permissions.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

161| `permissions.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |

162| `permissions.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

163| `permissions.network.dangerously_allow_non_loopback_admin` | `boolean` | Permit non-loopback bind addresses for the managed proxy admin listener. |

164| `permissions.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

165| `permissions.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |

166| `permissions.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener from the managed network proxy. |

167| `permissions.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

168| `permissions.network.enabled` | `boolean` | Enable the managed network proxy configuration for subprocesses. |

169| `permissions.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |

170| `permissions.network.proxy_url` | `string` | HTTP proxy endpoint used by the managed network proxy. |

171| `permissions.network.socks_url` | `string` | SOCKS5 proxy endpoint used by the managed network proxy. |

139| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |172| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |

173| `plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default. |

140| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |174| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

141| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |175| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |

142| `profiles.<name>.experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |176| `profiles.<name>.analytics.enabled` | `boolean` | Profile-scoped analytics enablement override. |

143| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |177| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |

144| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |

145| `profiles.<name>.model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |178| `profiles.<name>.model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |

179| `profiles.<name>.model_instructions_file` | `string (path)` | Profile-scoped replacement for the built-in instruction file. |

146| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |180| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |

147| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |181| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |

182| `profiles.<name>.plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Profile-scoped Plan-mode reasoning override. |

183| `profiles.<name>.service_tier` | `flex | fast` | Profile-scoped service tier preference for new turns. |

184| `profiles.<name>.tools_view_image` | `boolean` | Enable or disable the `view_image` tool in that profile. |

148| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |185| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |

186| `profiles.<name>.windows.sandbox` | `unelevated | elevated` | Profile-scoped Windows sandbox mode override. |

149| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |187| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |

150| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |188| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |

151| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |189| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |

156| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |194| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |

157| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |195| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |

158| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |196| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |

197| `service_tier` | `flex | fast` | Preferred service tier for new turns. `fast` is honored only when the `features.fast_mode` gate is enabled. |

159| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |198| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |

160| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |199| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |

161| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |200| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |

166| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |205| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |

167| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |206| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |

168| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |207| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |

208| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |

169| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |209| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |

170| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |210| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |

211| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |

171| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |212| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |

172| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |213| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

173| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |214| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |

174| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |215| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

216| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |

175| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |217| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |

176| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |218| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |

177| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |219| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |

178| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |220| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

221| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |

179| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |222| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |

180| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |223| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

224| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |

181 225 

182Key226Key

183 227 

205 249 

206Key250Key

207 251 

252`agents.<name>.nickname_candidates`

253 

254Type / Values

255 

256`array<string>`

257 

258Details

259 

260Optional pool of display nicknames for spawned agents in that role.

261 

262Key

263 

264`agents.job_max_runtime_seconds`

265 

266Type / Values

267 

268`number`

269 

270Details

271 

272Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.

273 

274Key

275 

208`agents.max_depth`276`agents.max_depth`

209 277 

210Type / Values278Type / Values

225 293 

226Details294Details

227 295 

228Maximum number of agent threads that can be open concurrently.296Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.

229 297 

230Key298Key

231 299 

241 309 

242Key310Key

243 311 

312`analytics.enabled`

313 

314Type / Values

315 

316`boolean`

317 

318Details

319 

320Enable or disable analytics for this machine/profile. When unset, the client default applies.

321 

322Key

323 

244`approval_policy`324`approval_policy`

245 325 

246Type / Values326Type / Values

457 537 

458Key538Key

459 539 

540`commit_attribution`

541 

542Type / Values

543 

544`string`

545 

546Details

547 

548Override the commit co-author trailer text. Set an empty string to disable automatic attribution.

549 

550Key

551 

460`compact_prompt`552`compact_prompt`

461 553 

462Type / Values554Type / Values

505 597 

506Key598Key

507 599 

508`experimental_use_freeform_apply_patch`600`experimental_use_unified_exec_tool`

509 601 

510Type / Values602Type / Values

511 603 

513 605 

514Details606Details

515 607 

516Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.608Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

517 609 

518Key610Key

519 611 

520`experimental_use_unified_exec_tool`612`features.apps`

521 613 

522Type / Values614Type / Values

523 615 

525 617 

526Details618Details

527 619 

528Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.620Enable ChatGPT Apps/connectors support (experimental).

529 621 

530Key622Key

531 623 

532`features.apply_patch_freeform`624`features.apps_mcp_gateway`

533 625 

534Type / Values626Type / Values

535 627 

537 629 

538Details630Details

539 631 

540Expose the freeform `apply_patch` tool (experimental).632Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).

541 633 

542Key634Key

543 635 

544`features.apps`636`features.artifact`

545 637 

546Type / Values638Type / Values

547 639 

549 641 

550Details642Details

551 643 

552Enable ChatGPT Apps/connectors support (experimental).644Enable native artifact tools such as slides and spreadsheets (under development).

553 645 

554Key646Key

555 647 

556`features.apps_mcp_gateway`648`features.child_agents_md`

557 649 

558Type / Values650Type / Values

559 651 

561 653 

562Details654Details

563 655 

564Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).656Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).

565 657 

566Key658Key

567 659 

568`features.child_agents_md`660`features.collaboration_modes`

569 661 

570Type / Values662Type / Values

571 663 

573 665 

574Details666Details

575 667 

576Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).668Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key.

577 669 

578Key670Key

579 671 

580`features.collaboration_modes`672`features.default_mode_request_user_input`

581 673 

582Type / Values674Type / Values

583 675 

585 677 

586Details678Details

587 679 

588Enable collaboration modes such as plan mode (stable; on by default).680Allow `request_user_input` in default collaboration mode (under development; off by default).

589 681 

590Key682Key

591 683 

597 689 

598Details690Details

599 691 

600Enable the elevated Windows sandbox pipeline (experimental).692Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it.

693 

694Key

695 

696`features.enable_request_compression`

697 

698Type / Values

699 

700`boolean`

701 

702Details

703 

704Compress streaming request bodies with zstd when supported (stable; on by default).

601 705 

602Key706Key

603 707 

609 713 

610Details714Details

611 715 

612Run the Windows restricted-token sandbox (experimental).716Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it.

717 

718Key

719 

720`features.fast_mode`

721 

722Type / Values

723 

724`boolean`

725 

726Details

727 

728Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

613 729 

614Key730Key

615 731 

616`features.multi_agent`732`features.image_detail_original`

617 733 

618Type / Values734Type / Values

619 735 

621 737 

622Details738Details

623 739 

624Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).740Allow image outputs with `detail = "original"` on supported models (under development).

741 

742Key

743 

744`features.image_generation`

745 

746Type / Values

747 

748`boolean`

749 

750Details

751 

752Enable the built-in image generation tool (under development).

625 753 

626Key754Key

627 755 

645 773 

646Details774Details

647 775 

648Force PowerShell UTF-8 output (defaults to true).776Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.

777 

778Key

779 

780`features.prevent_idle_sleep`

781 

782Type / Values

783 

784`boolean`

785 

786Details

787 

788Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

649 789 

650Key790Key

651 791 

657 797 

658Details798Details

659 799 

660Refresh remote model list before showing readiness (experimental).800Legacy toggle for an older remote-model readiness flow. Current builds do not use it.

661 801 

662Key802Key

663 803 

669 809 

670Details810Details

671 811 

672Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).812Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.

813 

814Key

815 

816`features.responses_websockets`

817 

818Type / Values

819 

820`boolean`

821 

822Details

823 

824Prefer the Responses API WebSocket transport for supported providers (under development).

825 

826Key

827 

828`features.responses_websockets_v2`

829 

830Type / Values

831 

832`boolean`

833 

834Details

835 

836Enable Responses API WebSocket v2 mode (under development).

673 837 

674Key838Key

675 839 

693 857 

694Details858Details

695 859 

696Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).860Legacy toggle for an older Apps discovery flow. Current builds do not use it.

697 861 

698Key862Key

699 863 

705 869 

706Details870Details

707 871 

708Snapshot shell environment to speed up repeated commands (beta).872Snapshot shell environment to speed up repeated commands (stable; on by default).

709 873 

710Key874Key

711 875 

721 885 

722Key886Key

723 887 

888`features.skill_env_var_dependency_prompt`

889 

890Type / Values

891 

892`boolean`

893 

894Details

895 

896Prompt for missing skill environment-variable dependencies (under development).

897 

898Key

899 

900`features.skill_mcp_dependency_install`

901 

902Type / Values

903 

904`boolean`

905 

906Details

907 

908Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

909 

910Key

911 

912`features.sqlite`

913 

914Type / Values

915 

916`boolean`

917 

918Details

919 

920Enable SQLite-backed state persistence (stable; on by default).

921 

922Key

923 

924`features.steer`

925 

926Type / Values

927 

928`boolean`

929 

930Details

931 

932Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.

933 

934Key

935 

936`features.undo`

937 

938Type / Values

939 

940`boolean`

941 

942Details

943 

944Enable undo support (stable; off by default).

945 

946Key

947 

724`features.unified_exec`948`features.unified_exec`

725 949 

726Type / Values950Type / Values

729 953 

730Details954Details

731 955 

732Use the unified PTY-backed exec tool (beta).956Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

733 957 

734Key958Key

735 959 

865 1089 

866Key1090Key

867 1091 

868`include_apply_patch_tool`

869 

870Type / Values

871 

872`boolean`

873 

874Details

875 

876Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.

877 

878Key

879 

880`instructions`1092`instructions`

881 1093 

882Type / Values1094Type / Values

1069 1281 

1070Key1282Key

1071 1283 

1284`mcp_servers.<id>.oauth_resource`

1285 

1286Type / Values

1287 

1288`string`

1289 

1290Details

1291 

1292Optional RFC 8707 OAuth resource parameter to include during MCP login.

1293 

1294Key

1295 

1072`mcp_servers.<id>.required`1296`mcp_servers.<id>.required`

1073 1297 

1074Type / Values1298Type / Values

1081 1305 

1082Key1306Key

1083 1307 

1308`mcp_servers.<id>.scopes`

1309 

1310Type / Values

1311 

1312`array<string>`

1313 

1314Details

1315 

1316OAuth scopes to request when authenticating to that MCP server.

1317 

1318Key

1319 

1084`mcp_servers.<id>.startup_timeout_ms`1320`mcp_servers.<id>.startup_timeout_ms`

1085 1321 

1086Type / Values1322Type / Values

1345 1581 

1346Key1582Key

1347 1583 

1584`model_providers.<id>.supports_websockets`

1585 

1586Type / Values

1587 

1588`boolean`

1589 

1590Details

1591 

1592Whether that provider supports the Responses API WebSocket transport.

1593 

1594Key

1595 

1348`model_providers.<id>.wire_api`1596`model_providers.<id>.wire_api`

1349 1597 

1350Type / Values1598Type / Values

1351 1599 

1352`chat | responses`1600`responses`

1353 1601 

1354Details1602Details

1355 1603 

1356Protocol used by the provider (defaults to `chat` if omitted).1604Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.

1357 1605 

1358Key1606Key

1359 1607 

1401 1649 

1402Details1650Details

1403 1651 

1404Control GPT-5 Responses API verbosity (defaults to `medium`).1652Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.

1405 1653 

1406Key1654Key

1407 1655 

1609 1857 

1610Key1858Key

1611 1859 

1860`otel.metrics_exporter`

1861 

1862Type / Values

1863 

1864`none | statsig | otlp-http | otlp-grpc`

1865 

1866Details

1867 

1868Select the OpenTelemetry metrics exporter (defaults to `statsig`).

1869 

1870Key

1871 

1612`otel.trace_exporter`1872`otel.trace_exporter`

1613 1873 

1614Type / Values1874Type / Values

1693 1953 

1694Key1954Key

1695 1955 

1956`permissions.network.admin_url`

1957 

1958Type / Values

1959 

1960`string`

1961 

1962Details

1963 

1964Admin endpoint for the managed network proxy.

1965 

1966Key

1967 

1968`permissions.network.allow_local_binding`

1969 

1970Type / Values

1971 

1972`boolean`

1973 

1974Details

1975 

1976Permit local bind/listen operations through the managed proxy.

1977 

1978Key

1979 

1980`permissions.network.allow_unix_sockets`

1981 

1982Type / Values

1983 

1984`array<string>`

1985 

1986Details

1987 

1988Allowlist of Unix socket paths permitted through the managed proxy.

1989 

1990Key

1991 

1992`permissions.network.allow_upstream_proxy`

1993 

1994Type / Values

1995 

1996`boolean`

1997 

1998Details

1999 

2000Allow the managed proxy to chain to another upstream proxy.

2001 

2002Key

2003 

2004`permissions.network.allowed_domains`

2005 

2006Type / Values

2007 

2008`array<string>`

2009 

2010Details

2011 

2012Allowlist of domains permitted through the managed proxy.

2013 

2014Key

2015 

2016`permissions.network.dangerously_allow_all_unix_sockets`

2017 

2018Type / Values

2019 

2020`boolean`

2021 

2022Details

2023 

2024Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.

2025 

2026Key

2027 

2028`permissions.network.dangerously_allow_non_loopback_admin`

2029 

2030Type / Values

2031 

2032`boolean`

2033 

2034Details

2035 

2036Permit non-loopback bind addresses for the managed proxy admin listener.

2037 

2038Key

2039 

2040`permissions.network.dangerously_allow_non_loopback_proxy`

2041 

2042Type / Values

2043 

2044`boolean`

2045 

2046Details

2047 

2048Permit non-loopback bind addresses for the managed proxy listener.

2049 

2050Key

2051 

2052`permissions.network.denied_domains`

2053 

2054Type / Values

2055 

2056`array<string>`

2057 

2058Details

2059 

2060Denylist of domains blocked by the managed proxy.

2061 

2062Key

2063 

2064`permissions.network.enable_socks5`

2065 

2066Type / Values

2067 

2068`boolean`

2069 

2070Details

2071 

2072Expose a SOCKS5 listener from the managed network proxy.

2073 

2074Key

2075 

2076`permissions.network.enable_socks5_udp`

2077 

2078Type / Values

2079 

2080`boolean`

2081 

2082Details

2083 

2084Allow UDP over the SOCKS5 listener when enabled.

2085 

2086Key

2087 

2088`permissions.network.enabled`

2089 

2090Type / Values

2091 

2092`boolean`

2093 

2094Details

2095 

2096Enable the managed network proxy configuration for subprocesses.

2097 

2098Key

2099 

2100`permissions.network.mode`

2101 

2102Type / Values

2103 

2104`limited | full`

2105 

2106Details

2107 

2108Network proxy mode used for subprocess traffic.

2109 

2110Key

2111 

2112`permissions.network.proxy_url`

2113 

2114Type / Values

2115 

2116`string`

2117 

2118Details

2119 

2120HTTP proxy endpoint used by the managed network proxy.

2121 

2122Key

2123 

2124`permissions.network.socks_url`

2125 

2126Type / Values

2127 

2128`string`

2129 

2130Details

2131 

2132SOCKS5 proxy endpoint used by the managed network proxy.

2133 

2134Key

2135 

1696`personality`2136`personality`

1697 2137 

1698Type / Values2138Type / Values

1705 2145 

1706Key2146Key

1707 2147 

2148`plan_mode_reasoning_effort`

2149 

2150Type / Values

2151 

2152`none | minimal | low | medium | high | xhigh`

2153 

2154Details

2155 

2156Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default.

2157 

2158Key

2159 

1708`profile`2160`profile`

1709 2161 

1710Type / Values2162Type / Values

1729 2181 

1730Key2182Key

1731 2183 

1732`profiles.<name>.experimental_use_freeform_apply_patch`2184`profiles.<name>.analytics.enabled`

1733 2185 

1734Type / Values2186Type / Values

1735 2187 

1737 2189 

1738Details2190Details

1739 2191 

1740Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.2192Profile-scoped analytics enablement override.

1741 2193 

1742Key2194Key

1743 2195 

1753 2205 

1754Key2206Key

1755 2207 

1756`profiles.<name>.include_apply_patch_tool`2208`profiles.<name>.model_catalog_json`

1757 2209 

1758Type / Values2210Type / Values

1759 2211 

1760`boolean`2212`string (path)`

1761 2213 

1762Details2214Details

1763 2215 

1764Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.2216Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).

1765 2217 

1766Key2218Key

1767 2219 

1768`profiles.<name>.model_catalog_json`2220`profiles.<name>.model_instructions_file`

1769 2221 

1770Type / Values2222Type / Values

1771 2223 

1773 2225 

1774Details2226Details

1775 2227 

1776Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).2228Profile-scoped replacement for the built-in instruction file.

1777 2229 

1778Key2230Key

1779 2231 

1801 2253 

1802Key2254Key

1803 2255 

2256`profiles.<name>.plan_mode_reasoning_effort`

2257 

2258Type / Values

2259 

2260`none | minimal | low | medium | high | xhigh`

2261 

2262Details

2263 

2264Profile-scoped Plan-mode reasoning override.

2265 

2266Key

2267 

2268`profiles.<name>.service_tier`

2269 

2270Type / Values

2271 

2272`flex | fast`

2273 

2274Details

2275 

2276Profile-scoped service tier preference for new turns.

2277 

2278Key

2279 

2280`profiles.<name>.tools_view_image`

2281 

2282Type / Values

2283 

2284`boolean`

2285 

2286Details

2287 

2288Enable or disable the `view_image` tool in that profile.

2289 

2290Key

2291 

1804`profiles.<name>.web_search`2292`profiles.<name>.web_search`

1805 2293 

1806Type / Values2294Type / Values

1813 2301 

1814Key2302Key

1815 2303 

2304`profiles.<name>.windows.sandbox`

2305 

2306Type / Values

2307 

2308`unelevated | elevated`

2309 

2310Details

2311 

2312Profile-scoped Windows sandbox mode override.

2313 

2314Key

2315 

1816`project_doc_fallback_filenames`2316`project_doc_fallback_filenames`

1817 2317 

1818Type / Values2318Type / Values

1933 2433 

1934Key2434Key

1935 2435 

2436`service_tier`

2437 

2438Type / Values

2439 

2440`flex | fast`

2441 

2442Details

2443 

2444Preferred service tier for new turns. `fast` is honored only when the `features.fast_mode` gate is enabled.

2445 

2446Key

2447 

1936`shell_environment_policy.exclude`2448`shell_environment_policy.exclude`

1937 2449 

1938Type / Values2450Type / Values

2053 2565 

2054Key2566Key

2055 2567 

2568`sqlite_home`

2569 

2570Type / Values

2571 

2572`string (path)`

2573 

2574Details

2575 

2576Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.

2577 

2578Key

2579 

2056`suppress_unstable_features_warning`2580`suppress_unstable_features_warning`

2057 2581 

2058Type / Values2582Type / Values

2077 2601 

2078Key2602Key

2079 2603 

2604`tools.view_image`

2605 

2606Type / Values

2607 

2608`boolean`

2609 

2610Details

2611 

2612Enable the local-image attachment tool `view_image`.

2613 

2614Key

2615 

2080`tools.web_search`2616`tools.web_search`

2081 2617 

2082Type / Values2618Type / Values

2125 2661 

2126Key2662Key

2127 2663 

2664`tui.model_availability_nux.<model>`

2665 

2666Type / Values

2667 

2668`integer`

2669 

2670Details

2671 

2672Internal startup-tooltip state keyed by model slug.

2673 

2674Key

2675 

2128`tui.notification_method`2676`tui.notification_method`

2129 2677 

2130Type / Values2678Type / Values

2173 2721 

2174Key2722Key

2175 2723 

2724`tui.theme`

2725 

2726Type / Values

2727 

2728`string`

2729 

2730Details

2731 

2732Syntax-highlighting theme override (kebab-case theme name).

2733 

2734Key

2735 

2176`web_search`2736`web_search`

2177 2737 

2178Type / Values2738Type / Values

2195 2755 

2196Track Windows onboarding acknowledgement (Windows only).2756Track Windows onboarding acknowledgement (Windows only).

2197 2757 

2758Key

2759 

2760`windows.sandbox`

2761 

2762Type / Values

2763 

2764`unelevated | elevated`

2765 

2766Details

2767 

2768Windows-only native sandbox mode when running Codex natively on Windows.

2769 

2198Expand to view all2770Expand to view all

2199 2771 

2200You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).2772You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).

2214For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched2786For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched

2215requirements. See the security page for precedence details.2787requirements. See the security page for precedence details.

2216 2788 

2789Use `[features]` in `requirements.toml` to pin feature flags by the same

2790canonical keys that `config.toml` uses. Omitted keys remain unconstrained.

2791 

2217| Key | Type / Values | Details |2792| Key | Type / Values | Details |

2218| --- | --- | --- |2793| --- | --- | --- |

2219| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`). |2794| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`). |

2220| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2795| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |

2221| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |2796| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |

2797| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |

2798| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |

2222| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |2799| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |

2223| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |2800| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |

2224| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |2801| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |

2269 2846 

2270Key2847Key

2271 2848 

2849`features`

2850 

2851Type / Values

2852 

2853`table`

2854 

2855Details

2856 

2857Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.

2858 

2859Key

2860 

2861`features.<name>`

2862 

2863Type / Values

2864 

2865`boolean`

2866 

2867Details

2868 

2869Require a specific canonical feature key to stay enabled or disabled.

2870 

2871Key

2872 

2272`mcp_servers`2873`mcp_servers`

2273 2874 

2274Type / Values2875Type / Values