config-reference.md Codex Docs, 2026-02-21 00:33 UTC → 2026-03-25 18:24 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.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |

16| `approval_policy` | `untrusted | on-request | never` | Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |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. |

17| `apps.<id>.disabled_reason` | `unknown | user` | Optional reason attached when an app/connector is disabled. |17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |

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

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

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

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

22| `approval_policy.granular.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are allowed to surface instead of being 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. |

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

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

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

30| `apps.<id>.default_tools_approval_mode` | `auto | prompt | approve` | Default approval behavior for tools in this app unless a per-tool override exists. |

31| `apps.<id>.default_tools_enabled` | `boolean` | Default enabled state for tools in this app unless a per-tool override exists. |

32| `apps.<id>.destructive_enabled` | `boolean` | Allow or block tools in this app that advertise `destructive_hint = true`. |

18| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |33| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |

34| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |

35| `apps.<id>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. |

36| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |

37| `background_terminal_max_timeout` | `number` | Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key. |

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

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

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

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

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

24| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |45| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |

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

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

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

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

29| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |48| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |

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

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

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

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

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

35| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |

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

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

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

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

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

41| `features.search_tool` | `boolean` | Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental). |

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

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

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

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

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

47| `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"`. |

48| `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"`. |

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

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

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

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

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

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

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

73| `mcp_oauth_callback_url` | `string` | Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port. |

60| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |74| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |

61| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |75| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |

62| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |76| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |

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

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

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

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

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

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

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

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

77| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |93| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |

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

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

79| `model_context_window` | `number` | Context window tokens available to the active model. |96| `model_context_window` | `number` | Context window tokens available to the active model. |

80| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |97| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |

81| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |98| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

124| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |161| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

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

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

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

128| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |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. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

155| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |200| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

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

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

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

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

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

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

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

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

164 213 

165Key214Key

166 215 

188 237 

189Key238Key

190 239 

191`agents.max_threads`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`

192 253 

193Type / Values254Type / Values

194 255 

196 257 

197Details258Details

198 259 

199Maximum number of agent threads that can be open concurrently.260Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.

200 261 

201Key262Key

202 263 

203`approval_policy`264`agents.max_depth`

204 265 

205Type / Values266Type / Values

206 267 

207`untrusted | on-request | never`268`number`

208 269 

209Details270Details

210 271 

211Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.272Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).

212 273 

213Key274Key

214 275 

215`apps.<id>.disabled_reason`276`agents.max_threads`

216 277 

217Type / Values278Type / Values

218 279 

219`unknown | user`280`number`

220 281 

221Details282Details

222 283 

223Optional reason attached when an app/connector is disabled.284Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.

224 285 

225Key286Key

226 287 

227`apps.<id>.enabled`288`allow_login_shell`

228 289 

229Type / Values290Type / Values

230 291 

232 293 

233Details294Details

234 295 

235Enable or disable a specific app/connector by id (default: true).296Allow 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.

236 297 

237Key298Key

238 299 

239`chatgpt_base_url`300`analytics.enabled`

240 301 

241Type / Values302Type / Values

242 303 

243`string`304`boolean`

244 305 

245Details306Details

246 307 

247Override the base URL used during the ChatGPT login flow.308Enable or disable analytics for this machine/profile. When unset, the client default applies.

248 309 

249Key310Key

250 311 

251`check_for_update_on_startup`312`approval_policy`

313 

314Type / Values

315 

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`

252 325 

253Type / Values326Type / Values

254 327 

256 329 

257Details330Details

258 331 

259Check for Codex updates on startup (set to false only when updates are centrally managed).332When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

260 333 

261Key334Key

262 335 

263`cli_auth_credentials_store`336`approval_policy.granular.request_permissions`

264 337 

265Type / Values338Type / Values

266 339 

267`file | keyring | auto`340`boolean`

268 341 

269Details342Details

270 343 

271Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).344When `true`, prompts from the `request_permissions` tool are allowed to surface.

272 345 

273Key346Key

274 347 

275`compact_prompt`348`approval_policy.granular.rules`

276 349 

277Type / Values350Type / Values

278 351 

279`string`352`boolean`

280 353 

281Details354Details

282 355 

283Inline override for the history compaction prompt.356When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.

284 357 

285Key358Key

286 359 

287`developer_instructions`360`approval_policy.granular.sandbox_approval`

288 361 

289Type / Values362Type / Values

290 363 

291`string`364`boolean`

292 365 

293Details366Details

294 367 

295Additional developer instructions injected into the session (optional).368When `true`, sandbox escalation approval prompts are allowed to surface.

