config-reference.md Codex Docs, 2026-03-17 00:33 UTC → 2026-04-20 18:26 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 | 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.guardian_approval` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). Use with `approvals_reviewer = "guardian_subagent"`. |

56| `features.image_generation` | `boolean` | Enable the built-in image generation tool (under development). |54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

213| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |220| `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). |221| `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). |222| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

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

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

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

221| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |229| `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. |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. |

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

225 234 

226Key235Key

227 236 

325 334 

326Type / Values335Type / Values

327 336 

328`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 } }`

329 338 

330Details339Details

331 340 

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

333 342 

334Key343Key

335 344 

336`approval_policy.reject.mcp_elicitations`345`approval_policy.granular.mcp_elicitations`

337 346 

338Type / Values347Type / Values

339 348 

341 350 

342Details351Details

343 352 

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

345 354 

346Key355Key

347 356 

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

349 358 

350Type / Values359Type / Values

351 360 

353 362 

354Details363Details

355 364 

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

357 366 

358Key367Key

359 368 

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

361 370 

362Type / Values371Type / Values

363 372 

365 374 

366Details375Details

367 376 

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

369 414 

370Key415Key

371 416 

561 606 

562Key607Key

563 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 

564`developer_instructions`621`developer_instructions`

565 622 

566Type / Values623Type / Values

621 678 

622Key679Key

623 680 

624`features.apps_mcp_gateway`681`features.codex_hooks`

625 682 

626Type / Values683Type / Values

627 684 

629 686 

630Details687Details

631 688 

632Route 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).

633 690 

634Key691Key

635 692 

636`features.artifact`693`features.enable_request_compression`

637 694 

638Type / Values695Type / Values

639 696 

641 698 

642Details699Details

643 700 

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

645 702 

646Key703Key

647 704 

648`features.child_agents_md`705`features.fast_mode`

649 706 

650Type / Values707Type / Values

651 708 

653 710 

654Details711Details

655 712 

656Append 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).

657 714 

658Key715Key

659 716 

660`features.collaboration_modes`717`features.guardian_approval`

661 718 

662Type / Values719Type / Values

663 720 

665 722 

666Details723Details

667 724 

668Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key.725Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). Use with `approvals_reviewer = "guardian_subagent"`.

669 726 

670Key727Key

671 728 

672`features.default_mode_request_user_input`729`features.memories`

673 730 

674Type / Values731Type / Values

675 732 

677 734 

678Details735Details

679 736 

680Allow `request_user_input` in default collaboration mode (under development; off by default).737Enable [Memories](https://developers.openai.com/codex/memories) (off by default).

681 738 

682Key739Key

683 740 

684`features.elevated_windows_sandbox`741`features.multi_agent`

685 742 

686Type / Values743Type / Values

687 744 

689 746 

690Details747Details

691 748 

692Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it.749Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

693 750 

694Key751Key

695 752 

696`features.enable_request_compression`753`features.personality`

697 754 

698Type / Values755Type / Values

699 756 

701 758 

702Details759Details

703 760 

704Compress streaming request bodies with zstd when supported (stable; on by default).761Enable personality selection controls (stable; on by default).

705 762 

706Key763Key

707 764 

708`features.experimental_windows_sandbox`765`features.prevent_idle_sleep`

709 766 

710Type / Values767Type / Values

711 768 

713 770 

714Details771Details

715 772 

716Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it.773Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

717 774 

718Key775Key

719 776 

720`features.fast_mode`777`features.shell_snapshot`

721 778 

722Type / Values779Type / Values

723 780 

725 782 

726Details783Details

727 784 

728Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).785Snapshot shell environment to speed up repeated commands (stable; on by default).

729 786 

730Key787Key

731 788 

732`features.image_detail_original`789`features.shell_tool`

733 790 

734Type / Values791Type / Values

735 792 

737 794 

738Details795Details

739 796 

