config-reference.md Codex Docs, 2026-02-19 20:53 UTC → 2026-03-08 18:10 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/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 

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

10| --- | --- | --- |12| --- | --- | --- |

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

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

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

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

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

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

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

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

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

20| `compact_prompt` | `string` | Inline override for the history compaction prompt. |40| `compact_prompt` | `string` | Inline override for the history compaction prompt. |

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

22| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |42| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |

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

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

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

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

27| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |45| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

79| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |114| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

122| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |175| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

153| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |214| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

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

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

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

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

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

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

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

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

162 226 

163Key227Key

164 228 

186 250 

187Key251Key

188 252 

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

190 254 

191Type / Values255Type / Values

192 256 

193`number`257`array<string>`

194 258 

195Details259Details

196 260 

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

198 262 

199Key263Key

200 264 

201`approval_policy`265`agents.job_max_runtime_seconds`

202 266 

203Type / Values267Type / Values

204 268 

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

206 270 

207Details271Details

208 272 

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

210 274 

211Key275Key

212 276 

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

214 278 

215Type / Values279Type / Values

216 280 

217`unknown | user`281`number`

218 282 

219Details283Details

220 284 

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

222 286 

223Key287Key

224 288 

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

226 290 

227Type / Values291Type / Values

228 292 

229`boolean`293`number`

230 294 

231Details295Details

232 296 

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

234 298 

235Key299Key

236 300 

237`chatgpt_base_url`301`allow_login_shell`

238 302 

239Type / Values303Type / Values

240 304 

241`string`305`boolean`

242 306 

243Details307Details

244 308 

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

246 310 

247Key311Key

248 312 

249`check_for_update_on_startup`313`analytics.enabled`

250 314 

251Type / Values315Type / Values

252 316 

254 318 

255Details319Details

256 320 

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

258 322 

259Key323Key

260 324 

261`cli_auth_credentials_store`325`approval_policy`

262 326 

263Type / Values327Type / Values

264 328 

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

266 330 

267Details331Details

268 332 

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

270 334 

271Key335Key

272 336 

273`compact_prompt`337`approval_policy.reject.mcp_elicitations`

274 338 

275Type / Values339Type / Values

276 340 

277`string`341`boolean`

278 342 

279Details343Details

280 344 

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

282 346 

283Key347Key

284 348 

285`developer_instructions`349`approval_policy.reject.rules`

286 350 

287Type / Values351Type / Values

288 352 

289`string`353`boolean`

290 354 

291Details355Details

292 356 

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

294 358 

295Key359Key

296 360 

297`disable_paste_burst`361`approval_policy.reject.sandbox_approval`

298 362 

299Type / Values363Type / Values

300 364 

302 366 

303Details367Details

304 368 

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

306 370 

307Key371Key

308 372 

309`experimental_compact_prompt_file`373`apps._default.destructive_enabled`

310 374 

311Type / Values375Type / Values

312 376 

313`string (path)`377`boolean`

314 378 

315Details379Details

316 380 

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

318 382 

319Key383Key

320 384 

321`experimental_use_freeform_apply_patch`385`apps._default.enabled`

322 386 

323Type / Values387Type / Values

324 388 

326 390 

327Details391Details

328 392 

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

330 394 

331Key395Key

332 396 

333`experimental_use_unified_exec_tool`397`apps._default.open_world_enabled`

334 398 

335Type / Values399Type / Values

336 400 

338 402 

339Details403Details

340 404 

341Legacy 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`.

342 406 

343Key407Key

344 408 

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

346 410 

347Type / Values411Type / Values

348 412 

349`boolean`413`auto | prompt | approve`

350 414 

351Details415Details

352 416 

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

354 418 

355Key419Key

356 420 

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

358 422 

359Type / Values423Type / Values

360 424 

362 426 

363Details427Details

364 428 

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

366 430 

367Key431Key

368 432 

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

370 434 

371Type / Values435Type / Values

372 436 

374 438 

375Details439Details

376 440 

377Route 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`.

378 442 

379Key443Key

380 444 

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

382 446 

383Type / Values447Type / Values

384 448 

386 450 

387Details451Details

388 452 

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

390 454 

391Key455Key

392 456 

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

394 458 

395Type / Values459Type / Values

396 460 

398 462 

399Details463Details

400 464 

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

402 466 

403Key467Key

404 468 

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

406 470 

407Type / Values471Type / Values

408 472 

409`boolean`473`auto | prompt | approve`

410 474 

411Details475Details

412 476 

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

414 478 

415Key479Key

416 480 

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

418 482 

419Type / Values483Type / Values

