config-reference.md Codex Docs, 2026-02-24 00:33 UTC → 2026-04-09 00:33 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. |

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. |20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |

19| `approval_policy.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |21| `approval_policy` | `untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or 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. |

20| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |22| `approval_policy.granular.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected. |

21| `approval_policy.reject.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are auto-rejected. |23| `approval_policy.granular.request_permissions` | `boolean` | When `true`, prompts from the `request_permissions` tool are allowed to surface. |

24| `approval_policy.granular.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface. |

25| `approval_policy.granular.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are allowed to surface. |

26| `approval_policy.granular.skill_approval` | `boolean` | When `true`, skill-script approval prompts are allowed to surface. |

22| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |27| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |

23| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |28| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |

24| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |29| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |

33| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |38| `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). |39| `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). |40| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |

41| `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. |42| `compact_prompt` | `string` | Inline override for the history compaction prompt. |

43| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. |

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

38| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |45| `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). |46| `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`. |47| `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). |48| `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). |49| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |

45| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |50| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

46| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |51| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |

47| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |52| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |

48| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |

49| `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.personality` | `boolean` | Enable personality selection controls (stable; on by default). |53| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |

51| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |54| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |

52| `features.remote_models` | `boolean` | Refresh remote model list before showing readiness (experimental). |55| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |

53| `features.request_rule` | `boolean` | Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default). |

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

56| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (beta). |

57| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |56| `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). |57| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |

59| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |58| `features.smart_approvals` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). |

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

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

60| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |61| `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"`. |62| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |

62| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |63| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |

67| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |68| `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. |69| `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. |70| `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`. |71| `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`. |72| `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. |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. |

84| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |84| `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. |85| `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. |86| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |

87| `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. |88| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |

89| `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. |90| `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. |91| `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. |92| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |

91| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |93| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |

92| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |94| `model` | `string` | Model to use (e.g., `gpt-5.4`). |

93| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |95| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |

94| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |96| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |

95| `model_context_window` | `number` | Context window tokens available to the active model. |97| `model_context_window` | `number` | Context window tokens available to the active model. |

107| `model_providers.<id>.requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). |109| `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). |110| `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). |111| `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). |112| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

113| `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). |114| `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. |115| `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. |116| `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`). |117| `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. |118| `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. |119| `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. |120| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |

119| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |122| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |

120| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |123| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |

121| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |124| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |

125| `openai_base_url` | `string` | Base URL override for the built-in `openai` model provider. |

122| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |126| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |

123| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |127| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |

124| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |128| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |

129| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |133| `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. |134| `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. |135| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |

136| `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. |137| `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. |138| `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. |139| `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. |141| `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. |142| `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. |143| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |

144| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |

145| `permissions.<name>.filesystem.":project_roots".<subpath>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself. |

146| `permissions.<name>.filesystem.<path>` | `"read" | "write" | "none" | table` | Grant direct access for a path or special token, or scope nested entries under that root. |

147| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

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

149| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

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

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

152| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

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

154| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |

155| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

156| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |

157| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |

158| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |

159| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |

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

161| `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`). |162| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

141| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |163| `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`. |164| `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`. |165| `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). |166| `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). |

167| `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. |168| `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. |169| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |

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

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

172| `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"`). |173| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |

174| `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. |175| `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. |176| `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. |177| `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. |182| `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. |183| `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"`. |184| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |

185| `service_tier` | `flex | fast` | Preferred service tier for new turns. |

159| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |186| `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. |187| `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. |188| `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. |193| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |

167| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |194| `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`. |195| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |

196| `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. |197| `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. |198| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |

171| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |199| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |

200| `tools.web_search` | `boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }` | Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location. |

172| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |201| `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). |202| `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). |203| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

204| `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). |205| `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. |206| `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). |207| `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. |208| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

209| `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. |210| `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). |211| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

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

213| `windows.sandbox_private_desktop` | `boolean` | Run the final sandboxed child process on a private desktop by default on native Windows. Set `false` only for compatibility with the older `Winsta0\\Default` behavior. |

181 214 

182Key215Key

183 216 

205 238 

206Key239Key

207 240 

241`agents.<name>.nickname_candidates`

242 

243Type / Values

244 

245`array<string>`

246 

247Details

248 

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

250 

251Key

252 

253`agents.job_max_runtime_seconds`

254 

255Type / Values

256 

257`number`

258 

259Details

260 

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

262 

263Key

264 

208`agents.max_depth`265`agents.max_depth`

209 266 

210Type / Values267Type / Values

225 282 

226Details283Details

227 284 

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

229 286 

230Key287Key

231 288 

241 298 

242Key299Key

243 300 

301`analytics.enabled`

302 

303Type / Values

304 

305`boolean`

306 

307Details

308 

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

310 

311Key

312 

244`approval_policy`313`approval_policy`

245 314 

246Type / Values315Type / Values

247 316 

248`untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }`317`untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }`

249 318 

250Details319Details

251 320 

252Controls 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.321Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or 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.

253 322 

254Key323Key

255 324 

256`approval_policy.reject.mcp_elicitations`325`approval_policy.granular.mcp_elicitations`

257 326 

258Type / Values327Type / Values

259 328 

261 330 

262Details331Details

263 332 

264When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.333When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

265 334 

266Key335Key

267 336 

268`approval_policy.reject.rules`337`approval_policy.granular.request_permissions`

269 338 

270Type / Values339Type / Values

271 340 

273 342 

274Details343Details

275 344 

276When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.345When `true`, prompts from the `request_permissions` tool are allowed to surface.

277 346 

278Key347Key

279 348 

280`approval_policy.reject.sandbox_approval`349`approval_policy.granular.rules`

281 350 

282Type / Values351Type / Values

283 352 

285 354 

286Details355Details

287 356 

288When `true`, sandbox escalation approval prompts are auto-rejected.357When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.

358 

359Key

360 

361`approval_policy.granular.sandbox_approval`

362 

363Type / Values

364 

365`boolean`

366 

367Details

368 

369When `true`, sandbox escalation approval prompts are allowed to surface.

370 

371Key

372 

373`approval_policy.granular.skill_approval`

374 

375Type / Values

376 

377`boolean`

378 

379Details

380 

381When `true`, skill-script approval prompts are allowed to surface.

289 382 

290Key383Key

291 384 

457 550 

458Key551Key

459 552 

460`compact_prompt`553`commit_attribution`

461 554 

462Type / Values555Type / Values

463 556 

465 558 

466Details559Details

467 560 

468Inline override for the history compaction prompt.561Override the commit co-author trailer text. Set an empty string to disable automatic attribution.

469 562 

470Key563Key

471 564 

472`developer_instructions`565`compact_prompt`

473 566 

474Type / Values567Type / Values

475 568 

477 570 

478Details571Details

479 572 

480Additional developer instructions injected into the session (optional).573Inline override for the history compaction prompt.

481 574 

482Key575Key

483 576 

484`disable_paste_burst`577`default_permissions`

485 578 

486Type / Values579Type / Values

487 580 

488`boolean`581`string`

489 582 

490Details583Details

491 584 

492Disable burst-paste detection in the TUI.585Name of the default permissions profile to apply to sandboxed tool calls.

493 586 

494Key587Key

495 588 

496`experimental_compact_prompt_file`589`developer_instructions`

497 590 

498Type / Values591Type / Values

499 592 

500`string (path)`593`string`

501 594 

502Details595Details

503 596 

504Load the compaction prompt override from a file (experimental).597Additional developer instructions injected into the session (optional).

505 598 

506Key599Key

507 600 

508`experimental_use_freeform_apply_patch`601`disable_paste_burst`

509 602 

510Type / Values603Type / Values

511 604 

513 606 

514Details607Details

515 608 

516Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.609Disable burst-paste detection in the TUI.

517 610 

518Key611Key

519 612 

520`experimental_use_unified_exec_tool`613`experimental_compact_prompt_file`

521 614 

522Type / Values615Type / Values

523 616 

524`boolean`617`string (path)`

525 618 

526Details619Details

527 620 

528Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.621Load the compaction prompt override from a file (experimental).

529 622 

530Key623Key

531 624 

532`features.apply_patch_freeform`625`experimental_use_unified_exec_tool`

533 626 

534Type / Values627Type / Values

535 628 

537 630 

538Details631Details

539 632 

540Expose the freeform `apply_patch` tool (experimental).633Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

541 634 

542Key635Key

543 636 

553 646 

554Key647Key

555 648 

556`features.apps_mcp_gateway`649`features.codex_hooks`

557 

558Type / Values

559 

560`boolean`

561 

562Details

563 

564Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).

565 

566Key

567 

568`features.child_agents_md`

569 

570Type / Values

571 

572`boolean`

573 

574Details

575 

576Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).

577 

578Key

579 

580`features.collaboration_modes`

581 650 

582Type / Values651Type / Values

583 652 

585 654 

586Details655Details

587 656 

588Enable collaboration modes such as plan mode (stable; on by default).657Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).

589 658 

590Key659Key

591 660 

592`features.elevated_windows_sandbox`661`features.enable_request_compression`

593 662 

594Type / Values663Type / Values

595 664 

597 666 

598Details667Details

599 668 

600Enable the elevated Windows sandbox pipeline (experimental).669Compress streaming request bodies with zstd when supported (stable; on by default).

601 670 

602Key671Key

603 672 

604`features.experimental_windows_sandbox`673`features.fast_mode`

605 674 

606Type / Values675Type / Values

607 676 

609 678 

610Details679Details

611 680 

612Run the Windows restricted-token sandbox (experimental).681Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

613 682 

614Key683Key

615 684 

621 690 

622Details691Details

623 692 

624Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).693Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

625 694 

626Key695Key

627 696 

637 706 

638Key707Key

639 708 

640`features.powershell_utf8`709`features.prevent_idle_sleep`

641 

642Type / Values

643 

644`boolean`

645 

646Details

647 

648Force PowerShell UTF-8 output (defaults to true).

649 

650Key

651 

652`features.remote_models`

653 710 

654Type / Values711Type / Values

655 712 

657 714 

658Details715Details

659 716 

660Refresh remote model list before showing readiness (experimental).717Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

661 718 

662Key719Key

663 720 

664`features.request_rule`721`features.shell_snapshot`

665 722 

666Type / Values723Type / Values

667 724 

669 726 

670Details727Details

671 728 

672Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).729Snapshot shell environment to speed up repeated commands (stable; on by default).

673 730 

674Key731Key

675 732 

676`features.runtime_metrics`733`features.shell_tool`

677 734 

678Type / Values735Type / Values

679 736 

681 738 

682Details739Details

683 740 

684Show runtime metrics summary in TUI turn separators (experimental).741Enable the default `shell` tool for running commands (stable; on by default).

685 742 

686Key743Key

687 744 

688`features.search_tool`745`features.skill_mcp_dependency_install`

689 746 

690Type / Values747Type / Values

691 748 

693 750 

694Details751Details

695 752 

696Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).753Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

697 754 

698Key755Key

699 756 

700`features.shell_snapshot`757`features.smart_approvals`

701 758 

702Type / Values759Type / Values

703 760 

705 762 

706Details763Details

707 764 

708Snapshot shell environment to speed up repeated commands (beta).765Route eligible approval requests through the guardian reviewer subagent (experimental; off by default).

709 766 

710Key767Key

711 768 

712`features.shell_tool`769`features.undo`

713 770 

714Type / Values771Type / Values

715 772 

717 774 

718Details775Details

719 776 

720Enable the default `shell` tool for running commands (stable; on by default).777Enable undo support (stable; off by default).

721 778 

722Key779Key

723 780 

729 786 

730Details787Details

731 788 

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

733 

734Key

735 

736`features.use_linux_sandbox_bwrap`

737 

738Type / Values

739 

740`boolean`

741 

742Details

743 

744Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).

745 790 

746Key791Key

747 792 

865 910 

866Key911Key

867 912 

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`913`instructions`