740Allow image outputs with `detail = "original"` on supported models (under development).797Enable the default `shell` tool for running commands (stable; on by default).

741 798 

742Key799Key

743 800 

744`features.image_generation`801`features.skill_mcp_dependency_install`

745 802 

746Type / Values803Type / Values

747 804 

749 806 

750Details807Details

751 808 

752Enable the built-in image generation tool (under development).809Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

753 810 

754Key811Key

755 812 

756`features.personality`813`features.undo`

757 814 

758Type / Values815Type / Values

759 816 

761 818 

762Details819Details

763 820 

764Enable personality selection controls (stable; on by default).821Enable undo support (stable; off by default).

765 822 

766Key823Key

767 824 

768`features.powershell_utf8`825`features.unified_exec`

769 826 

770Type / Values827Type / Values

771 828 

773 830 

774Details831Details

775 832 

776Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.833Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

777 834 

778Key835Key

779 836 

780`features.prevent_idle_sleep`837`features.web_search`

781 838 

782Type / Values839Type / Values

783 840 

785 842 

786Details843Details

787 844 

788Prevent the machine from sleeping while a turn is actively running (experimental; off by default).845Deprecated legacy toggle; prefer the top-level `web_search` setting.

789 846 

790Key847Key

791 848 

792`features.remote_models`849`features.web_search_cached`

793 850 

794Type / Values851Type / Values

795 852 

797 854 

798Details855Details

799 856 

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

801 858 

802Key859Key

803 860 

804`features.request_rule`861`features.web_search_request`

805 862 

806Type / Values863Type / Values

807 864 

809 866 

810Details867Details

811 868 

812Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.869Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.

813 870 

814Key871Key

815 872 

816`features.responses_websockets`873`feedback.enabled`

817 874 

818Type / Values875Type / Values

819 876 

821 878 

822Details879Details

823 880 

824Prefer the Responses API WebSocket transport for supported providers (under development).881Enable feedback submission via `/feedback` across Codex surfaces (default: true).

825 882 

826Key883Key

827 884 

828`features.responses_websockets_v2`885`file_opener`

829 886 

830Type / Values887Type / Values

831 888 

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

833 890 

834Details891Details

835 892 

836Enable Responses API WebSocket v2 mode (under development).893URI scheme used to open citations from Codex output (default: `vscode`).

837 894 

838Key895Key

839 896 

840`features.runtime_metrics`897`forced_chatgpt_workspace_id`

841 898 

842Type / Values899Type / Values

843 900 

844`boolean`901`string (uuid)`

845 902 

846Details903Details

847 904 

848Show runtime metrics summary in TUI turn separators (experimental).905Limit ChatGPT logins to a specific workspace identifier.

849 906 

850Key907Key

851 908 

852`features.search_tool`909`forced_login_method`

853 910 

854Type / Values911Type / Values

855 912 

856`boolean`913`chatgpt | api`

857 914 

858Details915Details

859 916 

860Legacy toggle for an older Apps discovery flow. Current builds do not use it.917Restrict Codex to a specific authentication method.

861 918 

862Key919Key

863 920 

864`features.shell_snapshot`921`hide_agent_reasoning`

865 922 

866Type / Values923Type / Values

867 924 

869 926 

870Details927Details

871 928 

872Snapshot shell environment to speed up repeated commands (stable; on by default).929Suppress reasoning events in both the TUI and `codex exec` output.

873 930 

874Key931Key

875 932 

876`features.shell_tool`933`history.max_bytes`

877 934 

878Type / Values935Type / Values

879 936 

880`boolean`937`number`

881 938 

882Details939Details

883 940 

884Enable the default `shell` tool for running commands (stable; on by default).941If set, caps the history file size in bytes by dropping oldest entries.

885 942 

886Key943Key

887 944 

888`features.skill_env_var_dependency_prompt`945`history.persistence`

889 946 

890Type / Values947Type / Values

891 948 

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

893 950 

