config-reference.md Codex Docs, 2026-03-08 00:35 UTC → 2026-04-17 00:44 UTC

15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |

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

17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |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. |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 | guardian_subagent` | Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent. |

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

38| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |41| `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. |42| `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. |43| `compact_prompt` | `string` | Inline override for the history compaction prompt. |

44| `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). |45| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |

42| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |46| `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). |47| `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`. |48| `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). |49| `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). |50| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |

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). |51| `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). |52| `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). |53| `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). |54| `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.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default). |

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

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

60| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |56| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |

61| `features.remote_models` | `boolean` | Legacy toggle for an older remote-model readiness flow. Current builds do not use it. |

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

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

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

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

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

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

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

69| `features.skill_env_var_dependency_prompt` | `boolean` | Prompt for missing skill environment-variable dependencies (under development). |

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

71| `features.sqlite` | `boolean` | Enable SQLite-backed state persistence (stable; on by default). |60| `features.smart_approvals` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

104| `memories.no_memories_if_mcp_or_web_search` | `boolean` | When `true`, threads that use MCP tool calls or web search are kept out of memory generation. Defaults to `false`. |

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

106| `model` | `string` | Model to use (e.g., `gpt-5.4`). |

110| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |107| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |

111| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |108| `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. |

112| `model_context_window` | `number` | Context window tokens available to the active model. |109| `model_context_window` | `number` | Context window tokens available to the active model. |

113| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |110| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

156| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |161| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |

157| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |162| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |

158| `permissions.network.admin_url` | `string` | Admin endpoint for the managed network proxy. |163| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |

159| `permissions.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |164| `permissions.<name>.filesystem.":project_roots".<subpath>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself. |

160| `permissions.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |165| `permissions.<name>.filesystem.<path>` | `"read" | "write" | "none" | table` | Grant direct access for a path or special token, or scope nested entries under that root. |

161| `permissions.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |166| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

162| `permissions.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |167| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

163| `permissions.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |168| `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_admin` | `boolean` | Permit non-loopback bind addresses for the managed proxy admin listener. |169| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

165| `permissions.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |170| `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.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |171| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |

167| `permissions.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener from the managed network proxy. |172| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

168| `permissions.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |173| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |

169| `permissions.network.enabled` | `boolean` | Enable the managed network proxy configuration for subprocesses. |174| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |

170| `permissions.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |175| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |

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

172| `permissions.network.socks_url` | `string` | SOCKS5 proxy endpoint used by the managed network proxy. |177| `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. |

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

174| `plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default. |179| `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. |

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

195| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |200| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |

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

197| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |202| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |

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

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

200| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |205| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |

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

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

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

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

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

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

213| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |219| `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. |

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

215| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |221| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |

216| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |222| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

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

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

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

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

222| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |229| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |

223| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |230| `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. |

224| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |231| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

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

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

226 234 

227Key235Key

228 236 

294 302 

295Details303Details

296 304 

297Maximum number of agent threads that can be open concurrently.305Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.

298 306 

299Key307Key

300 308 

326 334 

327Type / Values335Type / Values

328 336 

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

330 338 

331Details339Details

332 340 

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

334 342 

335Key343Key

336 344 

337`approval_policy.reject.mcp_elicitations`345`approval_policy.granular.mcp_elicitations`

338 346 

339Type / Values347Type / Values

340 348 

342 350 

343Details351Details

344 352 

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

346 354 

347Key355Key

348 356 

349`approval_policy.reject.rules`357`approval_policy.granular.request_permissions`

350 358 

351Type / Values359Type / Values

352 360 

354 362 

355Details363Details

356 364 

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

358 366 

359Key367Key

360 368 

361`approval_policy.reject.sandbox_approval`369`approval_policy.granular.rules`

362 370 

363Type / Values371Type / Values

364 372 

366 374 

367Details375Details

368 376 

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

378 

379Key

