config-reference.md Codex Docs, 2026-02-23 18:27 UTC → 2026-03-17 18:24 UTC

6 6 

7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.

8 8 

9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).

10 10 

11| Key | Type / Values | Details |11| Key | Type / Values | Details |

12| --- | --- | --- |12| --- | --- | --- |

13| `agents.<name>.config_file` | `string (path)` | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |13| `agents.<name>.config_file` | `string (path)` | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |

14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |

15| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |

16| `approval_policy` | `untrusted | on-request | never` | Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |16| `agents.job_max_runtime_seconds` | `number` | Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker. |

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

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

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

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

21| `approval_policy` | `untrusted | on-request | never | { 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). |

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

37| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |58| `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). |59| `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). |60| `features.remote_models` | `boolean` | Legacy toggle for an older remote-model readiness flow. Current builds do not use it. |

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

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

63| `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). |64| `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). |65| `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). |66| `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). |67| `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). |68| `features.skill_env_var_dependency_prompt` | `boolean` | Prompt for missing skill environment-variable dependencies (under development). |

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

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

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

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

73| `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). |74| `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. |75| `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"`. |76| `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. |82| `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. |83| `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. |84| `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`. |85| `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`. |86| `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. |87| `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_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. |89| `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. |90| `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. |91| `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. |98| `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. |99| `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. |100| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |

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

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

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

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