894Details951Details

895 952 

896Prompt for missing skill environment-variable dependencies (under development).953Control whether Codex saves session transcripts to history.jsonl.

897 954 

898Key955Key

899 956 

900`features.skill_mcp_dependency_install`957`instructions`

901 958 

902Type / Values959Type / Values

903 960 

904`boolean`961`string`

905 962 

906Details963Details

907 964 

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

909 966 

910Key967Key

911 968 

912`features.sqlite`969`log_dir`

913 970 

914Type / Values971Type / Values

915 972 

916`boolean`973`string (path)`

917 974 

918Details975Details

919 976 

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

921 978 

922Key979Key

923 980 

924`features.steer`981`mcp_oauth_callback_port`

925 982 

926Type / Values983Type / Values

927 984 

928`boolean`985`integer`

929 986 

930Details987Details

931 988 

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

933 990 

934Key991Key

935 992 

936`features.undo`993`mcp_oauth_callback_url`

937 994 

938Type / Values995Type / Values

939 996 

940`boolean`997`string`

941 998 

942Details999Details

943 1000 

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

945 1002 

946Key1003Key

947 1004 

948`features.unified_exec`1005`mcp_oauth_credentials_store`

949 1006 

950Type / Values1007Type / Values

951 1008 

952`boolean`1009`auto | file | keyring`

953 1010 

954Details1011Details

955 1012 

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

957 1014 

958Key1015Key

959 1016 

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

961 1018 

962Type / Values1019Type / Values

963 1020 

964`boolean`1021`array<string>`

965 1022 

966Details1023Details

967 1024 

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

969 1026 

970Key1027Key

971 1028 

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

973 1030 

974Type / Values1031Type / Values

975 1032 

976`boolean`1033`string`

977 1034 

978Details1035Details

979 1036 

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

981 1038 

982Key1039Key

983 1040 

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

985 1042 

986Type / Values1043Type / Values

987 1044 

988`boolean`1045`string`

989 1046 

990Details1047Details

991 1048 

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

993 1050 

994Key1051Key

995 1052 

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

997 1054 

998Type / Values1055Type / Values

999 1056 

1000`boolean`1057`string`

1001 1058 

1002Details1059Details

1003 1060 

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

1005 1062 

1006Key1063Key

1007 1064 

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

1009 1066 

1010Type / Values1067Type / Values

1011 1068 

1012`boolean`1069`array<string>`

1013 1070 

1014Details1071Details

1015 1072 

1016Enable feedback submission via `/feedback` across Codex surfaces (default: true).1073Deny list applied after `enabled_tools` for the MCP server.

1017 1074 

1018Key1075Key

1019 1076 

1020`file_opener`1077`mcp_servers.<id>.enabled`

1021 1078 

1022Type / Values1079Type / Values

1023 1080 

1024`vscode | vscode-insiders | windsurf | cursor | none`1081`boolean`

1025 1082 

1026Details1083Details

1027 1084 

1028URI scheme used to open citations from Codex output (default: `vscode`).1085Disable an MCP server without removing its configuration.

1029 1086 

1030Key1087Key

1031 1088 

1032`forced_chatgpt_workspace_id`1089`mcp_servers.<id>.enabled_tools`

1033 1090 

1034Type / Values1091Type / Values

1035 1092 

1036`string (uuid)`1093`array<string>`

1037 1094 

1038Details1095Details

1039 1096 

1040Limit ChatGPT logins to a specific workspace identifier.1097Allow list of tool names exposed by the MCP server.

1041 1098 

1042Key1099Key

1043 1100 

1044`forced_login_method`1101`mcp_servers.<id>.env`

1045 1102 

1046Type / Values1103Type / Values

1047 1104 

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

1049 1106 

1050Details1107Details

1051 1108 

1052Restrict Codex to a specific authentication method.1109Environment variables forwarded to the MCP stdio server.

1053 1110 

