config-reference.md Codex Docs, 2026-02-19 20:53 UTC → 2026-03-17 00:33 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). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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`. |85| `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`. |86| `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. |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. |

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

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

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

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

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

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

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

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

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

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

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

75| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |108| `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). |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. |

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

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

79| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |113| `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). |123| `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). |124| `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). |125| `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). |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. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

148| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |206| `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`. |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. |

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

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

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

153| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |213| `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). |214| `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). |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. |

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

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

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

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

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

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

162 225 

163Key226Key

164 227 

186 249 

187Key250Key

188 251 

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

190 253 

191Type / Values254Type / Values

192 255 

193`number`256`array<string>`

194 257 

195Details258Details

196 259 

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

198 261 

199Key262Key

200 263 

201`approval_policy`264`agents.job_max_runtime_seconds`

202 265 

203Type / Values266Type / Values

204 267 

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

206 269 

207Details270Details

208 271 

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

210 273 

211Key274Key

212 275 

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

214 277 

215Type / Values278Type / Values

216 279 

217`unknown | user`280`number`

218 281 

219Details282Details

220 283 

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

222 285 

223Key286Key

224 287 

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

226 289 

227Type / Values290Type / Values

228 291 

229`boolean`292`number`

230 293 

231Details294Details

232 295 

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

234 297 

235Key298Key

236 299 

237`chatgpt_base_url`300`allow_login_shell`

238 301 

239Type / Values302Type / Values

240 303 

241`string`304`boolean`

242 305 

243Details306Details

244 307 

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

246 309 

247Key310Key

248 311 

249`check_for_update_on_startup`312`analytics.enabled`

250 313 

251Type / Values314Type / Values

252 315 

254 317 

255Details318Details

256 319 

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

258 321 

259Key322Key

260 323 

261`cli_auth_credentials_store`324`approval_policy`

262 325 

263Type / Values326Type / Values

264 327 

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

266 329 

267Details330Details

268 331 

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

270 333 

271Key334Key

272 335 

273`compact_prompt`336`approval_policy.reject.mcp_elicitations`

274 337 

275Type / Values338Type / Values

276 339 

277`string`340`boolean`

278 341 

279Details342Details

280 343 

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

282 345 

283Key346Key

284 347 

285`developer_instructions`348`approval_policy.reject.rules`

286 349 

287Type / Values350Type / Values

288 351 

289`string`352`boolean`

290 353 

291Details354Details

292 355 

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

294 357 

295Key358Key

296 359 

297`disable_paste_burst`360`approval_policy.reject.sandbox_approval`

298 361 

299Type / Values362Type / Values

300 363 

302 365 

303Details366Details

304 367 

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

306 369 

307Key370Key

308 371 

309`experimental_compact_prompt_file`372`apps._default.destructive_enabled`

310 373 

311Type / Values374Type / Values

312 375 

313`string (path)`376`boolean`

314 377 

315Details378Details

316 379 

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

318 381 

319Key382Key

320 383 

321`experimental_use_freeform_apply_patch`384`apps._default.enabled`

322 385 

323Type / Values386Type / Values

324 387 

326 389 

327Details390Details

328 391 

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

330 393 

331Key394Key

332 395 

333`experimental_use_unified_exec_tool`396`apps._default.open_world_enabled`

334 397 

335Type / Values398Type / Values

336 399 

338 401 

339Details402Details

340 403 

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

342 405 

343Key406Key

344 407 

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

346 409 

347Type / Values410Type / Values

348 411 

349`boolean`412`auto | prompt | approve`

350 413 

351Details414Details

352 415 

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

354 417 

355Key418Key

356 419 

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

358 421 

359Type / Values422Type / Values

360 423 

362 425 

363Details426Details

364 427 

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

366 429 

367Key430Key

368 431 

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

370 433 

371Type / Values434Type / Values

372 435 

374 437 

375Details438Details

376 439 

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

378 441 

379Key442Key

380 443 

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

382 445 

383Type / Values446Type / Values

384 447 

386 449 

387Details450Details

388 451 

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

390 453 

391Key454Key

392 455 

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

394 457 

395Type / Values458Type / Values

396 459 

398 461 

399Details462Details

400 463 

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

402 465 

403Key466Key

404 467 

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

406 469 

407Type / Values470Type / Values

408 471 

409`boolean`472`auto | prompt | approve`

410 473 

411Details474Details

412 475 

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

414 477 

415Key478Key

416 479 

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

418 481 

419Type / Values482Type / Values

420 483 

422 485 

423Details486Details

424 487 

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

426 489 

427Key490Key

428 491 

429`features.multi_agent`492`background_terminal_max_timeout`

430 493 

431Type / Values494Type / Values

432 495 

433`boolean`496`number`

434 497 

435Details498Details

436 499 

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

438 501 

439Key502Key

440 503 

441`features.personality`504`chatgpt_base_url`

442 505 

443Type / Values506Type / Values

444 507 

445`boolean`508`string`

446 509 

447Details510Details

448 511 

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

450 513 

451Key514Key

452 515 

453`features.powershell_utf8`516`check_for_update_on_startup`

454 517 

455Type / Values518Type / Values

456 519 

458 521 

459Details522Details

460 523 

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

462 525 

463Key526Key

464 527 

465`features.remote_models`528`cli_auth_credentials_store`

466 529 

467Type / Values530Type / Values

468 531 

469`boolean`532`file | keyring | auto`

470 533 

471Details534Details

472 535 

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

474 537 

475Key538Key

476 539 

477`features.request_rule`540`commit_attribution`

478 541 

479Type / Values542Type / Values

480 543 

481`boolean`544`string`

482 545 

483Details546Details

484 547 

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

486 549 

487Key550Key

488 551 

489`features.runtime_metrics`552`compact_prompt`

490 553 

491Type / Values554Type / Values

492 555 

493`boolean`556`string`

494 557 

495Details558Details

496 559 

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

498 561 

499Key562Key

500 563 

501`features.search_tool`564`developer_instructions`

502 565 

503Type / Values566Type / Values

504 567 

505`boolean`568`string`

506 569 

507Details570Details

508 571 

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

510 573 

511Key574Key

512 575 

513`features.shell_snapshot`576`disable_paste_burst`

514 577 

515Type / Values578Type / Values

516 579 

518 581 

519Details582Details

520 583 

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

522 585 

523Key586Key

524 587 

525`features.shell_tool`588`experimental_compact_prompt_file`

526 589 

527Type / Values590Type / Values

528 591 

529`boolean`592`string (path)`

530 593 

531Details594Details

532 595 

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

534 597 

535Key598Key

536 599 

537`features.unified_exec`600`experimental_use_unified_exec_tool`

538 601 

539Type / Values602Type / Values

540 603 

542 605 

543Details606Details

544 607 

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

546 609 

547Key610Key

548 611 

549`features.use_linux_sandbox_bwrap`612`features.apps`

550 613 

551Type / Values614Type / Values

552 615 

554 617 

555Details618Details

556 619 

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

558 621 

559Key622Key

560 623 

561`features.web_search`624`features.apps_mcp_gateway`

562 625 

563Type / Values626Type / Values

564 627 

566 629 

567Details630Details

568 631 

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

570 633 

571Key634Key

572 635 

573`features.web_search_cached`636`features.artifact`

574 637 

575Type / Values638Type / Values

576 639 

578 641 

579Details642Details

580 643 

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

582 645 

583Key646Key

584 647 

585`features.web_search_request`648`features.child_agents_md`

586 649 

587Type / Values650Type / Values

588 651 

590 653 

591Details654Details

592 655 

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

594 657 

595Key658Key

596 659 

597`feedback.enabled`660`features.collaboration_modes`

598 661 

599Type / Values662Type / Values

600 663 

602 665 

603Details666Details

604 667 

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

606 669 

607Key670Key

608 671 

609`file_opener`672`features.default_mode_request_user_input`

610 673 

611Type / Values674Type / Values

612 675 

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

614 677 

615Details678Details

616 679 

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

618 681 

619Key682Key

620 683 

621`forced_chatgpt_workspace_id`684`features.elevated_windows_sandbox`

622 685 

623Type / Values686Type / Values

624 687 

625`string (uuid)`688`boolean`

626 689 

627Details690Details

628 691 

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

630 693 

631Key694Key

632 695 

633`forced_login_method`696`features.enable_request_compression`

634 697 

635Type / Values698Type / Values

636 699 

637`chatgpt | api`700`boolean`

638 701 

639Details702Details

640 703 

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

642 705 

643Key706Key

644 707 

645`hide_agent_reasoning`708`features.experimental_windows_sandbox`

646 709 

647Type / Values710Type / Values

648 711 

650 713 

651Details714Details

652 715 

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

654 717 

655Key718Key

656 719 

657`history.max_bytes`720`features.fast_mode`

658 721 

659Type / Values722Type / Values

660 723 

661`number`724`boolean`

662 725 

663Details726Details

664 727 

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

666 729 

667Key730Key

668 731 

669`history.persistence`732`features.image_detail_original`

670 733 

671Type / Values734Type / Values

672 735 

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

674 737 

675Details738Details

676 739 

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

678 741 

679Key742Key

680 743 

681`include_apply_patch_tool`744`features.image_generation`

682 745 

683Type / Values746Type / Values

684 747 

686 749 

687Details750Details

688 751 

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

690 753 

691Key754Key

692 755 

693`instructions`756`features.personality`

694 757 

695Type / Values758Type / Values

696 759 

697`string`760`boolean`

698 761 

699Details762Details

700 763 

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

702 765 

703Key766Key

704 767 

705`log_dir`768`features.powershell_utf8`

706 769 

707Type / Values770Type / Values

708 771 

709`string (path)`772`boolean`

710 773 

711Details774Details

712 775 

713Directory 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.

714 777 

715Key778Key

716 779 

717`mcp_oauth_callback_port`780`features.prevent_idle_sleep`

718 781 

719Type / Values782Type / Values

720 783 

721`integer`784`boolean`

722 785 

723Details786Details

724 787 

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

726 789 

727Key790Key

728 791 

729`mcp_oauth_credentials_store`792`features.remote_models`

730 793 

731Type / Values794Type / Values

732 795 

733`auto | file | keyring`796`boolean`

734 797 

735Details798Details

736 799 

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

738 801 

739Key802Key

740 803 

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

742 805 

743Type / Values806Type / Values

744 807 

745`array<string>`808`boolean`

746 809 

747Details810Details

748 811 

749Arguments 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.

750 813 

751Key814Key

752 815 

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

754 817 

755Type / Values818Type / Values

756 819 

757`string`820`boolean`

758 821 

759Details822Details

760 823 

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

762 825 

763Key826Key

764 827 

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

766 829 

767Type / Values830Type / Values

768 831 

769`string`832`boolean`

770 833 

771Details834Details

772 835 

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

774 837 

775Key838Key

776 839 

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

778 841 

779Type / Values842Type / Values

780 843 

781`string`844`boolean`

782 845 

783Details846Details

784 847 

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

786 849 

787Key850Key

788 851 

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

790 853 

791Type / Values854Type / Values

792 855 

793`array<string>`856`boolean`

794 857 

795Details858Details

796 859 

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

798 861 

799Key862Key

800 863 

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

802 865 

803Type / Values866Type / Values

804 867 

806 869 

807Details870Details

808 871 

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

810 873 

811Key874Key

812 875 

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

814 877 

815Type / Values878Type / Values

816 879 

817`array<string>`880`boolean`

818 881 

819Details882Details

820 883 

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

822 885 

823Key886Key

824 887 

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

826 889 

827Type / Values890Type / Values

828 891 

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

830 893 

831Details894Details

832 895 

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

834 897 

835Key898Key

836 899 

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

838 901 

839Type / Values902Type / Values

840 903 

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

842 905 

843Details906Details

844 907 

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

846 909 

847Key910Key

848 911 

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

850 913 

851Type / Values914Type / Values

852 915 

853`array<string>`916`boolean`

854 917 

855Details918Details

856 919 

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

858 921 

859Key922Key

860 923 

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

862 925 

863Type / Values926Type / Values

864 927 

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

866 929 

867Details930Details

868 931 

869Static 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.

870 933 

871Key934Key

872 935 

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

874 937 

875Type / Values938Type / Values

876 939 

878 941 

879Details942Details

880 943 

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

882 945 

883Key946Key

884 947 

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

886 949 

887Type / Values950Type / Values

888 951 

889`number`952`boolean`

890 953 

891Details954Details

892 955 

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

894 957 

895Key958Key

896 959 

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

898 961 

899Type / Values962Type / Values

900 963 

901`number`964`boolean`

902 965 

903Details966Details

904 967 

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

906 969 

907Key970Key

908 971 

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

910 973 

911Type / Values974Type / Values

912 975 

913`number`976`boolean`

914 977 

915Details978Details

916 979 

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

918 981 

919Key982Key

920 983 

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

922 985 

923Type / Values986Type / Values

924 987 

925`string`988`boolean`

926 989 

927Details990Details

928 991 

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

930 993 

931Key994Key

932 995 

933`model`996`features.web_search_request`

934 997 

935Type / Values998Type / Values

936 999 

937`string`1000`boolean`

938 1001 

939Details1002Details

940 1003 

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

942 1005 

943Key1006Key

944 1007 

945`model_auto_compact_token_limit`1008`feedback.enabled`

946 1009