config-reference.md Codex Docs, 2026-03-16 18:25 UTC → 2026-04-23 18:31 UTC

18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |

19| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |19| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |

20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |

21| `approval_policy` | `untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |21| `approval_policy` | `untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |

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

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

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

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

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

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

25| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |28| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |

26| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |29| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |

27| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |30| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |

32| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |35| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |

33| `apps.<id>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. |36| `apps.<id>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. |

34| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |37| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |

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

35| `background_terminal_max_timeout` | `number` | Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key. |39| `background_terminal_max_timeout` | `number` | Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key. |

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

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

38| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |42| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |

39| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |43| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |

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

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

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

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

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

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

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

46| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |51| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (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). |52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

53| `features.experimental_windows_sandbox` | `boolean` | Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it. |

54| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |53| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |

55| `features.image_detail_original` | `boolean` | Allow image outputs with `detail = "original"` on supported models (under development). |54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |

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

57| `features.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). |56| `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). |57| `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). |58| `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). |59| `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). |60| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |

71| `features.sqlite` | `boolean` | Enable SQLite-backed state persistence (stable; on by default). |

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

73| `features.undo` | `boolean` | Enable undo support (stable; off by default). |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"`. |

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

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

99| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |86| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |

100| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |87| `mcp_servers.<id>.env_vars` | `array<string | { name = string, source = "local" | "remote" }>` | Additional environment variables to whitelist for an MCP stdio server. String entries default to `source = "local"`; use `source = "remote"` only with executor-backed remote stdio. |

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

101| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |89| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |

102| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |90| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |

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

106| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |94| `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. |95| `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. |96| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |

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

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

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

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

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

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

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

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

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

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

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

110| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |108| `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. |109| `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. |110| `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`. |111| `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`). |112| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |

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

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

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

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

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

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

119| `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. |120| `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. |121| `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. |122| `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. |142| `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. |143| `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. |144| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |

145| `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). |146| `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`). |147| `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. |148| `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. |161| `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. |162| `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. |163| `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. |164| `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. |165| `permissions.<name>.filesystem.":project_roots".<subpath-or-glob>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`. |

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

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

162| `permissions.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |168| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

163| `permissions.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |169| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

164| `permissions.network.dangerously_allow_non_loopback_admin` | `boolean` | Permit non-loopback bind addresses for the managed proxy admin listener. |170| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

165| `permissions.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |171| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

166| `permissions.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |172| `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. |

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

168| `permissions.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |174| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

169| `permissions.network.enabled` | `boolean` | Enable the managed network proxy configuration for subprocesses. |175| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |

170| `permissions.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |176| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |

171| `permissions.network.proxy_url` | `string` | HTTP proxy endpoint used by the managed network proxy. |177| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |

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

179| `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`. |180| `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. |181| `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`). |182| `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. |202| `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. |203| `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"`. |204| `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. |205| `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. |206| `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. |207| `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. |208| `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. |216| `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. |217| `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. |218| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |

219| `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`. |220| `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. |221| `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. |222| `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). |223| `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). |224| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

217| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |225| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |

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

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

219| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |228| `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). |229| `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. |230| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

231| `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). |232| `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. |233| `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). |234| `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. |235| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |

236| `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 237 

227Key238Key

228 239 

326 337 

327Type / Values338Type / Values

328 339 

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

330 341 

331Details342Details

332 343 

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.344Controls 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 345 

335Key346Key

336 347 

337`approval_policy.reject.mcp_elicitations`348`approval_policy.granular.mcp_elicitations`

338 349 

339Type / Values350Type / Values

340 351 

342 353 

343Details354Details

344 355 

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

346 357 

347Key358Key

348 359 

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

350 361 

351Type / Values362Type / Values

352 363 

354 365 

355Details366Details

356 367 

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

358 369 

359Key370Key

360 371 

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

362 373 

363Type / Values374Type / Values

364 375 

366 377 

367Details378Details

368 379 

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

381 

382Key

383 

384`approval_policy.granular.sandbox_approval`

385 

386Type / Values

387 

388`boolean`

389 

390Details

391 

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

393 

394Key

395 

396`approval_policy.granular.skill_approval`

397 

398Type / Values

399 

400`boolean`

401 

402Details

403 

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

405 

406Key

407 

408`approvals_reviewer`

409 

410Type / Values

411 

412`user | auto_review`

413 

414Details

415 

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

370 417 

371Key418Key

372 419 

490 537 

491Key538Key

492 539 

540`auto_review.policy`

541 

542Type / Values

543 

544`string`

545 

546Details

547 

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

549 

550Key

551 

493`background_terminal_max_timeout`552`background_terminal_max_timeout`

494 553 

495Type / Values554Type / Values

562 621 

563Key622Key

564 623 

624`default_permissions`

625 

626Type / Values

627 

628`string`

629 

630Details

631 

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

633 

634Key

635 

565`developer_instructions`636`developer_instructions`

566 637 

567Type / Values638Type / Values

622 693 

623Key694Key

624 695 

625`features.apps_mcp_gateway`696`features.codex_hooks`

626 697 

627Type / Values698Type / Values

628 699 

630 701 

631Details702Details

632 703 

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

634 705 

635Key706Key

636 707 

637`features.artifact`708`features.enable_request_compression`

638 709 

639Type / Values710Type / Values

640 711 

642 713 

643Details714Details

644 715 

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

646 717 

647Key718Key

648 719 

649`features.child_agents_md`720`features.fast_mode`

650 721 

651Type / Values722Type / Values

652 723 

654 725 

655Details726Details

656 727 

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

658 729 

659Key730Key

660 731 

661`features.collaboration_modes`732`features.memories`

662 733 

663Type / Values734Type / Values

664 735 

666 737 

667Details738Details

668 739 

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

670 741 

671Key742Key

672 743 

673`features.default_mode_request_user_input`744`features.multi_agent`

674 745 

675Type / Values746Type / Values

676 747 

678 749 

679Details750Details

680 751 

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

682 753 

683Key754Key

684 755 

685`features.elevated_windows_sandbox`756`features.personality`

686 757 

687Type / Values758Type / Values

688 759 

690 761 

691Details762Details

692 763 

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

694 765 

695Key766Key

696 767 

697`features.enable_request_compression`768`features.prevent_idle_sleep`

698 769 

699Type / Values770Type / Values

700 771 

702 773 

703Details774Details

704 775 

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

706 777 

707Key778Key

708 779 

709`features.experimental_windows_sandbox`780`features.shell_snapshot`

710 781 

711Type / Values782Type / Values

712 783 

714 785 

715Details786Details

716 787 

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

718 789 

719Key790Key

720 791 

721`features.fast_mode`792`features.shell_tool`

722 793 

723Type / Values794Type / Values

724 795 

726 797 

727Details798Details

728 799 

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

730 801 

731Key802Key

732 803 

733`features.image_detail_original`804`features.skill_mcp_dependency_install`

734 805 

735Type / Values806Type / Values

736 807 

738 809 

739Details810Details

740 811 

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

742 813 

743Key814Key

744 815 

745`features.image_generation`816`features.undo`

746 817 

747Type / Values818Type / Values

748 819 

750 821 

751Details822Details

752 823 

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

754 825 

755Key826Key

756 827 

757`features.multi_agent`828`features.unified_exec`

758 829 

759Type / Values830Type / Values

760 831 

762 833 

763Details834Details

764 835 

765Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default).836Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

766 837 

767Key838Key

768 839 

769`features.personality`840`features.web_search`

770 841 

771Type / Values842Type / Values

772 843 

774 845 

775Details846Details

776 847 

777Enable personality selection controls (stable; on by default).848Deprecated legacy toggle; prefer the top-level `web_search` setting.

778 849 

779Key850Key

780 851 

781`features.powershell_utf8`852`features.web_search_cached`

782 853 

783Type / Values854Type / Values

784 855 

786 857 

787Details858Details

788 859 

789Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.860Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.

790 861 

791Key862Key

792 863 

793`features.prevent_idle_sleep`864`features.web_search_request`

794 865 

795Type / Values866Type / Values

796 867 

798 869 

799Details870Details

800 871 

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

802 873 

803Key874Key

804 875 

805`features.remote_models`876`feedback.enabled`

806 877 

807Type / Values878Type / Values

808 879 

810 881 

811Details882Details

812 883 

813Legacy toggle for an older remote-model readiness flow. Current builds do not use it.884Enable feedback submission via `/feedback` across Codex surfaces (default: true).

814 885 

815Key886Key

816 887 

817`features.request_rule`888`file_opener`

818 889 

819Type / Values890Type / Values

820 891 

821`boolean`892`vscode | vscode-insiders | windsurf | cursor | none`

822 893 

823Details894Details

824 895 

825Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.896URI scheme used to open citations from Codex output (default: `vscode`).

826 897 

827Key898Key

828 899 

829`features.responses_websockets`900`forced_chatgpt_workspace_id`

830 901 

831Type / Values902Type / Values

832 903 

833`boolean`904`string (uuid)`

834 905 

835Details906Details

836 907 

837Prefer the Responses API WebSocket transport for supported providers (under development).908Limit ChatGPT logins to a specific workspace identifier.

838 909 

839Key910Key

840 911 

841`features.responses_websockets_v2`912`forced_login_method`

842 913 

843Type / Values914Type / Values

844 915 

845`boolean`916`chatgpt | api`

846 917 

847Details918Details

848 919 

849Enable Responses API WebSocket v2 mode (under development).920Restrict Codex to a specific authentication method.

850 921 

851Key922Key

852 923 

853`features.runtime_metrics`924`hide_agent_reasoning`

854 925 

855Type / Values926Type / Values

856 927 

858 929 

859Details930Details

860 931 

861Show runtime metrics summary in TUI turn separators (experimental).932Suppress reasoning events in both the TUI and `codex exec` output.

862 933 

863Key934Key

864 935 

865`features.search_tool`936`history.max_bytes`

866 937 

867Type / Values938Type / Values

868 939 

869`boolean`940`number`

870 941 

871Details942Details

872 943 

873Legacy toggle for an older Apps discovery flow. Current builds do not use it.944If set, caps the history file size in bytes by dropping oldest entries.

874 945 

875Key946Key

876 947 

877`features.shell_snapshot`948`history.persistence`

878 949 

879Type / Values950Type / Values

880 951 

881`boolean`952`save-all | none`

882 953 

883Details954Details

884 955 

885Snapshot shell environment to speed up repeated commands (stable; on by default).956Control whether Codex saves session transcripts to history.jsonl.

886 957 

887Key958Key

888 959 

889`features.shell_tool`960`instructions`

890 961 

891Type / Values962Type / Values

892 963 

893`boolean`964`string`

894 965 

895Details966Details

896 967 

897Enable the default `shell` tool for running commands (stable; on by default).968Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.

898 969 

899Key970Key

900 971 

901`features.skill_env_var_dependency_prompt`972`log_dir`

902 973 

903Type / Values974Type / Values

904 975 

905`boolean`976`string (path)`

906 977 

907Details978Details

908 979 

909Prompt for missing skill environment-variable dependencies (under development).980Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.

910 981 

911Key982Key

912 983 

913`features.skill_mcp_dependency_install`984`mcp_oauth_callback_port`

914 985 

915Type / Values986Type / Values

916 987 

917`boolean`988`integer`

918 989 

919Details990Details

920 991 

921Allow prompting and installing missing MCP dependencies for skills (stable; on by default).992Optional 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.

922 993 

923Key994Key

924 995 

925`features.sqlite`996`mcp_oauth_callback_url`

926 997 

927Type / Values998Type / Values

928 999 

929`boolean`1000`string`

930 1001 

931Details1002Details

932 1003 

933Enable SQLite-backed state persistence (stable; on by default).1004Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.

934 1005 

935Key1006Key

936 1007 

937`features.steer`1008`mcp_oauth_credentials_store`

938 1009 

939Type / Values1010Type / Values

940 1011 

941`boolean`1012`auto | file | keyring`

942 1013 

943Details1014Details

944 1015 

945Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.1016Preferred store for MCP OAuth credentials.

946 1017 

947Key1018Key

948 1019 

949`features.undo`1020`mcp_servers.<id>.args`

950 1021 

951Type / Values1022Type / Values

952 1023 

953`boolean`1024`array<string>`

954 1025 

955Details1026Details

956 1027 

957Enable undo support (stable; off by default).1028Arguments passed to the MCP stdio server command.

958 1029 

959Key1030Key

960 1031 

961`features.unified_exec`1032`mcp_servers.<id>.bearer_token_env_var`

962 1033 

963Type / Values1034Type / Values

964 1035 

965`boolean`1036`string`

966 1037 

967Details1038Details

968 1039 

969Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).1040Environment variable sourcing the bearer token for an MCP HTTP server.

970 1041 

971Key1042Key

972 1043 

973`features.use_linux_sandbox_bwrap`1044`mcp_servers.<id>.command`

974 1045 

975Type / Values1046Type / Values

976 1047 

977`boolean`1048`string`

978 1049 

979Details1050Details

980 1051 

981Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).1052Launcher command for an MCP stdio server.

982 1053 

983Key1054Key

984 1055 

985`features.web_search`1056`mcp_servers.<id>.cwd`

986 1057 

987Type / Values1058Type / Values

988 1059 

989`boolean`1060`string`

990 1061 

991Details1062Details

992 1063 

993Deprecated legacy toggle; prefer the top-level `web_search` setting.1064Working directory for the MCP stdio server process.

994 1065 

995Key1066Key

996 1067 

997`features.web_search_cached`1068`mcp_servers.<id>.disabled_tools`

998 1069 

999Type / Values1070Type / Values

1000 1071 

1001`boolean`1072`array<string>`

1002 1073 

1003Details1074Details

1004 1075 

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

1006 1077 

1007Key1078Key

1008 1079 

1009`features.web_search_request`1080`mcp_servers.<id>.enabled`

1010 1081 

1011Type / Values1082Type / Values

1012 1083 

1014 1085 

1015Details1086Details

1016 1087 

1017Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.1088Disable an MCP server without removing its configuration.

1018 1089 

1019Key1090Key

1020 1091 

1021`feedback.enabled`1092`mcp_servers.<id>.enabled_tools`

1022 1093 

1023Type / Values1094Type / Values

1024 1095 

1025`boolean`1096`array<string>`

1026 1097 

1027Details1098Details

1028 1099 

1029Enable feedback submission via `/feedback` across Codex surfaces (default: true).1100Allow list of tool names exposed by the MCP server.

1030 1101 

1031Key1102Key

1032 1103 

1033`file_opener`1104`mcp_servers.<id>.env`

1034 1105 

1035Type / Values1106Type / Values

1036 1107 

1037`vscode | vscode-insiders | windsurf | cursor | none`1108`map<string,string>`

1038 1109 

1039Details1110Details

1040 1111 

1041URI scheme used to open citations from Codex output (default: `vscode`).1112Environment variables forwarded to the MCP stdio server.

1042 1113 

1043Key1114Key

1044 1115 

1045`forced_chatgpt_workspace_id`1116`mcp_servers.<id>.env_http_headers`

1046 1117 

1047Type / Values1118Type / Values

1048 1119 

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

1050 1121 

1051Details1122Details

1052 1123 

1053Limit ChatGPT logins to a specific workspace identifier.1124HTTP headers populated from environment variables for an MCP HTTP server.

1054 1125 

1055Key1126Key

1056 1127 

1057`forced_login_method`1128`mcp_servers.<id>.env_vars`

1058 1129 

1059Type / Values1130Type / Values

1060 1131 

1061`chatgpt | api`1132`array<string | { name = string, source = "local" | "remote" }>`

1062 1133 

1063Details1134Details

1064 1135 

1065Restrict Codex to a specific authentication method.1136Additional environment variables to whitelist for an MCP stdio server. String entries default to `source = "local"`; use `source = "remote"` only with executor-backed remote stdio.

1066 1137 

1067Key1138Key

1068 1139 

1069`hide_agent_reasoning`1140`mcp_servers.<id>.experimental_environment`

1070 1141 

1071Type / Values1142Type / Values

1072 1143 

1073`boolean`1144`local | remote`

1074 1145 

1075Details1146Details

1076 1147 

1077Suppress reasoning events in both the TUI and `codex exec` output.1148Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.

1078 1149 

1079Key1150Key

1080 1151 

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

1082 1153 

1083Type / Values1154Type / Values

1084 1155 

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

1086 1157 

1087Details1158Details

1088 1159 

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

1090 1161 

1091Key1162Key

1092 1163 

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

1094 1165 

1095Type / Values1166Type / Values

1096 1167 

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

1098 1169 

1099Details1170Details

1100 1171 

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

1102 1173 

1103Key1174Key

1104 1175 

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

1106 1177 

1107Type / Values1178Type / Values

1108 1179 

1109`string`1180`boolean`

1110 1181 

1111Details1182Details

1112 1183 

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

1114 1185 

1115Key1186Key

1116 1187 

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

1118 1189 

1119Type / Values1190Type / Values

1120 1191 

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

1122 1193 

1123Details1194Details

1124 1195 

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

1126 1197 

1127Key1198Key

1128 1199 

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

1130 1201 

1131Type / Values1202Type / Values

1132 1203 

1133`integer`1204`number`

1134 1205 

1135Details1206Details

1136 1207 

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.1208Alias for `startup_timeout_sec` in milliseconds.

1138 1209 

1139Key1210Key

1140 1211 

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

1142 1213 

1143Type / Values1214Type / Values

1144 1215 

1145`string`1216`number`

1146 1217 

1147Details1218Details

1148 1219 

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

1150 1221 

1151Key1222Key

1152 1223 

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

1154 1225 

1155Type / Values1226Type / Values

1156 1227 

1157`auto | file | keyring`1228`number`

1158 1229 

1159Details1230Details

1160 1231 

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

1162 1233 

1163Key1234Key

1164 1235 

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

1166 1237 

1167Type / Values1238Type / Values

1168 1239 

1169`array<string>`1240`string`

1170 1241 

1171Details1242Details

1172 1243 

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

1174 1245 

1175Key1246Key

1176 1247 

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

1178 1249 

1179Type / Values1250Type / Values

1180 1251 

1182 1253 

1183Details1254Details

1184 1255 

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

1186 1257 

1187Key1258Key

1188 1259 

1189`mcp_servers.<id>.command`1260`memories.disable_on_external_context`

1190 1261 

1191Type / Values1262Type / Values

1192 1263 

1193`string`1264`boolean`

1194 1265 

1195Details1266Details

1196 1267 

1197Launcher command for an MCP stdio server.1268When `true`, threads that use external context such as MCP tool calls, web search, or tool search are kept out of memory generation. Defaults to `false`. Legacy alias: `memories.no_memories_if_mcp_or_web_search`.

1198 1269 

1199Key1270Key

1200 1271 

1201`mcp_servers.<id>.cwd`1272`memories.extract_model`

1202 1273 

1203Type / Values1274Type / Values

1204 1275 

1206 1277 

1207Details1278Details

1208 1279 

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

1210 1281 

1211Key1282Key

1212 1283 

1213`mcp_servers.<id>.disabled_tools`1284`memories.generate_memories`

1214 1285 

1215Type / Values1286Type / Values

1216 1287 

1217`array<string>`1288`boolean`

1218 1289 

1219Details1290Details

1220 1291 

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

1222 1293 

1223Key1294Key

1224 1295 

1225`mcp_servers.<id>.enabled`1296`memories.max_raw_memories_for_consolidation`

1226 1297 

1227Type / Values1298Type / Values

1228 1299 

1229`boolean`1300`number`

1230 1301 

1231Details1302Details

1232 1303 

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

1234 1305 

1235Key1306Key

1236 1307 

1237`mcp_servers.<id>.enabled_tools`1308`memories.max_rollout_age_days`

1238 1309 

1239Type / Values1310Type / Values

1240 1311 

1241`array<string>`1312`number`

1242 1313 

1243Details1314Details

1244 1315 

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

1246 1317 

1247Key1318Key

1248 1319 

1249`mcp_servers.<id>.env`1320`memories.max_rollouts_per_startup`

1250 1321 

1251Type / Values1322Type / Values

1252 1323 

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

1254 1325 

1255Details1326Details

1256 1327 

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

1258 1329 

1259Key1330Key

1260 1331 

1261`mcp_servers.<id>.env_http_headers`1332`memories.max_unused_days`

1262 1333 

1263Type / Values1334Type / Values

1264 1335 

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

1266 1337 

1267Details1338Details

1268 1339 

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

1270 1341 

1271Key1342Key

1272 1343 

1273`mcp_servers.<id>.env_vars`1344`memories.min_rollout_idle_hours`

1274 1345 

1275Type / Values1346Type / Values

1276 1347 

1277`array<string>`1348`number`

1278 1349 

1279Details1350Details

1280 1351 

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

1282 1353 

1283Key1354Key

1284 1355 

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

1286 1357 

1287Type / Values1358Type / Values

1288 1359 

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

1290 1361 

1291Details1362Details

1292 1363 

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

1294 1365 

1295Key1366Key

1296 1367 

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

1298 1369 

1299Type / Values1370Type / Values

1300 1371 

1302 1373 

1303Details1374Details

1304 1375 

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

1306 1377 

1307Key1378Key

1308 1379 

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

1310 1381 

1311Type / Values1382Type / Values

1312 1383 

1313`boolean`1384`number`

1314 1385 

1315Details1386Details

1316 1387 

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