881 914 

882Type / Values915Type / Values

1069 1102 

1070Key1103Key

1071 1104 

1105`mcp_servers.<id>.oauth_resource`

1106 

1107Type / Values

1108 

1109`string`

1110 

1111Details

1112 

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

1114 

1115Key

1116 

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

1073 1118 

1074Type / Values1119Type / Values

1081 1126 

1082Key1127Key

1083 1128 

1129`mcp_servers.<id>.scopes`

1130 

1131Type / Values

1132 

1133`array<string>`

1134 

1135Details

1136 

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

1138 

1139Key

1140 

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

1085 1142 

1086Type / Values1143Type / Values

1137 1194 

1138Details1195Details

1139 1196 

1140Model to use (e.g., `gpt-5-codex`).1197Model to use (e.g., `gpt-5.4`).

1141 1198 

1142Key1199Key

1143 1200 

1345 1402 

1346Key1403Key

1347 1404 

1405`model_providers.<id>.supports_websockets`

1406 

1407Type / Values

1408 

1409`boolean`

1410 

1411Details

1412 

1413Whether that provider supports the Responses API WebSocket transport.

1414 

1415Key

1416 

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

1349 1418 

1350Type / Values1419Type / Values

1351 1420 

1352`chat | responses`1421`responses`

1353 1422 

