config-reference.md Codex Docs, 2026-02-23 18:27 UTC → 2026-03-16 18:25 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 | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |

22| `approval_policy.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |

23| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |

24| `approval_policy.reject.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are auto-rejected. |

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

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

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

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

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

30| `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). |31| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |

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

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

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

35| `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. |36| `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). |37| `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). |38| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |

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

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

24| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |42| `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). |43| `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`. |44| `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). |45| `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). |46| `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). |

47| `features.artifact` | `boolean` | Enable native artifact tools such as slides and spreadsheets (under development). |

31| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |48| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |

32| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |49| `features.collaboration_modes` | `boolean` | Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key. |

33| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |50| `features.default_mode_request_user_input` | `boolean` | Allow `request_user_input` in default collaboration mode (under development; off by default). |

34| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |51| `features.elevated_windows_sandbox` | `boolean` | Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it. |

35| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

53| `features.experimental_windows_sandbox` | `boolean` | Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it. |

54| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |

55| `features.image_detail_original` | `boolean` | Allow image outputs with `detail = "original"` on supported models (under development). |

56| `features.image_generation` | `boolean` | Enable the built-in image generation tool (under development). |

57| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default). |

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

37| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |59| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere. |

38| `features.remote_models` | `boolean` | Refresh remote model list before showing readiness (experimental). |60| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |

39| `features.request_rule` | `boolean` | Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default). |61| `features.remote_models` | `boolean` | Legacy toggle for an older remote-model readiness flow. Current builds do not use it. |

62| `features.request_rule` | `boolean` | Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset. |

63| `features.responses_websockets` | `boolean` | Prefer the Responses API WebSocket transport for supported providers (under development). |

64| `features.responses_websockets_v2` | `boolean` | Enable Responses API WebSocket v2 mode (under development). |

40| `features.runtime_metrics` | `boolean` | Show runtime metrics summary in TUI turn separators (experimental). |65| `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). |66| `features.search_tool` | `boolean` | Legacy toggle for an older Apps discovery flow. Current builds do not use it. |

42| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (beta). |67| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |

43| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |68| `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). |69| `features.skill_env_var_dependency_prompt` | `boolean` | Prompt for missing skill environment-variable dependencies (under development). |

70| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |

71| `features.sqlite` | `boolean` | Enable SQLite-backed state persistence (stable; on by default). |

72| `features.steer` | `boolean` | Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior. |

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

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

45| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |75| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |

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

53| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |83| `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. |84| `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. |85| `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`. |86| `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`. |87| `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. |88| `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. |

89| `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. |90| `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. |91| `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. |92| `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. |99| `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. |100| `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. |101| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |

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

104| `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. |105| `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. |106| `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. |107| `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. |108| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |

77| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |109| `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). |110| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |

111| `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. |112| `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`. |113| `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`). |114| `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). |124| `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). |125| `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). |126| `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). |127| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

128| `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). |129| `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. |130| `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. |131| `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`). |132| `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. |133| `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. |134| `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. |135| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |

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

150| `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. |151| `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. |152| `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. |153| `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. |155| `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. |156| `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. |157| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |

158| `permissions.network.admin_url` | `string` | Admin endpoint for the managed network proxy. |

159| `permissions.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

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

161| `permissions.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

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

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

164| `permissions.network.dangerously_allow_non_loopback_admin` | `boolean` | Permit non-loopback bind addresses for the managed proxy admin listener. |

165| `permissions.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

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

167| `permissions.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener from the managed network proxy. |

168| `permissions.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

169| `permissions.network.enabled` | `boolean` | Enable the managed network proxy configuration for subprocesses. |

170| `permissions.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |

171| `permissions.network.proxy_url` | `string` | HTTP proxy endpoint used by the managed network proxy. |

172| `permissions.network.socks_url` | `string` | SOCKS5 proxy endpoint used by the managed network proxy. |

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

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

125| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |176| `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`. |177| `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`. |178| `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`. |179| `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). |

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

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

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

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

187| `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. |188| `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. |189| `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. |190| `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. |195| `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. |196| `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"`. |197| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |

198| `service_tier` | `flex | fast` | Preferred service tier for new turns. `fast` is honored only when the `features.fast_mode` gate is enabled. |

142| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |199| `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. |200| `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. |201| `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. |206| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |

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

209| `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. |210| `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. |211| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |

212| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |

154| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |213| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |

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

217| `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). |218| `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. |219| `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). |220| `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. |221| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

222| `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. |223| `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). |224| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

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

164 226 

165Key227Key

166 228 

188 250 

189Key251Key

190 252 

191`agents.max_threads`253`agents.<name>.nickname_candidates`

192 254 

193Type / Values255Type / Values

194 256 

195`number`257`array<string>`

196 258 

197Details259Details

198 260 

199Maximum number of agent threads that can be open concurrently.261Optional pool of display nicknames for spawned agents in that role.

200 262 

201Key263Key

202 264 

203`approval_policy`265`agents.job_max_runtime_seconds`

204 266 

205Type / Values267Type / Values

206 268 

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

208 270 

209Details271Details

210 272 

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.273Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.

212 274 

213Key275Key

214 276 

215`apps.<id>.disabled_reason`277`agents.max_depth`

216 278 

217Type / Values279Type / Values

218 280 

219`unknown | user`281`number`

220 282 

221Details283Details

222 284 

223Optional reason attached when an app/connector is disabled.285Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).

224 286 

225Key287Key

226 288 

227`apps.<id>.enabled`289`agents.max_threads`

228 290 

229Type / Values291Type / Values

230 292 

231`boolean`293`number`

232 294 

233Details295Details

234 296 

235Enable or disable a specific app/connector by id (default: true).297Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.

236 298 

237Key299Key

238 300 

239`chatgpt_base_url`301`allow_login_shell`

240 302 

241Type / Values303Type / Values

242 304 

243`string`305`boolean`

244 306 

245Details307Details

246 308 

247Override the base URL used during the ChatGPT login flow.309Allow 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.

248 310 

249Key311Key

250 312 

251`check_for_update_on_startup`313`analytics.enabled`

252 314 

253Type / Values315Type / Values

254 316 

256 318 

257Details319Details

258 320 

259Check for Codex updates on startup (set to false only when updates are centrally managed).321Enable or disable analytics for this machine/profile. When unset, the client default applies.

260 322 

261Key323Key

262 324 

263`cli_auth_credentials_store`325`approval_policy`

264 326 

265Type / Values327Type / Values

266 328 

267`file | keyring | auto`329`untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }`

268 330 

269Details331Details

270 332 

271Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).333Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.

272 334 

273Key335Key

274 336 

275`compact_prompt`337`approval_policy.reject.mcp_elicitations`

276 338 

277Type / Values339Type / Values

278 340 

279`string`341`boolean`

280 342 

281Details343Details

282 344 

283Inline override for the history compaction prompt.345When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.

284 346 

285Key347Key

286 348 

287`developer_instructions`349`approval_policy.reject.rules`

288 350 

289Type / Values351Type / Values

290 352 

291`string`353`boolean`

292 354 

293Details355Details

294 356 

295Additional developer instructions injected into the session (optional).357When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.

296 358 

297Key359Key

298 360 

299`disable_paste_burst`361`approval_policy.reject.sandbox_approval`

300 362 

301Type / Values363Type / Values

302 364 

304 366 

305Details367Details

306 368 

307Disable burst-paste detection in the TUI.369When `true`, sandbox escalation approval prompts are auto-rejected.

308 370 

309Key371Key

310 372 

311`experimental_compact_prompt_file`373`apps._default.destructive_enabled`

312 374 

313Type / Values375Type / Values

314 376 

315`string (path)`377`boolean`

316 378 

317Details379Details

318 380 

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

320 382 

321Key383Key

322 384 

323`experimental_use_freeform_apply_patch`385`apps._default.enabled`

324 386 

325Type / Values387Type / Values

326 388 

328 390 

329Details391Details

330 392 

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

332 394 

333Key395Key

334 396 

335`experimental_use_unified_exec_tool`397`apps._default.open_world_enabled`

336 398 

337Type / Values399Type / Values

338 400 

340 402 

341Details403Details

342 404 

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

344 406 

345Key407Key

346 408 

347`features.apply_patch_freeform`409`apps.<id>.default_tools_approval_mode`

348 410 

349Type / Values411Type / Values

350 412 

351`boolean`413`auto | prompt | approve`

352 414 

353Details415Details

354 416 

355Expose the freeform `apply_patch` tool (experimental).417Default approval behavior for tools in this app unless a per-tool override exists.

356 418 

357Key419Key

358 420 

359`features.apps`421`apps.<id>.default_tools_enabled`

360 422 

361Type / Values423Type / Values

362 424 

364 426 

365Details427Details

366 428 

367Enable ChatGPT Apps/connectors support (experimental).429Default enabled state for tools in this app unless a per-tool override exists.

368 430 

369Key431Key

370 432 

371`features.apps_mcp_gateway`433`apps.<id>.destructive_enabled`

372 434 

373Type / Values435Type / Values

374 436 

376 438 

377Details439Details

378 440 

379Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).441Allow or block tools in this app that advertise `destructive_hint = true`.

380 442 

381Key443Key

382 444 

383`features.child_agents_md`445`apps.<id>.enabled`

384 446 

385Type / Values447Type / Values

386 448 

388 450 

389Details451Details

390 452 

391Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).453Enable or disable a specific app/connector by id (default: true).

392 454 

393Key455Key

394 456 

395`features.collaboration_modes`457`apps.<id>.open_world_enabled`

396 458 

397Type / Values459Type / Values

398 460 

400 462 

401Details463Details

402 464 

403Enable collaboration modes such as plan mode (stable; on by default).465Allow or block tools in this app that advertise `open_world_hint = true`.

404 466 

405Key467Key

406 468 

407`features.elevated_windows_sandbox`469`apps.<id>.tools.<tool>.approval_mode`

408 470 

409Type / Values471Type / Values

410 472 

411`boolean`473`auto | prompt | approve`

412 474 

413Details475Details

414 476 

415Enable the elevated Windows sandbox pipeline (experimental).477Per-tool approval behavior override for a single app tool.

416 478 

417Key479Key

418 480 

419`features.experimental_windows_sandbox`481`apps.<id>.tools.<tool>.enabled`

420 482 

421Type / Values483Type / Values

422 484 

424 486 

425Details487Details

426 488 

427Run the Windows restricted-token sandbox (experimental).489Per-tool enabled override for an app tool (for example `repos/list`).

428 490 

429Key491Key

430 492 

431`features.multi_agent`493`background_terminal_max_timeout`

432 494 

433Type / Values495Type / Values

434 496 

435`boolean`497`number`

436 498 

437Details499Details

438 500 

439Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).501Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.

440 502 

441Key503Key

442 504 

443`features.personality`505`chatgpt_base_url`

444 506 

445Type / Values507Type / Values

446 508 

447`boolean`509`string`

448 510 

449Details511Details

450 512 

451Enable personality selection controls (stable; on by default).513Override the base URL used during the ChatGPT login flow.

452 514 

453Key515Key

454 516 

455`features.powershell_utf8`517`check_for_update_on_startup`

456 518 

457Type / Values519Type / Values

458 520 

460 522 

461Details523Details

462 524 

463Force PowerShell UTF-8 output (defaults to true).525Check for Codex updates on startup (set to false only when updates are centrally managed).

464 526 

465Key527Key

466 528 

467`features.remote_models`529`cli_auth_credentials_store`

468 530 

469Type / Values531Type / Values

470 532 

471`boolean`533`file | keyring | auto`

472 534 

473Details535Details

474 536 

475Refresh remote model list before showing readiness (experimental).537Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).

476 538 

477Key539Key

478 540 

479`features.request_rule`541`commit_attribution`

480 542 

481Type / Values543Type / Values

482 544 

483`boolean`545`string`

484 546 

485Details547Details

486 548 

487Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).549Override the commit co-author trailer text. Set an empty string to disable automatic attribution.

488 550 

489Key551Key

490 552 

491`features.runtime_metrics`553`compact_prompt`

492 554 

493Type / Values555Type / Values

494 556 

495`boolean`557`string`

496 558 

497Details559Details

498 560 

499Show runtime metrics summary in TUI turn separators (experimental).561Inline override for the history compaction prompt.

500 562 

501Key563Key

502 564 

503`features.search_tool`565`developer_instructions`

504 566 

505Type / Values567Type / Values

506 568 

507`boolean`569`string`

508 570 

509Details571Details

510 572 

511Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).573Additional developer instructions injected into the session (optional).

512 574 

513Key575Key

514 576 

515`features.shell_snapshot`577`disable_paste_burst`

516 578 

517Type / Values579Type / Values

518 580 

520 582 

521Details583Details

522 584 

523Snapshot shell environment to speed up repeated commands (beta).585Disable burst-paste detection in the TUI.

524 586 

525Key587Key

526 588 

527`features.shell_tool`589`experimental_compact_prompt_file`

528 590 

529Type / Values591Type / Values

530 592 

531`boolean`593`string (path)`

532 594 

533Details595Details

534 596 

535Enable the default `shell` tool for running commands (stable; on by default).597Load the compaction prompt override from a file (experimental).

536 598 

537Key599Key

538 600 

539`features.unified_exec`601`experimental_use_unified_exec_tool`

540 602 

541Type / Values603Type / Values

542 604 

544 606 

545Details607Details

546 608 

547Use the unified PTY-backed exec tool (beta).609Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

548 610 

549Key611Key

550 612 

551`features.use_linux_sandbox_bwrap`613`features.apps`

552 614 

553Type / Values615Type / Values

554 616 

556 618 

557Details619Details

558 620 

559Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).621Enable ChatGPT Apps/connectors support (experimental).

560 622 

561Key623Key

562 624 

563`features.web_search`625`features.apps_mcp_gateway`

564 626 

565Type / Values627Type / Values

566 628 

568 630 

569Details631Details

570 632 

571Deprecated legacy toggle; prefer the top-level `web_search` setting.633Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).

572 634 

573Key635Key

574 636 

575`features.web_search_cached`637`features.artifact`

576 638 

577Type / Values639Type / Values

578 640 

580 642 

581Details643Details

582 644 

583Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.645Enable native artifact tools such as slides and spreadsheets (under development).

584 646 

585Key647Key

586 648 

587`features.web_search_request`649`features.child_agents_md`

588 650 

589Type / Values651Type / Values

590 652 

592 654 

593Details655Details

594 656 

595Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.657Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).

596 658 

597Key659Key

598 660 

599`feedback.enabled`661`features.collaboration_modes`

600 662 

601Type / Values663Type / Values

602 664 

604 666 

605Details667Details

606 668 

607Enable feedback submission via `/feedback` across Codex surfaces (default: true).669Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key.

608 670 

609Key671Key

610 672 

611`file_opener`673`features.default_mode_request_user_input`

612 674 

613Type / Values675Type / Values

614 676 

615`vscode | vscode-insiders | windsurf | cursor | none`677`boolean`

616 678 

617Details679Details

618 680 

619URI scheme used to open citations from Codex output (default: `vscode`).681Allow `request_user_input` in default collaboration mode (under development; off by default).

620 682 

621Key683Key

622 684 

623`forced_chatgpt_workspace_id`685`features.elevated_windows_sandbox`

624 686 

625Type / Values687Type / Values

626 688 

627`string (uuid)`689`boolean`

628 690 

629Details691Details

630 692 

631Limit ChatGPT logins to a specific workspace identifier.693Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it.

632 694 

633Key695Key

634 696 

635`forced_login_method`697`features.enable_request_compression`

636 698 

637Type / Values699Type / Values

638 700 

639`chatgpt | api`701`boolean`

640 702 

641Details703Details

642 704 

643Restrict Codex to a specific authentication method.705Compress streaming request bodies with zstd when supported (stable; on by default).

644 706 

645Key707Key

646 708 

647`hide_agent_reasoning`709`features.experimental_windows_sandbox`

648 710 

649Type / Values711Type / Values

650 712 

652 714 

653Details715Details

654 716 

655Suppress reasoning events in both the TUI and `codex exec` output.717Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it.

656 718 

657Key719Key

658 720 

659`history.max_bytes`721`features.fast_mode`

660 722 

661Type / Values723Type / Values

662 724 

663`number`725`boolean`

664 726 

665Details727Details

666 728 

667If set, caps the history file size in bytes by dropping oldest entries.729Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

668 730 

669Key731Key

670 732 

671`history.persistence`733`features.image_detail_original`

672 734 

673Type / Values735Type / Values

674 736 

675`save-all | none`737`boolean`

676 738 

677Details739Details

678 740 

679Control whether Codex saves session transcripts to history.jsonl.741Allow image outputs with `detail = "original"` on supported models (under development).

680 742 

681Key743Key

682 744 

683`include_apply_patch_tool`745`features.image_generation`

684 746 

685Type / Values747Type / Values

686 748 

688 750 

689Details751Details

690 752 

691Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.753Enable the built-in image generation tool (under development).

692 754 

693Key755Key

694 756 

695`instructions`757`features.multi_agent`

696 758 

697Type / Values759Type / Values

698 760 

699`string`761`boolean`

700 762 

701Details763Details

702 764 

703Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.765Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default).

704 766 

705Key767Key

706 768 

707`log_dir`769`features.personality`

708 770 

709Type / Values771Type / Values

710 772 

711`string (path)`773`boolean`

712 774 

713Details775Details

714 776 

715Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.777Enable personality selection controls (stable; on by default).

716 778 

717Key779Key

718 780 

719`mcp_oauth_callback_port`781`features.powershell_utf8`

720 782 

721Type / Values783Type / Values

722 784 

723`integer`785`boolean`

724 786 

725Details787Details

726 788 

727Optional 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.789Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.

728 790 

729Key791Key

730 792 

731`mcp_oauth_credentials_store`793`features.prevent_idle_sleep`

732 794 

733Type / Values795Type / Values

734 796 

735`auto | file | keyring`797`boolean`

736 798 

737Details799Details

738 800 

739Preferred store for MCP OAuth credentials.801Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

740 802 

741Key803Key

742 804 

743`mcp_servers.<id>.args`805`features.remote_models`

744 806 

745Type / Values807Type / Values

746 808 

747`array<string>`809`boolean`

748 810 

749Details811Details

750 812 

751Arguments passed to the MCP stdio server command.813Legacy toggle for an older remote-model readiness flow. Current builds do not use it.

752 814 

753Key815Key

754 816 

755`mcp_servers.<id>.bearer_token_env_var`817`features.request_rule`

756 818 

757Type / Values819Type / Values

758 820 

759`string`821`boolean`

760 822 

761Details823Details

762 824 

763Environment variable sourcing the bearer token for an MCP HTTP server.825Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.

764 826 

765Key827Key

766 828 

767`mcp_servers.<id>.command`829`features.responses_websockets`

768 830 

769Type / Values831Type / Values

770 832 

771`string`833`boolean`

772 834 

773Details835Details

774 836 

775Launcher command for an MCP stdio server.837Prefer the Responses API WebSocket transport for supported providers (under development).

776 838 

777Key839Key

778 840 

779`mcp_servers.<id>.cwd`841`features.responses_websockets_v2`

780 842 

781Type / Values843Type / Values

782 844 

783`string`845`boolean`

784 846 

785Details847Details

786 848 

787Working directory for the MCP stdio server process.849Enable Responses API WebSocket v2 mode (under development).

788 850 

789Key851Key

790 852 

791`mcp_servers.<id>.disabled_tools`853`features.runtime_metrics`

792 854 

793Type / Values855Type / Values

794 856 

795`array<string>`857`boolean`

796 858 

797Details859Details

798 860 

799Deny list applied after `enabled_tools` for the MCP server.861Show runtime metrics summary in TUI turn separators (experimental).

800 862 

801Key863Key

802 864 

803`mcp_servers.<id>.enabled`865`features.search_tool`

804 866 

805Type / Values867Type / Values

806 868 

808 870 

809Details871Details

810 872 

811Disable an MCP server without removing its configuration.873Legacy toggle for an older Apps discovery flow. Current builds do not use it.

812 874 

813Key875Key

814 876 

815`mcp_servers.<id>.enabled_tools`877`features.shell_snapshot`

816 878 

817Type / Values879Type / Values

818 880 

819`array<string>`881`boolean`

820 882 

821Details883Details

822 884 

823Allow list of tool names exposed by the MCP server.885Snapshot shell environment to speed up repeated commands (stable; on by default).

824 886 

825Key887Key

826 888 

827`mcp_servers.<id>.env`889`features.shell_tool`

828 890 

829Type / Values891Type / Values

830 892 

831`map<string,string>`893`boolean`

832 894 

833Details895Details

834 896 

835Environment variables forwarded to the MCP stdio server.897Enable the default `shell` tool for running commands (stable; on by default).

836 898 

837Key899Key

838 900 

839`mcp_servers.<id>.env_http_headers`901`features.skill_env_var_dependency_prompt`

840 902 

841Type / Values903Type / Values

842 904 

843`map<string,string>`905`boolean`

844 906 

845Details907Details

846 908 

847HTTP headers populated from environment variables for an MCP HTTP server.909Prompt for missing skill environment-variable dependencies (under development).

848 910 

849Key911Key

850 912 

851`mcp_servers.<id>.env_vars`913`features.skill_mcp_dependency_install`

852 914 

853Type / Values915Type / Values

854 916 

855`array<string>`917`boolean`

856 918 

857Details919Details

858 920 

859Additional environment variables to whitelist for an MCP stdio server.921Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

860 922 

861Key923Key

862 924 

863`mcp_servers.<id>.http_headers`925`features.sqlite`

864 926 

865Type / Values927Type / Values

866 928 

867`map<string,string>`929`boolean`

868 930 

869Details931Details

870 932 

871Static HTTP headers included with each MCP HTTP request.933Enable SQLite-backed state persistence (stable; on by default).

872 934 

873Key935Key

874 936 

875`mcp_servers.<id>.required`937`features.steer`

876 938 

877Type / Values939Type / Values

878 940 

880 942 

881Details943Details

882 944 

883When true, fail startup/resume if this enabled MCP server cannot initialize.945Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.

884 946 

885Key947Key

886 948 

887`mcp_servers.<id>.startup_timeout_ms`949`features.undo`

888 950 

889Type / Values951Type / Values

890 952 

891`number`953`boolean`

892 954 

893Details955Details

894 956 

895Alias for `startup_timeout_sec` in milliseconds.957Enable undo support (stable; off by default).

896 958 

897Key959Key

898 960 

899`mcp_servers.<id>.startup_timeout_sec`961`features.unified_exec`

900 962 

901Type / Values963Type / Values

902 964 

903`number`965`boolean`

904 966 

905Details967Details

906 968 

907Override the default 10s startup timeout for an MCP server.969Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

908 970 

909Key971Key

910 972 

911`mcp_servers.<id>.tool_timeout_sec`973`features.use_linux_sandbox_bwrap`

912 974 

913Type / Values975Type / Values

914 976 

915`number`977`boolean`

916 978 

917Details979Details

918 980 

919Override the default 60s per-tool timeout for an MCP server.981Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).

920 982 

921Key983Key

922 984 

923`mcp_servers.<id>.url`985`features.web_search`

924 986 

925Type / Values987Type / Values

926 988 

927`string`989`boolean`

928 990 

929Details991Details

930 992 

931Endpoint for an MCP streamable HTTP server.993Deprecated legacy toggle; prefer the top-level `web_search` setting.

932 994 

933Key995Key

934 996 

935`model`997`features.web_search_cached`

936 998 

937Type / Values999Type / Values

938 1000 

939`string`1001`boolean`

940 1002 

941Details1003Details

942 1004 

943Model to use (e.g., `gpt-5-codex`).1005Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.

944 1006 

945Key1007Key

946 1008