127| `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). |128| `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. |129| `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. |130| `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`). |131| `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. |132| `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. |133| `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. |134| `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. |146| `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. |147| `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. |148| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

197| `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. |198| `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. |199| `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. |200| `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. |205| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |

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

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

211| `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. |212| `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. |213| `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). |214| `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). |215| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

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

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

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

164 225 

165Key226Key

166 227 

188 249 

189Key250Key

190 251 

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

192 253 

193Type / Values254Type / Values

194 255 

195`number`256`array<string>`

196 257 

197Details258Details

198 259 

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

200 261 

201Key262Key

202 263 

203`approval_policy`264`agents.job_max_runtime_seconds`

204 265 

205Type / Values266Type / Values

206 267 

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

208 269 

209Details270Details

210 271 

211Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.272Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.

212 273 

213Key274Key

214 275 

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

216 277 

217Type / Values278Type / Values

218 279 

219`unknown | user`280`number`

220 281 

221Details282Details

222 283 

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

224 285 

225Key286Key

226 287 

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

228 289 

229Type / Values290Type / Values

230 291 

231`boolean`292`number`

232 293 

233Details294Details

234 295 

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

236 297 

237Key298Key

238 299 

239`chatgpt_base_url`300`allow_login_shell`

240 301 

241Type / Values302Type / Values

242 303 

243`string`304`boolean`

244 305 

245Details306Details

246 307 

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

249Key310Key

250 311 

251`check_for_update_on_startup`312`analytics.enabled`

252 313 

253Type / Values314Type / Values

254 315 

256 317 

257Details318Details

258 319 

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

260 321 

261Key322Key

262 323 

263`cli_auth_credentials_store`324`approval_policy`

264 325 

265Type / Values326Type / Values

266 327 

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

268 329 

269Details330Details

270 331 

271Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).332Controls 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 333 

273Key334Key

274 335 

275`compact_prompt`336`approval_policy.reject.mcp_elicitations`

276 337 

277Type / Values338Type / Values

278 339 

279`string`340`boolean`

280 341 

281Details342Details

282 343 

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

284 345 

285Key346Key

286 347 

287`developer_instructions`348`approval_policy.reject.rules`

288 349 

289Type / Values350Type / Values

290 351 

291`string`352`boolean`

292 353 

293Details354Details

294 355 

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

296 357 

297Key358Key

298 359 

299`disable_paste_burst`360`approval_policy.reject.sandbox_approval`

300 361 

301Type / Values362Type / Values

302 363 

304 365 

305Details366Details

306 367 

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

308 369 

309Key370Key

310 371 

311`experimental_compact_prompt_file`372`apps._default.destructive_enabled`

312 373 

313Type / Values374Type / Values

314 375 

315`string (path)`376`boolean`

316 377 

317Details378Details

318 379 

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

320 381 

321Key382Key

322 383 

323`experimental_use_freeform_apply_patch`384`apps._default.enabled`

324 385 

325Type / Values386Type / Values

326 387 

328 389 

329Details390Details

330 391 

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

332 393 

333Key394Key

334 395 

335`experimental_use_unified_exec_tool`396`apps._default.open_world_enabled`

336 397 

337Type / Values398Type / Values

338 399 

340 401 

341Details402Details

342 403 

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

344 405 

345Key406Key

346 407 

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

348 409 

349Type / Values410Type / Values

350 411 

351`boolean`412`auto | prompt | approve`

352 413 

353Details414Details

354 415 

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

356 417 

357Key418Key

358 419 

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

360 421 

361Type / Values422Type / Values

362 423 

364 425 

365Details426Details

366 427 

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

368 429 

369Key430Key

370 431 

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

372 433 

373Type / Values434Type / Values

374 435 

376 437 

377Details438Details

378 439 

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

380 441 

381Key442Key

382 443 

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

384 445 

385Type / Values446Type / Values

386 447 

388 449 

389Details450Details

390 451 

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

392 453 

393Key454Key

394 455 

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

396 457 

397Type / Values458Type / Values

398 459 

400 461 

401Details462Details

402 463 

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

404 465 

405Key466Key

406 467 

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

408 469 

409Type / Values470Type / Values

410 471 

411`boolean`472`auto | prompt | approve`

412 473 

413Details474Details

414 475 

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

416 477 

417Key478Key

418 479 

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

420 481 

421Type / Values482Type / Values

422 483 

424 485 

425Details486Details

426 487 

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

428 489 

429Key490Key

430 491 

431`features.multi_agent`492`background_terminal_max_timeout`

432 493 

433Type / Values494Type / Values

434 495 

435`boolean`496`number`

436 497 

437Details498Details

438 499 

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

440 501 

441Key502Key

442 503 

443`features.personality`504`chatgpt_base_url`

444 505 

445Type / Values506Type / Values

446 507 

447`boolean`508`string`

448 509 

449Details510Details

450 511 

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

452 513 

453Key514Key

454 515 

455`features.powershell_utf8`516`check_for_update_on_startup`

456 517 

457Type / Values518Type / Values

458 519 

460 521 

461Details522Details

462 523 

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

464 525 

465Key526Key

466 527 

467`features.remote_models`528`cli_auth_credentials_store`

468 529 

469Type / Values530Type / Values

470 531 

471`boolean`532`file | keyring | auto`

472 533 

473Details534Details

474 535 

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

476 537 

477Key538Key

478 539 

479`features.request_rule`540`commit_attribution`

480 541 

481Type / Values542Type / Values

482 543 

483`boolean`544`string`

484 545 

485Details546Details

486 547 

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

488 549 

489Key550Key

490 551 

491`features.runtime_metrics`552`compact_prompt`

492 553 

493Type / Values554Type / Values

494 555 

495`boolean`556`string`

496 557 

497Details558Details

498 559 

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

500 561 

501Key562Key

502 563 

503`features.search_tool`564`developer_instructions`

504 565 

505Type / Values566Type / Values

506 567 

507`boolean`568`string`

508 569 

509Details570Details

510 571 

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

512 573 

513Key574Key

514 575 

515`features.shell_snapshot`576`disable_paste_burst`

516 577 

517Type / Values578Type / Values

518 579 

520 581 

521Details582Details

522 583 

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

524 585 

525Key586Key

526 587 

527`features.shell_tool`588`experimental_compact_prompt_file`

528 589 

529Type / Values590Type / Values

530 591 

531`boolean`592`string (path)`

532 593 

533Details594Details

534 595 

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

536 597 

537Key598Key

538 599 

539`features.unified_exec`600`experimental_use_unified_exec_tool`

540 601 

541Type / Values602Type / Values

542 603 

544 605 

545Details606Details

546 607 

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

548 609 

549Key610Key

550 611 

551`features.use_linux_sandbox_bwrap`612`features.apps`

552 613 

553Type / Values614Type / Values

554 615 

556 617 

557Details618Details

558 619 

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

560 621 

561Key622Key

562 623 

563`features.web_search`624`features.apps_mcp_gateway`

564 625 

565Type / Values626Type / Values

566 627 

568 629 

569Details630Details

570 631 

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

572 633 

573Key634Key

574 635 

575`features.web_search_cached`636`features.artifact`

576 637 

577Type / Values638Type / Values

578 639 

580 641 

581Details642Details

582 643 

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

584 645 

585Key646Key

586 647 

587`features.web_search_request`648`features.child_agents_md`

588 649 

589Type / Values650Type / Values

590 651 

592 653 

593Details654Details

594 655 

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

596 657 

597Key658Key

598 659 

599`feedback.enabled`660`features.collaboration_modes`

600 661 

601Type / Values662Type / Values

602 663 

604 665 

605Details666Details

606 667 

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

608 669 

609Key670Key

610 671 

611`file_opener`672`features.default_mode_request_user_input`

612 673 

613Type / Values674Type / Values

614 675 

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

616 677 

617Details678Details

618 679 

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

620 681 

621Key682Key

622 683 

623`forced_chatgpt_workspace_id`684`features.elevated_windows_sandbox`

624 685 

625Type / Values686Type / Values

626 687 

627`string (uuid)`688`boolean`

628 689 

629Details690Details

630 691 

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

632 693 

633Key694Key

634 695 

635`forced_login_method`696`features.enable_request_compression`

636 697 

637Type / Values698Type / Values

638 699 

639`chatgpt | api`700`boolean`

640 701 

641Details702Details

642 703 

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

644 705 

645Key706Key

646 707 

647`hide_agent_reasoning`708`features.experimental_windows_sandbox`

648 709 

649Type / Values710Type / Values

650 711 

652 713 

653Details714Details

654 715 

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

656 717 

657Key718Key

658 719 

659`history.max_bytes`720`features.fast_mode`

660 721 

661Type / Values722Type / Values

662 723 

663`number`724`boolean`

664 725 

665Details726Details

666 727 

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

668 729 

669Key730Key

670 731 

671`history.persistence`732`features.image_detail_original`

672 733 

673Type / Values734Type / Values

674 735 

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

676 737 

677Details738Details

678 739 

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

680 741 

681Key742Key

682 743 

683`include_apply_patch_tool`744`features.image_generation`

684 745 

685Type / Values746Type / Values

686 747 

688 749 

689Details750Details

690 751 

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

692 753 

693Key754Key

694 755 

695`instructions`756`features.personality`

696 757 

697Type / Values758Type / Values

698 759 

699`string`760`boolean`

700 761 

701Details762Details

702 763 

703Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.764Enable personality selection controls (stable; on by default).

704 765 

705Key766Key

706 767 

707`log_dir`768`features.powershell_utf8`

708 769 

709Type / Values770Type / Values

710 771 

711`string (path)`772`boolean`

712 773 

713Details774Details

714 775 

715Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.776Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.

716 777 

717Key778Key

718 779 

719`mcp_oauth_callback_port`780`features.prevent_idle_sleep`

720 781 

721Type / Values782Type / Values

722 783 

723`integer`784`boolean`

724 785 

725Details786Details

726 787 

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.788Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

728 789 

729Key790Key

730 791 

731`mcp_oauth_credentials_store`792`features.remote_models`

732 793 

733Type / Values794Type / Values

734 795 

735`auto | file | keyring`796`boolean`

736 797 

737Details798Details

738 799 

739Preferred store for MCP OAuth credentials.800Legacy toggle for an older remote-model readiness flow. Current builds do not use it.

740 801 

741Key802Key

742 803 

743`mcp_servers.<id>.args`804`features.request_rule`

744 805 

745Type / Values806Type / Values

746 807 

747`array<string>`808`boolean`

748 809 

749Details810Details

750 811 

751Arguments passed to the MCP stdio server command.812Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.

752 813 

753Key814Key

754 815 

755`mcp_servers.<id>.bearer_token_env_var`816`features.responses_websockets`

756 817 

757Type / Values818Type / Values

758 819 

759`string`820`boolean`

760 821 

761Details822Details

762 823 

763Environment variable sourcing the bearer token for an MCP HTTP server.824Prefer the Responses API WebSocket transport for supported providers (under development).

764 825 

765Key826Key

766 827 

767`mcp_servers.<id>.command`828`features.responses_websockets_v2`

768 829 

769Type / Values830Type / Values

770 831 

771`string`832`boolean`

772 833 

773Details834Details

774 835 

775Launcher command for an MCP stdio server.836Enable Responses API WebSocket v2 mode (under development).

776 837 

777Key838Key

778 839 

779`mcp_servers.<id>.cwd`840`features.runtime_metrics`

780 841 

781Type / Values842Type / Values

782 843 

783`string`844`boolean`

784 845 

785Details846Details

786 847 

787Working directory for the MCP stdio server process.848Show runtime metrics summary in TUI turn separators (experimental).

788 849 

789Key850Key

790 851 

791`mcp_servers.<id>.disabled_tools`852`features.search_tool`

792 853 

793Type / Values854Type / Values

794 855 

795`array<string>`856`boolean`

796 857 

797Details858Details

798 859 

799Deny list applied after `enabled_tools` for the MCP server.860Legacy toggle for an older Apps discovery flow. Current builds do not use it.

800 861 

801Key862Key

802 863 

803`mcp_servers.<id>.enabled`864`features.shell_snapshot`

804 865 

805Type / Values866Type / Values

806 867 

808 869 

809Details870Details

810 871 

811Disable an MCP server without removing its configuration.872Snapshot shell environment to speed up repeated commands (stable; on by default).

812 873 

813Key874Key

814 875 

815`mcp_servers.<id>.enabled_tools`876`features.shell_tool`

816 877 

817Type / Values878Type / Values

818 879 

819`array<string>`880`boolean`

820 881 

821Details882Details

822 883 

823Allow list of tool names exposed by the MCP server.884Enable the default `shell` tool for running commands (stable; on by default).

824 885 

825Key886Key

826 887 

827`mcp_servers.<id>.env`888`features.skill_env_var_dependency_prompt`

828 889 

829Type / Values890Type / Values

830 891 

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

832 893 

833Details894Details

834 895 

835Environment variables forwarded to the MCP stdio server.896Prompt for missing skill environment-variable dependencies (under development).

836 897 

837Key898Key

838 899 

839`mcp_servers.<id>.env_http_headers`900`features.skill_mcp_dependency_install`

840 901 

841Type / Values902Type / Values

842 903 

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

844 905 

845Details906Details

846 907 

847HTTP headers populated from environment variables for an MCP HTTP server.908Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

848 909 

849Key910Key

850 911 

851`mcp_servers.<id>.env_vars`912`features.sqlite`

852 913 

853Type / Values914Type / Values

854 915 

855`array<string>`916`boolean`

856 917 

857Details918Details

858 919 

859Additional environment variables to whitelist for an MCP stdio server.920Enable SQLite-backed state persistence (stable; on by default).

860 921 

861Key922Key

862 923 

863`mcp_servers.<id>.http_headers`924`features.steer`

864 925 

865Type / Values926Type / Values

866 927 

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

868 929 

869Details930Details

870 931 

871Static HTTP headers included with each MCP HTTP request.932Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.

872 933 

873Key934Key

874 935 

875`mcp_servers.<id>.required`936`features.undo`

876 937 

877Type / Values938Type / Values

878 939 

880 941 

881Details942Details

882 943 

883When true, fail startup/resume if this enabled MCP server cannot initialize.944Enable undo support (stable; off by default).

884 945 

885Key946Key

886 947 

887`mcp_servers.<id>.startup_timeout_ms`948`features.unified_exec`

888 949 

889Type / Values950Type / Values

890 951 

891`number`952`boolean`

892 953 

893Details954Details

894 955 

895Alias for `startup_timeout_sec` in milliseconds.956Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

896 957 

897Key958Key

898 959 

899`mcp_servers.<id>.startup_timeout_sec`960`features.use_linux_sandbox_bwrap`

900 961 

901Type / Values962Type / Values

902 963 

903`number`964`boolean`

904 965 

905Details966Details

906 967 

907Override the default 10s startup timeout for an MCP server.968Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).

908 969 

909Key970Key

910 971 

911`mcp_servers.<id>.tool_timeout_sec`972`features.web_search`

912 973 

913Type / Values974Type / Values

914 975 

915`number`976`boolean`

916 977 

917Details978Details

918 979 

919Override the default 60s per-tool timeout for an MCP server.980Deprecated legacy toggle; prefer the top-level `web_search` setting.

920 981 

921Key982Key

922 983 

923`mcp_servers.<id>.url`984`features.web_search_cached`

924 985 

925Type / Values986Type / Values

926 987 

927`string`988`boolean`

928 989 

929Details990Details

930 991 

931Endpoint for an MCP streamable HTTP server.992Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.

932 993 

933Key994Key

934 995 

935`model`996`features.web_search_request`

936 997 

937Type / Values998Type / Values

938 999 

939`string`1000`boolean`

940 1001 

941Details1002Details

942 1003 

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

944 1005 

945Key1006Key

946 1007 

947`model_auto_compact_token_limit`1008`feedback.enabled`