config-reference.md Codex Docs, 2026-03-13 00:34 UTC → 2026-04-25 06:37 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_rollout_idle_hours` | `number` | Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

227Key239Key

228 240 

326 338 

327Type / Values339Type / Values

328 340 

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

330 342 

331Details343Details

332 344 

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

335Key347Key

336 348 

337`approval_policy.reject.mcp_elicitations`349`approval_policy.granular.mcp_elicitations`

338 350 

339Type / Values351Type / Values

340 352 

342 354 

343Details355Details

344 356 

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

346 358 

347Key359Key

348 360 

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

350 362 

351Type / Values363Type / Values

352 364 

354 366 

355Details367Details

356 368 

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

358 370 

359Key371Key

360 372 

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

362 374 

363Type / Values375Type / Values

364 376 

366 378 

367Details379Details

368 380 

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

382 

383Key

384 

385`approval_policy.granular.sandbox_approval`

386 

387Type / Values

388 

389`boolean`

390 

391Details

392 

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

394 

395Key

396 

397`approval_policy.granular.skill_approval`

398 

399Type / Values

400 

401`boolean`

402 

403Details

404 

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

406 

407Key

408 

409`approvals_reviewer`

410 

411Type / Values

412 

413`user | auto_review`

414 

415Details

416 

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

371Key419Key

372 420 

490 538 

491Key539Key

492 540 

541`auto_review.policy`

542 

543Type / Values

544 

545`string`

546 

547Details

548 

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

550 

551Key

552 

493`background_terminal_max_timeout`553`background_terminal_max_timeout`

494 554 

495Type / Values555Type / Values

562 622 

563Key623Key

564 624 

625`default_permissions`

626 

627Type / Values

628 

629`string`

630 

631Details

632 

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

634 

635Key

636 

565`developer_instructions`637`developer_instructions`

566 638 

567Type / Values639Type / Values

622 694 

623Key695Key

624 696 

625`features.apps_mcp_gateway`697`features.codex_hooks`

626 698 

627Type / Values699Type / Values

628 700 

630 702 

631Details703Details

632 704 

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

634 706 

635Key707Key

636 708 

637`features.artifact`709`features.enable_request_compression`

638 710 

639Type / Values711Type / Values

640 712 

642 714 

643Details715Details

644 716 

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

646 718 

647Key719Key

648 720 

649`features.child_agents_md`721`features.fast_mode`

650 722 

651Type / Values723Type / Values

652 724 

654 726 

655Details727Details

656 728 

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

658 730 

659Key731Key

660 732 

661`features.collaboration_modes`733`features.memories`

662 734 

663Type / Values735Type / Values

664 736 

666 738 

667Details739Details

668 740 

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

670 742 

671Key743Key

672 744 

673`features.default_mode_request_user_input`745`features.multi_agent`

674 746 

675Type / Values747Type / Values

676 748 

678 750 

679Details751Details

680 752 

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

682 754 

683Key755Key

684 756 

685`features.elevated_windows_sandbox`757`features.personality`

686 758 

687Type / Values759Type / Values

688 760 

690 762 

691Details763Details

692 764 

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

694 766 

695Key767Key

696 768 

697`features.enable_request_compression`769`features.prevent_idle_sleep`

698 770 

699Type / Values771Type / Values

700 772 

702 774 

703Details775Details

704 776 

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

706 778 

707Key779Key

708 780 

709`features.experimental_windows_sandbox`781`features.shell_snapshot`

710 782 

711Type / Values783Type / Values

712 784 

714 786 

715Details787Details

716 788 

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

718 790 

719Key791Key

720 792 

721`features.fast_mode`793`features.shell_tool`

722 794 

723Type / Values795Type / Values

724 796 

726 798 

727Details799Details

728 800 

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

730 802 

731Key803Key

732 804 

733`features.image_detail_original`805`features.skill_mcp_dependency_install`

734 806 

735Type / Values807Type / Values

736 808 

738 810 

739Details811Details

740 812 

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

742 814 

743Key815Key

744 816 

745`features.image_generation`817`features.undo`

746 818 

747Type / Values819Type / Values

748 820 

750 822 

751Details823Details

752 824 

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

754 826 

755Key827Key

756 828 

757`features.multi_agent`829`features.unified_exec`

758 830 

759Type / Values831Type / Values

760 832 

762 834 

763Details835Details

764 836 

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

766 838 

767Key839Key

768 840 

769`features.personality`841`features.web_search`

770 842 

771Type / Values843Type / Values

772 844 

774 846 

775Details847Details

776 848 

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

778 850 

779Key851Key

780 852 

781`features.powershell_utf8`853`features.web_search_cached`

782 854 

783Type / Values855Type / Values

784 856 

786 858 

787Details859Details

788 860 

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

790 862 

791Key863Key

792 864 

793`features.prevent_idle_sleep`865`features.web_search_request`

794 866 

795Type / Values867Type / Values

796 868 

798 870 

799Details871Details

800 872 

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

802 874 

803Key875Key

804 876 

805`features.remote_models`877`feedback.enabled`

806 878 

807Type / Values879Type / Values

808 880 

810 882 

811Details883Details

812 884 

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

814 886 

815Key887Key

816 888 

817`features.request_rule`889`file_opener`

818 890 

819Type / Values891Type / Values

820 892 

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

822 894 

823Details895Details

824 896 

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

826 898 

827Key899Key

828 900 

829`features.responses_websockets`901`forced_chatgpt_workspace_id`

830 902 

831Type / Values903Type / Values

832 904 

833`boolean`905`string (uuid)`

834 906 

835Details907Details

836 908 

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

838 910 

839Key911Key

840 912 

841`features.responses_websockets_v2`913`forced_login_method`

842 914 

843Type / Values915Type / Values

844 916 

845`boolean`917`chatgpt | api`

846 918 

847Details919Details

848 920 

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

850 922 

851Key923Key

852 924 

853`features.runtime_metrics`925`hide_agent_reasoning`

854 926 

855Type / Values927Type / Values

856 928 

858 930 

859Details931Details

860 932 

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

862 934 

863Key935Key

864 936 

865`features.search_tool`937`history.max_bytes`

866 938 

867Type / Values939Type / Values

868 940 

869`boolean`941`number`

870 942 

871Details943Details

872 944 

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

874 946 

875Key947Key

876 948 

877`features.shell_snapshot`949`history.persistence`

878 950 

879Type / Values951Type / Values

880 952 

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

882 954 

883Details955Details

884 956 

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

886 958 

887Key959Key

888 960 

889`features.shell_tool`961`hooks`

890 962 

891Type / Values963Type / Values

892 964 

893`boolean`965`table`

894 966 

895Details967Details

896 968 

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

898 970 

899Key971Key

900 972 

901`features.skill_env_var_dependency_prompt`973`instructions`

902 974 

903Type / Values975Type / Values

904 976 

905`boolean`977`string`

906 978 

907Details979Details

908 980 

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

910 982 

911Key983Key

912 984 

913`features.skill_mcp_dependency_install`985`log_dir`

914 986 

915Type / Values987Type / Values

916 988 

917`boolean`989`string (path)`

918 990 

919Details991Details

920 992 

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

922 994 

923Key995Key

924 996 

925`features.sqlite`997`mcp_oauth_callback_port`

926 998 

927Type / Values999Type / Values

928 1000 

929`boolean`1001`integer`

930 1002 

931Details1003Details

932 1004 

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

935Key1007Key

936 1008 

937`features.steer`1009`mcp_oauth_callback_url`

938 1010 

939Type / Values1011Type / Values

940 1012 

941`boolean`1013`string`

942 1014 

943Details1015Details

944 1016 

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

946 1018 

947Key1019Key

948 1020 

949`features.undo`1021`mcp_oauth_credentials_store`

950 1022 

951Type / Values1023Type / Values

952 1024 

953`boolean`1025`auto | file | keyring`

954 1026 

955Details1027Details

956 1028 

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

958 1030 

959Key1031Key

960 1032 

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

962 1034 

963Type / Values1035Type / Values

964 1036 

965`boolean`1037`array<string>`

966 1038 

967Details1039Details

968 1040 

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

970 1042 

971Key1043Key

972 1044 

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

974 1046 

975Type / Values1047Type / Values

976 1048 

977`boolean`1049`string`

978 1050 

979Details1051Details

980 1052 

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

982 1054 

983Key1055Key

984 1056 

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

986 1058 

987Type / Values1059Type / Values

988 1060 

989`boolean`1061`string`

990 1062 

991Details1063Details

992 1064 

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

994 1066 

995Key1067Key

996 1068 

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

998 1070 

999Type / Values1071Type / Values

1000 1072 

1001`boolean`1073`string`

1002 1074 

1003Details1075Details

1004 1076 

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

1006 1078 

1007Key1079Key

1008 1080 

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

1010 1082 

1011Type / Values1083Type / Values

1012 1084 

1013`boolean`1085`array<string>`

1014 1086 

1015Details1087Details

1016 1088 

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

1018 1090 

1019Key1091Key

1020 1092 

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

1022 1094 

1023Type / Values1095Type / Values

1024 1096 

1026 1098 

1027Details1099Details

1028 1100 

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

1030 1102 

1031Key1103Key

1032 1104 

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

1034 1106 

1035Type / Values1107Type / Values

1036 1108 

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

1038 1110 

1039Details1111Details

1040 1112 

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

1042 1114 

1043Key1115Key

1044 1116 

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

1046 1118 

1047Type / Values1119Type / Values

1048 1120 

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

1050 1122 

1051Details1123Details

1052 1124 

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

1054 1126 

1055Key1127Key

1056 1128 

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

1058 1130 

1059Type / Values1131Type / Values

1060 1132 

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

1062 1134 

1063Details1135Details

1064 1136 

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

1066 1138 

1067Key1139Key

1068 1140 

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

1070 1142 

1071Type / Values1143Type / Values

1072 1144 

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

1074 1146 

1075Details1147Details

1076 1148 

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

1079Key1151Key

1080 1152 

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

1082 1154 

1083Type / Values1155Type / Values

1084 1156 

1085`number`1157`local | remote`

1086 1158 

1087Details1159Details

1088 1160 

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

1090 1162 

1091Key1163Key

1092 1164 

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

1094 1166 

1095Type / Values1167Type / Values

1096 1168 

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

1098 1170 

1099Details1171Details

1100 1172 

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

1102 1174 

1103Key1175Key

1104 1176 

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

1106 1178 

1107Type / Values1179Type / Values

1108 1180 

1110 1182 

1111Details1183Details

1112 1184 

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

1114 1186 

1115Key1187Key

1116 1188 

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

1118 1190 

1119Type / Values1191Type / Values

1120 1192 

1121`string (path)`1193`boolean`

1122 1194 

1123Details1195Details

1124 1196 

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

1126 1198 

1127Key1199Key

1128 1200 

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

1130 1202 

1131Type / Values1203Type / Values

1132 1204 

1133`integer`1205`array<string>`

1134 1206 

1135Details1207Details

1136 1208 

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

1138 1210 

1139Key1211Key

1140 1212 

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

1142 1214 

1143Type / Values1215Type / Values

1144 1216 

1145`string`1217`number`

1146 1218 

1147Details1219Details

1148 1220 

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

1150 1222 

1151Key1223Key

1152 1224 

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

1154 1226 

1155Type / Values1227Type / Values

1156 1228 

1157`auto | file | keyring`1229`number`

1158 1230 

1159Details1231Details

1160 1232 

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

1162 1234 

1163Key1235Key

1164 1236 

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

1166 1238 

1167Type / Values1239Type / Values

1168 1240 

1169`array<string>`1241`number`

1170 1242 

1171Details1243Details

1172 1244 

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

1174 1246 

1175Key1247Key

1176 1248 

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

1178 1250 

1179Type / Values1251Type / Values

1180 1252 

1182 1254 

1183Details1255Details

1184 1256 

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

1186 1258 

1187Key1259Key

1188 1260 

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

1190 1262 

1191Type / Values1263Type / Values

1192 1264 

1194 1266 

1195Details1267Details

1196 1268 

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

1198 1270 

1199Key1271Key

1200 1272 

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

1202 1274 

1203Type / Values1275Type / Values

1204 1276 

1205`string`1277`boolean`

1206 1278 

1207Details1279Details

1208 1280 

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

1211Key1283Key

1212 1284 

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

1214 1286 

1215Type / Values1287Type / Values

1216 1288 

1217`array<string>`1289`string`

1218 1290 

1219Details1291Details

1220 1292 

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

1222 1294 

1223Key1295Key

1224 1296 

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

1226 1298 

1227Type / Values1299Type / Values

1228 1300 

1230 1302 

1231Details1303Details

1232 1304 

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

1234 1306 

1235Key1307Key

1236 1308 

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

1238 1310 

1239Type / Values1311Type / Values

1240 1312 

1241`array<string>`1313`number`

1242 1314 

1243Details1315Details

1244 1316 

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

1246 1318 

1247Key1319Key

1248 1320 

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

1250 1322 

1251Type / Values1323Type / Values

1252 1324 

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

1254 1326 

1255Details1327Details

1256 1328 

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

1258 1330 

1259Key1331Key

1260 1332 

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

1262 1334 

1263Type / Values1335Type / Values

1264 1336 

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

1266 1338 

1267Details1339Details

1268 1340 

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

1270 1342 

1271Key1343Key

1272 1344 

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

1274 1346 

1275Type / Values1347Type / Values

1276 1348 

1277`array<string>`1349`number`

1278 1350 

1279Details1351Details

1280 1352 

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

1282 1354 

1283Key1355Key

1284 1356 

1285`mcp_servers.<id>.http_headers`1357`memories.min_rollout_idle_hours`

1286 1358 

1287Type / Values1359Type / Values

1288 1360 

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

1290 1362 

1291Details1363Details

1292 1364 

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

1294 1366 

1295Key1367Key

1296 1368 

1297`mcp_servers.<id>.oauth_resource`1369`memories.use_memories`

1370 

1371Type / Values

1372 

1373`boolean`

1374 

1375Details

1376 

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

1378 

1379Key