config-reference.md Codex Docs, 2026-03-17 00:33 UTC → 2026-04-25 00:42 UTC

18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |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. |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. |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. |21| `approval_policy` | `untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |

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

23| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |23| `approval_policy.granular.request_permissions` | `boolean` | When `true`, prompts from the `request_permissions` tool are allowed to surface. |

24| `approval_policy.reject.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are auto-rejected. |24| `approval_policy.granular.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface. |

25| `approval_policy.granular.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are allowed to surface. |

26| `approval_policy.granular.skill_approval` | `boolean` | When `true`, skill-script approval prompts are allowed to surface. |

27| `approvals_reviewer` | `user | auto_review` | Who reviews eligible approval prompts under `on-request` or granular approval policies. Defaults to `user`; `auto_review` uses the reviewer subagent. This setting doesn't change sandboxing or review actions already allowed inside the sandbox. |

25| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |28| `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. |29| `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`. |30| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |

32| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |35| `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. |36| `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`). |37| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |

38| `auto_review.policy` | `string` | Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored. |

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

36| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |40| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |

37| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |41| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |

38| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |42| `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. |43| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |

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

45| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. |

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

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

43| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |48| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |

44| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |49| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |

45| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |50| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (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). |51| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. |

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

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

49| `features.collaboration_modes` | `boolean` | Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key. |

50| `features.default_mode_request_user_input` | `boolean` | Allow `request_user_input` in default collaboration mode (under development; off by default). |

51| `features.elevated_windows_sandbox` | `boolean` | Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it. |

52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on 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). |53| `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). |54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |

56| `features.image_generation` | `boolean` | Enable the built-in image generation tool (under development). |55| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |

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

58| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere. |

59| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |57| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off 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). |

64| `features.runtime_metrics` | `boolean` | Show runtime metrics summary in TUI turn separators (experimental). |

65| `features.search_tool` | `boolean` | Legacy toggle for an older Apps discovery flow. Current builds do not use it. |

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

67| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |59| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |

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). |60| `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). |61| `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). |62| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (stable; enabled by default except on Windows). |

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

75| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |63| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |

76| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |64| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |

77| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |65| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |

82| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |70| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |

83| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |71| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |

84| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |72| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |

73| `hooks` | `table` | Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events. |

85| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |74| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |

86| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |75| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |

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

96| `mcp_servers.<id>.enabled_tools` | `array<string>` | Allow list of tool names exposed by the MCP server. |85| `mcp_servers.<id>.enabled_tools` | `array<string>` | Allow list of tool names exposed by the MCP server. |

97| `mcp_servers.<id>.env` | `map<string,string>` | Environment variables forwarded to the MCP stdio server. |86| `mcp_servers.<id>.env` | `map<string,string>` | Environment variables forwarded to the MCP stdio server. |

98| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |87| `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_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |88| `mcp_servers.<id>.env_vars` | `array<string | { name = string, source = "local" | "remote" }>` | Additional environment variables to whitelist for an MCP stdio server. String entries default to `source = "local"`; use `source = "remote"` only with executor-backed remote stdio. |

89| `mcp_servers.<id>.experimental_environment` | `local | remote` | Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented. |

100| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |90| `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. |91| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |

102| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |92| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |

105| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |95| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |

106| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |96| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |

107| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |97| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |

108| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |98| `memories.consolidation_model` | `string` | Optional model override for global memory consolidation. |

99| `memories.disable_on_external_context` | `boolean` | When `true`, threads that use external context such as MCP tool calls, web search, or tool search are kept out of memory generation. Defaults to `false`. Legacy alias: `memories.no_memories_if_mcp_or_web_search`. |

100| `memories.extract_model` | `string` | Optional model override for per-thread memory extraction. |

101| `memories.generate_memories` | `boolean` | When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`. |

102| `memories.max_raw_memories_for_consolidation` | `number` | Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`. |

103| `memories.max_rollout_age_days` | `number` | Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`. |

104| `memories.max_rollouts_per_startup` | `number` | Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`. |

105| `memories.max_unused_days` | `number` | Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`. |

106| `memories.min_rollout_idle_hours` | `number` | Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`. |

107| `memories.use_memories` | `boolean` | When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`. |

108| `model` | `string` | Model to use (e.g., `gpt-5.5`). |

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

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

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

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

114| `model_providers.<id>` | `table` | Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden. |

115| `model_providers.<id>.auth` | `table` | Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`. |

