config-reference.md Codex Docs, 2026-03-03 00:35 UTC → 2026-03-09 00:34 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.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |50| `features.default_mode_request_user_input` | `boolean` | Allow `request_user_input` in default collaboration mode (under development; off by default). |

51| `features.elevated_windows_sandbox` | `boolean` | Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it. |

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). |

57| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

69| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |86| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |

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

71| `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. |88| `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. |

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

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

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

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

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

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

86| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |105| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |

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

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

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

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

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

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

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

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

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

111| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |131| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |

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

113| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |133| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |

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

115| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |135| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |

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

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

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

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

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

131| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |152| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

174| `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. |

138| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |175| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

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

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

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

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

143| `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_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). |

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

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

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

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

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

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

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

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

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

148| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |189| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |

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

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

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

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

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

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

158| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |200| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |

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

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

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

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

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

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

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

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

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

170| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |214| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

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

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

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

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

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

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

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

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

177| `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. |223| `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. |

178| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |224| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

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

204 250 

205Key251Key

206 252 

253`agents.<name>.nickname_candidates`

254 

255Type / Values

256 

257`array<string>`

258 

259Details

260 

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

262 

263Key

264 

265`agents.job_max_runtime_seconds`

266 

267Type / Values

268 

269`number`

270 

271Details

272 

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

274 

275Key

276 

207`agents.max_depth`277`agents.max_depth`

208 278 

209Type / Values279Type / Values

224 294 

225Details295Details

226 296 

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

228 298 

229Key299Key

230 300 

240 310 

241Key311Key

242 312 

313`analytics.enabled`

314 

315Type / Values

316 

317`boolean`

318 

319Details

320 

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

322 

323Key

324 

243`approval_policy`325`approval_policy`

244 326 

245Type / Values327Type / Values

456 538 

457Key539Key

458 540 

541`commit_attribution`

542 

543Type / Values

544 

545`string`

546 

547Details

548 

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

550 

551Key

552 

459`compact_prompt`553`compact_prompt`

460 554 

461Type / Values555Type / Values

504 598 

505Key599Key

506 600 

507`experimental_use_freeform_apply_patch`601`experimental_use_unified_exec_tool`

508 602 

509Type / Values603Type / Values

510 604 

512 606 

513Details607Details

514 608 

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

516 610 

517Key611Key

518 612 

519`experimental_use_unified_exec_tool`613`features.apps`

520 614 

521Type / Values615Type / Values

522 616 

524 618 

525Details619Details

526 620 

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

528 622 

529Key623Key

530 624 

531`features.apply_patch_freeform`625`features.apps_mcp_gateway`

532 626 

533Type / Values627Type / Values

534 628 

536 630 

537Details631Details

538 632 

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

540 634 

541Key635Key

542 636 

543`features.apps`637`features.artifact`

544 638 

545Type / Values639Type / Values

546 640 

548 642 

549Details643Details

550 644 

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

552 646 

553Key647Key

554 648 

555`features.apps_mcp_gateway`649`features.child_agents_md`

556 650 

557Type / Values651Type / Values

558 652 

560 654 

561Details655Details

562 656 

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

564 658 

565Key659Key

566 660 

567`features.child_agents_md`661`features.collaboration_modes`

568 662 

569Type / Values663Type / Values

570 664 

572 666 

573Details667Details

574 668 

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

576 670 

577Key671Key

578 672 

579`features.collaboration_modes`673`features.default_mode_request_user_input`

674 

675Type / Values

676 

677`boolean`

678 

679Details

680 

681Allow `request_user_input` in default collaboration mode (under development; off by default).

682 

683Key

684 

685`features.elevated_windows_sandbox`

686 

687Type / Values

688 

689`boolean`

690 

691Details

692 

693Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it.

694 

695Key

696 

697`features.enable_request_compression`

698 

699Type / Values

700 

701`boolean`

702 

703Details

704 

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

706 

707Key

708 

709`features.experimental_windows_sandbox`

710 

711Type / Values

712 

713`boolean`

714 

715Details

716 

717Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it.

718 

719Key

720 

721`features.fast_mode`

722 

723Type / Values

724 

725`boolean`

726 

727Details

728 

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

730 

731Key

732 

733`features.image_detail_original`

734 

735Type / Values

736 

737`boolean`

738 

739Details

740 

741Allow image outputs with `detail = "original"` on supported models (under development).

742 

743Key

744 

745`features.image_generation`

580 746 

581Type / Values747Type / Values