1354Details1423Details

1355 1424 

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

1357 1426 

1358Key1427Key

1359 1428 

1401 1470 

1402Details1471Details

1403 1472 

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

1405 1474 

1406Key1475Key

1407 1476 

1489 1558 

1490Key1559Key

1491 1560 

1561`openai_base_url`

1562 

1563Type / Values

1564 

1565`string`

1566 

1567Details

1568 

1569Base URL override for the built-in `openai` model provider.

1570 

1571Key

1572 

1492`oss_provider`1573`oss_provider`

1493 1574 

1494Type / Values1575Type / Values

1609 1690 

1610Key1691Key

1611 1692 

1693`otel.metrics_exporter`

1694 

1695Type / Values

1696 

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

1698 

1699Details

1700 

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

1702 

1703Key

1704 

1612`otel.trace_exporter`1705`otel.trace_exporter`

1613 1706 

1614Type / Values1707Type / Values

1693 1786 

1694Key1787Key

1695 1788 

1789`permissions.<name>.filesystem`

1790 

1791Type / Values

1792 

1793`table`

1794 

1795Details

1796 

1797Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.

1798 

1799Key

1800 

1801`permissions.<name>.filesystem.":project_roots".<subpath>`

1802 

1803Type / Values

1804 

1805`"read" | "write" | "none"`

1806 

1807Details

1808 

1809Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself.

1810 

1811Key

1812 

1813`permissions.<name>.filesystem.<path>`

1814 

1815Type / Values

1816 

1817`"read" | "write" | "none" | table`

1818 

1819Details

1820 

1821Grant direct access for a path or special token, or scope nested entries under that root.

1822 

1823Key

1824 

1825`permissions.<name>.network.allow_local_binding`

1826 

1827Type / Values

1828 

1829`boolean`

1830 

1831Details

1832 

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

1834 

1835Key

1836 

1837`permissions.<name>.network.allow_unix_sockets`

1838 

1839Type / Values

1840 

1841`array<string>`

1842 

1843Details

1844 

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

1846 

1847Key

1848 

1849`permissions.<name>.network.allow_upstream_proxy`

1850 

1851Type / Values

1852 

1853`boolean`

1854 

1855Details

1856 

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

1858 

1859Key

1860 

1861`permissions.<name>.network.allowed_domains`

1862 

1863Type / Values

1864 

1865`array<string>`

1866 

1867Details

1868 

1869Allowlist of domains permitted through the managed proxy.

1870 