420 484 

422 486 

423Details487Details

424 488 

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

426 490 

427Key491Key

428 492 

429`features.multi_agent`493`background_terminal_max_timeout`

430 494 

431Type / Values495Type / Values

432 496 

433`boolean`497`number`

434 498 

435Details499Details

436 500 

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

438 502 

439Key503Key

440 504 

441`features.personality`505`chatgpt_base_url`

442 506 

443Type / Values507Type / Values

444 508 

445`boolean`509`string`

446 510 

447Details511Details

448 512 

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

450 514 

451Key515Key

452 516 

453`features.powershell_utf8`517`check_for_update_on_startup`

454 518 

455Type / Values519Type / Values

456 520 

458 522 

459Details523Details

460 524 

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

462 526 

463Key527Key

464 528 

465`features.remote_models`529`cli_auth_credentials_store`

466 530 

467Type / Values531Type / Values

468 532 

469`boolean`533`file | keyring | auto`

470 534 

471Details535Details

472 536 

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

474 538 

475Key539Key

476 540 

477`features.request_rule`541`commit_attribution`

478 542 

479Type / Values543Type / Values

480 544 

481`boolean`545`string`

482 546 

483Details547Details

484 548 

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

486 550 

487Key551Key

488 552 

489`features.runtime_metrics`553`compact_prompt`

490 554 

491Type / Values555Type / Values

492 556 

493`boolean`557`string`

494 558 

495Details559Details

496 560 

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

498 562 

499Key563Key

500 564 

501`features.search_tool`565`developer_instructions`

502 566 

503Type / Values567Type / Values

504 568 

505`boolean`569`string`

506 570 

507Details571Details

508 572 

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

510 574 

511Key575Key

512 576 

513`features.shell_snapshot`577`disable_paste_burst`

514 578 

515Type / Values579Type / Values

516 580 

518 582 

519Details583Details

520 584 

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

522 586 

523Key587Key

524 588 

525`features.shell_tool`589`experimental_compact_prompt_file`

526 590 

527Type / Values591Type / Values

528 592 

529`boolean`593`string (path)`

530 594 

531Details595Details

532 596 

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

534 598 

535Key599Key

536 600 

537`features.unified_exec`601`experimental_use_unified_exec_tool`

538 602 

539Type / Values603Type / Values

540 604 

542 606 

543Details607Details

544 608 

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

546 610 

547Key611Key

548 612 

549`features.use_linux_sandbox_bwrap`613`features.apps`

550 614 

551Type / Values615Type / Values

552 616 

554 618 

555Details619Details

556 620 

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

558 622 

559Key623Key

560 624 

561`features.web_search`625`features.apps_mcp_gateway`

562 626 

563Type / Values627Type / Values

564 628 

566 630 

567Details631Details

568 632 

569Deprecated 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).

570 634 

571Key635Key

572 636 

573`features.web_search_cached`637`features.artifact`

574 638 

575Type / Values639Type / Values

576 640 

578 642 

579Details643Details

580 644 

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

582 646 

583Key647Key

584 648 

585`features.web_search_request`649`features.child_agents_md`

586 650 

587Type / Values651Type / Values

588 652 

590 654 

591Details655Details

592 656 

593Deprecated 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).

594 658 

595Key659Key

596 660 

597`feedback.enabled`661`features.collaboration_modes`

598 662 

599Type / Values663Type / Values

600 664 

602 666 

603Details667Details

604 668 

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

606 670 

607Key671Key

608 672 

609`file_opener`673`features.default_mode_request_user_input`

610 674 

611Type / Values675Type / Values

612 676 

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

614 678 

615Details679Details

616 680 

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

618 682 

619Key683Key

620 684 

621`forced_chatgpt_workspace_id`685`features.elevated_windows_sandbox`

622 686 

623Type / Values687Type / Values

624 688 

625`string (uuid)`689`boolean`

626 690 

627Details691Details

628 692 

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

630 694 

631Key695Key

632 696 

633`forced_login_method`697`features.enable_request_compression`

634 698 

635Type / Values699Type / Values

636 700 

637`chatgpt | api`701`boolean`

638 702 

639Details703Details

640 704 

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

642 706 

643Key707Key

644 708 

645`hide_agent_reasoning`709`features.experimental_windows_sandbox`

646 710 

647Type / Values711Type / Values

648 712 

650 714 

651Details715Details

652 716 

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

654 718 

655Key719Key

656 720 

657`history.max_bytes`721`features.fast_mode`

658 722 

659Type / Values723Type / Values

660 724 

661`number`725`boolean`

662 726 

