config-reference.md Codex Docs, 2026-03-17 00:33 UTC → 2026-04-24 18:20 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.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"`. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

193| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |201| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |

194| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |202| `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. |203| `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"`. |204| `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. |205| `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. |206| `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. |207| `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. |208| `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. |216| `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. |217| `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. |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`. |

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

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

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

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

217| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |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). |

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

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

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

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

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

225 237 

226Key238Key

227 239 

325 337 

326Type / Values338Type / Values

327 339 

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

329 341 

330Details342Details

331 343 

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

333 345 

334Key346Key

335 347 

336`approval_policy.reject.mcp_elicitations`348`approval_policy.granular.mcp_elicitations`

337 349 

338Type / Values350Type / Values

339 351 

341 353 

342Details354Details

343 355 

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

345 357 

346Key358Key

347 359 

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

349 361 

350Type / Values362Type / Values

351 363 

353 365 

354Details366Details

355 367 

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

357 369 

358Key370Key

359 371 

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

361 373 

362Type / Values374Type / Values

363 375 

365 377 

366Details378Details

367 379 

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

369 417 

370Key418Key

371 419 

489 537 

490Key538Key

491 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 

492`background_terminal_max_timeout`552`background_terminal_max_timeout`

493 553 

494Type / Values554Type / Values

561 621 

562Key622Key

563 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 

564`developer_instructions`636`developer_instructions`

565 637 

566Type / Values638Type / Values

621 693 

622Key694Key

623 695 

624`features.apps_mcp_gateway`696`features.codex_hooks`

625 697 

626Type / Values698Type / Values

627 699 

629 701 

630Details702Details

631 703 

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

633 705 

634Key706Key

635 707 

636`features.artifact`708`features.enable_request_compression`

637 709 

638Type / Values710Type / Values

639 711 

641 713 

642Details714Details

643 715 

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

645 717 

646Key718Key

647 719 

648`features.child_agents_md`720`features.fast_mode`

649 721 

650Type / Values722Type / Values

651 723 

653 725 

654Details726Details

655 727 

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

657 729 

658Key730Key

659 731 

660`features.collaboration_modes`732`features.memories`

661 733 

662Type / Values734Type / Values

663 735 

665 737 

666Details738Details

667 739 

668Legacy 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).

669 741 

670Key742Key

671 743 

672`features.default_mode_request_user_input`744`features.multi_agent`

673 745 

674Type / Values746Type / Values

675 747 

677 749 

678Details750Details

679 751 