1871Key

1872 

1873`permissions.<name>.network.dangerously_allow_all_unix_sockets`

1874 

1875Type / Values

1876 

1877`boolean`

1878 

1879Details

1880 

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

1882 

1883Key

1884 

1885`permissions.<name>.network.dangerously_allow_non_loopback_proxy`

1886 

1887Type / Values

1888 

1889`boolean`

1890 

1891Details

1892 

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

1894 

1895Key

1896 

1897`permissions.<name>.network.denied_domains`

1898 

1899Type / Values

1900 

1901`array<string>`

1902 

1903Details

1904 

1905Denylist of domains blocked by the managed proxy.

1906 

1907Key

1908 

1909`permissions.<name>.network.enable_socks5`

1910 

1911Type / Values

1912 

1913`boolean`

1914 

1915Details

1916 

1917Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.

1918 

1919Key

1920 

1921`permissions.<name>.network.enable_socks5_udp`

1922 

1923Type / Values

1924 

1925`boolean`

1926 

1927Details

1928 

1929Allow UDP over the SOCKS5 listener when enabled.

1930 

1931Key

1932 

1933`permissions.<name>.network.enabled`

1934 

1935Type / Values

1936 

1937`boolean`

1938 

1939Details

1940 

1941Enable network access for this named permissions profile.

1942 

1943Key

1944 

1945`permissions.<name>.network.mode`

1946 

1947Type / Values

1948 

1949`limited | full`

1950 

1951Details

1952 

1953Network proxy mode used for subprocess traffic.

1954 

1955Key

1956 

1957`permissions.<name>.network.proxy_url`

1958 

1959Type / Values

1960 

1961`string`

1962 

1963Details

1964 

1965HTTP proxy endpoint used when this permissions profile enables the managed network proxy.

1966 

1967Key

1968 

1969`permissions.<name>.network.socks_url`

1970 

1971Type / Values

1972 

1973`string`

1974 

1975Details

1976 

1977SOCKS5 proxy endpoint used by this permissions profile.

1978 

1979Key

1980 

1696`personality`1981`personality`

1697 1982 

1698Type / Values1983Type / Values

1705 1990 

1706Key1991Key

1707 1992 

1993`plan_mode_reasoning_effort`

1994 

1995Type / Values

1996 

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

1998 

1999Details

2000 

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

2002 

2003Key

2004 

1708`profile`2005`profile`

1709 2006 

1710Type / Values2007Type / Values

1729 2026 

1730Key2027Key

1731 2028 

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

1733 2030 

1734Type / Values2031Type / Values

1735 2032 

1737 2034 

1738Details2035Details

1739 2036 

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

1741 2038 

1742Key2039Key

1743 2040 

1753 2050 

1754Key2051Key

1755 2052 

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

1757 2054 

1758Type / Values2055Type / Values

1759 2056 

1760`boolean`2057`string (path)`

1761 2058 

1762Details2059Details

1763 2060 

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

1765 2062 

1766Key2063Key

1767 2064 

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

1769 2066 

1770Type / Values2067Type / Values

1771 2068 

1773 2070 

1774Details2071Details

1775 2072 

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

1777 2074 

1778Key2075Key

1779 2076 

1801 2098 

1802Key2099Key

1803 2100 

2101`profiles.<name>.plan_mode_reasoning_effort`

2102 

2103Type / Values

2104 

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

2106 

2107Details

2108 

2109Profile-scoped Plan-mode reasoning override.

2110 

2111Key

2112 

2113`profiles.<name>.service_tier`

2114 

2115Type / Values

2116 

2117`flex | fast`

2118 

2119Details

2120 

2121Profile-scoped service tier preference for new turns.

2122 

2123Key

2124 

2125`profiles.<name>.tools_view_image`

2126 

2127Type / Values

2128 

2129`boolean`

2130 

2131Details

2132 

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

2134 

2135Key

2136 

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

1805 2138 

1806Type / Values2139Type / Values

1813 2146 

1814Key2147Key