296 369 

297Key370Key

298 371 

299`disable_paste_burst`372`approval_policy.granular.skill_approval`

300 373 

301Type / Values374Type / Values

302 375 

304 377 

305Details378Details

306 379 

307Disable burst-paste detection in the TUI.380When `true`, skill-script approval prompts are allowed to surface.

308 381 

309Key382Key

310 383 

311`experimental_compact_prompt_file`384`apps._default.destructive_enabled`

312 385 

313Type / Values386Type / Values

314 387 

315`string (path)`388`boolean`

316 389 

317Details390Details

318 391 

319Load the compaction prompt override from a file (experimental).392Default allow/deny for app tools with `destructive_hint = true`.

320 393 

321Key394Key

322 395 

323`experimental_use_freeform_apply_patch`396`apps._default.enabled`

324 397 

325Type / Values398Type / Values

326 399 

328 401 

329Details402Details

330 403 

331Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.404Default app enabled state for all apps unless overridden per app.

332 405 

333Key406Key

334 407 

335`experimental_use_unified_exec_tool`408`apps._default.open_world_enabled`

336 409 

337Type / Values410Type / Values

338 411 

340 413 

341Details414Details

342 415 

343Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.416Default allow/deny for app tools with `open_world_hint = true`.

417 

418Key

419 

420`apps.<id>.default_tools_approval_mode`

421 

422Type / Values

423 

424`auto | prompt | approve`

425 

426Details

427 

428Default approval behavior for tools in this app unless a per-tool override exists.

344 429 

345Key430Key

346 431 

347`features.apply_patch_freeform`432`apps.<id>.default_tools_enabled`

348 433 

349Type / Values434Type / Values

350 435 

352 437 

353Details438Details

354 439 

355Expose the freeform `apply_patch` tool (experimental).440Default enabled state for tools in this app unless a per-tool override exists.

356 441 

357Key442Key

358 443 

359`features.apps`444`apps.<id>.destructive_enabled`

360 445 

361Type / Values446Type / Values

362 447 

364 449 

365Details450Details

366 451 

367Enable ChatGPT Apps/connectors support (experimental).452Allow or block tools in this app that advertise `destructive_hint = true`.

368 453 

369Key454Key

370 455 

371`features.apps_mcp_gateway`456`apps.<id>.enabled`

372 457 

373Type / Values458Type / Values

374 459 

376 461 

377Details462Details

378 463 

379Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).464Enable or disable a specific app/connector by id (default: true).

380 465 

381Key466Key

382 467 

383`features.child_agents_md`468`apps.<id>.open_world_enabled`

384 469 

385Type / Values470Type / Values

386 471 

388 473 

389Details474Details

390 475 

391Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).476Allow or block tools in this app that advertise `open_world_hint = true`.

477 

478Key

479 

480`apps.<id>.tools.<tool>.approval_mode`

481 

482Type / Values

483 

484`auto | prompt | approve`

485 

486Details

487 

488Per-tool approval behavior override for a single app tool.

392 489 

393Key490Key

394 491 

395`features.collaboration_modes`492`apps.<id>.tools.<tool>.enabled`

396 493 

397Type / Values494Type / Values

398 495 

400 497 

401Details498Details

402 499 

403Enable collaboration modes such as plan mode (stable; on by default).500Per-tool enabled override for an app tool (for example `repos/list`).

501 

502Key

503 

504`background_terminal_max_timeout`

505 

506Type / Values

507 

508`number`

509 

510Details

511 

512Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.

513 

514Key

515 

516`chatgpt_base_url`

517 

518Type / Values

519 

520`string`

521 

522Details

523 

524Override the base URL used during the ChatGPT login flow.

404 525 

405Key526Key

406 527 

407`features.elevated_windows_sandbox`528`check_for_update_on_startup`

408 529 

409Type / Values530Type / Values

410 531 

412 533 

413Details534Details

414 535 

415Enable the elevated Windows sandbox pipeline (experimental).536Check for Codex updates on startup (set to false only when updates are centrally managed).

537 

538Key

539 

540`cli_auth_credentials_store`

541 

542Type / Values

543 

544`file | keyring | auto`

545 

546Details

547 

548Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).

549 

550Key

551 

552`commit_attribution`

553 

554Type / Values

555 

556`string`

557 

558Details

559 

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

561 

562Key

563 

564`compact_prompt`

565 

566Type / Values

567 

568`string`

569 

570Details

571 

572Inline override for the history compaction prompt.

573 

574Key

575 

