config-reference.md Codex Docs, 2026-02-19 20:37 UTC → 2026-04-08 00:40 UTC

1# Configuration Reference1# Configuration Reference

2 2 

3Complete reference for Codex config.toml and requirements.toml

4 

5Use this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with [Config basics](https://developers.openai.com/codex/config-basic) and [Advanced Config](https://developers.openai.com/codex/config-advanced).3Use this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with [Config basics](https://developers.openai.com/codex/config-basic) and [Advanced Config](https://developers.openai.com/codex/config-advanced).

6 4 

7## `config.toml`5## `config.toml`

8 6 

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

10 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/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 

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.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |

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

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

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

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

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

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

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). |56| `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). |57| `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). |58| `features.smart_approvals` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). |

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

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

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

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

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

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

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

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

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

74| `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. |75| `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. |76| `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. |77| `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. |84| `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. |85| `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. |86| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |

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

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

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

73| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |90| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |

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

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

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

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

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

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

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

80| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |98| `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`). |99| `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). |109| `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). |110| `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). |111| `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). |112| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

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

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

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

97| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |116| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |

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

99| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |118| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |

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

101| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |120| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |

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

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

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

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

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

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

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

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

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

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

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

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

117| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |138| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

128| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |166| `profiles.<name>.model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |

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

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

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

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

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

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

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

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

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

133| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |176| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |

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

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

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

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

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

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

143| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |187| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

163| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |211| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

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

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

164 214 

165Key215Key

166 216 

188 238 

189Key239Key

190 240 

241`agents.<name>.nickname_candidates`

242 

243Type / Values

244 

245`array<string>`

246 

247Details

248 

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

250 

251Key

252 

253`agents.job_max_runtime_seconds`

254 

255Type / Values

256 

257`number`

258 

259Details

260 

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

262 

263Key

264 

265`agents.max_depth`

266 

267Type / Values

268 

269`number`

270 

271Details

272 

273Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).

274 

275Key

276 

191`agents.max_threads`277`agents.max_threads`

192 278 

193Type / Values279Type / Values

196 282 

197Details283Details

198 284 

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

286 

287Key

288 

289`allow_login_shell`

290 

291Type / Values

292 

293`boolean`

294 

295Details

296 

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

298 

299Key

300 

301`analytics.enabled`

302 

303Type / Values

304 

305`boolean`

306 

307Details

308 

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

200 310 

201Key311Key

202 312 

204 314 

205Type / Values315Type / Values

206 316 

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

208 318 

209Details319Details

210 320 

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.321Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.

212 322 

213Key323Key

214 324 

215`apps.<id>.disabled_reason`325`approval_policy.granular.mcp_elicitations`

216 326 

217Type / Values327Type / Values

218 328 

219`unknown | user`329`boolean`

220 330 

221Details331Details

222 332 

223Optional reason attached when an app/connector is disabled.333When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

224 334 

225Key335Key

226 336 

227`apps.<id>.enabled`337`approval_policy.granular.request_permissions`

228 338 

229Type / Values339Type / Values

230 340 

232 342 

233Details343Details

234 344 

235Enable or disable a specific app/connector by id (default: true).345When `true`, prompts from the `request_permissions` tool are allowed to surface.

236 346 

237Key347Key

238 348 

239`chatgpt_base_url`349`approval_policy.granular.rules`

240 350 

241Type / Values351Type / Values

242 352 

243`string`353`boolean`

244 354 

245Details355Details

246 356 

247Override the base URL used during the ChatGPT login flow.357When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.

248 358 

249Key359Key

250 360 

251`check_for_update_on_startup`361`approval_policy.granular.sandbox_approval`

252 362 

253Type / Values363Type / Values

254 364 

256 366 

257Details367Details

258 368 

259Check for Codex updates on startup (set to false only when updates are centrally managed).369When `true`, sandbox escalation approval prompts are allowed to surface.

260 370 

261Key371Key

262 372 

263`cli_auth_credentials_store`373`approval_policy.granular.skill_approval`

264 374 

265Type / Values375Type / Values

266 376 

267`file | keyring | auto`377`boolean`

268 378 

269Details379Details

270 380 

271Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).381When `true`, skill-script approval prompts are allowed to surface.

272 382 

273Key383Key

274 384 

275`compact_prompt`385`apps._default.destructive_enabled`

276 386 

277Type / Values387Type / Values

278 388 

279`string`389`boolean`

280 390 

281Details391Details

282 392 

283Inline override for the history compaction prompt.393Default allow/deny for app tools with `destructive_hint = true`.

284 394 

285Key395Key

286 396 

287`developer_instructions`397`apps._default.enabled`

288 398 

289Type / Values399Type / Values

290 400 

291`string`401`boolean`

292 402 

293Details403Details

294 404 

295Additional developer instructions injected into the session (optional).405Default app enabled state for all apps unless overridden per app.

296 406 

297Key407Key

298 408 

299`disable_paste_burst`409`apps._default.open_world_enabled`

300 410 

301Type / Values411Type / Values

302 412 

304 414 

305Details415Details

306 416 

307Disable burst-paste detection in the TUI.417Default allow/deny for app tools with `open_world_hint = true`.

308 418 

309Key419Key

310 420 

311`experimental_compact_prompt_file`421`apps.<id>.default_tools_approval_mode`

312 422 

313Type / Values423Type / Values

314 424 

315`string (path)`425`auto | prompt | approve`

316 426 

317Details427Details

318 428 

319Load the compaction prompt override from a file (experimental).429Default approval behavior for tools in this app unless a per-tool override exists.

320 430 

321Key431Key

322 432 

323`experimental_use_freeform_apply_patch`433`apps.<id>.default_tools_enabled`

324 434 

325Type / Values435Type / Values

326 436 

328 438 

329Details439Details

330 440 

331Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.441Default enabled state for tools in this app unless a per-tool override exists.

332 442 

333Key443Key

334 444 

335`experimental_use_unified_exec_tool`445`apps.<id>.destructive_enabled`

336 446 

337Type / Values447Type / Values

338 448 

340 450 

341Details451Details

342 452 

343Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.453Allow or block tools in this app that advertise `destructive_hint = true`.

344 454 

345Key455Key

346 456 

347`features.apply_patch_freeform`457`apps.<id>.enabled`

348 458 

349Type / Values459Type / Values

350 460 

352 462 

353Details463Details

354 464 

355Expose the freeform `apply_patch` tool (experimental).465Enable or disable a specific app/connector by id (default: true).

356 466 

357Key467Key

358 468 

359`features.apps`469`apps.<id>.open_world_enabled`

360 470 

361Type / Values471Type / Values

362 472 

364 474 

365Details475Details

366 476 

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

368 478 

369Key479Key

370 480 

371`features.apps_mcp_gateway`481`apps.<id>.tools.<tool>.approval_mode`

372 482 

373Type / Values483Type / Values

374 484 

375`boolean`485`auto | prompt | approve`

376 486 

377Details487Details

378 488 

379Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).489Per-tool approval behavior override for a single app tool.

380 490 

381Key491Key

382 492 

383`features.child_agents_md`493`apps.<id>.tools.<tool>.enabled`

384 494 

385Type / Values495Type / Values

386 496 

388 498 

389Details499Details

390 500 

391Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).501Per-tool enabled override for an app tool (for example `repos/list`).

502 

503Key

504 

505`background_terminal_max_timeout`

506 

507Type / Values

508 

509`number`

510 

511Details

512 

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

514 

515Key

516 

517`chatgpt_base_url`

518 

519Type / Values

520 

521`string`

522 

523Details

524 

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

392 526 

393Key527Key

394 528 

395`features.collaboration_modes`529`check_for_update_on_startup`

396 530 

397Type / Values531Type / Values

398 532 

400 534 

401Details535Details

402 536 

403Enable collaboration modes such as plan mode (stable; on by default).537Check for Codex updates on startup (set to false only when updates are centrally managed).

538 

539Key

540 

541`cli_auth_credentials_store`

542 

543Type / Values

544 

545`file | keyring | auto`

546 

547Details

548 

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

550 

551Key

552 

553`commit_attribution`

554 

555Type / Values

556 

557`string`

558 

559Details

560 

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

562 

563Key

564 

565`compact_prompt`

566 

567Type / Values

568 

569`string`

570 

571Details

572 

573Inline override for the history compaction prompt.

574 

575Key

576 

577`default_permissions`

578 

579Type / Values

580 

581`string`

582 

583Details

584 

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

586 

587Key

588 

589`developer_instructions`

590 

591Type / Values

592 

593`string`

594 

595Details

596 

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

404 598 

405Key599Key

406 600 

407`features.elevated_windows_sandbox`601`disable_paste_burst`

408 602 

409Type / Values603Type / Values

410 604 

412 606 

413Details607Details

414 608 

415Enable the elevated Windows sandbox pipeline (experimental).609Disable burst-paste detection in the TUI.

610 

611Key

612 

613`experimental_compact_prompt_file`

614 

615Type / Values

616 

617`string (path)`

618 

619Details

620 

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

416 622 

417Key623Key

418 624 

419`features.experimental_windows_sandbox`625`experimental_use_unified_exec_tool`

420 626 

421Type / Values627Type / Values

422 628 

424 630 

425Details631Details

426 632 

427Run the Windows restricted-token sandbox (experimental).633Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

428 634 

429Key635Key

430 636 

431`features.multi_agent`637`features.apps`

432 638 

433Type / Values639Type / Values

434 640 

436 642 

437Details643Details

438 644 

439Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).645Enable ChatGPT Apps/connectors support (experimental).

440 646 

441Key647Key

442 648 

443`features.personality`649`features.codex_hooks`

444 650 

445Type / Values651Type / Values

446 652 

448 654 

449Details655Details

450 656 

451Enable personality selection controls (stable; on by default).657Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).

452 658 

453Key659Key

454 660 

455`features.powershell_utf8`661`features.enable_request_compression`

456 662 

457Type / Values663Type / Values

458 664 

460 666 

461Details667Details

462 668 

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

464 670 

465Key671Key

466 672 

467`features.remote_models`673`features.fast_mode`

468 674 

469Type / Values675Type / Values

470 676 

472 678 

473Details679Details

474 680 

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

476 682 

477Key683Key

478 684 

479`features.request_rule`685`features.multi_agent`

480 686 

481Type / Values687Type / Values

482 688 

484 690 

485Details691Details

486 692 

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

488 694 

489Key695Key

490 696 

491`features.runtime_metrics`697`features.personality`

492 698 

493Type / Values699Type / Values

494 700 

496 702 

497Details703Details

498 704 

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

500 706 

501Key707Key

502 708 

503`features.search_tool`709`features.prevent_idle_sleep`

504 710 

505Type / Values711Type / Values

506 712 

508 714 

509Details715Details

510 716 

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

512 718 

513Key719Key

514 720 

520 726 

521Details727Details

522 728 

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

524 730 

525Key731Key

526 732 

536 742 

537Key743Key

538 744 

539`features.unified_exec`745`features.skill_mcp_dependency_install`

746 

747Type / Values

748 

749`boolean`

750 

751Details

752 

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

754 

755Key

756 

757`features.smart_approvals`

758 

759Type / Values

760 

761`boolean`

762 

763Details

764 

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

766 

767Key

768 

769`features.undo`

540 770 

541Type / Values771Type / Values

542 772 

544 774 

545Details775Details

546 776 

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

548 778 

549Key779Key

550 780 

551`features.use_linux_sandbox_bwrap`781`features.unified_exec`

552 782 

553Type / Values783Type / Values

554 784 

556 786 

557Details787Details

558 788 

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

560 790 

561Key791Key

562 792 

680 910 

681Key911Key

682 912 

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

696 914 

697Type / Values915Type / Values

728 946 

729Key947Key

730 948 

949`mcp_oauth_callback_url`

950 

951Type / Values

952 

953`string`

954 

955Details

956 

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

958 

959Key

960 

731`mcp_oauth_credentials_store`961`mcp_oauth_credentials_store`

732 962 

733Type / Values963Type / Values

872 1102 

873Key1103Key

874 1104 

1105`mcp_servers.<id>.oauth_resource`

1106 

1107Type / Values

1108 

1109`string`

1110 

1111Details

1112 

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

1114 

1115Key

1116 

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

876 1118 

877Type / Values1119Type / Values

884 1126 

885Key1127Key

886 1128 

1129`mcp_servers.<id>.scopes`

1130 

1131Type / Values

1132 

1133`array<string>`

1134 

1135Details

1136 

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

1138 

1139Key

1140 

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

888 1142 

889Type / Values1143Type / Values

940 1194 

941Details1195Details

942 1196 

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

944 1198 

945Key1199Key

946 1200 

956 1210 

957Key1211Key

958 1212 

959`model_context_window`1213`model_catalog_json`

960 1214 

961Type / Values1215Type / Values

962 1216 

963`number`1217`string (path)`

964 1218 

965Details1219Details

966 1220 

967Context window tokens available to the active model.1221Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.

968 1222 

969Key1223Key

970 1224 

971`model_instructions_file`1225`model_context_window`

1226 

1227Type / Values

1228 

1229`number`

1230 

1231Details

1232 

1233Context window tokens available to the active model.

1234 

1235Key

1236 

1237`model_instructions_file`

972 1238 

973Type / Values1239Type / Values

974 1240 

1136 1402 

1137Key1403Key

1138 1404 

1405`model_providers.<id>.supports_websockets`

1406 

1407Type / Values

1408 

1409`boolean`

1410 

1411Details

1412 

1413Whether that provider supports the Responses API WebSocket transport.

1414 

1415Key

1416 

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

1140 1418 

1141Type / Values1419Type / Values

1142 1420 

1143`chat | responses`1421`responses`

1144 1422 

1145Details1423Details

1146 1424 

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

1148 1426 

1149Key1427Key

1150 1428 

1192 1470 

1193Details1471Details

1194 1472 

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

1196 1474 

1197Key1475Key

1198 1476 

1280 1558 

1281Key1559Key

1282 1560 

1561`openai_base_url`

1562 

1563Type / Values

1564 

1565`string`

1566 

1567Details

1568 

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

1570 

1571Key

1572 

1283`oss_provider`1573`oss_provider`

1284 1574 

1285Type / Values1575Type / Values

1400 1690 

1401Key1691Key

1402 1692 

1693`otel.metrics_exporter`

1694 

1695Type / Values

1696 

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

1698 

1699Details

1700 

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

1702 

1703Key

1704 

1403`otel.trace_exporter`1705`otel.trace_exporter`

1404 1706 

1405Type / Values1707Type / Values

1484 1786 

1485Key1787Key

1486 1788 

1789`permissions.<name>.filesystem`

1790 

1791Type / Values

1792 

1793`table`

1794 

1795Details

1796 

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

1798 

1799Key

1800 

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

1802 

1803Type / Values

1804 

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

1806 

1807Details

1808 

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

1810 

1811Key

1812 

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

1814 

1815Type / Values

1816 

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

1818 

1819Details

1820 

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

1822 

1823Key

1824 

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

1826 

1827Type / Values

1828 

1829`boolean`

1830 

1831Details

1832 

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

1834 

1835Key

1836 

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

1838 

1839Type / Values

1840 

1841`array<string>`

1842 

1843Details

1844 

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

1846 

1847Key

1848 

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

1850 

1851Type / Values

1852 

1853`boolean`

1854 

1855Details

1856 

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

1858 

1859Key

1860 

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

1862 

1863Type / Values

1864 

1865`array<string>`

1866 

1867Details

1868 

1869Allowlist of domains permitted through the managed proxy.

1870 

1871Key

1872 

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

1874 

1875Type / Values

1876 

1877`boolean`

1878 

1879Details

1880 

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

1882 

1883Key

1884 

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

1886 

1887Type / Values

1888 

1889`boolean`

1890 

1891Details

1892 

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

1894 

1895Key

1896 

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

1898 

1899Type / Values

1900 

1901`array<string>`

1902 

1903Details

1904 

1905Denylist of domains blocked by the managed proxy.

1906 

1907Key

1908 

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

1910 

1911Type / Values

1912 

1913`boolean`

1914 

1915Details

1916 

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

1918 

1919Key

1920 

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

1922 

1923Type / Values

1924 

1925`boolean`

1926 

1927Details

1928 

1929Allow UDP over the SOCKS5 listener when enabled.

1930 

1931Key

1932 

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

1934 

1935Type / Values

1936 

1937`boolean`

1938 

1939Details

1940 

1941Enable network access for this named permissions profile.

1942 

1943Key

1944 

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

1946 

1947Type / Values

1948 

1949`limited | full`

1950 

1951Details

1952 

1953Network proxy mode used for subprocess traffic.

1954 

1955Key

1956 

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

1958 

1959Type / Values

1960 

1961`string`

1962 

1963Details

1964 

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

1966 

1967Key

1968 

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

1970 

1971Type / Values

1972 

1973`string`

1974 

1975Details

1976 

1977SOCKS5 proxy endpoint used by this permissions profile.

1978 

1979Key

1980 

1487`personality`1981`personality`

1488 1982 

1489Type / Values1983Type / Values

1496 1990 

1497Key1991Key

1498 1992 

1993`plan_mode_reasoning_effort`

1994 

1995Type / Values

1996 

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

1998 

1999Details

2000 

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

2002 

2003Key

2004 

1499`profile`2005`profile`

1500 2006 

1501Type / Values2007Type / Values

1520 2026 

1521Key2027Key

1522 2028 

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

1524 2030 

1525Type / Values2031Type / Values

1526 2032 

1528 2034 

1529Details2035Details

1530 2036 

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

1532 2038 

1533Key2039Key

1534 2040 

1544 2050 

1545Key2051Key

1546 2052 

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

1548 2054 

1549Type / Values2055Type / Values

1550 2056 

1551`boolean`2057`string (path)`

1552 2058 

1553Details2059Details

1554 2060 

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

2062 

2063Key

2064 

2065`profiles.<name>.model_instructions_file`

2066 

2067Type / Values

2068 

2069`string (path)`

2070 

2071Details

2072 

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

1556 2074 

1557Key2075Key

1558 2076 

1580 2098 

1581Key2099Key

1582 2100 

2101`profiles.<name>.plan_mode_reasoning_effort`

2102 

2103Type / Values

2104 

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

2106 

2107Details

2108 

2109Profile-scoped Plan-mode reasoning override.

2110 

2111Key

2112 

2113`profiles.<name>.service_tier`

2114 

2115Type / Values

2116 

2117`flex | fast`

2118 

2119Details

2120 

2121Profile-scoped service tier preference for new turns.

2122 

2123Key

2124 

2125`profiles.<name>.tools_view_image`

2126 

2127Type / Values

2128 

2129`boolean`

2130 

2131Details

2132 

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

2134 

2135Key

2136 

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

1584 2138 

1585Type / Values2139Type / Values

1592 2146 

1593Key2147Key

1594 2148 

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

2150 

2151Type / Values

2152 

2153`unelevated | elevated`

2154 

2155Details

2156 

2157Profile-scoped Windows sandbox mode override.

2158 

2159Key

2160 

1595`project_doc_fallback_filenames`2161`project_doc_fallback_filenames`

1596 2162 

1597Type / Values2163Type / Values

1712 2278 

1713Key2279Key

1714 2280 

2281`service_tier`

2282 

2283Type / Values

2284 

2285`flex | fast`

2286 

2287Details

2288 

2289Preferred service tier for new turns.

2290 

2291Key

2292 

1715`shell_environment_policy.exclude`2293`shell_environment_policy.exclude`

1716 2294 

1717Type / Values2295Type / Values

1832 2410 

1833Key2411Key

1834 2412 

2413`sqlite_home`

2414 

2415Type / Values

2416 

2417`string (path)`

2418 

2419Details

2420 

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

2422 

2423Key

2424 

1835`suppress_unstable_features_warning`2425`suppress_unstable_features_warning`

1836 2426 

1837Type / Values2427Type / Values

1856 2446 

1857Key2447Key

1858 2448 

1859`tools.web_search`2449`tools.view_image`

1860 2450 

1861Type / Values2451Type / Values

1862 2452 

1864 2454 

1865Details2455Details

1866 2456 

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

2458 

2459Key

2460 

2461`tools.web_search`

2462 

2463Type / Values

2464 

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

2466 

2467Details

2468 

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

1868 2470 

1869Key2471Key

1870 2472 

1904 2506 

1905Key2507Key

1906 2508 

2509`tui.model_availability_nux.<model>`

2510 

2511Type / Values

2512 

2513`integer`

2514 

2515Details

2516 

2517Internal startup-tooltip state keyed by model slug.

2518 

2519Key

2520 

1907`tui.notification_method`2521`tui.notification_method`