680Allow `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).

681 753 

682Key754Key

683 755 

684`features.elevated_windows_sandbox`756`features.personality`

685 757 

686Type / Values758Type / Values

687 759 

689 761 

690Details762Details

691 763 

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

693 765 

694Key766Key

695 767 

696`features.enable_request_compression`768`features.prevent_idle_sleep`

697 769 

698Type / Values770Type / Values

699 771 

701 773 

702Details774Details

703 775 

704Compress 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).

705 777 

706Key778Key

707 779 

708`features.experimental_windows_sandbox`780`features.shell_snapshot`

709 781 

710Type / Values782Type / Values

711 783 

713 785 

714Details786Details

715 787 

716Legacy 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).

717 789 

718Key790Key

719 791 

720`features.fast_mode`792`features.shell_tool`

721 793 

722Type / Values794Type / Values

723 795 

725 797 

726Details798Details

727 799 

728Enable 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).

729 801 

730Key802Key

731 803 

732`features.image_detail_original`804`features.skill_mcp_dependency_install`

733 805 

734Type / Values806Type / Values

735 807 

737 809 

738Details810Details

739 811 

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

741 813 

742Key814Key

743 815 

744`features.image_generation`816`features.undo`

745 817 

746Type / Values818Type / Values

747 819 

749 821 

750Details822Details

751 823 

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

753 825 

754Key826Key

755 827 

756`features.personality`828`features.unified_exec`

757 829 

758Type / Values830Type / Values

759 831 

761 833 

762Details834Details

763 835 

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

765 837 

766Key838Key

767 839 

768`features.powershell_utf8`840`features.web_search`

769 841 

770Type / Values842Type / Values

771 843 

773 845 

774Details846Details

775 847 

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

777 849 

778Key850Key

779 851 

780`features.prevent_idle_sleep`852`features.web_search_cached`

781 853 

782Type / Values854Type / Values

783 855 

785 857 

786Details858Details

787 859 

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

789 861 

790Key862Key

791 863 

792`features.remote_models`864`features.web_search_request`

793 865 

794Type / Values866Type / Values

795 867 

797 869 

798Details870Details

799 871 

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

801 873 

802Key874Key

803 875 

804`features.request_rule`876`feedback.enabled`

805 877 

806Type / Values878Type / Values

807 879 

809 881 

810Details882Details

811 883 

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

813 885 

814Key886Key

815 887 

816`features.responses_websockets`888`file_opener`

817 889 

818Type / Values890Type / Values

819 891 

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

821 893 

822Details894Details

823 895 

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

825 897 

826Key898Key

827 899 

828`features.responses_websockets_v2`900`forced_chatgpt_workspace_id`

829 901 

830Type / Values902Type / Values

831 903 

832`boolean`904`string (uuid)`

833 905 

834Details906Details

835 907 

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

837 909 

838Key910Key

839 911 

840`features.runtime_metrics`912`forced_login_method`

841 913 

842Type / Values914Type / Values

843 915 

844`boolean`916`chatgpt | api`

845 917 

846Details918Details

847 919 

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

849 921 

850Key922Key

851 923 

852`features.search_tool`924`hide_agent_reasoning`

853 925 

854Type / Values926Type / Values

855 927 

857 929 

858Details930Details

859 931 

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

861 933 

862Key934Key

863 935 

864`features.shell_snapshot`936`history.max_bytes`

865 937 

866Type / Values938Type / Values

867 939 

868`boolean`940`number`

869 941 

870Details942Details

871 943 

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

873 945 

874Key946Key

875 947 

876`features.shell_tool`948`history.persistence`

877 949 

878Type / Values950Type / Values

879 951 

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

881 953 

882Details954Details

883 955 

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

885 957 

886Key958Key

887 959 

888`features.skill_env_var_dependency_prompt`960`instructions`

889 961 

890Type / Values962Type / Values

891 963 

892`boolean`964`string`

893 965 

894Details966Details

895 967 

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

897 969 

898Key970Key

899 971 

900`features.skill_mcp_dependency_install`972`log_dir`

901 973 

902Type / Values974Type / Values

903 975 

904`boolean`976`string (path)`

905 977 

906Details978Details

907 979 

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

909 981 

910Key982Key

911 983 

912`features.sqlite`984`mcp_oauth_callback_port`

913 985 

914Type / Values986Type / Values

915 987 

916`boolean`988`integer`

917 989 

918Details990Details

919 991 

920Enable SQLite-backed state persistence (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.

921 993 

922Key994Key

923 995 

924`features.steer`996`mcp_oauth_callback_url`

925 997 

926Type / Values998Type / Values

927 999 

928`boolean`1000`string`

929 1001 

930Details1002Details

931 1003 

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

933 1005 

934Key1006Key

935 1007 

936`features.undo`1008`mcp_oauth_credentials_store`

937 1009 

938Type / Values1010Type / Values

939 1011 

940`boolean`1012`auto | file | keyring`

941 1013 

942Details1014Details

943 1015 

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

945 1017 

946Key1018Key

947 1019 

948`features.unified_exec`1020`mcp_servers.<id>.args`

949 1021 

950Type / Values1022Type / Values

951 1023 

952`boolean`1024`array<string>`

953 1025 

954Details1026Details

955 1027 

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

957 1029 

958Key1030Key

959 1031 

960`features.use_linux_sandbox_bwrap`1032`mcp_servers.<id>.bearer_token_env_var`

961 1033 

962Type / Values1034Type / Values

963 1035 

964`boolean`1036`string`

965 1037 

966Details1038Details

967 1039 

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

969 1041 

970Key1042Key

971 1043 

972`features.web_search`1044`mcp_servers.<id>.command`

973 1045 

974Type / Values1046Type / Values

975 1047 

976`boolean`1048`string`

977 1049 

978Details1050Details

979 1051 

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

981 1053 

982Key1054Key

983 1055 

984`features.web_search_cached`1056`mcp_servers.<id>.cwd`

985 1057 

986Type / Values1058Type / Values

987 1059 

988`boolean`1060`string`

989 1061 

990Details1062Details

991 1063 

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

993 1065 

994Key1066Key

995 1067 

996`features.web_search_request`1068`mcp_servers.<id>.disabled_tools`

997 1069 

998Type / Values1070Type / Values

999 1071 

1000`boolean`1072`array<string>`

1001 1073 

1002Details1074Details

1003 1075 

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

1005 1077 

1006Key1078Key

1007 1079 

1008`feedback.enabled`1080`mcp_servers.<id>.enabled`

1009 1081 

1010Type / Values1082Type / Values

1011 1083 

1013 1085 

1014Details1086Details

1015 1087 

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

1017 1089 

1018Key1090Key

1019 1091 

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

1021 1093 

1022Type / Values1094Type / Values

1023 1095 

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

1025 1097 

1026Details1098Details

1027 1099 

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

1029 1101 

1030Key1102Key

1031 1103 

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

1033 1105 

1034Type / Values1106Type / Values

1035 1107 

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

1037 1109 

1038Details1110Details

1039 1111 

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

1041 1113 

1042Key1114Key

1043 1115 

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

1045 1117 

1046Type / Values1118Type / Values

1047 1119 

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

1049 1121 

1050Details1122Details

1051 1123 

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

1053 1125 

1054Key1126Key

1055 1127 

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

1057 1129 

1058Type / Values1130Type / Values

1059 1131 

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

1061 1133 

1062Details1134Details

1063 1135 

1064Suppress reasoning events in both the TUI and `codex exec` output.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.

1065 1137 

1066Key1138Key

1067 1139 

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

1069 1141 

1070Type / Values1142Type / Values

1071 1143 

1072`number`1144`local | remote`

1073 1145 

1074Details1146Details

1075 1147 

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

1077 1149 

1078Key1150Key

1079 1151 

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

1081 1153 

1082Type / Values1154Type / Values

1083 1155 

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

1085 1157 

1086Details1158Details

1087 1159 

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

1089 1161 

1090Key1162Key

1091 1163 

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

1093 1165 

1094Type / Values1166Type / Values

1095 1167 

1097 1169 

1098Details1170Details

1099 1171 

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

1101 1173 

1102Key1174Key

1103 1175 

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

1105 1177 

1106Type / Values1178Type / Values

1107 1179 

1108`string (path)`1180`boolean`

1109 1181 

1110Details1182Details

1111 1183 

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

1113 1185 

1114Key1186Key

1115 1187 

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

1117 1189 

1118Type / Values1190Type / Values

1119 1191 

1120`integer`1192`array<string>`

1121 1193 

1122Details1194Details

1123 1195 

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

1125 1197 

1126Key1198Key

1127 1199 

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

1129 1201 

1130Type / Values1202Type / Values

1131 1203 

1132`string`1204`number`

1133 1205 

1134Details1206Details

1135 1207 

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

1137 1209 

1138Key1210Key

1139 1211 

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

1141 1213 

1142Type / Values1214Type / Values

1143 1215 

1144`auto | file | keyring`1216`number`

1145 1217 

1146Details1218Details

1147 1219 

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

1149 1221 

1150Key1222Key

1151 1223 

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

1153 1225 

1154Type / Values1226Type / Values

1155 1227 

1156`array<string>`1228`number`

1157 1229 

1158Details1230Details

1159 1231 

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

1161 1233 

1162Key1234Key

1163 1235 

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

1165 1237 

1166Type / Values1238Type / Values

1167 1239 

1169 1241 

1170Details1242Details

1171 1243 

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

1173 1245 

1174Key1246Key

1175 1247 

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

1177 1249 

1178Type / Values1250Type / Values

1179 1251 

1181 1253 

1182Details1254Details

1183 1255 

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

1185 1257 

1186Key1258Key

1187 1259 

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

1189 1261 

1190Type / Values1262Type / Values

1191 1263 

1192`string`1264`boolean`

1193 1265 

1194Details1266Details

1195 1267 

1196Working directory for the MCP stdio server process.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`.