380 

381`approval_policy.granular.sandbox_approval`

382 

383Type / Values

384 

385`boolean`

386 

387Details

388 

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

390 

391Key

392 

393`approval_policy.granular.skill_approval`

394 

395Type / Values

396 

397`boolean`

398 

399Details

400 

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

402 

403Key

404 

405`approvals_reviewer`

406 

407Type / Values

408 

409`user | guardian_subagent`

410 

411Details

412 

413Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent.

370 414 

371Key415Key

372 416 

562 606 

563Key607Key

564 608 

609`default_permissions`

610 

611Type / Values

612 

613`string`

614 

615Details

616 

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

618 

619Key

620 

565`developer_instructions`621`developer_instructions`

566 622 

567Type / Values623Type / Values

622 678 

623Key679Key

624 680 

625`features.apps_mcp_gateway`681`features.codex_hooks`

626 682 

627Type / Values683Type / Values

628 684 

630 686 

631Details687Details

632 688 

633Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).689Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).

634 690 

635Key691Key

636 692 

637`features.artifact`693`features.enable_request_compression`

638 694 

639Type / Values695Type / Values

640 696 

642 698 

643Details699Details

644 700 

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

646 702 

647Key703Key

648 704 

649`features.child_agents_md`705`features.fast_mode`

650 706 

651Type / Values707Type / Values

652 708 

654 710 

655Details711Details

656 712 

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

658 714 

659Key715Key

660 716 

661`features.collaboration_modes`717`features.memories`

662 718 

663Type / Values719Type / Values

664 720 

666 722 

667Details723Details

668 724 

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

670 726 

671Key727Key

672 728 

673`features.default_mode_request_user_input`729`features.multi_agent`

674 730 

675Type / Values731Type / Values

676 732 

678 734 

679Details735Details

680 736 

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

682 738 

683Key739Key

684 740 

685`features.elevated_windows_sandbox`741`features.personality`

686 742 

687Type / Values743Type / Values

688 744 

690 746 

691Details747Details

692 748 

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

694 750 

695Key751Key

696 752 

697`features.enable_request_compression`753`features.prevent_idle_sleep`

698 754 

699Type / Values755Type / Values

700 756 

702 758 

703Details759Details

704 760 

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

706 762 

707Key763Key

708 764 

709`features.experimental_windows_sandbox`765`features.shell_snapshot`

710 766 

711Type / Values767Type / Values

712 768 

714 770 

715Details771Details

716 772 

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

718 774 

719Key775Key

720 776 

721`features.fast_mode`777`features.shell_tool`

722 778 

723Type / Values779Type / Values

724 780 

726 782 

727Details783Details

728 784 

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

730 786 

731Key787Key

732 788 

733`features.image_detail_original`789`features.skill_mcp_dependency_install`

734 790 

735Type / Values791Type / Values

736 792 

738 794 

739Details795Details

740 796 

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

742 798 

743Key799Key

744 800 

745`features.image_generation`801`features.smart_approvals`

746 802 

747Type / Values803Type / Values

748 804 

750 806 

751Details807Details

752 808 

753Enable the built-in image generation tool (under development).809Route eligible approval requests through the guardian reviewer subagent (experimental; off by default).

754 810 

755Key811Key

756 812 

757`features.multi_agent`813`features.undo`

758 814 

759Type / Values815Type / Values

760 816 

762 818 

763Details819Details

764 820 

765Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default).821Enable undo support (stable; off by default).

766 822 

767Key823Key

768 824 

769`features.personality`825`features.unified_exec`

770 826 

771Type / Values827Type / Values

772 828 

774 830 

775Details831Details

776 832 

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

778 834 

779Key835Key

780 836 

781`features.powershell_utf8`837`features.web_search`

782 838 

783Type / Values839Type / Values

784 840 

786 842 

787Details843Details

788 844 

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

790 846 

791Key847Key

792 848 

