config-reference.md Codex Docs, 2026-02-23 18:27 UTC → 2026-04-02 18:23 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.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-codex`). |

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

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`

972 1226 

973Type / Values1227Type / Values

974 1228 

975`string (path)`1229`number`

1230 

1231Details

1232 

1233Context window tokens available to the active model.

1234 

1235Key

1236 

1237`model_instructions_file`

1238 

1239Type / Values

1240 

1241`string (path)`

976 1242 

977Details1243Details

978 1244 

1128 1394 

1129Type / Values1395Type / Values

1130 1396 

1131`number`1397`number`

1398 

1399Details

1400 

1401Retry count for SSE streaming interruptions (default: 5).

1402 

1403Key

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 

1417`model_providers.<id>.wire_api`

1418 

1419Type / Values

1420 

1421`responses`

1422 

1423Details

1424 

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

1426 

1427Key

1428 

1429`model_reasoning_effort`

1430 

1431Type / Values

1432 

1433`minimal | low | medium | high | xhigh`

1434 

1435Details

1436 

1437Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).

1438 

1439Key

1440 

1441`model_reasoning_summary`

1442 

1443Type / Values

1444 

1445`auto | concise | detailed | none`

1446 

1447Details

1448 

1449Select reasoning summary detail or disable summaries entirely.

1450 

1451Key

1452 

1453`model_supports_reasoning_summaries`

1454 

1455Type / Values

1456 

1457`boolean`

1458 

1459Details

1460 

1461Force Codex to send or not send reasoning metadata.

1462 

1463Key

1464 

1465`model_verbosity`

1466 

1467Type / Values

1468 

1469`low | medium | high`

1470 

1471Details

1472 

1473Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.

1474 

1475Key

1476 

1477`notice.hide_full_access_warning`

1478 

1479Type / Values

1480 

1481`boolean`

1482 

1483Details

1484 

1485Track acknowledgement of the full access warning prompt.

1486 

1487Key

1488 

1489`notice.hide_gpt-5.1-codex-max_migration_prompt`

1490 

1491Type / Values

1492 

1493`boolean`

1494 

1495Details

1496 

1497Track acknowledgement of the gpt-5.1-codex-max migration prompt.

1498 

1499Key

1500 

1501`notice.hide_gpt5_1_migration_prompt`

1502 

1503Type / Values

1504 

1505`boolean`

1506 

1507Details

1508 

1509Track acknowledgement of the GPT-5.1 migration prompt.

1510 

1511Key

1512 

1513`notice.hide_rate_limit_model_nudge`

1514 

1515Type / Values

1516 

1517`boolean`

1518 

1519Details

1520 

1521Track opt-out of the rate limit model switch reminder.

1522 

1523Key

1524 

1525`notice.hide_world_writable_warning`

1526 

1527Type / Values

1528 

1529`boolean`

1530 

1531Details

1532 

1533Track acknowledgement of the Windows world-writable directories warning.

1534 

1535Key

1536 

1537`notice.model_migrations`

1538 

1539Type / Values

1540 

1541`map<string,string>`

1542 

1543Details

1544 

1545Track acknowledged model migrations as old->new mappings.

1546 

1547Key

1548 

1549`notify`

1550 

1551Type / Values

1552 

1553`array<string>`

1554 

1555Details

1556 

1557Command invoked for notifications; receives a JSON payload from Codex.

1558 

1559Key

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 

1573`oss_provider`

1574 

1575Type / Values

1576 

1577`lmstudio | ollama`

1578 

1579Details

1580 

1581Default local provider used when running with `--oss` (defaults to prompting if unset).

1582 

1583Key

1584 

1585`otel.environment`

1586 

1587Type / Values

1588 

1589`string`

1590 

1591Details

1592 

1593Environment tag applied to emitted OpenTelemetry events (default: `dev`).

1594 

1595Key

1596 

1597`otel.exporter`

1598 

1599Type / Values

1600 

1601`none | otlp-http | otlp-grpc`

1602 

1603Details

1604 

1605Select the OpenTelemetry exporter and provide any endpoint metadata.

1606 

1607Key

1608 

1609`otel.exporter.<id>.endpoint`

1610 

1611Type / Values

1612 

1613`string`

1614 

1615Details

1616 

1617Exporter endpoint for OTEL logs.

1618 

1619Key

1620 

1621`otel.exporter.<id>.headers`

1622 

1623Type / Values

1624 

1625`map<string,string>`

1626 

1627Details

1628 

1629Static headers included with OTEL exporter requests.

1630 

1631Key

1632 

1633`otel.exporter.<id>.protocol`

1634 

1635Type / Values

1636 

1637`binary | json`

1638 

1639Details

1640 

1641Protocol used by the OTLP/HTTP exporter.

1642 

1643Key

1644 

1645`otel.exporter.<id>.tls.ca-certificate`

1646 

1647Type / Values

1648 

1649`string`

1650 

1651Details

1652 

1653CA certificate path for OTEL exporter TLS.

1654 

1655Key

1656 

1657`otel.exporter.<id>.tls.client-certificate`

1658 

1659Type / Values

1660 

1661`string`

1662 

1663Details

1664 