576`default_permissions`

577 

578Type / Values

579 

580`string`

581 

582Details

583 

584Name of the default permissions profile to apply to sandboxed tool calls.

585 

586Key

587 

588`developer_instructions`

589 

590Type / Values

591 

592`string`

593 

594Details

595 

596Additional developer instructions injected into the session (optional).

416 597 

417Key598Key

418 599 

419`features.experimental_windows_sandbox`600`disable_paste_burst`

420 601 

421Type / Values602Type / Values

422 603 

424 605 

425Details606Details

426 607 

427Run the Windows restricted-token sandbox (experimental).608Disable burst-paste detection in the TUI.

428 609 

429Key610Key

430 611 

431`features.multi_agent`612`experimental_compact_prompt_file`

613 

614Type / Values

615 

616`string (path)`

617 

618Details

619 

620Load the compaction prompt override from a file (experimental).

621 

622Key

623 

624`experimental_use_unified_exec_tool`

432 625 

433Type / Values626Type / Values

434 627 

436 629 

437Details630Details

438 631 

439Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).632Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

440 633 

441Key634Key

442 635 

443`features.personality`636`features.apps`

444 637 

445Type / Values638Type / Values

446 639 

448 641 

449Details642Details

450 643 

451Enable personality selection controls (stable; on by default).644Enable ChatGPT Apps/connectors support (experimental).

452 645 

453Key646Key

454 647 

455`features.powershell_utf8`648`features.enable_request_compression`

456 649 

457Type / Values650Type / Values

458 651 

460 653 

461Details654Details

462 655 

463Force PowerShell UTF-8 output (defaults to true).656Compress streaming request bodies with zstd when supported (stable; on by default).

464 657 

465Key658Key

466 659 

467`features.remote_models`660`features.fast_mode`

468 661 

469Type / Values662Type / Values

470 663 

472 665 

473Details666Details

474 667 

475Refresh remote model list before showing readiness (experimental).668Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

476 669 

477Key670Key

478 671 

479`features.request_rule`672`features.multi_agent`

480 673 

481Type / Values674Type / Values

482 675 

484 677 

485Details678Details

486 679 

487Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).680Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

488 681 

489Key682Key

490 683 

491`features.runtime_metrics`684`features.personality`

492 685 

493Type / Values686Type / Values

494 687 

496 689 

497Details690Details

498 691 

499Show runtime metrics summary in TUI turn separators (experimental).692Enable personality selection controls (stable; on by default).

500 693 

501Key694Key

502 695 

503`features.search_tool`696`features.prevent_idle_sleep`

504 697 

505Type / Values698Type / Values

506 699 

508 701 

509Details702Details

510 703 

511Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).704Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

512 705 

513Key706Key

514 707 

520 713 

521Details714Details

522 715 

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

524 717 

525Key718Key

526 719 

536 729 

537Key730Key

538 731 

539`features.unified_exec`732`features.skill_mcp_dependency_install`

733 

734Type / Values

735 

736`boolean`

737 

738Details

739 

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

741 

742Key

743 

744`features.smart_approvals`

745 

746Type / Values

747 

748`boolean`

749 

750Details

751 

752Route eligible approval requests through the guardian reviewer subagent (experimental; off by default).

753 

754Key

755 

756`features.undo`

540 757 

541Type / Values758Type / Values

542 759 

544 761 

545Details762Details

546 763 

547Use the unified PTY-backed exec tool (beta).764Enable undo support (stable; off by default).

548 765 

549Key766Key

550 767 

551`features.use_linux_sandbox_bwrap`768`features.unified_exec`

552 769 

553Type / Values770Type / Values

554 771 

556 773 

557Details774Details

558 775 

559Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).776Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

560 777 

561Key778Key

562 779 

680 897 

681Key898Key

682 899 

683`include_apply_patch_tool`

684 

685Type / Values

686 

687`boolean`

688 

689Details

690 

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

692 

693Key

694 

695`instructions`900`instructions`

696 901 

697Type / Values902Type / Values

728 933 

729Key934Key

730 935 

936`mcp_oauth_callback_url`

937 

938Type / Values

939 

940`string`

941 

942Details

943 

944Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.

945 

946Key

947 

731`mcp_oauth_credentials_store`948`mcp_oauth_credentials_store`

732 949 

733Type / Values950Type / Values

872 1089 

873Key1090Key

874 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 

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

876 1105 

877Type / Values1106Type / Values

884 1113 

885Key1114Key

886 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 

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

888 1129 

889Type / Values1130Type / Values

956 1197 