582 748 

584 750 

585Details751Details

586 752 

587Enable collaboration modes such as plan mode (stable; on by default).753Enable the built-in image generation tool (under development).

588 754 

589Key755Key

590 756 

596 762 

597Details763Details

598 764 

599Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).765Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default).

600 766 

601Key767Key

602 768 

620 786 

621Details787Details

622 788 

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

790 

791Key

792 

793`features.prevent_idle_sleep`

794 

795Type / Values

796 

797`boolean`

798 

799Details

800 

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

624 802 

625Key803Key

626 804 

632 810 

633Details811Details

634 812 

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

636 814 

637Key815Key

638 816 

644 822 

645Details823Details

646 824 

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

826 

827Key

828 

829`features.responses_websockets`

830 

831Type / Values

832 

833`boolean`

834 

835Details

836 

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

838 

839Key

840 

841`features.responses_websockets_v2`

842 

843Type / Values

844 

845`boolean`

846 

847Details

848 

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

648 850 

649Key851Key

650 852 

668 870 

669Details871Details

670 872 

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

672 874 

673Key875Key

674 876 

680 882 

681Details883Details

682 884 

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

684 886 

685Key887Key

686 888 

696 898 

697Key899Key

698 900 

901`features.skill_env_var_dependency_prompt`

902 

903Type / Values

904 

905`boolean`

906 

907Details

908 

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

910 

911Key

912 

913`features.skill_mcp_dependency_install`

914 

915Type / Values

916 

917`boolean`

918 

919Details

920 

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

922 

923Key

924 

925`features.sqlite`

926 

927Type / Values

928 

929`boolean`

930 

931Details

932 

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

934 

935Key

936 

937`features.steer`

938 

939Type / Values

940 

941`boolean`

942 

943Details

944 

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

946 

947Key

948 

949`features.undo`

950 

951Type / Values

952 

953`boolean`

954 

955Details

956 

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

958 

959Key

960 

699`features.unified_exec`961`features.unified_exec`

700 962 

701Type / Values963Type / Values

704 966 

705Details967Details

706 968 

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

708 970 

709Key971Key

710 972 

840 1102 

841Key1103Key

842 1104 

843`include_apply_patch_tool`

844 

845Type / Values

846 

847`boolean`

848 

849Details

850 

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

852 

853Key

854 

855`instructions`1105`instructions`

856 1106 

857Type / Values1107Type / Values

1044 1294 

1045Key1295Key

1046 1296 

1297`mcp_servers.<id>.oauth_resource`

1298 

1299Type / Values

1300 

1301`string`

1302 

1303Details

1304 

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

1306 

1307Key

1308 

1047`mcp_servers.<id>.required`1309`mcp_servers.<id>.required`

1048 1310 

1049Type / Values1311Type / Values

1056 1318 

1057Key1319Key

1058 1320 

1321`mcp_servers.<id>.scopes`

1322 

1323Type / Values

1324 

1325`array<string>`

1326 

1327Details

1328 

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

1330 

1331Key

1332 

1059`mcp_servers.<id>.startup_timeout_ms`1333`mcp_servers.<id>.startup_timeout_ms`

1060 1334 

1061Type / Values1335Type / Values

1320 1594 

1321Key1595Key

1322 1596 

1597`model_providers.<id>.supports_websockets`

1598 

1599Type / Values

1600 

1601`boolean`

1602 

1603Details

1604 

1605Whether that provider supports the Responses API WebSocket transport.

1606 

1607Key

1608 

1323`model_providers.<id>.wire_api`1609`model_providers.<id>.wire_api`

1324 1610 

1325Type / Values1611Type / Values

1326 1612 

1327`chat | responses`1613`responses`

1328 1614 

1329Details1615Details

1330 1616 

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

1332 1618 

1333Key1619Key

1334 1620 

1376 1662 

1377Details1663Details

1378 1664 

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

1380 1666 

1381Key1667Key

1382 1668 

1584 1870 

1585Key1871Key

1586 1872 

1873`otel.metrics_exporter`

1874 

1875Type / Values

1876 

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

1878 

1879Details

1880 

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

1882 

1883Key

1884 

1587`otel.trace_exporter`1885`otel.trace_exporter`

1588 1886 

1589Type / Values1887Type / Values

1668 1966 

1669Key1967Key

1670 1968 

1671`personality`1969`permissions.network.admin_url`

1672 1970 

1673Type / Values1971Type / Values

1674 1972 

1675`none | friendly | pragmatic`1973`string`

