config-reference.md Codex Docs, 2026-02-24 00:33 UTC → 2026-03-20 00:35 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.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

45| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |50| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |

46| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |51| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |

47| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |

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

51| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |53| `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). |54| `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). |55| `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). |56| `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). |57| `features.smart_approvals` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). |

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

59| `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. |60| `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"`. |61| `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"`. |62| `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. |67| `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. |68| `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. |69| `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`. |70| `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`. |71| `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. |72| `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. |83| `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. |84| `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. |85| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |

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

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

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

112| `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). |113| `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. |114| `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. |115| `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`). |116| `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. |117| `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. |118| `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. |119| `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. |121| `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. |122| `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. |123| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |

124| `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). |125| `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`). |126| `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. |127| `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. |132| `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. |133| `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. |134| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

158| `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`. |159| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |

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

141| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |162| `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`. |163| `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`. |164| `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). |165| `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_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. |167| `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. |168| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |

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

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

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

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

184| `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. |185| `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. |186| `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. |187| `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. |192| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |

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

195| `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. |196| `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. |197| `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. |198| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |

199| `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. |200| `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). |201| `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). |202| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

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

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

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

212| `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 213 

182Key214Key

183 215 

205 237 

206Key238Key

207 239 

240`agents.<name>.nickname_candidates`

241 

242Type / Values

243 

244`array<string>`

245 

246Details

247 

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

249 

250Key

251 

252`agents.job_max_runtime_seconds`

253 

254Type / Values

255 

256`number`

257 

258Details

259 

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

261 

262Key

263 

208`agents.max_depth`264`agents.max_depth`

209 265 

210Type / Values266Type / Values

225 281 

226Details282Details

227 283 

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

229 285 

230Key286Key

231 287 

241 297 

242Key298Key

243 299 

300`analytics.enabled`

301 

302Type / Values

303 

304`boolean`

305 

306Details

307 

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

309 

310Key

311 

244`approval_policy`312`approval_policy`

245 313 

246Type / Values314Type / Values

247 315 

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

317 

318Details

319 

320Controls 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.

321 

322Key

323 

324`approval_policy.granular.mcp_elicitations`

325 

326Type / Values

327 

328`boolean`

249 329 

250Details330Details

251 331 

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.332When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

253 333 

254Key334Key

255 335 

256`approval_policy.reject.mcp_elicitations`336`approval_policy.granular.request_permissions`

257 337 

258Type / Values338Type / Values

259 339 

261 341 

262Details342Details

263 343 

264When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.344When `true`, prompts from the `request_permissions` tool are allowed to surface.

265 345 

266Key346Key

267 347 

268`approval_policy.reject.rules`348`approval_policy.granular.rules`

269 349 

270Type / Values350Type / Values

271 351 

273 353 

274Details354Details

275 355 

276When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.356When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.

277 357 

278Key358Key

279 359 

280`approval_policy.reject.sandbox_approval`360`approval_policy.granular.sandbox_approval`

281 361 

282Type / Values362Type / Values

283 363 

285 365 

286Details366Details

287 367 

288When `true`, sandbox escalation approval prompts are auto-rejected.368When `true`, sandbox escalation approval prompts are allowed to surface.

369 

370Key

371 

372`approval_policy.granular.skill_approval`

373 

374Type / Values

375 

376`boolean`

377 

378Details

379 

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

289 381 

290Key382Key

291 383 

457 549 

458Key550Key

459 551 

460`compact_prompt`552`commit_attribution`

461 553 

462Type / Values554Type / Values

463 555 

465 557 

466Details558Details

467 559 

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

469 561 

470Key562Key

471 563 

472`developer_instructions`564`compact_prompt`

473 565 

474Type / Values566Type / Values

475 567 

477 569 

478Details570Details

479 571 

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

481 573 

482Key574Key

483 575 

484`disable_paste_burst`576`default_permissions`

485 577 

486Type / Values578Type / Values

487 579 

488`boolean`580`string`

489 581 

490Details582Details

491 583 

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

493 585 

494Key586Key

495 587 

496`experimental_compact_prompt_file`588`developer_instructions`

497 589 

498Type / Values590Type / Values

499 591 

500`string (path)`592`string`

501 593 

502Details594Details

503 595 

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

505 597 

506Key598Key

507 599 

508`experimental_use_freeform_apply_patch`600`disable_paste_burst`

509 601 

510Type / Values602Type / Values

511 603 

513 605 

514Details606Details

515 607 

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

