config-reference.md Codex Docs, 2026-03-13 18:15 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.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |

112| `model_context_window` | `number` | Context window tokens available to the active model. |112| `model_context_window` | `number` | Context window tokens available to the active model. |

113| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |113| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |

114| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |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). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

174| `plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default. |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. |

175| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |184| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

214| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |224| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

215| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |225| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |

216| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |226| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

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

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

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

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

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

222| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |234| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |

223| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |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. |

224| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |236| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

225| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |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. |

226 239 

227Key240Key

228 241 

326 339 

327Type / Values340Type / Values

328 341 

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

330 343 

331Details344Details

332 345 

333Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.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.

334 347 

335Key348Key

336 349 

337`approval_policy.reject.mcp_elicitations`350`approval_policy.granular.mcp_elicitations`

338 351 

339Type / Values352Type / Values

340 353 

342 355 

343Details356Details

344 357 

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

346 359 

347Key360Key

348 361 

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

350 363 

351Type / Values364Type / Values

352 365 

354 367 

355Details368Details

356 369 

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

358 371 

359Key372Key

360 373 

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

362 375 

363Type / Values376Type / Values

364 377 

366 379 

367Details380Details

368 381 

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

370 419 

371Key420Key

372 421 

490 539 

491Key540Key

492 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 

493`background_terminal_max_timeout`554`background_terminal_max_timeout`

494 555 

495Type / Values556Type / Values

562 623 

563Key624Key

564 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 

565`developer_instructions`638`developer_instructions`

566 639 

567Type / Values640Type / Values

622 695 

623Key696Key

624 697 

625`features.apps_mcp_gateway`698`features.codex_hooks`

626 699 

627Type / Values700Type / Values

628 701 

630 703 

631Details704Details

632 705 

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

634 707 

635Key708Key

636 709 

637`features.artifact`710`features.enable_request_compression`

638 711 

639Type / Values712Type / Values

640 713 

642 715 

643Details716Details

644 717 

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

646 719 

647Key720Key

648 721 

649`features.child_agents_md`722`features.fast_mode`

650 723 

651Type / Values724Type / Values

652 725 

654 727 

655Details728Details

656 729 

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

658 731 

659Key732Key

660 733 

661`features.collaboration_modes`734`features.memories`

662 735 

663Type / Values736Type / Values

664 737 

666 739 

667Details740Details

668 741 

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

670 743 

671Key744Key

672 745 

673`features.default_mode_request_user_input`746`features.multi_agent`

674 747 

675Type / Values748Type / Values

676 749 

678 751 

679Details752Details

680 753 

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

682 755 

683Key756Key

684 757 

685`features.elevated_windows_sandbox`758`features.personality`

686 759 

687Type / Values760Type / Values

688 761 

690 763 

691Details764Details

692 765 

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

694 767 

695Key768Key

696 769 

697`features.enable_request_compression`770`features.prevent_idle_sleep`

698 771 

699Type / Values772Type / Values

700 773 

702 775 

703Details776Details

704 777 

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

706 779 

707Key780Key

708 781 

709`features.experimental_windows_sandbox`782`features.shell_snapshot`

710 783 

711Type / Values784Type / Values

712 785 

714 787 

715Details788Details

716 789 

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

718 791 

719Key792Key

720 793 

721`features.fast_mode`794`features.shell_tool`

722 795 

723Type / Values796Type / Values

724 797 

726 799 

727Details800Details

728 801 

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

730 803 

731Key804Key

732 805 

733`features.image_detail_original`806`features.skill_mcp_dependency_install`

734 807 

735Type / Values808Type / Values

736 809 

738 811 

739Details812Details

740 813 

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

742 815 

743Key816Key

744 817 

745`features.image_generation`818`features.undo`

746 819 

747Type / Values820Type / Values

748 821 

750 823 

751Details824Details

752 825 

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

754 827 

755Key828Key

756 829 

757`features.multi_agent`830`features.unified_exec`

758 831 

759Type / Values832Type / Values

760 833 

762 835 

763Details836Details

764 837 

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

766 839 

767Key840Key

768 841 

769`features.personality`842`features.web_search`

770 843 

771Type / Values844Type / Values

772 845 

774 847 

775Details848Details

776 849 

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

778 851 

779Key852Key

780 853 

781`features.powershell_utf8`854`features.web_search_cached`

782 855 

783Type / Values856Type / Values

784 857 

786 859 

787Details860Details

788 861 

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

790 863 

791Key864Key

792 865 

793`features.prevent_idle_sleep`866`features.web_search_request`

794 867 

795Type / Values868Type / Values

796 869 

798 871 

799Details872Details

800 873 

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

802 875 

803Key876Key

804 877 

805`features.remote_models`878`feedback.enabled`

806 879 

807Type / Values880Type / Values

808 881 

810 883 

811Details884Details

812 885 

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

814 887 

815Key888Key

816 889 

817`features.request_rule`890`file_opener`

818 891 

819Type / Values892Type / Values

820 893 

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

822 895 

823Details896Details

824 897 

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

826 899 

827Key900Key

828 901 

829`features.responses_websockets`902`forced_chatgpt_workspace_id`

830 903 

831Type / Values904Type / Values

832 905 

833`boolean`906`string (uuid)`

834 907 

835Details908Details

836 909 

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

838 911 

839Key912Key

840 913 

841`features.responses_websockets_v2`914`forced_login_method`

842 915 

843Type / Values916Type / Values

844 917 

845`boolean`918`chatgpt | api`

846 919 

847Details920Details

848 921 

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

850 923 

851Key924Key

852 925 

853`features.runtime_metrics`926`hide_agent_reasoning`

854 927 

855Type / Values928Type / Values

856 929 

858 931 

859Details932Details

860 933 

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

862 935 

863Key936Key

864 937 

865`features.search_tool`938`history.max_bytes`

866 939 

867Type / Values940Type / Values

868 941 

869`boolean`942`number`

870 943 

871Details944Details

872 945 

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

874 947 

875Key948Key

876 949 

877`features.shell_snapshot`950`history.persistence`

878 951 

879Type / Values952Type / Values

880 953 

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

882 955 

883Details956Details

884 957 

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

886 959 

887Key960Key

888 961 

889`features.shell_tool`962`hooks`

890 963 

891Type / Values964Type / Values

892 965 

893`boolean`966`table`

894 967 

895Details968Details

896 969 

897Enable the default `shell` tool for running commands (stable; on by default).970Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.

898 971 

899Key972Key

900 973 

901`features.skill_env_var_dependency_prompt`974`instructions`

902 975 

903Type / Values976Type / Values

904 977 

905`boolean`978`string`

906 979 

907Details980Details

908 981 

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

910 983 

911Key984Key

912 985 

913`features.skill_mcp_dependency_install`986`log_dir`

914 987 

915Type / Values988Type / Values

916 989 

917`boolean`990`string (path)`

918 991 

919Details992Details

920 993 

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

922 995 

923Key996Key

924 997 

925`features.sqlite`998`mcp_oauth_callback_port`

926 999 

927Type / Values1000Type / Values

928 1001 

929`boolean`1002`integer`

930 1003 

931Details1004Details

932 1005 

933Enable SQLite-backed state persistence (stable; on by default).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.

934 1007 

935Key1008Key

936 1009 

937`features.steer`1010`mcp_oauth_callback_url`

938 1011 

939Type / Values1012Type / Values

940 1013 

941`boolean`1014`string`

942 1015 

943Details1016Details

944 1017 

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

946 1019 

947Key1020Key

948 1021 

949`features.undo`1022`mcp_oauth_credentials_store`

950 1023 

951Type / Values1024Type / Values

952 1025 

953`boolean`1026`auto | file | keyring`

954 1027 

955Details1028Details

956 1029 

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

958 1031 

959Key1032Key

960 1033 

961`features.unified_exec`1034`mcp_servers.<id>.args`

962 1035 

963Type / Values1036Type / Values

964 1037 

965`boolean`1038`array<string>`

966 1039 

967Details1040Details

968 1041 

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

970 1043 

971Key1044Key

972 1045 

973`features.use_linux_sandbox_bwrap`1046`mcp_servers.<id>.bearer_token_env_var`

974 1047 

975Type / Values1048Type / Values

976 1049 

977`boolean`1050`string`

978 1051 

979Details1052Details

980 1053 

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

982 1055 

983Key1056Key

984 1057 

985`features.web_search`1058`mcp_servers.<id>.command`

986 1059 

987Type / Values1060Type / Values

988 1061 

989`boolean`1062`string`

990 1063 

991Details1064Details

992 1065 

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

994 1067 

995Key1068Key

996 1069 

997`features.web_search_cached`1070`mcp_servers.<id>.cwd`

998 1071 

999Type / Values1072Type / Values

1000 1073 

1001`boolean`1074`string`

1002 1075 

1003Details1076Details

1004 1077 

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

1006 1079 

1007Key1080Key

1008 1081 

1009`features.web_search_request`1082`mcp_servers.<id>.disabled_tools`

1010 1083 

1011Type / Values1084Type / Values

1012 1085 

1013`boolean`1086`array<string>`

1014 1087 

1015Details1088Details

1016 1089 

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

1018 1091 

1019Key1092Key

1020 1093 

1021`feedback.enabled`1094`mcp_servers.<id>.enabled`

1022 1095 

1023Type / Values1096Type / Values

1024 1097 

1026 1099 

1027Details1100Details

1028 1101 

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

1030 1103 

1031Key1104Key

1032 1105 

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

1034 1107 

1035Type / Values1108Type / Values

1036 1109 

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

1038 1111 

1039Details1112Details

1040 1113 

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

1042 1115 

1043Key1116Key

1044 1117 

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

1046 1119 

1047Type / Values1120Type / Values

1048 1121 

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

1050 1123 

1051Details1124Details

1052 1125 

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

1054 1127 

1055Key1128Key

1056 1129 

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

1058 1131 

1059Type / Values1132Type / Values

1060 1133 

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

1062 1135 

1063Details1136Details

1064 1137 

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

1066 1139 

1067Key1140Key

1068 1141 

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

1070 1143 

1071Type / Values1144Type / Values

1072 1145 

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

1074 1147 

1075Details1148Details

1076 1149 

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

1078 1151 

1079Key1152Key

1080 1153 

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

1082 1155 

1083Type / Values1156Type / Values

1084 1157 

1085`number`1158`local | remote`

1086 1159 

1087Details1160Details

1088 1161 

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

1090 1163 

1091Key1164Key

1092 1165 

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

1094 1167 

1095Type / Values1168Type / Values

1096 1169 

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

1098 1171 

1099Details1172Details

1100 1173 

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

1102 1175 

1103Key1176Key

1104 1177 

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

1106 1179 

1107Type / Values1180Type / Values

1108 1181 

1110 1183 

1111Details1184Details

1112 1185 

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

1114 1187 

1115Key1188Key

1116 1189 

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

1118 1191 

1119Type / Values1192Type / Values

1120 1193 

1121`string (path)`1194`boolean`

1122 1195 

1123Details1196Details

1124 1197 

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

1126 1199 

1127Key1200Key

1128 1201 

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

1130 1203 

1131Type / Values1204Type / Values

1132 1205 

1133`integer`1206`array<string>`

1134 1207 

1135Details1208Details

1136 1209 

1137Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS.1210OAuth scopes to request when authenticating to that MCP server.

1138 1211 

1139Key1212Key

1140 1213 

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

1142 1215 

1143Type / Values1216Type / Values

1144 1217 

1145`string`1218`number`

1146 1219 

1147Details1220Details

1148 1221 

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

1150 1223 

1151Key1224Key

1152 1225 

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

1154 1227 

1155Type / Values1228Type / Values

1156 1229 

1157`auto | file | keyring`1230`number`

1158 1231 

1159Details1232Details

1160 1233 

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

1162 1235 

1163Key1236Key

1164 1237 

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

1166 1239 

1167Type / Values1240Type / Values

1168 1241 

1169`array<string>`1242`number`

1170 1243 

1171Details1244Details

1172 1245 

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

1174 1247 

1175Key1248Key

1176 1249 

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

1178 1251 

1179Type / Values1252Type / Values

1180 1253 

1182 1255 

1183Details1256Details

1184 1257 

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

1186 1259 

1187Key1260Key

1188 1261 

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

1190 1263 

1191Type / Values1264Type / Values

1192 1265 

1194 1267 

1195Details1268Details

1196 1269 

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

1198 1271 

1199Key1272Key

1200 1273 

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

1202 1275 

1203Type / Values1276Type / Values

1204 1277 

1205`string`1278`boolean`

1206 1279 

1207Details1280Details

1208 1281 

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

1210 1283 

1211Key1284Key

1212 1285 

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

1214 1287 

1215Type / Values1288Type / Values

1216 1289 

1217`array<string>`1290`string`

1218 1291 

1219Details1292Details

1220 1293 

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

1222 1295 

1223Key1296Key

1224 1297 

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

1226 1299 

1227Type / Values1300Type / Values

1228 1301 

1230 1303 

1231Details1304Details

1232 1305 

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

1234 1307 

1235Key1308Key

1236 1309 

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

1238 1311 

1239Type / Values1312Type / Values

1240 1313 

1241`array<string>`1314`number`

1242 1315 

1243Details1316Details

1244 1317 

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

1246 1319 

1247Key1320Key

1248 1321 

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

1250 1323 

1251Type / Values1324Type / Values

1252 1325 

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

1254 1327 

1255Details1328Details

1256 1329 

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

1258 1331 

1259Key1332Key

1260 1333 

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

1262 1335 

1263Type / Values1336Type / Values

1264 1337 

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

1266 1339 

1267Details1340Details

1268 1341 

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

1270 1343 

1271Key1344Key

1272 1345 

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

1274 1347 

1275Type / Values1348Type / Values

1276 1349 

1277`array<string>`1350`number`

1278 1351 

1279Details1352Details

1280 1353 

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

1282 1355 

1283Key1356Key

1284 1357 

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

1286 1359 

1287Type / Values1360Type / Values

1288 1361 

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

1290 1363 

1291Details1364Details

1292 1365 

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

1294 1367 

1295Key1368Key

1296 1369 

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

1298 1371 

1299Type / Values1372Type / Values

1300 1373 

1301`string`1374`number`

1302 1375