793`features.prevent_idle_sleep`849`features.web_search_cached`

794 850 

795Type / Values851Type / Values

796 852 

798 854 

799Details855Details

800 856 

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

802 858 

803Key859Key

804 860 

805`features.remote_models`861`features.web_search_request`

806 862 

807Type / Values863Type / Values

808 864 

810 866 

811Details867Details

812 868 

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

814 870 

815Key871Key

816 872 

817`features.request_rule`873`feedback.enabled`

818 874 

819Type / Values875Type / Values

820 876 

822 878 

823Details879Details

824 880 

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

826 882 

827Key883Key

828 884 

829`features.responses_websockets`885`file_opener`

830 886 

831Type / Values887Type / Values

832 888 

833`boolean`889`vscode | vscode-insiders | windsurf | cursor | none`

834 890 

835Details891Details

836 892 

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

838 894 

839Key895Key

840 896 

841`features.responses_websockets_v2`897`forced_chatgpt_workspace_id`

842 898 

843Type / Values899Type / Values

844 900 

845`boolean`901`string (uuid)`

846 902 

847Details903Details

848 904 

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

850 906 

851Key907Key

852 908 

853`features.runtime_metrics`909`forced_login_method`

854 910 

855Type / Values911Type / Values

856 912 

857`boolean`913`chatgpt | api`

858 914 

859Details915Details

860 916 

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

862 918 

863Key919Key

864 920 

865`features.search_tool`921`hide_agent_reasoning`

866 922 

867Type / Values923Type / Values

868 924 

870 926 

871Details927Details

872 928 

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

874 930 

875Key931Key

876 932 

877`features.shell_snapshot`933`history.max_bytes`

878 934 

879Type / Values935Type / Values

880 936 

881`boolean`937`number`

882 938 

883Details939Details

884 940 

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

886 942 

887Key943Key

888 944 

889`features.shell_tool`945`history.persistence`

890 946 

891Type / Values947Type / Values

892 948 

893`boolean`949`save-all | none`

894 950 

895Details951Details

896 952 

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

898 954 

899Key955Key

900 956 

901`features.skill_env_var_dependency_prompt`957`instructions`

902 958 

903Type / Values959Type / Values

904 960 

905`boolean`961`string`

906 962 

907Details963Details

908 964 

909Prompt for missing skill environment-variable dependencies (under development).965Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.

910 966 

911Key967Key

912 968 

913`features.skill_mcp_dependency_install`969`log_dir`

914 970 

915Type / Values971Type / Values

916 972 

917`boolean`973`string (path)`

918 974 

919Details975Details

920 976 

921Allow prompting and installing missing MCP dependencies for skills (stable; on by default).977Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.

922 978 

923Key979Key

924 980 

925`features.sqlite`981`mcp_oauth_callback_port`

926 982 

927Type / Values983Type / Values

928 984 

929`boolean`985`integer`

930 986 

931Details987Details

932 988 

933Enable SQLite-backed state persistence (stable; on by default).989Optional 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.

934 990 

935Key991Key

936 992 

937`features.steer`993`mcp_oauth_callback_url`

938 994 

939Type / Values995Type / Values

940 996 

941`boolean`997`string`

942 998 

943Details999Details

944 1000 

945Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.1001Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.

946 1002 

947Key1003Key

948 1004 

949`features.undo`1005`mcp_oauth_credentials_store`

950 1006 

951Type / Values1007Type / Values

952 1008 

953`boolean`1009`auto | file | keyring`

954 1010 

955Details1011Details

956 1012 

957Enable undo support (stable; off by default).1013Preferred store for MCP OAuth credentials.

958 1014 

959Key1015Key

960 1016 

961`features.unified_exec`1017`mcp_servers.<id>.args`

962 1018 

963Type / Values1019Type / Values

964 1020 

965`boolean`1021`array<string>`

966 1022 

967Details1023Details

