config-reference.md Codex Docs, 2026-03-31 06:35 UTC → 2026-04-24 18:20 UTC

24| `approval_policy.granular.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface. |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. |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. |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. |

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

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

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

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

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

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

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

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

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

49| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |51| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |

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

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

54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |

52| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |55| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |

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

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

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

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

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

58| `features.smart_approvals` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

144| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |164| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |

145| `permissions.<name>.filesystem.":project_roots".<subpath>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself. |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"`. |

146| `permissions.<name>.filesystem.<path>` | `"read" | "write" | "none" | table` | Grant direct access for a path or special token, or scope nested entries under that root. |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. |

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

147| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |168| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

148| `permissions.<name>.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |

149| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |169| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

150| `permissions.<name>.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |

151| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |170| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

152| `permissions.<name>.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. |

153| `permissions.<name>.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. |

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

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

156| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |175| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |

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

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

159| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |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. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

201| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |222| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

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

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

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

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

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

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

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

209| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |232| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |

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

211| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |234| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

382 405 

383Key406Key

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

417 

418Key

419 

385`apps._default.destructive_enabled`420`apps._default.destructive_enabled`

386 421 

387Type / Values422Type / Values

502 537 

503Key538Key

504 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 

505`background_terminal_max_timeout`552`background_terminal_max_timeout`

506 553 

507Type / Values554Type / Values

682 729 

683Key730Key

684 731 

732`features.memories`

733 

734Type / Values

735 

736`boolean`

737 

738Details

739 

