config-reference.md Codex Docs, 2026-03-18 00:36 UTC → 2026-04-29 12:40 UTC

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

87| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |76| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

106| `memories.min_rate_limit_remaining_percent` | `number` | Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`. |

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

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

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

111| `model_context_window` | `number` | Context window tokens available to the active model. |112| `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`. |113| `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`). |114| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |

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

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

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

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

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

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

121| `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. |122| `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. |123| `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. |124| `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. |144| `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. |145| `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. |146| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |

147| `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). |148| `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`). |149| `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. |150| `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. |163| `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. |164| `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. |165| `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. |166| `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. |167| `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. |168| `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. |169| `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. |170| `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. |171| `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. |172| `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. |173| `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. |174| `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. |175| `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. |176| `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. |177| `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. |178| `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. |179| `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. |180| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |

181| `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`. |182| `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. |183| `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`). |184| `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. |197| `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. |198| `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. |199| `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. |200| `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). |201| `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. |202| `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. |203| `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. |204| `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. |205| `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"`. |206| `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. |207| `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. |208| `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. |209| `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. |210| `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. |218| `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. |219| `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. |220| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |

221| `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`. |222| `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. |223| `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. |224| `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). |225| `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). |226| `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. |227| `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). |228| `tui.notification_condition` | `unfocused | always` | Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`. |

229| `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. |230| `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). |231| `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. |232| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

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