1676 1974 

1677Details1975Details

1678 1976 

1679Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.1977Admin endpoint for the managed network proxy.

1680 1978 

1681Key1979Key

1682 1980 

1683`profile`1981`permissions.network.allow_local_binding`

1684 1982 

1685Type / Values1983Type / Values

1686 1984 

1687`string`1985`boolean`

1688 1986 

1689Details1987Details

1690 1988 

1691Default profile applied at startup (equivalent to `--profile`).1989Permit local bind/listen operations through the managed proxy.

1692 1990 

1693Key1991Key

1694 1992 

1695`profiles.<name>.*`1993`permissions.network.allow_unix_sockets`

1994 

1995Type / Values

1996 

1997`array<string>`

1998 

1999Details

2000 

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

2002 

2003Key

2004 

2005`permissions.network.allow_upstream_proxy`

2006 

2007Type / Values

2008 

2009`boolean`

2010 

2011Details

2012 

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

2014 

2015Key

2016 

2017`permissions.network.allowed_domains`

2018 

2019Type / Values

2020 

2021`array<string>`

2022 

2023Details

2024 

2025Allowlist of domains permitted through the managed proxy.

2026 

2027Key

2028 

2029`permissions.network.dangerously_allow_all_unix_sockets`

2030 

2031Type / Values

2032 

2033`boolean`

2034 

2035Details

2036 

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

2038 

2039Key

2040 

2041`permissions.network.dangerously_allow_non_loopback_admin`

2042 

2043Type / Values

2044 

2045`boolean`

2046 

2047Details

2048 

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

2050 

2051Key

2052 

2053`permissions.network.dangerously_allow_non_loopback_proxy`

2054 

2055Type / Values

2056 

2057`boolean`

2058 

2059Details

2060 

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

2062 

2063Key

2064 

2065`permissions.network.denied_domains`

2066 

2067Type / Values

2068 

2069`array<string>`

2070 

2071Details

2072 

2073Denylist of domains blocked by the managed proxy.

2074 

2075Key

2076 

2077`permissions.network.enable_socks5`

2078 

2079Type / Values

2080 

2081`boolean`

2082 

2083Details

2084 

2085Expose a SOCKS5 listener from the managed network proxy.

2086 

2087Key

2088 

2089`permissions.network.enable_socks5_udp`

2090 

2091Type / Values

2092 

2093`boolean`

2094 

2095Details

2096 

2097Allow UDP over the SOCKS5 listener when enabled.

2098 

2099Key

2100 

2101`permissions.network.enabled`

2102 

2103Type / Values

2104 

2105`boolean`

2106 

2107Details

2108 

2109Enable the managed network proxy configuration for subprocesses.

2110 

2111Key

2112 

2113`permissions.network.mode`

2114 

2115Type / Values

2116 

2117`limited | full`

2118 

2119Details

2120 

2121Network proxy mode used for subprocess traffic.

2122 

2123Key

2124 

2125`permissions.network.proxy_url`

2126 

2127Type / Values

2128 

2129`string`

2130 

2131Details

2132 

2133HTTP proxy endpoint used by the managed network proxy.

2134 

2135Key

2136 

2137`permissions.network.socks_url`

2138 

2139Type / Values

2140 

2141`string`

2142 

2143Details

2144 

2145SOCKS5 proxy endpoint used by the managed network proxy.

2146 

2147Key

2148 

2149`personality`

2150 

2151Type / Values

2152 

2153`none | friendly | pragmatic`

2154 

2155Details

2156 

2157Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.

2158 

2159Key

2160 

2161`plan_mode_reasoning_effort`

2162 

2163Type / Values

2164 

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

2166 

2167Details

2168 

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

2170 

2171Key

2172 

2173`profile`

2174 

2175Type / Values

2176 

2177`string`

2178 

2179Details

2180 

2181Default profile applied at startup (equivalent to `--profile`).

2182 

2183Key

2184 

2185`profiles.<name>.*`

1696 2186 

1697Type / Values2187Type / Values

1698 2188 

1704 2194 

1705Key2195Key

1706 2196 

1707`profiles.<name>.experimental_use_freeform_apply_patch`2197`profiles.<name>.analytics.enabled`

1708 2198 

1709Type / Values2199Type / Values

1710 2200 

1712 2202 

1713Details2203Details

1714 2204 

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

1716 2206 

1717Key2207Key

1718 2208 

1728 2218 

1729Key2219Key

1730 2220 