968 1024 

969Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).1025Arguments passed to the MCP stdio server command.

970 1026 

971Key1027Key

972 1028 

973`features.use_linux_sandbox_bwrap`1029`mcp_servers.<id>.bearer_token_env_var`

974 1030 

975Type / Values1031Type / Values

976 1032 

977`boolean`1033`string`

978 1034 

979Details1035Details

980 1036 

981Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).1037Environment variable sourcing the bearer token for an MCP HTTP server.

982 1038 

983Key1039Key

984 1040 

985`features.web_search`1041`mcp_servers.<id>.command`

986 1042 

987Type / Values1043Type / Values

988 1044 

989`boolean`1045`string`

990 1046 

991Details1047Details

992 1048 

993Deprecated legacy toggle; prefer the top-level `web_search` setting.1049Launcher command for an MCP stdio server.

994 1050 

995Key1051Key

996 1052 

997`features.web_search_cached`1053`mcp_servers.<id>.cwd`

998 1054 

999Type / Values1055Type / Values

1000 1056 

1001`boolean`1057`string`

1002 1058 

1003Details1059Details

1004 1060 

1005Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.1061Working directory for the MCP stdio server process.

1006 1062 

1007Key1063Key

1008 1064 

1009`features.web_search_request`1065`mcp_servers.<id>.disabled_tools`

1010 1066 

1011Type / Values1067Type / Values

1012 1068 

1013`boolean`1069`array<string>`

1014 1070 

1015Details1071Details

1016 1072 

1017Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.1073Deny list applied after `enabled_tools` for the MCP server.

1018 1074 

1019Key1075Key

1020 1076 

1021`feedback.enabled`1077`mcp_servers.<id>.enabled`

1022 1078 

1023Type / Values1079Type / Values

1024 1080 

1026 1082 

1027Details1083Details

1028 1084 

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

1030 1086 

1031Key1087Key

1032 1088 

1033`file_opener`1089`mcp_servers.<id>.enabled_tools`

1034 1090 

1035Type / Values1091Type / Values

1036 1092 

1037`vscode | vscode-insiders | windsurf | cursor | none`1093`array<string>`

1038 1094 

1039Details1095Details

1040 1096 

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

1042 1098 

1043Key1099Key

1044 1100 

1045`forced_chatgpt_workspace_id`1101`mcp_servers.<id>.env`

1046 1102 

1047Type / Values1103Type / Values

1048 1104 

1049`string (uuid)`1105`map<string,string>`

1050 1106 

1051Details1107Details

1052 1108 

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

1054 1110 

1055Key1111Key

1056 1112 

1057`forced_login_method`1113`mcp_servers.<id>.env_http_headers`

1058 1114 

1059Type / Values1115Type / Values

1060 1116 

1061`chatgpt | api`1117`map<string,string>`

1062 1118 

1063Details1119Details

1064 1120 

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

1066 1122 

1067Key1123Key

1068 1124 

1069`hide_agent_reasoning`1125`mcp_servers.<id>.env_vars`

1070 1126 

1071Type / Values1127Type / Values

1072 1128 

1073`boolean`1129`array<string>`

1074 1130 

1075Details1131Details

1076 1132 

1077Suppress reasoning events in both the TUI and `codex exec` output.1133Additional environment variables to whitelist for an MCP stdio server.

1078 1134 

1079Key1135Key

1080 1136 

1081`history.max_bytes`1137`mcp_servers.<id>.http_headers`

1082 1138 

1083Type / Values1139Type / Values

1084 1140 

1085`number`1141`map<string,string>`

1086 1142 

1087Details1143Details

1088 1144 

1089If set, caps the history file size in bytes by dropping oldest entries.1145Static HTTP headers included with each MCP HTTP request.

1090 1146 

1091Key1147Key

1092 1148 

1093`history.persistence`1149`mcp_servers.<id>.oauth_resource`

1094 1150 