116| `model_providers.<id>.auth.args` | `array<string>` | Arguments passed to the token command. |

117| `model_providers.<id>.auth.command` | `string` | Command to run when Codex needs a bearer token. The command must print the token to stdout. |

118| `model_providers.<id>.auth.cwd` | `string (path)` | Working directory for the token command. |

119| `model_providers.<id>.auth.refresh_interval_ms` | `number` | How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry. |

120| `model_providers.<id>.auth.timeout_ms` | `number` | Maximum token command runtime in milliseconds (default: 5000). |

114| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |121| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |

115| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |122| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |

116| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |123| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |

136| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |143| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |

137| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |144| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |

138| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |145| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |

146| `openai_base_url` | `string` | Base URL override for the built-in `openai` model provider. |

139| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |147| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |

140| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |148| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |

141| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |149| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |

154| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |162| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |

155| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |163| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate 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. |164| `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. |165| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |

158| `permissions.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |166| `permissions.<name>.filesystem.":project_roots".<subpath-or-glob>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`. |

159| `permissions.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |167| `permissions.<name>.filesystem.<path-or-glob>` | `"read" | "write" | "none" | table` | Grant direct access for a path, glob pattern, or special token, or scope nested entries under that root. Use `"none"` to deny reads for matching paths. |

160| `permissions.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |168| `permissions.<name>.filesystem.glob_scan_max_depth` | `number` | Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set. |

161| `permissions.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |169| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations 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. |170| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

163| `permissions.network.dangerously_allow_non_loopback_admin` | `boolean` | Permit non-loopback bind addresses for the managed proxy admin listener. |171| `permissions.<name>.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_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |172| `permissions.<name>.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. |173| `permissions.<name>.network.domains` | `map<string, allow | deny>` | Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values. |

166| `permissions.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener from the managed network proxy. |174| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |

167| `permissions.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |175| `permissions.<name>.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. |176| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |

169| `permissions.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |177| `permissions.<name>.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. |178| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |

171| `permissions.network.socks_url` | `string` | SOCKS5 proxy endpoint used by the managed network proxy. |179| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |

180| `permissions.<name>.network.unix_sockets` | `map<string, allow | none>` | Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values. |

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

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

187| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |196| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |

188| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |197| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |

189| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |198| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |

190| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers. |199| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers, including project-local config, hooks, and rules. |

191| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |200| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |

192| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |201| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |

193| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |202| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` 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. |203| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |

195| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |204| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |

196| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |205| `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. |206| `service_tier` | `flex | fast` | Preferred service tier for new turns. |

198| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |207| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |

199| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |208| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |

200| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |209| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |

208| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |217| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |

209| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |218| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |

210| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |219| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |

220| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

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

212| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |222| `tools.web_search` | `boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }` | Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location. |

213| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |223| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

214| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |224| `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.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |225| `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. |226| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |

217| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |227| `tui.notification_condition` | `unfocused | always` | Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`. |

228| `tui.notification_method` | `auto | osc9 | bel` | Notification method for terminal notifications (default: auto). |

218| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |229| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |

219| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |230| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |

220| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |231| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

232| `tui.terminal_title` | `array<string> | null` | Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates. |

221| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |233| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |

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. |234| `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| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |235| `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. |236| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |

237| `windows.sandbox_private_desktop` | `boolean` | Run the final sandboxed child process on a private desktop by default on native Windows. Set `false` only for compatibility with the older `Winsta0\\Default` behavior. |

225 238 

226Key239Key

227 240 

325 338 

326Type / Values339Type / Values

327 340 

328`untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }`341`untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }`

329 342 

330Details343Details

331 344 

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.345Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.

333 346 

334Key347Key

335 348 

336`approval_policy.reject.mcp_elicitations`349`approval_policy.granular.mcp_elicitations`

337 350 

338Type / Values351Type / Values

339 352 

341 354 

342Details355Details

343 356 

344When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.357When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

345 358 

346Key359Key

347 360 

348`approval_policy.reject.rules`361`approval_policy.granular.request_permissions`

349 362 

350Type / Values363Type / Values

351 364 

353 366 

354Details367Details

355 368 

356When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.369When `true`, prompts from the `request_permissions` tool are allowed to surface.

357 370 

358Key371Key

359 372 

360`approval_policy.reject.sandbox_approval`373`approval_policy.granular.rules`

361 374 

362Type / Values375Type / Values

363 376 

365 378 

366Details379Details

367 380 

368When `true`, sandbox escalation approval prompts are auto-rejected.381When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.

382 

383Key

384 

385`approval_policy.granular.sandbox_approval`

386 

387Type / Values

388 

389`boolean`

390 

391Details

392 

393When `true`, sandbox escalation approval prompts are allowed to surface.

394 

395Key

396 

397`approval_policy.granular.skill_approval`

398 

399Type / Values

400 

401`boolean`

402 

403Details

404 

405When `true`, skill-script approval prompts are allowed to surface.

406 

407Key

408 

409`approvals_reviewer`

410 

411Type / Values

412 

413`user | auto_review`

414 

415Details

416 

417Who reviews eligible approval prompts under `on-request` or granular approval policies. Defaults to `user`; `auto_review` uses the reviewer subagent. This setting doesn't change sandboxing or review actions already allowed inside the sandbox.

369 418 

370Key419Key

371 420 

489 538 

490Key539Key

491 540 

541`auto_review.policy`

542 

543Type / Values

544 

545`string`

546 

547Details

548 

549Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored.

550 

551Key

552 

492`background_terminal_max_timeout`553`background_terminal_max_timeout`

493 554 

494Type / Values555Type / Values

561 622 

562Key623Key

563 624 

625`default_permissions`

626 

627Type / Values

628 

629`string`

630 

631Details

632 

633Name of the default permissions profile to apply to sandboxed tool calls.

634 

635Key

636 

564`developer_instructions`637`developer_instructions`

565 638 

566Type / Values639Type / Values

621 694 

622Key695Key

623 696 

624`features.apps_mcp_gateway`697`features.codex_hooks`

625 698 

626Type / Values699Type / Values

627 700 

629 702 

630Details703Details

631 704 

632Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).705Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.

633 706 

634Key707Key

635 708 

636`features.artifact`709`features.enable_request_compression`

637 710 

638Type / Values711Type / Values

639 712 

641 714 

642Details715Details

643 716 

644Enable native artifact tools such as slides and spreadsheets (under development).717Compress streaming request bodies with zstd when supported (stable; on by default).

645 718 

646Key719Key

647 720 

648`features.child_agents_md`721`features.fast_mode`

649 722 

650Type / Values723Type / Values

651 724 

653 726 

654Details727Details

655 728 

656Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).729Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

657 730 

658Key731Key

659 732 

660`features.collaboration_modes`733`features.memories`

661 734 

662Type / Values735Type / Values

663 736 

665 738 

666Details739Details

667 740 

668Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key.741Enable [Memories](https://developers.openai.com/codex/memories) (off by default).

669 742 

670Key743Key

671 744 

672`features.default_mode_request_user_input`745`features.multi_agent`

673 746 

674Type / Values747Type / Values

675 748 

677 750 

678Details751Details

679 752 

680Allow `request_user_input` in default collaboration mode (under development; off by default).753Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

681 754 

682Key755Key

683 756 

684`features.elevated_windows_sandbox`757`features.personality`

685 758 

686Type / Values759Type / Values

687 760 

689 762 

690Details763Details

691 764 

692Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it.765Enable personality selection controls (stable; on by default).

693 766 

694Key767Key

695 768 

696`features.enable_request_compression`769`features.prevent_idle_sleep`

697 770 

698Type / Values771Type / Values

699 772 

701 774 

702Details775Details

703 776 

704Compress streaming request bodies with zstd when supported (stable; on by default).777Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

705 778 

706Key779Key

707 780 

708`features.experimental_windows_sandbox`781`features.shell_snapshot`

709 782 

710Type / Values783Type / Values

711 784 

713 786 

714Details787Details

715 788 

716Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it.789Snapshot shell environment to speed up repeated commands (stable; on by default).

717 790 

718Key791Key

719 792 

720`features.fast_mode`793`features.shell_tool`

721 794 

722Type / Values795Type / Values

723 796 

725 798 

726Details799Details

727 800 

728Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).801Enable the default `shell` tool for running commands (stable; on by default).

729 802 

730Key803Key

731 804 

732`features.image_detail_original`805`features.skill_mcp_dependency_install`

733 806 

734Type / Values807Type / Values

735 808 

737 810 

738Details811Details

739 812 

740Allow image outputs with `detail = "original"` on supported models (under development).813Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

741 814 

742Key815Key

743 816 

744`features.image_generation`817`features.undo`

745 818 

746Type / Values819Type / Values

747 820 

749 822 

750Details823Details

751 824 

752Enable the built-in image generation tool (under development).825Enable undo support (stable; off by default).

753 826 

754Key827Key

755 828 

756`features.personality`829`features.unified_exec`

757 830 

758Type / Values831Type / Values

759 832 

761 834 

762Details835Details

763 836 

764Enable personality selection controls (stable; on by default).837Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

765 838 

766Key839Key

767 840 

768`features.powershell_utf8`841`features.web_search`

769 842 

770Type / Values843Type / Values

771 844 

773 846 

774Details847Details

775 848 

776Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.849Deprecated legacy toggle; prefer the top-level `web_search` setting.

777 850 

778Key851Key

779 852 

780`features.prevent_idle_sleep`853`features.web_search_cached`

781 854 

782Type / Values855Type / Values

783 856 

785 858 

786Details859Details

787 860 

788Prevent the machine from sleeping while a turn is actively running (experimental; off by default).861Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.

789 862 

790Key863Key

791 864 

792`features.remote_models`865`features.web_search_request`

793 866 

794Type / Values867Type / Values

795 868 

797 870 

798Details871Details

799 872 

800Legacy toggle for an older remote-model readiness flow. Current builds do not use it.873Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.

801 874 

802Key875Key

803 876 

804`features.request_rule`877`feedback.enabled`

805 878 

806Type / Values879Type / Values

807 880 

809 882 

810Details883Details

811 884 

812Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.885Enable feedback submission via `/feedback` across Codex surfaces (default: true).

813 886 

814Key887Key

815 888 

816`features.responses_websockets`889`file_opener`

817 890 

818Type / Values891Type / Values

819 892 

820`boolean`893`vscode | vscode-insiders | windsurf | cursor | none`

821 894 

822Details895Details

823 896 

824Prefer the Responses API WebSocket transport for supported providers (under development).897URI scheme used to open citations from Codex output (default: `vscode`).

825 898 

826Key899Key

827 900 

828`features.responses_websockets_v2`901`forced_chatgpt_workspace_id`

829 902 

830Type / Values903Type / Values

831 904 

832`boolean`905`string (uuid)`

833 906 

834Details907Details

835 908 

836Enable Responses API WebSocket v2 mode (under development).909Limit ChatGPT logins to a specific workspace identifier.

837 910 

838Key911Key

839 912 

840`features.runtime_metrics`913`forced_login_method`

841 914 

842Type / Values915Type / Values

843 916 

844`boolean`917`chatgpt | api`

845 918 

846Details919Details

847 920 

848Show runtime metrics summary in TUI turn separators (experimental).921Restrict Codex to a specific authentication method.

849 922 

850Key923Key

851 924 

852`features.search_tool`925`hide_agent_reasoning`

853 926 

854Type / Values927Type / Values

855 928 

857 930 

858Details931Details

859 932 

860Legacy toggle for an older Apps discovery flow. Current builds do not use it.933Suppress reasoning events in both the TUI and `codex exec` output.

861 934 

862Key935Key

863 936 

864`features.shell_snapshot`937`history.max_bytes`

865 938 

866Type / Values939Type / Values

867 940 

868`boolean`941`number`

869 942 

870Details943Details

871 944 

872Snapshot shell environment to speed up repeated commands (stable; on by default).945If set, caps the history file size in bytes by dropping oldest entries.

873 946 

874Key947Key

875 948 

876`features.shell_tool`949`history.persistence`

877 950 

878Type / Values951Type / Values

879 952 

880`boolean`953`save-all | none`

881 954 

882Details955Details

883 956 

884Enable the default `shell` tool for running commands (stable; on by default).957Control whether Codex saves session transcripts to history.jsonl.

885 958 

886Key959Key

887 960 

888`features.skill_env_var_dependency_prompt`961`hooks`

889 962 

890Type / Values963Type / Values

891 964 

892`boolean`965`table`

893 966 

894Details967Details

895 968 

896Prompt for missing skill environment-variable dependencies (under development).969Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.

897 970 

898Key971Key

899 972 

900`features.skill_mcp_dependency_install`973`instructions`

901 974 

902Type / Values975Type / Values

903 976 

904`boolean`977`string`

905 978 

906Details979Details

907 980 

908Allow prompting and installing missing MCP dependencies for skills (stable; on by default).981Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.

909 982 

910Key983Key

911 984 

912`features.sqlite`985`log_dir`

913 986 

914Type / Values987Type / Values

915 988 

916`boolean`989`string (path)`

917 990 

918Details991Details

919 992 

920Enable SQLite-backed state persistence (stable; on by default).993Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.

921 994 

922Key995Key

923 996 

924`features.steer`997`mcp_oauth_callback_port`

925 998 

926Type / Values999Type / Values

927 1000 

928`boolean`1001`integer`

929 1002 

930Details1003Details

931 1004 

932Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.1005Optional 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.

933 1006 

934Key1007Key

935 1008 

936`features.undo`1009`mcp_oauth_callback_url`

937 1010 

938Type / Values1011Type / Values

939 1012 

940`boolean`1013`string`

941 1014 

942Details1015Details

943 1016 

944Enable undo support (stable; off by default).1017Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.

945 1018 

946Key1019Key

947 1020 

948`features.unified_exec`1021`mcp_oauth_credentials_store`

949 1022 

950Type / Values1023Type / Values

951 1024 

952`boolean`1025`auto | file | keyring`

953 1026 

954Details1027Details

955 1028 

956Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).1029Preferred store for MCP OAuth credentials.

957 1030 

958Key1031Key

959 1032 

960`features.use_linux_sandbox_bwrap`1033`mcp_servers.<id>.args`

961 1034 

962Type / Values1035Type / Values

963 1036 

964`boolean`1037`array<string>`

965 1038 

966Details1039Details

967 1040 

968Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).1041Arguments passed to the MCP stdio server command.

969 1042 

970Key1043Key

971 1044 

972`features.web_search`1045`mcp_servers.<id>.bearer_token_env_var`

973 1046 

974Type / Values1047Type / Values

975 1048 

976`boolean`1049`string`

977 1050 

978Details1051Details

979 1052 

980Deprecated legacy toggle; prefer the top-level `web_search` setting.1053Environment variable sourcing the bearer token for an MCP HTTP server.

981 1054 

982Key1055Key

983 1056 

984`features.web_search_cached`1057`mcp_servers.<id>.command`

985 1058 

986Type / Values1059Type / Values

987 1060 

988`boolean`1061`string`

989 1062 

990Details1063Details

991 1064 

992Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.1065Launcher command for an MCP stdio server.

993 1066 

994Key1067Key

995 1068 

996`features.web_search_request`1069`mcp_servers.<id>.cwd`

997 1070 

998Type / Values1071Type / Values

999 1072 

1000`boolean`1073`string`

1001 1074 

1002Details1075Details

1003 1076 

1004Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.1077Working directory for the MCP stdio server process.

1005 1078 

1006Key1079Key

1007 1080 

1008`feedback.enabled`1081`mcp_servers.<id>.disabled_tools`

1082 

1083Type / Values

1084 

1085`array<string>`

1086 

1087Details

1088 

1089Deny list applied after `enabled_tools` for the MCP server.

1090 

1091Key

1092 

1093`mcp_servers.<id>.enabled`

1009 1094 

1010Type / Values1095Type / Values

1011 1096 

1013 1098 

1014Details1099Details

1015 1100 

1016Enable feedback submission via `/feedback` across Codex surfaces (default: true).1101Disable an MCP server without removing its configuration.

1017 1102 

1018Key1103Key

1019 1104 

1020`file_opener`1105`mcp_servers.<id>.enabled_tools`

1021 1106 

1022Type / Values1107Type / Values

1023 1108 

1024`vscode | vscode-insiders | windsurf | cursor | none`1109`array<string>`

1025 1110 

1026Details1111Details

1027 1112 

1028URI scheme used to open citations from Codex output (default: `vscode`).1113Allow list of tool names exposed by the MCP server.

1029 1114 

1030Key1115Key

1031 1116 

1032`forced_chatgpt_workspace_id`1117`mcp_servers.<id>.env`

1033 1118 

1034Type / Values1119Type / Values

1035 1120 

1036`string (uuid)`1121`map<string,string>`

1037 1122 

1038Details1123Details

1039 1124 

1040Limit ChatGPT logins to a specific workspace identifier.1125Environment variables forwarded to the MCP stdio server.

1041 1126 

1042Key1127Key

1043 1128 

1044`forced_login_method`1129`mcp_servers.<id>.env_http_headers`

1045 1130 

1046Type / Values1131Type / Values

1047 1132 

1048`chatgpt | api`1133`map<string,string>`

1049 1134 

1050Details1135Details

1051 1136 

1052Restrict Codex to a specific authentication method.1137HTTP headers populated from environment variables for an MCP HTTP server.

1053 1138 

1054Key1139Key

1055 1140 

1056`hide_agent_reasoning`1141`mcp_servers.<id>.env_vars`

1057 1142 

1058Type / Values1143Type / Values

1059 1144 

1060`boolean`1145`array<string | { name = string, source = "local" | "remote" }>`

1061 1146 

1062Details1147Details

1063 1148 

1064Suppress reasoning events in both the TUI and `codex exec` output.1149Additional environment variables to whitelist for an MCP stdio server. String entries default to `source = "local"`; use `source = "remote"` only with executor-backed remote stdio.

1065 1150 

1066Key1151Key

1067 1152 

1068`history.max_bytes`1153`mcp_servers.<id>.experimental_environment`

1069 1154 

1070Type / Values1155Type / Values

1071 1156 

1072`number`1157`local | remote`

1073 1158 

1074Details1159Details

1075 1160 

1076If set, caps the history file size in bytes by dropping oldest entries.1161Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.

1077 1162 

1078Key1163Key

1079 1164 

1080`history.persistence`1165`mcp_servers.<id>.http_headers`

1081 1166 

1082Type / Values1167Type / Values

1083 1168 

1084`save-all | none`1169`map<string,string>`

1085 1170 

1086Details1171Details

1087 1172 

1088Control whether Codex saves session transcripts to history.jsonl.1173Static HTTP headers included with each MCP HTTP request.

1089 1174 

1090Key1175Key

1091 1176 

1092`instructions`1177`mcp_servers.<id>.oauth_resource`

1093 1178 

1094Type / Values1179Type / Values

1095 1180 

1097 1182 

1098Details1183Details

1099 1184 

1100Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.1185Optional RFC 8707 OAuth resource parameter to include during MCP login.

1101 1186 

1102Key1187Key

1103 1188 

1104`log_dir`1189`mcp_servers.<id>.required`

1105 1190 

1106Type / Values1191Type / Values

1107 1192 

1108`string (path)`1193`boolean`

1109 1194 

1110Details1195Details

1111 1196 

1112Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.1197When true, fail startup/resume if this enabled MCP server cannot initialize.

1113 1198 

1114Key1199Key

1115 1200 

1116`mcp_oauth_callback_port`1201`mcp_servers.<id>.scopes`

1117 1202 

1118Type / Values1203Type / Values

1119 1204 

1120`integer`1205`array<string>`

1121 1206 

1122Details1207Details

1123 1208 

1124Optional 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.1209OAuth scopes to request when authenticating to that MCP server.

1125 1210 

1126Key1211Key

1127 1212 

1128`mcp_oauth_callback_url`1213`mcp_servers.<id>.startup_timeout_ms`

1129 1214 

1130Type / Values1215Type / Values

1131 1216 

1132`string`1217`number`

1133 1218 

1134Details1219Details

1135 1220 

1136Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.1221Alias for `startup_timeout_sec` in milliseconds.

1137 1222 

1138Key1223Key

1139 1224 

1140`mcp_oauth_credentials_store`1225`mcp_servers.<id>.startup_timeout_sec`

1141 1226 

1142Type / Values1227Type / Values

1143 1228 

1144`auto | file | keyring`1229`number`

1145 1230 

1146Details1231Details

1147 1232 

1148Preferred store for MCP OAuth credentials.1233Override the default 10s startup timeout for an MCP server.

1149 1234 

1150Key1235Key

1151 1236 

1152`mcp_servers.<id>.args`1237`mcp_servers.<id>.tool_timeout_sec`

1153 1238 

1154Type / Values1239Type / Values

1155 1240 

1156`array<string>`1241`number`

1157 1242 

1158Details1243Details

1159 1244 

1160Arguments passed to the MCP stdio server command.1245Override the default 60s per-tool timeout for an MCP server.

1161 1246 

1162Key1247Key

1163 1248 

1164`mcp_servers.<id>.bearer_token_env_var`1249`mcp_servers.<id>.url`

1165 1250 

1166Type / Values1251Type / Values

1167 1252 

1169 1254 

1170Details1255Details

1171 1256 

1172Environment variable sourcing the bearer token for an MCP HTTP server.1257Endpoint for an MCP streamable HTTP server.

1173 1258 

1174Key1259Key

1175 1260 

1176`mcp_servers.<id>.command`1261`memories.consolidation_model`

1177 1262 

1178Type / Values1263Type / Values

1179 1264 

1181 1266 

1182Details1267Details

1183 1268 

1184Launcher command for an MCP stdio server.1269Optional model override for global memory consolidation.

1185 1270 

1186Key1271Key

1187 1272 

1188`mcp_servers.<id>.cwd`1273`memories.disable_on_external_context`

1189 1274 

1190Type / Values1275Type / Values

1191 1276 

1192`string`1277`boolean`

1193 1278 

1194Details1279Details

1195 1280 

1196Working directory for the MCP stdio server process.1281When `true`, threads that use external context such as MCP tool calls, web search, or tool search are kept out of memory generation. Defaults to `false`. Legacy alias: `memories.no_memories_if_mcp_or_web_search`.

1197 1282 

1198Key1283Key

1199 1284 

1200`mcp_servers.<id>.disabled_tools`1285`memories.extract_model`

1201 1286 

1202Type / Values1287Type / Values

1203 1288 

1204`array<string>`1289`string`

1205 1290 

1206Details1291Details

1207 1292 

1208Deny list applied after `enabled_tools` for the MCP server.1293Optional model override for per-thread memory extraction.

1209 1294 

1210Key1295Key

1211 1296 

1212`mcp_servers.<id>.enabled`1297`memories.generate_memories`

1213 1298 

1214Type / Values1299Type / Values

1215 1300 

1217 1302 

1218Details1303Details

1219 1304 

1220Disable an MCP server without removing its configuration.1305When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.

1221 1306 

1222Key1307Key

1223 1308 

1224`mcp_servers.<id>.enabled_tools`1309`memories.max_raw_memories_for_consolidation`

1225 1310 

1226Type / Values1311Type / Values

1227 1312 

1228`array<string>`1313`number`

1229 1314 

1230Details1315Details

1231 1316 

1232Allow list of tool names exposed by the MCP server.1317Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.

1233 1318 

1234Key1319Key

1235 1320 

1236`mcp_servers.<id>.env`1321`memories.max_rollout_age_days`

1237 1322 

1238Type / Values1323Type / Values

1239 1324 

1240`map<string,string>`1325`number`

1241 1326 

1242Details1327Details

1243 1328 

1244Environment variables forwarded to the MCP stdio server.1329Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.

1245 1330 

1246Key1331Key

1247 1332 

1248`mcp_servers.<id>.env_http_headers`1333`memories.max_rollouts_per_startup`

1249 1334 

1250Type / Values1335Type / Values

1251 1336 

1252`map<string,string>`1337`number`

1253 1338 

1254Details1339Details

1255 1340 

1256HTTP headers populated from environment variables for an MCP HTTP server.1341Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.

1257 1342 

1258Key1343Key

1259 1344 

1260`mcp_servers.<id>.env_vars`1345`memories.max_unused_days`

1261 1346 

1262Type / Values1347Type / Values

1263 1348 

1264`array<string>`1349`number`

1265 1350 

1266Details1351Details

1267 1352 

1268Additional environment variables to whitelist for an MCP stdio server.1353Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.

1269 1354 

1270Key1355Key

1271 1356 

1272`mcp_servers.<id>.http_headers`1357`memories.min_rollout_idle_hours`

1273 1358 

1274Type / Values1359Type / Values

1275 1360 

1276`map<string,string>`1361`number`

1277 1362 

1278Details1363Details

1279 1364 

1280Static HTTP headers included with each MCP HTTP request.1365Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.

1281 1366 

1282Key1367Key

1283 1368 

1284`mcp_servers.<id>.oauth_resource`1369`memories.use_memories`

1370 

1371Type / Values

1372 

1373`boolean`

1374 

1375Details

1376 

1377When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.

1378 

1379Key

1380 

1381`model`

1285 1382 

1286Type / Values1383Type / Values

1287 1384 

1289 1386 

1290Details1387Details

1291 1388 

1292Optional RFC 8707 OAuth resource parameter to include during MCP login.1389Model to use (e.g., `gpt-5.5`).

1293 1390 

1294Key1391Key

1295 1392