238| `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 239 

226Key240Key

227 241 

325 339 

326Type / Values340Type / Values

327 341 

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

329 343 

330Details344Details

331 345 

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.346Controls 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 347 

334Key348Key

335 349 

336`approval_policy.reject.mcp_elicitations`350`approval_policy.granular.mcp_elicitations`

337 351 

338Type / Values352Type / Values

339 353 

341 355 

342Details356Details

343 357 

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

345 359 

346Key360Key

347 361 

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

349 363 

350Type / Values364Type / Values

351 365 

353 367 

354Details368Details

355 369 

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

357 371 

358Key372Key

359 373 

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

361 375 

362Type / Values376Type / Values

363 377 

365 379 

366Details380Details

367 381 

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

383 

384Key

385 

386`approval_policy.granular.sandbox_approval`

387 

388Type / Values

389 

390`boolean`

391 

392Details

393 

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

395 

396Key

397 

398`approval_policy.granular.skill_approval`

399 

400Type / Values

401 

402`boolean`

403 

404Details

405 

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

407 

408Key

409 

410`approvals_reviewer`

411 

412Type / Values

413 

414`user | auto_review`

415 

416Details

417 

418Who 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 419 

370Key420Key

371 421 

489 539 

490Key540Key

491 541 

542`auto_review.policy`

543 

544Type / Values

545 

546`string`

547 

548Details

549 

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

551 

552Key

553 

492`background_terminal_max_timeout`554`background_terminal_max_timeout`

493 555 

494Type / Values556Type / Values

561 623 

562Key624Key

563 625 

626`default_permissions`

627 

628Type / Values

629 

630`string`

631 

632Details

633 

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

635 

636Key

637 

564`developer_instructions`638`developer_instructions`

565 639 

566Type / Values640Type / Values

621 695 

622Key696Key

623 697 

624`features.apps_mcp_gateway`698`features.codex_hooks`

625 699 

626Type / Values700Type / Values

627 701 

629 703 

630Details704Details

631 705 

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

633 707 

634Key708Key

635 709 

636`features.artifact`710`features.enable_request_compression`

637 711 

638Type / Values712Type / Values

639 713 

641 715 

642Details716Details

643 717 

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

645 719 

646Key720Key

647 721 

648`features.child_agents_md`722`features.fast_mode`

649 723 

650Type / Values724Type / Values

651 725 

653 727 

654Details728Details

655 729 

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

657 731 

658Key732Key

659 733 

660`features.collaboration_modes`734`features.memories`

661 735 

662Type / Values736Type / Values

663 737 

665 739 

666Details740Details

667 741 

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

669 743 

670Key744Key

671 745 

672`features.default_mode_request_user_input`746`features.multi_agent`

673 747 

674Type / Values748Type / Values

675 749 

677 751 

678Details752Details

679 753 

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

681 755 

682Key756Key

683 757 

684`features.elevated_windows_sandbox`758`features.personality`

685 759 

686Type / Values760Type / Values

687 761 

689 763 

690Details764Details

691 765 

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

693 767 

694Key768Key

695 769 

696`features.enable_request_compression`770`features.prevent_idle_sleep`

697 771 

698Type / Values772Type / Values

699 773 

701 775 

702Details776Details

703 777 

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

705 779 

706Key780Key

707 781 

708`features.experimental_windows_sandbox`782`features.shell_snapshot`

709 783 

710Type / Values784Type / Values

711 785 

713 787 

714Details788Details

715 789 

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

717 791 

718Key792Key

719 793 

720`features.fast_mode`794`features.shell_tool`

721 795 

722Type / Values796Type / Values

723 797 

725 799 

726Details800Details

727 801 

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

729 803 

730Key804Key

731 805 

732`features.image_detail_original`806`features.skill_mcp_dependency_install`

733 807 

734Type / Values808Type / Values

735 809 

737 811 

738Details812Details

739 813 

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

741 815 

742Key816Key

743 817 

744`features.image_generation`818`features.undo`

745 819 

746Type / Values820Type / Values

747 821 

749 823 

750Details824Details

751 825 

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

753 827 

754Key828Key

755 829 

756`features.personality`830`features.unified_exec`

757 831 

758Type / Values832Type / Values

759 833 

761 835 

762Details836Details

763 837 

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

765 839 

766Key840Key

767 841 

768`features.powershell_utf8`842`features.web_search`

769 843 

770Type / Values844Type / Values

771 845 

773 847 

774Details848Details

775 849 

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

777 851 

778Key852Key

779 853 

780`features.prevent_idle_sleep`854`features.web_search_cached`

781 855 

782Type / Values856Type / Values

783 857 

785 859 

786Details860Details

787 861 

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

789 863 

790Key864Key

791 865 

792`features.remote_models`866`features.web_search_request`

793 867 

794Type / Values868Type / Values

795 869 

797 871 

798Details872Details

799 873 

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

801 875 

802Key876Key

803 877 

804`features.request_rule`878`feedback.enabled`

805 879 

806Type / Values880Type / Values

807 881 

809 883 

810Details884Details

811 885 

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

813 887 

814Key888Key

815 889 

816`features.responses_websockets`890`file_opener`

817 891 

818Type / Values892Type / Values

819 893 

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

821 895 

822Details896Details

823 897 

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

825 899 

826Key900Key

827 901 

828`features.responses_websockets_v2`902`forced_chatgpt_workspace_id`

829 903 

830Type / Values904Type / Values

831 905 

832`boolean`906`string (uuid)`

833 907 

834Details908Details

835 909 

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

837 911 

838Key912Key

839 913 

840`features.runtime_metrics`914`forced_login_method`

841 915 

842Type / Values916Type / Values

843 917 

844`boolean`918`chatgpt | api`

845 919 

846Details920Details

847 921 

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

849 923 

850Key924Key

851 925 

852`features.search_tool`926`hide_agent_reasoning`

853 927 

854Type / Values928Type / Values

855 929 

857 931 

858Details932Details

859 933 

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

861 935 

862Key936Key

863 937 

864`features.shell_snapshot`938`history.max_bytes`

865 939 

866Type / Values940Type / Values

867 941 

868`boolean`942`number`

869 943 

870Details944Details

871 945 

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

873 947 

874Key948Key

875 949 

876`features.shell_tool`950`history.persistence`

877 951 

878Type / Values952Type / Values

879 953 

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

881 955 

882Details956Details

883 957 

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

885 959 

886Key960Key

887 961 

888`features.skill_env_var_dependency_prompt`962`hooks`

889 963 

890Type / Values964Type / Values

891 965 

892`boolean`966`table`

893 967 

894Details968Details

895 969 

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

897 971 

898Key972Key

899 973 

900`features.skill_mcp_dependency_install`974`instructions`

901 975 

902Type / Values976Type / Values

903 977 

904`boolean`978`string`

905 979 

906Details980Details

907 981 

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

909 983 

910Key984Key

911 985 

912`features.sqlite`986`log_dir`

913 987 

914Type / Values988Type / Values

915 989 

916`boolean`990`string (path)`

917 991 

918Details992Details

919 993 

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

921 995 

922Key996Key

923 997 

924`features.steer`998`mcp_oauth_callback_port`

925 999 

926Type / Values1000Type / Values

927 1001 

928`boolean`1002`integer`

929 1003 

930Details1004Details

931 1005 

932Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.1006Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS.

933 1007 

934Key1008Key

935 1009 

936`features.undo`1010`mcp_oauth_callback_url`

937 1011 

938Type / Values1012Type / Values

939 1013 

940`boolean`1014`string`

941 1015 

942Details1016Details

943 1017 

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

945 1019 

946Key1020Key

947 1021 

948`features.unified_exec`1022`mcp_oauth_credentials_store`

949 1023 

950Type / Values1024Type / Values

951 1025 

952`boolean`1026`auto | file | keyring`

953 1027 

954Details1028Details

955 1029 

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

957 1031 

958Key1032Key

959 1033 

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

961 1035 

962Type / Values1036Type / Values

963 1037 

964`boolean`1038`array<string>`

965 1039 

966Details1040Details

967 1041 

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

969 1043 

970Key1044Key

971 1045 

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

973 1047 

974Type / Values1048Type / Values

975 1049 

976`boolean`1050`string`

977 1051 

978Details1052Details

979 1053 

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

981 1055 

982Key1056Key

983 1057 

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

985 1059 

986Type / Values1060Type / Values

987 1061 

988`boolean`1062`string`

989 1063 

990Details1064Details

991 1065 

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

993 1067 

994Key1068Key

995 1069 

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

997 1071 

998Type / Values1072Type / Values

999 1073 

1000`boolean`1074`string`

1001 1075 

1002Details1076Details

1003 1077 

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

1005 1079 

1006Key1080Key

1007 1081 

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

1083 

1084Type / Values

1085 

1086`array<string>`

1087 

1088Details

1089 

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

1091 

1092Key

1093 

1094`mcp_servers.<id>.enabled`

1009 1095 

1010Type / Values1096Type / Values

1011 1097 

1013 1099 

1014Details1100Details

1015 1101 

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

1017 1103 

1018Key1104Key

1019 1105 

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

1021 1107 

1022Type / Values1108Type / Values

1023 1109 

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

1025 1111 

1026Details1112Details

1027 1113 

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

1029 1115 

1030Key1116Key

1031 1117 

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

1033 1119 

1034Type / Values1120Type / Values

1035 1121 

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

1037 1123 

1038Details1124Details

1039 1125 

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

1041 1127 

1042Key1128Key

1043 1129 

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

1045 1131 

1046Type / Values1132Type / Values

1047 1133 

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

1049 1135 

1050Details1136Details

1051 1137 

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

1053 1139 

1054Key1140Key

1055 1141 

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

1057 1143 

1058Type / Values1144Type / Values

1059 1145 

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

1061 1147 

1062Details1148Details

1063 1149 

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

1066Key1152Key

1067 1153 

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

1069 1155 

1070Type / Values1156Type / Values

1071 1157 

1072`number`1158`local | remote`

1073 1159 

1074Details1160Details

1075 1161 

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

1077 1163 

1078Key1164Key

1079 1165 

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

1081 1167 

1082Type / Values1168Type / Values

1083 1169 

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

1085 1171 

1086Details1172Details

1087 1173 

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

1089 1175 

1090Key1176Key

1091 1177 

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

1093 1179 

1094Type / Values1180Type / Values

1095 1181 

1097 1183 

1098Details1184Details

1099 1185 

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

1101 1187 

1102Key1188Key

1103 1189 

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

1105 1191 

1106Type / Values1192Type / Values

1107 1193 

1108`string (path)`1194`boolean`

1109 1195 

1110Details1196Details

1111 1197 

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

1113 1199 

1114Key1200Key

1115 1201 

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

1117 1203 

1118Type / Values1204Type / Values

1119 1205 

1120`integer`1206`array<string>`

1121 1207 

1122Details1208Details

1123 1209 

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

1125 1211 

1126Key1212Key

1127 1213 

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

1129 1215 

1130Type / Values1216Type / Values

1131 1217 

1132`string`1218`number`

1133 1219 

1134Details1220Details

1135 1221 

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

1137 1223 

1138Key1224Key

1139 1225 

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

1141 1227 

1142Type / Values1228Type / Values

1143 1229 

1144`auto | file | keyring`1230`number`

1145 1231 

1146Details1232Details

1147 1233 

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

1149 1235 

1150Key1236Key

1151 1237 

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

1153 1239 

1154Type / Values1240Type / Values

1155 1241 

1156`array<string>`1242`number`

1157 1243 

1158Details1244Details

1159 1245 

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

1161 1247 

1162Key1248Key

1163 1249 

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

1165 1251 

1166Type / Values1252Type / Values

1167 1253 

1169 1255 

1170Details1256Details

1171 1257 

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

1173 1259 

1174Key1260Key

1175 1261 

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

1177 1263 

1178Type / Values1264Type / Values

1179 1265 

1181 1267 

1182Details1268Details

1183 1269 

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

1185 1271 

1186Key1272Key

1187 1273 

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

1189 1275 

1190Type / Values1276Type / Values

1191 1277 

1192`string`1278`boolean`

1193 1279 

1194Details1280Details

1195 1281 

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

1198Key1284Key

1199 1285 

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

1201 1287 

1202Type / Values1288Type / Values

1203 1289 

1204`array<string>`1290`string`

1205 1291 

1206Details1292Details

1207 1293 

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

1209 1295 

1210Key1296Key

1211 1297 

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

1213 1299 

1214Type / Values1300Type / Values

1215 1301 

1217 1303 

1218Details1304Details

1219 1305 

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

1221 1307 

1222Key1308Key

1223 1309 

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

1225 1311 

1226Type / Values1312Type / Values

1227 1313 

1228`array<string>`1314`number`

1229 1315 

1230Details1316Details

1231 1317 

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

1233 1319 

1234Key1320Key

1235 1321 

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

1237 1323 

1238Type / Values1324Type / Values

1239 1325 

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

1241 1327 

1242Details1328Details

1243 1329 

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

1245 1331 

1246Key1332Key

1247 1333 

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

1249 1335 

1250Type / Values1336Type / Values

1251 1337 

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

1253 1339 

1254Details1340Details

1255 1341 

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

1257 1343 

1258Key1344Key

1259 1345 

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

1261 1347 

1262Type / Values1348Type / Values

1263 1349 

1264`array<string>`1350`number`

1265 1351 

1266Details1352Details

1267 1353 

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

1269 1355 

1270Key1356Key

1271 1357 

1272`mcp_servers.<id>.http_headers`1358`memories.min_rate_limit_remaining_percent`

1273 1359 

1274Type / Values1360Type / Values

1275 1361 

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

1277 1363 

1278Details1364Details

1279 1365 

1280Static HTTP headers included with each MCP HTTP request.1366Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`.

1281 1367 

1282Key1368Key

1283 1369 

1284`mcp_servers.<id>.oauth_resource`1370`memories.min_rollout_idle_hours`

1285 1371 

1286Type / Values1372Type / Values

1287 1373 

1288`string`1374`number`

1289 1375 

1290Details1376Details

1291 1377 

1292Optional RFC 8707 OAuth resource parameter to include during MCP login.1378Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.

1293 1379 

1294Key1380Key

1295 1381 

1296`mcp_servers.<id>.required`1382`memories.use_memories`

1297 1383 

1298Type / Values1384Type / Values