1095Type / Values1151Type / Values

1096 1152 

1097`save-all | none`1153`string`

1098 1154 

1099Details1155Details

1100 1156 

1101Control whether Codex saves session transcripts to history.jsonl.1157Optional RFC 8707 OAuth resource parameter to include during MCP login.

1102 1158 

1103Key1159Key

1104 1160 

1105`instructions`1161`mcp_servers.<id>.required`

1106 1162 

1107Type / Values1163Type / Values

1108 1164 

1109`string`1165`boolean`

1110 1166 

1111Details1167Details

1112 1168 

1113Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.1169When true, fail startup/resume if this enabled MCP server cannot initialize.

1114 1170 

1115Key1171Key

1116 1172 

1117`log_dir`1173`mcp_servers.<id>.scopes`

1118 1174 

1119Type / Values1175Type / Values

1120 1176 

1121`string (path)`1177`array<string>`

1122 1178 

1123Details1179Details

1124 1180 

1125Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.1181OAuth scopes to request when authenticating to that MCP server.

1126 1182 

1127Key1183Key

1128 1184 

1129`mcp_oauth_callback_port`1185`mcp_servers.<id>.startup_timeout_ms`

1130 1186 

1131Type / Values1187Type / Values

1132 1188 

1133`integer`1189`number`

1134 1190 

1135Details1191Details

1136 1192 

1137Optional 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.1193Alias for `startup_timeout_sec` in milliseconds.

1138 1194 

1139Key1195Key

1140 1196 

1141`mcp_oauth_callback_url`1197`mcp_servers.<id>.startup_timeout_sec`

1142 1198 

1143Type / Values1199Type / Values

1144 1200 

1145`string`1201`number`

1146 1202 

1147Details1203Details

1148 1204 

1149Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.1205Override the default 10s startup timeout for an MCP server.

1150 1206 

1151Key1207Key

1152 1208 

1153`mcp_oauth_credentials_store`1209`mcp_servers.<id>.tool_timeout_sec`

1154 1210 

1155Type / Values1211Type / Values

1156 1212 

1157`auto | file | keyring`1213`number`

1158 1214 

1159Details1215Details

1160 1216 

1161Preferred store for MCP OAuth credentials.1217Override the default 60s per-tool timeout for an MCP server.

1162 1218 

1163Key1219Key

1164 1220 

1165`mcp_servers.<id>.args`1221`mcp_servers.<id>.url`

1166 1222 

1167Type / Values1223Type / Values

1168 1224 

1169`array<string>`1225`string`

1170 1226 

1171Details1227Details

1172 1228 

1173Arguments passed to the MCP stdio server command.1229Endpoint for an MCP streamable HTTP server.

1174 1230 

1175Key1231Key

1176 1232 

1177`mcp_servers.<id>.bearer_token_env_var`1233`memories.consolidation_model`

1178 1234 

1179Type / Values1235Type / Values

1180 1236 

1182 1238 

1183Details1239Details

1184 1240 

1185Environment variable sourcing the bearer token for an MCP HTTP server.1241Optional model override for global memory consolidation.

1186 1242 

1187Key1243Key

1188 1244 

1189`mcp_servers.<id>.command`1245`memories.extract_model`

1190 1246 

1191Type / Values1247Type / Values

1192 1248 

1194 1250 

1195Details1251Details

1196 1252 

1197Launcher command for an MCP stdio server.1253Optional model override for per-thread memory extraction.

1198 1254 

1199Key1255Key

1200 1256 

1201`mcp_servers.<id>.cwd`1257`memories.generate_memories`

1202 1258 

1203Type / Values1259Type / Values

1204 1260 

1205`string`1261`boolean`

1206 1262 

1207Details1263Details

1208 1264 

1209Working directory for the MCP stdio server process.1265When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.

1210 1266 

1211Key1267Key

1212 1268 