1665Client certificate path for OTEL exporter TLS.

1666 

1667Key

1668 

1669`otel.exporter.<id>.tls.client-private-key`

1670 

1671Type / Values

1672 

1673`string`

1674 

1675Details

1676 

1677Client private key path for OTEL exporter TLS.

1678 

1679Key

1680 

1681`otel.log_user_prompt`

1682 

1683Type / Values

1684 

1685`boolean`

1686 

1687Details

1688 

1689Opt in to exporting raw user prompts with OpenTelemetry logs.

1690 

1691Key

1692 

1693`otel.metrics_exporter`

1694 

1695Type / Values

1696 

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

1132 1698 

1133Details1699Details

1134 1700 

1135Retry count for SSE streaming interruptions (default: 5).1701Select the OpenTelemetry metrics exporter (defaults to `statsig`).

1136 1702 

1137Key1703Key

1138 1704 

1139`model_providers.<id>.wire_api`1705`otel.trace_exporter`

1140 1706 

1141Type / Values1707Type / Values

1142 1708 

1143`chat | responses`1709`none | otlp-http | otlp-grpc`

1144 1710 

1145Details1711Details

1146 1712 

1147Protocol used by the provider (defaults to `chat` if omitted).1713Select the OpenTelemetry trace exporter and provide any endpoint metadata.

1148 1714 

1149Key1715Key

1150 1716 

1151`model_reasoning_effort`1717`otel.trace_exporter.<id>.endpoint`

1152 1718 

1153Type / Values1719Type / Values

1154 1720 

1155`minimal | low | medium | high | xhigh`1721`string`

1156 1722 

1157Details1723Details

1158 1724 

1159Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).1725Trace exporter endpoint for OTEL logs.

1160 1726 

1161Key1727Key

1162 1728 

1163`model_reasoning_summary`1729`otel.trace_exporter.<id>.headers`

1164 1730 

1165Type / Values1731Type / Values

1166 1732 

1167`auto | concise | detailed | none`1733`map<string,string>`

1168 1734 

1169Details1735Details

1170 1736 

1171Select reasoning summary detail or disable summaries entirely.1737Static headers included with OTEL trace exporter requests.

1172 1738 

1173Key1739Key

1174 1740 

1175`model_supports_reasoning_summaries`1741`otel.trace_exporter.<id>.protocol`

1176 1742 

1177Type / Values1743Type / Values

1178 1744 

1179`boolean`1745`binary | json`

1180 1746 

1181Details1747Details

1182 1748 

1183Force Codex to send or not send reasoning metadata.1749Protocol used by the OTLP/HTTP trace exporter.

1184 1750 

1185Key1751Key

1186 1752 

1187`model_verbosity`1753`otel.trace_exporter.<id>.tls.ca-certificate`

1188 1754 

1189Type / Values1755Type / Values

1190 1756 

1191`low | medium | high`1757`string`

1192 1758 

1193Details1759Details

1194 1760 

1195Control GPT-5 Responses API verbosity (defaults to `medium`).1761CA certificate path for OTEL trace exporter TLS.

1196 1762 

1197Key1763Key

1198 1764 

1199`notice.hide_full_access_warning`1765`otel.trace_exporter.<id>.tls.client-certificate`

1200 1766 

1201Type / Values1767Type / Values

1202 1768 

1203`boolean`1769`string`

1204 1770 

1205Details1771Details

1206 1772 

1207Track acknowledgement of the full access warning prompt.1773Client certificate path for OTEL trace exporter TLS.

1208 1774 

1209Key1775Key

1210 1776 

1211`notice.hide_gpt-5.1-codex-max_migration_prompt`1777`otel.trace_exporter.<id>.tls.client-private-key`

1212 1778 

1213Type / Values1779Type / Values

1214 1780 

1215`boolean`1781`string`

1216 1782 

1217Details1783Details

1218 1784 

1219Track acknowledgement of the gpt-5.1-codex-max migration prompt.1785Client private key path for OTEL trace exporter TLS.

1220 1786 

1221Key1787Key

1222 1788 

1223`notice.hide_gpt5_1_migration_prompt`1789`permissions.<name>.filesystem`

1224 1790 

1225Type / Values1791Type / Values

1226 1792 

1227`boolean`1793`table`

1228 1794 

1229Details1795Details

1230 1796 

1231Track acknowledgement of the GPT-5.1 migration prompt.1797Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.

1232 1798 

1233Key1799Key

1234 1800 

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

1236 1802 

1237Type / Values1803Type / Values

1238 1804 

1239`boolean`1805`"read" | "write" | "none"`

1240 1806 

1241Details1807Details

1242 1808 

1243Track opt-out of the rate limit model switch reminder.1809Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself.

1244 1810 

1245Key1811Key

1246 1812 

1247`notice.hide_world_writable_warning`1813`permissions.<name>.filesystem.<path>`

1248 1814 

1249Type / Values1815Type / Values

1250 1816 

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

1252 1818 

1253Details1819Details

1254 1820 

1255Track acknowledgement of the Windows world-writable directories warning.1821Grant direct access for a path or special token, or scope nested entries under that root.

1256 1822 

1257Key1823Key

1258 1824