740Enable [Memories](https://developers.openai.com/codex/memories) (off by default).

741 

742Key

743 

685`features.multi_agent`744`features.multi_agent`

686 745 

687Type / Values746Type / Values

754 813 

755Key814Key

756 815 

757`features.smart_approvals`

758 

759Type / Values

760 

761`boolean`

762 

763Details

764 

765Route eligible approval requests through the guardian reviewer subagent (experimental; off by default).

766 

767Key

768 

769`features.undo`816`features.undo`

770 817 

771Type / Values818Type / Values

1082 1129 

1083Type / Values1130Type / Values

1084 1131 

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

1133 

1134Details

1135 

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.

1137 

1138Key

1139 

1140`mcp_servers.<id>.experimental_environment`

1141 

1142Type / Values

1143 

1144`local | remote`

1086 1145 

1087Details1146Details

1088 1147 

1089Additional environment variables to whitelist for an MCP stdio server.1148Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.

1090 1149 

1091Key1150Key

1092 1151 

1186 1245 

1187Key1246Key

1188 1247 

1248`memories.consolidation_model`

1249 

1250Type / Values

1251 

1252`string`

1253 

1254Details

1255 

1256Optional model override for global memory consolidation.

1257 

1258Key

1259 

1260`memories.disable_on_external_context`

1261 

1262Type / Values

1263 

1264`boolean`

1265 

1266Details

1267 

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

1269 

1270Key

1271 

1272`memories.extract_model`

1273 

1274Type / Values

1275 

1276`string`

1277 

1278Details

1279 

1280Optional model override for per-thread memory extraction.

1281 

1282Key

1283 

1284`memories.generate_memories`

1285 

1286Type / Values

1287 

1288`boolean`

1289 

1290Details

1291 

1292When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.

1293 

1294Key

1295 

1296`memories.max_raw_memories_for_consolidation`

1297 

1298Type / Values

1299 

1300`number`

1301 

1302Details

1303 

1304Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.

1305 

1306Key

1307 

1308`memories.max_rollout_age_days`

1309 

1310Type / Values

1311 

1312`number`

1313 

1314Details

1315 

1316Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.

1317 

1318Key

1319 

1320`memories.max_rollouts_per_startup`

1321 

1322Type / Values

1323 

1324`number`

1325 

1326Details

1327 

1328Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.

1329 

1330Key

1331 

1332`memories.max_unused_days`

1333 

1334Type / Values

1335 

1336`number`

1337 

1338Details

1339 

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

1341 

1342Key

1343 

1344`memories.min_rollout_idle_hours`

1345 

1346Type / Values

1347 

1348`number`

1349 

1350Details

1351 

1352Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.

1353 

1354Key

1355 

1356`memories.use_memories`

1357 

1358Type / Values

1359 

1360`boolean`

1361 

1362Details

1363 

1364When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.

1365 

1366Key

1367 

1189`model`1368`model`

1190 1369 

1191Type / Values1370Type / Values

1194 1373 

1195Details1374Details

1196 1375 

1197Model to use (e.g., `gpt-5-codex`).1376Model to use (e.g., `gpt-5.5`).

1198 1377 

1199Key1378Key

1200 1379 

1258 1437 

1259Key1438Key

1260 1439 

1440`model_providers.<id>`

1441 

1442Type / Values

1443 

1444`table`

1445 

1446Details

1447 

1448Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.

1449 

1450Key

1451 

1452`model_providers.<id>.auth`

1453 

1454Type / Values

1455 

1456`table`

1457 

1458Details

1459 

1460Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.

1461 

1462Key

1463 

1464`model_providers.<id>.auth.args`

1465 

1466Type / Values

1467 

1468`array<string>`

1469 

1470Details

1471 

1472Arguments passed to the token command.

1473 

1474Key

1475 

1476`model_providers.<id>.auth.command`

1477 

1478Type / Values

1479 

1480`string`

1481 

1482Details

1483 

1484Command to run when Codex needs a bearer token. The command must print the token to stdout.

1485 

1486Key

1487 

1488`model_providers.<id>.auth.cwd`

1489 

1490Type / Values

1491 

1492`string (path)`

1493 

1494Details

1495 

1496Working directory for the token command.

1497 

1498Key

1499 

1500`model_providers.<id>.auth.refresh_interval_ms`

1501 

1502Type / Values

1503 

1504`number`

1505 

1506Details

1507 

1508How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.

1509 

1510Key

1511 

1512`model_providers.<id>.auth.timeout_ms`

1513 

1514Type / Values

1515 

1516`number`

1517 

1518Details

1519 

1520Maximum token command runtime in milliseconds (default: 5000).

1521 

1522Key

1523 

1261`model_providers.<id>.base_url`1524`model_providers.<id>.base_url`

1262 1525 

1263Type / Values1526Type / Values

1798 2061 

1799Key2062Key

1800 2063 

1801`permissions.<name>.filesystem.":project_roots".<subpath>`2064`permissions.<name>.filesystem.":project_roots".<subpath-or-glob>`

1802 2065 

1803Type / Values2066Type / Values

1804 2067 

1806 2069 

1807Details2070Details

1808 2071 

1809Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself.2072Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`.

1810 2073 

1811Key2074Key

1812 2075 

1813`permissions.<name>.filesystem.<path>`2076`permissions.<name>.filesystem.<path-or-glob>`

1814 2077 

1815Type / Values2078Type / Values

1816 2079 

1818 2081 

1819Details2082Details

1820 2083 

1821Grant direct access for a path or special token, or scope nested entries under that root.2084Grant 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.

1822 2085 

1823Key2086Key

1824 2087 

1825`permissions.<name>.network.allow_local_binding`2088`permissions.<name>.filesystem.glob_scan_max_depth`

1826 2089 

1827Type / Values2090Type / Values

1828 2091 

1829`boolean`2092`number`

1830 2093 

1831Details2094Details

1832 2095 

1833Permit local bind/listen operations through the managed proxy.2096Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set.

1834 2097 

1835Key2098Key

1836 2099 

1837`permissions.<name>.network.allow_unix_sockets`2100`permissions.<name>.network.allow_local_binding`

1838 2101 

1839Type / Values2102Type / Values

1840 2103 

1841`array<string>`2104`boolean`

1842 2105 

1843Details2106Details

1844 2107 

1845Allowlist of Unix socket paths permitted through the managed proxy.2108Permit local bind/listen operations through the managed proxy.

1846 2109 

1847Key2110Key

1848 2111 

1858 2121 

1859Key2122Key

1860 2123 

1861`permissions.<name>.network.allowed_domains`

1862 

1863Type / Values

1864 

1865`array<string>`

1866 

1867Details

1868 

1869Allowlist of domains permitted through the managed proxy.

1870 

1871Key

1872 

1873`permissions.<name>.network.dangerously_allow_all_unix_sockets`2124`permissions.<name>.network.dangerously_allow_all_unix_sockets`

1874 2125 

1875Type / Values2126Type / Values

1894 2145 

1895Key2146Key

1896 2147 

1897`permissions.<name>.network.denied_domains`2148`permissions.<name>.network.domains`

1898 2149 

1899Type / Values2150Type / Values

1900 2151 

1901`array<string>`2152`map<string, allow | deny>`

1902 2153 

1903Details2154Details

1904 2155 

1905Denylist of domains blocked by the managed proxy.2156Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values.

1906 2157 

1907Key2158Key

1908 2159 

1978 2229 

1979Key2230Key

1980 2231 

2232`permissions.<name>.network.unix_sockets`

2233 

2234Type / Values

2235 

2236`map<string, allow | none>`

2237 

2238Details

2239 

2240Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values.

2241 

2242Key

2243 

1981`personality`2244`personality`

1982 2245 

1983Type / Values2246Type / Values

2202 2465 

2203Details2466Details

2204 2467 

2205Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers.2468Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers, including project-local config, hooks, and rules.

2206 2469 

2207Key2470Key

2208 2471 

2446 2709 

2447Key2710Key

2448 2711 

2712`tool_suggest.discoverables`

2713 

2714Type / Values

2715 

2716`array<table>`

2717 

2718Details

2719 

2720Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.

2721 

2722Key

2723 

2449`tools.view_image`2724`tools.view_image`

2450 2725 

2451Type / Values2726Type / Values

2518 2793 

2519Key2794Key

2520 2795 

2796`tui.notification_condition`

2797 

2798Type / Values

2799 

2800`unfocused | always`

2801 

2802Details

2803 

2804Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`.

2805 

2806Key

2807 

2521`tui.notification_method`2808`tui.notification_method`

2522 2809 

2523Type / Values2810Type / Values

2526 2813 

2527Details2814Details

2528 2815 

2529Notification method for unfocused terminal notifications (default: auto).2816Notification method for terminal notifications (default: auto).

2530 2817 

2531Key2818Key

2532 2819 

2566 2853 

2567Key2854Key

2568 2855 

2856`tui.terminal_title`

2857 

2858Type / Values

2859 

2860`array<string> | null`

2861 

2862Details

2863 

2864Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates.

2865 

2866Key

2867 

2569`tui.theme`2868`tui.theme`

2570 2869 

2571Type / Values2870Type / Values

2649| Key | Type / Values | Details |2948| Key | Type / Values | Details |

2650| --- | --- | --- |2949| --- | --- | --- |

2651| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). |2950| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). |