1213`mcp_servers.<id>.disabled_tools`1269`memories.max_raw_memories_for_consolidation`

1214 1270 

1215Type / Values1271Type / Values

1216 1272 

1217`array<string>`1273`number`

1218 1274 

1219Details1275Details

1220 1276 

1221Deny list applied after `enabled_tools` for the MCP server.1277Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.

1222 1278 

1223Key1279Key

1224 1280 

1225`mcp_servers.<id>.enabled`1281`memories.max_rollout_age_days`

1226 1282 

1227Type / Values1283Type / Values

1228 1284 

1229`boolean`1285`number`

1230 1286 

1231Details1287Details

1232 1288 

1233Disable an MCP server without removing its configuration.1289Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.

1234 1290 

1235Key1291Key

1236 1292 

1237`mcp_servers.<id>.enabled_tools`1293`memories.max_rollouts_per_startup`

1238 1294 

1239Type / Values1295Type / Values

1240 1296 

1241`array<string>`1297`number`

1242 1298 

1243Details1299Details

1244 1300 

1245Allow list of tool names exposed by the MCP server.1301Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.

1246 1302 

1247Key1303Key

1248 1304 

1249`mcp_servers.<id>.env`1305`memories.max_unused_days`

1250 1306 

1251Type / Values1307Type / Values

1252 1308 

1253`map<string,string>`1309`number`

1254 1310 

1255Details1311Details

1256 1312 

1257Environment variables forwarded to the MCP stdio server.1313Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.

1258 1314 

1259Key1315Key

1260 1316 

1261`mcp_servers.<id>.env_http_headers`1317`memories.min_rollout_idle_hours`

1262 1318 

1263Type / Values1319Type / Values

1264 1320 

1265`map<string,string>`1321`number`

1266 1322 

1267Details1323Details

1268 1324 

1269HTTP headers populated from environment variables for an MCP HTTP server.1325Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.

1270 1326 

1271Key1327Key

1272 1328 

1273`mcp_servers.<id>.env_vars`1329`memories.no_memories_if_mcp_or_web_search`

1274 1330 

1275Type / Values1331Type / Values

1276 1332 

1277`array<string>`1333`boolean`

1278 1334 

1279Details1335Details

1280 1336 

1281Additional environment variables to whitelist for an MCP stdio server.1337When `true`, threads that use MCP tool calls or web search are kept out of memory generation. Defaults to `false`.

1282 1338 

1283Key1339Key

1284 1340 

1285`mcp_servers.<id>.http_headers`1341`memories.use_memories`

1286 1342 

1287Type / Values1343Type / Values

1288 1344 

1289`map<string,string>`1345`boolean`

1290 1346 

1291Details1347Details

1292 1348 

1293Static HTTP headers included with each MCP HTTP request.1349When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.

1294 1350 

1295Key1351Key

1296 1352 

1297`mcp_servers.<id>.oauth_resource`1353`model`

1298 1354 

1299Type / Values1355Type / Values

1300 1356 

1302 1358 

1303Details1359Details

1304 1360 

1305Optional RFC 8707 OAuth resource parameter to include during MCP login.1361Model to use (e.g., `gpt-5.4`).

1306 1362 

1307Key1363Key

1308 1364 

1309`mcp_servers.<id>.required`1365`model_auto_compact_token_limit`

1310 1366 

1311Type / Values1367Type / Values

1312 1368 

1313`boolean`1369`number`

1314 1370 

1315Details1371Details

1316 1372 

1317When true, fail startup/resume if this enabled MCP server cannot initialize.1373Token threshold that triggers automatic history compaction (unset uses model defaults).

1318 1374 

1319Key1375Key

1320 1376 

1321`mcp_servers.<id>.scopes`1377`model_catalog_json`

1322 1378 

1323Type / Values1379Type / Values

1324 1380 

1325`array<string>`1381`string (path)`

1326 1382 

1327Details1383Details

1328 1384