517 609 

518Key610Key

519 611 

520`experimental_use_unified_exec_tool`612`experimental_compact_prompt_file`

521 613 

522Type / Values614Type / Values

523 615 

524`boolean`616`string (path)`

525 617 

526Details618Details

527 619 

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

529 621 

530Key622Key

531 623 

532`features.apply_patch_freeform`624`experimental_use_unified_exec_tool`

533 625 

534Type / Values626Type / Values

535 627 

537 629 

538Details630Details

539 631 

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

541 633 

542Key634Key

543 635 

553 645 

554Key646Key

555 647 

556`features.apps_mcp_gateway`648`features.enable_request_compression`

557 649 

558Type / Values650Type / Values

559 651 

561 653 

562Details654Details

563 655 

564Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).656Compress streaming request bodies with zstd when supported (stable; on by default).

565 657 

566Key658Key

567 659 

568`features.child_agents_md`660`features.fast_mode`

569 661 

570Type / Values662Type / Values

571 663 

573 665 

574Details666Details

575 667 

576Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).668Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

577 

578Key

579 

580`features.collaboration_modes`

581 

582Type / Values

583 

584`boolean`

585 

586Details

587 

588Enable collaboration modes such as plan mode (stable; on by default).

589 

590Key

591 

592`features.elevated_windows_sandbox`

593 

594Type / Values

595 

596`boolean`

597 

598Details

599 

600Enable the elevated Windows sandbox pipeline (experimental).

601 

602Key

603 

604`features.experimental_windows_sandbox`

605 

606Type / Values

607 

608`boolean`

609 

610Details

611 

612Run the Windows restricted-token sandbox (experimental).

613 669 

614Key670Key

615 671 

621 677 

622Details678Details

623 679 

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

625 681 

626Key682Key

627 683 

637 693 

638Key694Key

639 695 