1054Key1111Key

1055 1112 

1056`hide_agent_reasoning`1113`mcp_servers.<id>.env_http_headers`

1057 1114 

1058Type / Values1115Type / Values

1059 1116 

1060`boolean`1117`map<string,string>`

1061 1118 

1062Details1119Details

1063 1120 

1064Suppress reasoning events in both the TUI and `codex exec` output.1121HTTP headers populated from environment variables for an MCP HTTP server.

1065 1122 

1066Key1123Key

1067 1124 

1068`history.max_bytes`1125`mcp_servers.<id>.env_vars`

1069 1126 

1070Type / Values1127Type / Values

1071 1128 

1072`number`1129`array<string>`

1073 1130 

1074Details1131Details

1075 1132 

1076If set, caps the history file size in bytes by dropping oldest entries.1133Additional environment variables to whitelist for an MCP stdio server.

1077 1134 

1078Key1135Key

1079 1136 

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

1081 1138 

1082Type / Values1139Type / Values

1083 1140 

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

1085 1142 

1086Details1143Details

1087 1144 

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

1089 1146 

1090Key1147Key

1091 1148 

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

1093 1150 

1094Type / Values1151Type / Values

1095 1152 

1097 1154 

1098Details1155Details

1099 1156 

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

1101 1158 

1102Key1159Key

1103 1160 

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

1105 1162 

1106Type / Values1163Type / Values

1107 1164 

1108`string (path)`1165`boolean`

1109 1166 

1110Details1167Details

1111 1168 

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

1113 1170 

1114Key1171Key

1115 1172 

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

1117 1174 

1118Type / Values1175Type / Values

1119 1176 

1120`integer`1177`array<string>`

1121 1178 

1122Details1179Details

1123 1180 

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

1125 1182 

1126Key1183Key

1127 1184 

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

1129 1186 

1130Type / Values1187Type / Values

1131 1188 

1132`string`1189`number`

1133 1190 

1134Details1191Details

1135 1192 

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

1137 1194 

1138Key1195Key

1139 1196 

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

1141 1198 

1142Type / Values1199Type / Values

1143 1200 

1144`auto | file | keyring`1201`number`

1145 1202 

1146Details1203Details

1147 1204 

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

1149 1206 

1150Key1207Key

1151 1208 

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

1153 1210 

1154Type / Values1211Type / Values

1155 1212 

1156`array<string>`1213`number`

1157 1214 

1158Details1215Details

1159 1216 

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

1161 1218 

1162Key1219Key

1163 1220 

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

1165 1222 

1166Type / Values1223Type / Values

1167 1224 

1169 1226 

1170Details1227Details

1171 1228 

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

1173 1230 

1174Key1231Key

1175 1232 

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

1177 1234 

1178Type / Values1235Type / Values

1179 1236 

1181 1238 

1182Details1239Details

1183 1240 

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

1185 1242 

1186Key1243Key

1187 1244 

1188`mcp_servers.<id>.cwd`1245`memories.extract_model`

1189 1246 

1190Type / Values1247Type / Values

1191 1248 

1193 1250 

1194Details1251Details

1195 1252 

1196Working directory for the MCP stdio server process.1253Optional model override for per-thread memory extraction.

1197 1254 

1198Key1255Key

1199 1256 

1200`mcp_servers.<id>.disabled_tools`1257`memories.generate_memories`

1201 1258 

1202Type / Values1259Type / Values

1203 1260 

1204`array<string>`1261`boolean`

1205 1262 

1206Details1263Details

1207 1264 

1208Deny list applied after `enabled_tools` for the MCP server.1265When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.

1209 1266 

1210Key1267Key

1211 1268 

1212`mcp_servers.<id>.enabled`1269`memories.max_raw_memories_for_consolidation`

1213 1270 

1214Type / Values1271Type / Values

1215 1272 

1216`boolean`1273`number`

1217 1274 