1197 1269 

1198Key1270Key

1199 1271 

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

1201 1273 

1202Type / Values1274Type / Values

1203 1275 

1204`array<string>`1276`string`

1205 1277 

1206Details1278Details

1207 1279 

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

1209 1281 

1210Key1282Key

1211 1283 

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

1213 1285 

1214Type / Values1286Type / Values

1215 1287 

1217 1289 

1218Details1290Details

1219 1291 

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

1221 1293 

1222Key1294Key

1223 1295 

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

1225 1297 

1226Type / Values1298Type / Values

1227 1299 

1228`array<string>`1300`number`

1229 1301 

1230Details1302Details

1231 1303 

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

1233 1305 

1234Key1306Key

1235 1307 

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

1237 1309 

1238Type / Values1310Type / Values

1239 1311 

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

1241 1313 

1242Details1314Details

1243 1315 

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

1245 1317 

1246Key1318Key

1247 1319 

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

1249 1321 

1250Type / Values1322Type / Values

1251 1323 

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

1253 1325 

1254Details1326Details

1255 1327 

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

1257 1329 

1258Key1330Key

1259 1331 

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

1261 1333 

1262Type / Values1334Type / Values

1263 1335 

1264`array<string>`1336`number`

1265 1337 

1266Details1338Details

1267 1339 

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

1269 1341 

1270Key1342Key

1271 1343 

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

1273 1345 

1274Type / Values1346Type / Values

1275 1347 

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

1277 1349 

1278Details1350Details

1279 1351 

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

1281 1353 

1282Key1354Key

1283 1355 

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

1285 1357 

1286Type / Values1358Type / Values

1287 1359 

1288`string`1360`boolean`

1289 1361 

1290Details1362Details

1291 1363 

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

1293 1365 

1294Key1366Key

1295 1367 

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

1297 1369 

1298Type / Values1370Type / Values

1299 1371 

1300`boolean`1372`string`

1301 1373 

1302Details1374Details

1303 1375 

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

1305 1377 

1306Key1378Key

1307 1379