2951| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer`, such as `user` and `auto_review`. |

2652| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2952| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |

2653| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |2953| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |

2654| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |2954| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |

2655| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |2955| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |

2956| `guardian_policy_config` | `string` | Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored. |

2656| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |2957| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |

2657| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |2958| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |

2658| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |2959| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |

2659| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |2960| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |

2961| `permissions.filesystem.deny_read` | `array<string>` | Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config. |

2660| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |2962| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |

2661| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |2963| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |

2662| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |2964| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |

2679 2981 

2680Key2982Key

2681 2983 

2984`allowed_approvals_reviewers`

2985 

2986Type / Values

2987 

2988`array<string>`

2989 

2990Details

2991 

2992Allowed values for `approvals_reviewer`, such as `user` and `auto_review`.

2993 

2994Key

2995 

2682`allowed_sandbox_modes`2996`allowed_sandbox_modes`

2683 2997 

2684Type / Values2998Type / Values

2727 3041 

2728Key3042Key

2729 3043 

3044`guardian_policy_config`

3045 

3046Type / Values

3047 

3048`string`

3049 

3050Details

3051 

3052Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored.

3053 

3054Key

3055 

2730`mcp_servers`3056`mcp_servers`

2731 3057 

2732Type / Values3058Type / Values

2775 3101 

2776Key3102Key

2777 3103 

3104`permissions.filesystem.deny_read`

3105 

3106Type / Values

3107 

3108`array<string>`

3109 

3110Details

3111 

3112Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config.

3113 

3114Key

3115 

2778`rules`3116`rules`

2779 3117 

2780Type / Values3118Type / Values