1815 2148 

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

2150 

2151Type / Values

2152 

2153`unelevated | elevated`

2154 

2155Details

2156 

2157Profile-scoped Windows sandbox mode override.

2158 

2159Key

2160 

1816`project_doc_fallback_filenames`2161`project_doc_fallback_filenames`

1817 2162 

1818Type / Values2163Type / Values

1933 2278 

1934Key2279Key

1935 2280 

2281`service_tier`

2282 

2283Type / Values

2284 

2285`flex | fast`

2286 

2287Details

2288 

2289Preferred service tier for new turns.

2290 

2291Key

2292 

1936`shell_environment_policy.exclude`2293`shell_environment_policy.exclude`

1937 2294 

1938Type / Values2295Type / Values

2053 2410 

2054Key2411Key

2055 2412 

2413`sqlite_home`

2414 

2415Type / Values

2416 

2417`string (path)`

2418 

2419Details

2420 

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

2422 

2423Key

2424 

2056`suppress_unstable_features_warning`2425`suppress_unstable_features_warning`

2057 2426 

2058Type / Values2427Type / Values

2077 2446 

2078Key2447Key

2079 2448 

2080`tools.web_search`2449`tools.view_image`

2081 2450 

2082Type / Values2451Type / Values

2083 2452 

2085 2454 

2086Details2455Details

2087 2456 

2088Deprecated legacy toggle for web search; prefer the top-level `web_search` setting.2457Enable the local-image attachment tool `view_image`.

2458 

2459Key

2460 

2461`tools.web_search`

2462 

2463Type / Values

2464 

2465`boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }`

2466 

2467Details

2468 

2469Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location.

2089 2470 

2090Key2471Key

2091 2472 

2125 2506 

2126Key2507Key

2127 2508 

2509`tui.model_availability_nux.<model>`

2510 

2511Type / Values

2512 

2513`integer`

2514 

2515Details

2516 

2517Internal startup-tooltip state keyed by model slug.

2518 

2519Key

2520 

2128`tui.notification_method`2521`tui.notification_method`

2129 2522 

2130Type / Values2523Type / Values

2173 2566 

2174Key2567Key

2175 2568 

2569`tui.theme`

2570 

2571Type / Values

2572 

2573`string`

2574 

2575Details

2576 

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

2578 

2579Key

2580 

2176`web_search`2581`web_search`

2177 2582 

2178Type / Values2583Type / Values

2195 2600 

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

2197 2602 

2603Key

2604 

2605`windows.sandbox`

2606 

2607Type / Values

2608 

2609`unelevated | elevated`

2610 

2611Details

2612 

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

2614 

2615Key

2616 

2617`windows.sandbox_private_desktop`

2618 

2619Type / Values

2620 

2621`boolean`

2622 

2623Details

2624 

2625Run the final sandboxed child process on a private desktop by default on native Windows. Set `false` only for compatibility with the older `Winsta0\\Default` behavior.

2626 

2198Expand to view all2627Expand to view all

2199 2628 

2200You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).2629You 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-fetched2643For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched

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

2216 2645 

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

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

2648 

2217| Key | Type / Values | Details |2649| Key | Type / Values | Details |

2218| --- | --- | --- |2650| --- | --- | --- |

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

2220| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2652| `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`. |2653| `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`. |

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

2655| `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. |2656| `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). |2657| `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. |2658| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |

2241 2675 

2242Details2676Details

2243 2677 

2244Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`).2678Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`).

2245 2679 

2246Key2680Key

2247 2681 

2269 2703 

2270Key2704Key

2271 2705 

2706`features`

2707 

2708Type / Values

2709 

2710`table`

2711 

2712Details

2713 

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

2715 

2716Key

2717 

2718`features.<name>`

2719 

2720Type / Values

2721 

2722`boolean`

2723 

2724Details

2725 

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

2727 

2728Key

2729 

2272`mcp_servers`2730`mcp_servers`

2273 2731 

2274Type / Values2732Type / Values