1731`profiles.<name>.include_apply_patch_tool`2221`profiles.<name>.model_catalog_json`

1732 2222 

1733Type / Values2223Type / Values

1734 2224 

1735`boolean`2225`string (path)`

1736 2226 

1737Details2227Details

1738 2228 

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

1740 2230 

1741Key2231Key

1742 2232 

1743`profiles.<name>.model_catalog_json`2233`profiles.<name>.model_instructions_file`

1744 2234 

1745Type / Values2235Type / Values

1746 2236 

1748 2238 

1749Details2239Details

1750 2240 

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

1752 2242 

1753Key2243Key

1754 2244 

1776 2266 

1777Key2267Key

1778 2268 

2269`profiles.<name>.plan_mode_reasoning_effort`

2270 

2271Type / Values

2272 

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

2274 

2275Details

2276 

2277Profile-scoped Plan-mode reasoning override.

2278 

2279Key

2280 

2281`profiles.<name>.service_tier`

2282 

2283Type / Values

2284 

2285`flex | fast`

2286 

2287Details

2288 

2289Profile-scoped service tier preference for new turns.

2290 

2291Key

2292 

2293`profiles.<name>.tools_view_image`

2294 

2295Type / Values

2296 

2297`boolean`

2298 

2299Details

2300 

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

2302 

2303Key

2304 

1779`profiles.<name>.web_search`2305`profiles.<name>.web_search`

1780 2306 

1781Type / Values2307Type / Values

1788 2314 

1789Key2315Key

1790 2316 

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

2318 

2319Type / Values

2320 

2321`unelevated | elevated`

2322 

2323Details

2324 

2325Profile-scoped Windows sandbox mode override.

2326 

2327Key

2328 

1791`project_doc_fallback_filenames`2329`project_doc_fallback_filenames`

1792 2330 

1793Type / Values2331Type / Values

1908 2446 

1909Key2447Key

1910 2448 

2449`service_tier`

2450 

2451Type / Values

2452 

2453`flex | fast`

2454 

2455Details

2456 

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

2458 

2459Key

2460 

1911`shell_environment_policy.exclude`2461`shell_environment_policy.exclude`

1912 2462 

1913Type / Values2463Type / Values

2028 2578 

2029Key2579Key

2030 2580 

2581`sqlite_home`

2582 

2583Type / Values

2584 

2585`string (path)`

2586 

2587Details

2588 

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

2590 

2591Key

2592 

2031`suppress_unstable_features_warning`2593`suppress_unstable_features_warning`

2032 2594 

2033Type / Values2595Type / Values

2052 2614 

2053Key2615Key

2054 2616 

2617`tools.view_image`

2618 

2619Type / Values

2620 

2621`boolean`

2622 

2623Details

2624 

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

2626 

2627Key

2628 

2055`tools.web_search`2629`tools.web_search`

2056 2630 

2057Type / Values2631Type / Values

2100 2674 

2101Key2675Key

2102 2676 

2677`tui.model_availability_nux.<model>`

2678 

2679Type / Values

2680 

2681`integer`

2682 

2683Details

2684 

2685Internal startup-tooltip state keyed by model slug.

2686 

2687Key

2688 

2103`tui.notification_method`2689`tui.notification_method`

2104 2690 

2105Type / Values2691Type / Values

2148 2734 

2149Key2735Key

2150 2736 

2737`tui.theme`

2738 

2739Type / Values

2740 

2741`string`

2742 

2743Details

2744 

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

2746 

2747Key

2748 

2151`web_search`2749`web_search`

2152 2750 

2153Type / Values2751Type / Values

2201For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched2799For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched

2202requirements. See the security page for precedence details.2800requirements. See the security page for precedence details.

2203 2801 

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

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

2804 

2204| Key | Type / Values | Details |2805| Key | Type / Values | Details |

2205| --- | --- | --- |2806| --- | --- | --- |

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

2207| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2808| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |

2208| `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`. |2809| `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`. |

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

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

2209| `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. |2812| `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. |

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

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

2256 2859 

2257Key2860Key

2258 2861 

2862`features`

2863 

2864Type / Values

2865 

2866`table`

2867 

2868Details

2869 

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

2871 

2872Key

2873 

2874`features.<name>`

2875 

2876Type / Values

2877 

2878`boolean`

2879 

2880Details

2881 

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

2883 

2884Key

2885 

2259`mcp_servers`2886`mcp_servers`

2260 2887 

2261Type / Values2888Type / Values