640`features.powershell_utf8`696`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 697 

654Type / Values698Type / Values

655 699 

657 701 

658Details702Details

659 703 

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

661 705 

662Key706Key

663 707 

664`features.request_rule`708`features.shell_snapshot`

665 709 

666Type / Values710Type / Values

667 711 

669 713 

670Details714Details

671 715 

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

673 717 

674Key718Key

675 719 

676`features.runtime_metrics`720`features.shell_tool`

677 721 

678Type / Values722Type / Values

679 723 

681 725 

682Details726Details

683 727 

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

685 729 

686Key730Key

687 731 

688`features.search_tool`732`features.skill_mcp_dependency_install`

689 733 

690Type / Values734Type / Values

691 735 

693 737 

694Details738Details

695 739 

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

697 741 

698Key742Key

699 743 

700`features.shell_snapshot`744`features.smart_approvals`

701 745 

702Type / Values746Type / Values

703 747 

705 749 

706Details750Details

707 751 

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

709 753 

710Key754Key

711 755 

712`features.shell_tool`756`features.undo`

713 757 

714Type / Values758Type / Values

715 759 

717 761 

718Details762Details

719 763 

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

721 765 

722Key766Key

723 767 

729 773 

730Details774Details

731 775 

732Use the unified PTY-backed exec tool (beta).776Use 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 777 

746Key778Key

747 779 

865 897 

866Key898Key

867 899 

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

881 901 

882Type / Values902Type / Values

1069 1089 

1070Key1090Key

1071 1091 

1092`mcp_servers.<id>.oauth_resource`

1093 

1094Type / Values

1095 

1096`string`

1097 

1098Details

1099 

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

1101 

1102Key

1103 

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

1073 1105 

1074Type / Values1106Type / Values

1081 1113 

1082Key1114Key

1083 1115 

1116`mcp_servers.<id>.scopes`

1117 

1118Type / Values

1119 

1120`array<string>`

1121 

1122Details

1123 

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

1125 

1126Key

1127 

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

1085 1129 

1086Type / Values1130Type / Values

1345 1389 

1346Key1390Key

1347 1391 

1392`model_providers.<id>.supports_websockets`

1393 

1394Type / Values

1395 

1396`boolean`

1397 

1398Details

1399 

1400Whether that provider supports the Responses API WebSocket transport.

1401 

1402Key

1403 

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

1349 1405 

1350Type / Values1406Type / Values

1351 1407 

1352`chat | responses`1408`responses`

1353 1409 

1354Details1410Details

1355 1411 

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

1357 1413 

1358Key1414Key

1359 1415 

1401 1457 

1402Details1458Details

1403 1459 

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

1405 1461 

1406Key1462Key

1407 1463 

1489 1545 

1490Key1546Key

1491 1547 

1548`openai_base_url`

1549 

1550Type / Values

1551 

1552`string`

1553 

1554Details

1555 

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

1557 

1558Key

1559 

1492`oss_provider`1560`oss_provider`

1493 1561 

1494Type / Values1562Type / Values

1609 1677 

1610Key1678Key

1611 1679 

1680`otel.metrics_exporter`

1681 

1682Type / Values

1683 

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

1685 

1686Details

1687 

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

1689 

1690Key

1691 

1612`otel.trace_exporter`1692`otel.trace_exporter`

1613 1693 

1614Type / Values1694Type / Values

1693 1773 

1694Key1774Key

1695 1775 

1776`permissions.<name>.filesystem`

1777 

1778Type / Values

1779 

1780`table`

1781 

1782Details

1783 

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

1785 

1786Key

1787 

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

1789 

1790Type / Values

1791 

1792`"read" | "write" | "none"`

1793 

1794Details

1795 

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

1797 

1798Key

1799 

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

1801 

1802Type / Values

1803 

1804`"read" | "write" | "none" | table`

1805 

1806Details

1807 

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

1809 

1810Key

1811 

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

1813 

1814Type / Values

1815 

1816`boolean`

1817 

1818Details

1819 

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

1821 

1822Key

1823 

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

1825 

1826Type / Values

1827 

1828`array<string>`

1829 

1830Details

1831 

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

1833 

1834Key

1835 

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

1837 

1838Type / Values

1839 

1840`boolean`

1841 

1842Details

1843 

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

1845 

1846Key

1847 

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

1849 

1850Type / Values

1851 

1852`array<string>`

1853 

1854Details

1855 

1856Allowlist of domains permitted through the managed proxy.

1857 

1858Key

1859 

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

1861 

1862Type / Values

1863 

1864`boolean`

1865 

1866Details

1867 

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

1869 

1870Key

1871 

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

1873 

1874Type / Values

1875 

1876`boolean`

1877 

1878Details

1879 

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

1881 

1882Key

1883 

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

1885 

1886Type / Values

1887 

1888`array<string>`

1889 

1890Details

1891 

1892Denylist of domains blocked by the managed proxy.

1893 

1894Key

1895 

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

1897 

1898Type / Values

1899 

1900`boolean`

1901 

1902Details

1903 

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

1905 

1906Key

1907 

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

1909 

1910Type / Values

1911 

1912`boolean`

1913 

1914Details

1915 

1916Allow UDP over the SOCKS5 listener when enabled.

1917 

1918Key

1919 

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

1921 

1922Type / Values

1923 

1924`boolean`

1925 

1926Details

1927 

1928Enable network access for this named permissions profile.

1929 

1930Key

1931 

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

1933 

1934Type / Values

1935 

1936`limited | full`

1937 

1938Details

1939 

1940Network proxy mode used for subprocess traffic.

1941 

1942Key

1943 

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

1945 

1946Type / Values

1947 

1948`string`

1949 

1950Details

1951 

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

1953 

1954Key

1955 

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

1957 

1958Type / Values

1959 

1960`string`

1961 

1962Details

1963 

1964SOCKS5 proxy endpoint used by this permissions profile.

1965 

1966Key

1967 

1696`personality`1968`personality`

1697 1969 

1698Type / Values1970Type / Values

1705 1977 

1706Key1978Key

1707 1979 

1980`plan_mode_reasoning_effort`

1981 

1982Type / Values

1983 

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

1985 

1986Details

1987 

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

1989 

1990Key

1991 

1708`profile`1992`profile`

1709 1993 

1710Type / Values1994Type / Values

1729 2013 

1730Key2014Key

1731 2015 

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

1733 2017 

1734Type / Values2018Type / Values

1735 2019 

1737 2021 

1738Details2022Details

1739 2023 

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

1741 2025 

1742Key2026Key

1743 2027 

1753 2037 

1754Key2038Key

1755 2039 

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

1757 2041 

1758Type / Values2042Type / Values

1759 2043 

1760`boolean`2044`string (path)`

1761 2045 

1762Details2046Details

1763 2047 

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

1765 2049 

1766Key2050Key

1767 2051 

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

1769 2053 

1770Type / Values2054Type / Values

1771 2055 

1773 2057 

1774Details2058Details

1775 2059 

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

1777 2061 

1778Key2062Key

1779 2063 

1801 2085 

1802Key2086Key

1803 2087 

2088`profiles.<name>.plan_mode_reasoning_effort`

2089 

2090Type / Values

2091 

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

2093 

2094Details

2095 

2096Profile-scoped Plan-mode reasoning override.

2097 

2098Key

2099 

2100`profiles.<name>.service_tier`

2101 

2102Type / Values

2103 

2104`flex | fast`

2105 

2106Details

2107 

2108Profile-scoped service tier preference for new turns.

2109 

2110Key

2111 

2112`profiles.<name>.tools_view_image`

2113 

2114Type / Values

2115 

2116`boolean`

2117 

2118Details

2119 

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

2121 

2122Key

2123 

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

1805 2125 

1806Type / Values2126Type / Values

1813 2133 

1814Key2134Key

1815 2135 

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

2137 

2138Type / Values

2139 

2140`unelevated | elevated`

2141 

2142Details

2143 

2144Profile-scoped Windows sandbox mode override.

2145 

2146Key

2147 

1816`project_doc_fallback_filenames`2148`project_doc_fallback_filenames`

1817 2149 

1818Type / Values2150Type / Values

1933 2265 

1934Key2266Key

1935 2267 

2268`service_tier`

2269 

2270Type / Values

2271 

2272`flex | fast`

2273 

2274Details

2275 

2276Preferred service tier for new turns.

2277 

2278Key

2279 

1936`shell_environment_policy.exclude`2280`shell_environment_policy.exclude`

1937 2281 

1938Type / Values2282Type / Values

2053 2397 

2054Key2398Key

2055 2399 

2400`sqlite_home`

2401 

2402Type / Values

2403 

2404`string (path)`

2405 

2406Details

2407 

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

2409 

2410Key

2411 

2056`suppress_unstable_features_warning`2412`suppress_unstable_features_warning`

2057 2413 

2058Type / Values2414Type / Values

2077 2433 

2078Key2434Key

2079 2435 

2080`tools.web_search`2436`tools.view_image`

2081 2437 

2082Type / Values2438Type / Values

2083 2439 

2085 2441 

2086Details2442Details

2087 2443 

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

2445 

2446Key

2447 

2448`tools.web_search`

2449 

2450Type / Values

2451 

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

2453 

2454Details

2455 

2456Optional 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 2457 

2090Key2458Key

2091 2459 

2125 2493 

2126Key2494Key

2127 2495 

2496`tui.model_availability_nux.<model>`

2497 

2498Type / Values

2499 

2500`integer`

2501 

2502Details

2503 

2504Internal startup-tooltip state keyed by model slug.

2505 

2506Key

2507 

2128`tui.notification_method`2508`tui.notification_method`

2129 2509 

2130Type / Values2510Type / Values

2173 2553 

2174Key2554Key

2175 2555 

2556`tui.theme`

2557 

2558Type / Values

2559 

2560`string`

2561 

2562Details

2563 

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

2565 

2566Key

2567 

2176`web_search`2568`web_search`

2177 2569 

2178Type / Values2570Type / Values

2195 2587 

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

2197 2589 

2590Key

2591 

2592`windows.sandbox`

2593 

2594Type / Values

2595 

2596`unelevated | elevated`

2597 

2598Details

2599 

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

2601 

2602Key

2603 

2604`windows.sandbox_private_desktop`

2605 

2606Type / Values

2607 

2608`boolean`

2609 

2610Details

2611 

2612Run 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.

2613 

2198Expand to view all2614Expand to view all

2199 2615 

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

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

2216 2632 

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

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

2635 

2217| Key | Type / Values | Details |2636| Key | Type / Values | Details |

2218| --- | --- | --- |2637| --- | --- | --- |

2219| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`). |2638| `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`. |2639| `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`. |2640| `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`. |

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

2642| `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. |2643| `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). |2644| `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. |2645| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |

2241 2662 

2242Details2663Details

2243 2664 

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

2245 2666 

2246Key2667Key

2247 2668 

2269 2690 

2270Key2691Key

2271 2692 

2693`features`

2694 

2695Type / Values

2696 

2697`table`

2698 

2699Details

2700 

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

2702 

2703Key

2704 

2705`features.<name>`

2706 

2707Type / Values

2708 

2709`boolean`

2710 

2711Details

2712 

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

2714 

2715Key

2716 

2272`mcp_servers`2717`mcp_servers`

2273 2718 

2274Type / Values2719Type / Values