663Details727Details

664 728 

665If 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).

666 730 

667Key731Key

668 732 

669`history.persistence`733`features.image_detail_original`

670 734 

671Type / Values735Type / Values

672 736 

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

674 738 

675Details739Details

676 740 

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

678 742 

679Key743Key

680 744 

681`include_apply_patch_tool`745`features.image_generation`

682 746 

683Type / Values747Type / Values

684 748 

686 750 

687Details751Details

688 752 

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

690 754 

691Key755Key

692 756 

693`instructions`757`features.multi_agent`

694 758 

695Type / Values759Type / Values

696 760 

697`string`761`boolean`

698 762 

699Details763Details

700 764 

701Reserved 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).

702 766 

703Key767Key

704 768 

705`log_dir`769`features.personality`

706 770 

707Type / Values771Type / Values

708 772 

709`string (path)`773`boolean`

710 774 

711Details775Details

712 776 

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

714 778 

715Key779Key

716 780 

717`mcp_oauth_callback_port`781`features.powershell_utf8`

718 782 

719Type / Values783Type / Values

720 784 

721`integer`785`boolean`

722 786 

723Details787Details

724 788 

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

726 790 

727Key791Key

728 792 

729`mcp_oauth_credentials_store`793`features.prevent_idle_sleep`

730 794 

731Type / Values795Type / Values

732 796 

733`auto | file | keyring`797`boolean`

734 798 

735Details799Details

736 800 

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

738 802 

739Key803Key

740 804 

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

742 806 

743Type / Values807Type / Values

744 808 

745`array<string>`809`boolean`

746 810 

747Details811Details

748 812 

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

750 814 

751Key815Key

752 816 

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

754 818 

755Type / Values819Type / Values

756 820 

757`string`821`boolean`

758 822 

759Details823Details

760 824 

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

762 826 

763Key827Key

764 828 

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

766 830 

767Type / Values831Type / Values

768 832 

769`string`833`boolean`

770 834 

771Details835Details

772 836 

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

774 838 

775Key839Key

776 840 

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

778 842 

779Type / Values843Type / Values

780 844 

781`string`845`boolean`

782 846 

783Details847Details

784 848 

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

786 850 

787Key851Key

788 852 

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

790 854 

791Type / Values855Type / Values

792 856 

793`array<string>`857`boolean`

794 858 

795Details859Details

796 860 

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

798 862 

799Key863Key

800 864 

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

802 866 

803Type / Values867Type / Values

804 868 

806 870 

807Details871Details

808 872 

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

810 874 

811Key875Key

812 876 

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

814 878 

815Type / Values879Type / Values

816 880 

817`array<string>`881`boolean`

818 882 

819Details883Details

820 884 

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

822 886 

823Key887Key

824 888 

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

826 890 

827Type / Values891Type / Values

828 892 

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

830 894 

831Details895Details

832 896 

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

834 898 

835Key899Key

836 900 

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

838 902 

839Type / Values903Type / Values

840 904 

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

842 906 

843Details907Details

844 908 

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

846 910 

847Key911Key

848 912 

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

850 914 

851Type / Values915Type / Values

852 916 

853`array<string>`917`boolean`

854 918 

855Details919Details

856 920 

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

858 922 

859Key923Key

860 924 

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

862 926 

863Type / Values927Type / Values

864 928 

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

866 930 

867Details931Details

868 932 

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

870 934 

871Key935Key

872 936 

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

874 938 

875Type / Values939Type / Values

876 940 

878 942 

879Details943Details

880 944 

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

882 946 

883Key947Key

884 948 

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

886 950 

887Type / Values951Type / Values

888 952 

889`number`953`boolean`

890 954 

891Details955Details

892 956 

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

894 958 

895Key959Key

896 960 

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

898 962 

899Type / Values963Type / Values

900 964 

901`number`965`boolean`

902 966 

903Details967Details

904 968 

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

906 970 

907Key971Key

908 972 

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

910 974 

911Type / Values975Type / Values

912 976 

913`number`977`boolean`

914 978 

915Details979Details

916 980 

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

918 982 

919Key983Key

920 984 

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

922 986 

923Type / Values987Type / Values

924 988 

925`string`989`boolean`

926 990 

927Details991Details

928 992 

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

930 994 

931Key995Key

932 996 

933`model`997`features.web_search_cached`

934 998 

935Type / Values999Type / Values

936 1000 

937`string`1001`boolean`

938 1002 

939Details1003Details

940 1004 

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

942 1006 

943Key1007Key

944 1008 

945`model_auto_compact_token_limit`1009`features.web_search_request`