1218Details1275Details

1219 1276 

1220Disable an MCP server without removing its configuration.1277Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.

1221 1278 

1222Key1279Key

1223 1280 

1224`mcp_servers.<id>.enabled_tools`1281`memories.max_rollout_age_days`

1225 1282 

1226Type / Values1283Type / Values

1227 1284 

1228`array<string>`1285`number`

1229 1286 

1230Details1287Details

1231 1288 

1232Allow list of tool names exposed by the MCP server.1289Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.

1233 1290 

1234Key1291Key

1235 1292 

1236`mcp_servers.<id>.env`1293`memories.max_rollouts_per_startup`

1237 1294 

1238Type / Values1295Type / Values

1239 1296 

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

1241 1298 

1242Details1299Details

1243 1300 

1244Environment variables forwarded to the MCP stdio server.1301Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.

1245 1302 

1246Key1303Key

1247 1304 

1248`mcp_servers.<id>.env_http_headers`1305`memories.max_unused_days`

1249 1306 

1250Type / Values1307Type / Values

1251 1308 

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

1253 1310 

1254Details1311Details

1255 1312 

1256HTTP headers populated from environment variables for an MCP HTTP server.1313Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.

1257 1314 

1258Key1315Key

1259 1316 

1260`mcp_servers.<id>.env_vars`1317`memories.min_rollout_idle_hours`

1261 1318 

1262Type / Values1319Type / Values

1263 1320 

1264`array<string>`1321`number`

1265 1322 

1266Details1323Details

1267 1324 

1268Additional environment variables to whitelist for an MCP stdio server.1325Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.

1269 1326 

1270Key1327Key

1271 1328 

1272`mcp_servers.<id>.http_headers`1329`memories.no_memories_if_mcp_or_web_search`

1273 1330 

1274Type / Values1331Type / Values

1275 1332 

1276`map<string,string>`1333`boolean`

1277 1334 

1278Details1335Details

1279 1336 

1280Static HTTP headers included with each MCP HTTP request.1337When `true`, threads that use MCP tool calls or web search are kept out of memory generation. Defaults to `false`.

1281 1338 

1282Key1339Key

1283 1340 

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

1285 1342 

1286Type / Values1343Type / Values

1287 1344 

1288`string`1345`boolean`

1289 1346 

1290Details1347Details

1291 1348 

1292Optional RFC 8707 OAuth resource parameter to include during MCP login.1349When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.

1293 1350 

1294Key1351Key

1295 1352 

1296`mcp_servers.<id>.required`1353`model`

1297 1354 

1298Type / Values1355Type / Values

1299 1356 

1300`boolean`1357`string`

1301 1358 

1302Details1359Details

1303 1360 

1304When true, fail startup/resume if this enabled MCP server cannot initialize.1361Model to use (e.g., `gpt-5.4`).

1305 1362 

1306Key1363Key

1307 1364 

1308`mcp_servers.<id>.scopes`1365`model_auto_compact_token_limit`

1309 1366 

1310Type / Values1367Type / Values

1311 1368 

1312`array<string>`1369`number`

1313 1370 

1314Details1371Details

1315 1372 

1316OAuth scopes to request when authenticating to that MCP server.1373Token threshold that triggers automatic history compaction (unset uses model defaults).

1317 1374 

1318Key1375Key

1319 1376 

1320`mcp_servers.<id>.startup_timeout_ms`1377`model_catalog_json`

1321 1378 

1322Type / Values1379Type / Values

1323 1380 

1324`number`1381`string (path)`

1325 1382 

1326Details1383Details

1327 1384 

1328Alias for `startup_timeout_sec` in milliseconds.1385Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.

1329 1386 

1330Key1387Key

1331 1388 

1332`mcp_servers.<id>.startup_timeout_sec`1389`model_context_window`

1333 1390 

1334Type / Values1391Type / Values

1335 1392 

1337 1394 

1338Details1395Details