957Key1198Key

958 1199 

1200`model_catalog_json`

1201 

1202Type / Values

1203 

1204`string (path)`

1205 

1206Details

1207 

1208Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.

1209 

1210Key

1211 

959`model_context_window`1212`model_context_window`

960 1213 

961Type / Values1214Type / Values

1136 1389 

1137Key1390Key

1138 1391 

1139`model_providers.<id>.wire_api`1392`model_providers.<id>.supports_websockets`

1140 1393 

1141Type / Values1394Type / Values

1142 1395 

1143`chat | responses`1396`boolean`

1144 1397 

1145Details1398Details

1146 1399 

1147Protocol used by the provider (defaults to `chat` if omitted).1400Whether that provider supports the Responses API WebSocket transport.

1148 1401 

1149Key1402Key

1150 1403 

1151`model_reasoning_effort`1404`model_providers.<id>.wire_api`

1152 1405 

1153Type / Values1406Type / Values

1154 1407 

1155`minimal | low | medium | high | xhigh`1408`responses`

1409 

1410Details

1411 

1412Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.

1413 

1414Key

1415 

1416`model_reasoning_effort`

1417 

1418Type / Values

1419 

1420`minimal | low | medium | high | xhigh`

1156 1421 

1157Details1422Details

1158 1423 

1192 1457 

1193Details1458Details

1194 1459 

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

1196 1461 

1197Key1462Key

1198 1463 

1280 1545 

1281Key1546Key

1282 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 

1283`oss_provider`1560`oss_provider`

1284 1561 

1285Type / Values1562Type / Values

1400 1677 

1401Key1678Key

1402 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 

1403`otel.trace_exporter`1692`otel.trace_exporter`

1404 1693 

1405Type / Values1694Type / Values

1484 1773 

1485Key1774Key

1486 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 

1487`personality`1968`personality`

1488 1969 

1489Type / Values1970Type / Values

1496 1977 

1497Key1978Key

1498 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 

1499`profile`1992`profile`

1500 1993 

1501Type / Values1994Type / Values

1520 2013 

1521Key2014Key

1522 2015 

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

1524 2017 

1525Type / Values2018Type / Values

1526 2019 

1528 2021 

1529Details2022Details

1530 2023 

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

1532 2025 

1533Key2026Key

1534 2027 

1544 2037 

1545Key2038Key

1546 2039 

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

1548 2041 

1549Type / Values2042Type / Values

1550 2043 

1551`boolean`2044`string (path)`

1552 2045 

1553Details2046Details

1554 2047 

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

2049 

2050Key

2051 

2052`profiles.<name>.model_instructions_file`

2053 

2054Type / Values

2055 

2056`string (path)`

2057 

2058Details

2059 

2060Profile-scoped replacement for the built-in instruction file.

1556 2061 

1557Key2062Key

1558 2063 

1580 2085 

1581Key2086Key

1582 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 

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

1584 2125 

1585Type / Values2126Type / Values

1592 2133 

1593Key2134Key

1594 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 

1595`project_doc_fallback_filenames`2148`project_doc_fallback_filenames`

1596 2149 

1597Type / Values2150Type / Values

1712 2265 

1713Key2266Key

1714 2267 

2268`service_tier`

2269 

2270Type / Values

2271 

2272`flex | fast`

2273 

2274Details

2275 

2276Preferred service tier for new turns.

2277 

2278Key

2279 

1715`shell_environment_policy.exclude`2280`shell_environment_policy.exclude`

1716 2281 

1717Type / Values2282Type / Values

1832 2397 

1833Key2398Key

1834 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 

1835`suppress_unstable_features_warning`2412`suppress_unstable_features_warning`

1836 2413 

1837Type / Values2414Type / Values

1856 2433 

1857Key2434Key

1858 2435 

1859`tools.web_search`2436`tools.view_image`

1860 2437 

1861Type / Values2438Type / Values

1862 2439 

1864 2441 

1865Details2442Details

1866 2443 

1867Deprecated 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.

1868 2457 

1869Key2458Key

1870 2459 

1904 2493 

1905Key2494Key

1906 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 

1907`tui.notification_method`2508`tui.notification_method`

1908 2509 

1909Type / Values2510Type / Values

1952 2553 

1953Key2554Key

1954 2555 

2556`tui.theme`

2557 

2558Type / Values

2559 

2560`string`

2561 

2562Details

2563 

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

2565 

2566Key

2567 

1955`web_search`2568`web_search`

1956 2569 

1957Type / Values2570Type / Values

1974 2587