config-reference.md Codex Docs, 2026-03-16 18:25 UTC → 2026-05-01 18:29 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. Built-ins are `:read-only`, `:workspace`, and `:danger-no-sandbox`; custom profile names require matching `[permissions.<name>]` tables. |

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

126| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |133| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |

127| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |134| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

128| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |135| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |

136| `model_providers.amazon-bedrock.aws.profile` | `string` | AWS profile name used by the built-in `amazon-bedrock` provider. |

137| `model_providers.amazon-bedrock.aws.region` | `string` | AWS region used by the built-in `amazon-bedrock` provider. |

129| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |138| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |

130| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |139| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |

131| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |140| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |

137| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |146| `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. |147| `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. |148| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |

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

183| `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`. |184| `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. |185| `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`). |186| `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. |199| `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. |200| `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. |201| `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. |202| `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). |203| `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. |204| `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. |205| `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. |206| `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. |207| `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"`. |208| `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. |209| `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. |210| `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. |211| `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. |212| `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. |220| `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. |221| `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. |222| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |

223| `tool_suggest.disabled_tools` | `array<table>` | Disable suggestions for specific discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

224| `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`. |225| `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. |226| `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. |227| `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). |228| `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). |229| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

230| `tui.keymap.<context>.<action>` | `string | array<string>` | Keyboard shortcut binding for a TUI action. Supported contexts include `global`, `chat`, `composer`, `editor`, `pager`, `list`, and `approval`; context-specific bindings override `tui.keymap.global`. |

231| `tui.keymap.<context>.<action> = []` | `empty array` | Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, or `page-down`. |

217| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |232| `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). |233| `tui.notification_condition` | `unfocused | always` | Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`. |

234| `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. |235| `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). |236| `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. |237| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

238| `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). |239| `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. |240| `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). |241| `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. |242| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |

243| `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 244 

227Key245Key

228 246 

326 344 

327Type / Values345Type / Values

328 346 

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

330 348 

331Details349Details

332 350 

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.351Controls 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 352 

335Key353Key

336 354 

337`approval_policy.reject.mcp_elicitations`355`approval_policy.granular.mcp_elicitations`

338 356 

339Type / Values357Type / Values

340 358 

342 360 

343Details361Details

344 362 

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

346 364 

347Key365Key

348 366 

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

350 368 

351Type / Values369Type / Values

352 370 

354 372 

355Details373Details

356 374 

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

358 376 

359Key377Key

360 378 

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

362 380 

363Type / Values381Type / Values

364 382 

366 384 

367Details385Details

368 386 

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

388 

389Key

390 

391`approval_policy.granular.sandbox_approval`

392 

393Type / Values

394 

395`boolean`

396 

397Details

398 

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

400 

401Key

402 

403`approval_policy.granular.skill_approval`

404 

405Type / Values

406 

407`boolean`

408 

409Details

410 

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

412 

413Key

414 

415`approvals_reviewer`

416 

417Type / Values

418 

419`user | auto_review`

420 

421Details

422 

423Who 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 424 

371Key425Key

372 426 

490 544 

491Key545Key

492 546 

547`auto_review.policy`

548 

549Type / Values

550 

551`string`

552 

553Details

554 

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

556 

557Key

558 

493`background_terminal_max_timeout`559`background_terminal_max_timeout`

494 560 

495Type / Values561Type / Values

562 628 

563Key629Key

564 630 

631`default_permissions`

632 

633Type / Values

634 

635`string`

636 

637Details

638 

639Name of the default permissions profile to apply to sandboxed tool calls. Built-ins are `:read-only`, `:workspace`, and `:danger-no-sandbox`; custom profile names require matching `[permissions.<name>]` tables.

640 

641Key

642 

565`developer_instructions`643`developer_instructions`

566 644 

567Type / Values645Type / Values

622 700 

623Key701Key

624 702 

625`features.apps_mcp_gateway`703`features.codex_hooks`

626 704 

627Type / Values705Type / Values

628 706 

630 708 

631Details709Details

632 710 

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

634 712 

635Key713Key

636 714 

637`features.artifact`715`features.enable_request_compression`

638 716 

639Type / Values717Type / Values

640 718 

642 720 

643Details721Details

644 722 

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

646 724 

647Key725Key

648 726 

649`features.child_agents_md`727`features.fast_mode`

650 728 

651Type / Values729Type / Values

652 730 

654 732 

655Details733Details

656 734 

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

658 736 

659Key737Key

660 738 

661`features.collaboration_modes`739`features.memories`

662 740 

663Type / Values741Type / Values

664 742 

666 744 

667Details745Details

668 746 

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

670 748 

671Key749Key

672 750 

673`features.default_mode_request_user_input`751`features.multi_agent`

674 752 

675Type / Values753Type / Values

676 754 

678 756 

679Details757Details

680 758 

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

682 760 

683Key761Key

684 762 

685`features.elevated_windows_sandbox`763`features.personality`

686 764 

687Type / Values765Type / Values

688 766 

690 768 

691Details769Details

692 770 

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

694 772 

695Key773Key

696 774 

697`features.enable_request_compression`775`features.prevent_idle_sleep`

698 776 

699Type / Values777Type / Values

700 778 

702 780 

703Details781Details

704 782 

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

706 784 

707Key785Key

708 786 

709`features.experimental_windows_sandbox`787`features.shell_snapshot`

710 788 

711Type / Values789Type / Values

712 790 

714 792 

715Details793Details

716 794 

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

718 796 

719Key797Key

720 798 

721`features.fast_mode`799`features.shell_tool`

722 800 

723Type / Values801Type / Values

724 802 

726 804 

727Details805Details

728 806 

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

730 808 

731Key809Key

732 810 

733`features.image_detail_original`811`features.skill_mcp_dependency_install`

734 812 

735Type / Values813Type / Values

736 814 

738 816 

739Details817Details

740 818 

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

742 820 

743Key821Key

744 822 

745`features.image_generation`823`features.undo`

746 824 

747Type / Values825Type / Values

748 826 

750 828 

751Details829Details

752 830 

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

754 832 

755Key833Key

756 834 

757`features.multi_agent`835`features.unified_exec`

758 836 

759Type / Values837Type / Values

760 838 

762 840 

763Details841Details

764 842 

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

766 844 

767Key845Key

768 846 

769`features.personality`847`features.web_search`

770 848 

771Type / Values849Type / Values

772 850 

774 852 

775Details853Details

776 854 

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

778 856 

779Key857Key

780 858 

781`features.powershell_utf8`859`features.web_search_cached`

782 860 

783Type / Values861Type / Values

784 862 

786 864 

787Details865Details

788 866 

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

790 868 

791Key869Key

792 870 

793`features.prevent_idle_sleep`871`features.web_search_request`

794 872 

795Type / Values873Type / Values

796 874 

798 876 

799Details877Details

800 878 

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

802 880 

803Key881Key

804 882 

805`features.remote_models`883`feedback.enabled`

806 884 

807Type / Values885Type / Values

808 886 

810 888 

811Details889Details

812 890 

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

814 892 

815Key893Key

816 894 

817`features.request_rule`895`file_opener`

818 896 

819Type / Values897Type / Values

820 898 

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

822 900 

823Details901Details

824 902 

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

826 904 

827Key905Key

828 906 

829`features.responses_websockets`907`forced_chatgpt_workspace_id`

830 908 

831Type / Values909Type / Values

832 910 

833`boolean`911`string (uuid)`

834 912 

835Details913Details

836 914 

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

838 916 

839Key917Key

840 918 

841`features.responses_websockets_v2`919`forced_login_method`

842 920 

843Type / Values921Type / Values

844 922 

845`boolean`923`chatgpt | api`

846 924 

847Details925Details

848 926 

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

850 928 

851Key929Key

852 930 

853`features.runtime_metrics`931`hide_agent_reasoning`

854 932 

855Type / Values933Type / Values

856 934 

858 936 

859Details937Details

860 938 

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

862 940 

863Key941Key

864 942 

865`features.search_tool`943`history.max_bytes`

866 944 

867Type / Values945Type / Values

868 946 

869`boolean`947`number`

870 948 

871Details949Details

872 950 

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

874 952 

875Key953Key

876 954 

877`features.shell_snapshot`955`history.persistence`

878 956 

879Type / Values957Type / Values

880 958 

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

882 960 

883Details961Details

884 962 

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

886 964 

887Key965Key

888 966 

889`features.shell_tool`967`hooks`

890 968 

891Type / Values969Type / Values

892 970 

893`boolean`971`table`

894 972 

895Details973Details

896 974 

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

898 976 

899Key977Key

900 978 

901`features.skill_env_var_dependency_prompt`979`instructions`

902 980 

903Type / Values981Type / Values

904 982 

905`boolean`983`string`

906 984 

907Details985Details

908 986 

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

910 988 

911Key989Key

912 990 

913`features.skill_mcp_dependency_install`991`log_dir`

914 992 

915Type / Values993Type / Values

916 994 

917`boolean`995`string (path)`

918 996 

919Details997Details

920 998 

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

922 1000 

923Key1001Key

924 1002 

925`features.sqlite`1003`mcp_oauth_callback_port`

926 1004 

927Type / Values1005Type / Values

928 1006 

929`boolean`1007`integer`

930 1008 

931Details1009Details

932 1010 

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

935Key1013Key

936 1014 

937`features.steer`1015`mcp_oauth_callback_url`

938 1016 

939Type / Values1017Type / Values

940 1018 

941`boolean`1019`string`

942 1020 

943Details1021Details

944 1022 

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

946 1024 

947Key1025Key

948 1026 

949`features.undo`1027`mcp_oauth_credentials_store`

950 1028 

951Type / Values1029Type / Values

952 1030 

953`boolean`1031`auto | file | keyring`

954 1032 

955Details1033Details

956 1034 

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

958 1036 

959Key1037Key

960 1038 

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

962 1040 

963Type / Values1041Type / Values

964 1042 

965`boolean`1043`array<string>`

966 1044 

967Details1045Details

968 1046 

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

970 1048 

971Key1049Key

972 1050 

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

974 1052 

975Type / Values1053Type / Values

976 1054 

977`boolean`1055`string`

978 1056 

979Details1057Details

980 1058 

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

982 1060 

983Key1061Key

984 1062 

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

986 1064 

987Type / Values1065Type / Values

988 1066 

989`boolean`1067`string`

990 1068 

991Details1069Details

992 1070 

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

994 1072 

995Key1073Key

996 1074 

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

998 1076 

999Type / Values1077Type / Values

1000 1078 

1001`boolean`1079`string`

1002 1080 

1003Details1081Details

1004 1082 

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

1006 1084 

1007Key1085Key

1008 1086 

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

1010 1088 

1011Type / Values1089Type / Values

1012 1090 

1013`boolean`1091`array<string>`

1014 1092 

1015Details1093Details

1016 1094 

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

1018 1096 

1019Key1097Key

1020 1098 

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

1022 1100 

1023Type / Values1101Type / Values

1024 1102 

1026 1104 

1027Details1105Details

1028 1106 

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

1030 1108 

1031Key1109Key

1032 1110 

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

1034 1112 

1035Type / Values1113Type / Values

1036 1114 

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

1038 1116 

1039Details1117Details

1040 1118 

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

1042 1120 

1043Key1121Key

1044 1122 

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

1046 1124 

1047Type / Values1125Type / Values

1048 1126 

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

1050 1128 

1051Details1129Details

1052 1130 

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

1054 1132 

1055Key1133Key

1056 1134 

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

1058 1136 

1059Type / Values1137Type / Values

1060 1138 

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

1062 1140 

1063Details1141Details

1064 1142 

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

1066 1144 

1067Key1145Key

1068 1146 

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

1070 1148 

1071Type / Values1149Type / Values

1072 1150 

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

1074 1152 

1075Details1153Details

1076 1154 

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

1079Key1157Key

1080 1158 

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

1082 1160 

1083Type / Values1161Type / Values

1084 1162 

1085`number`1163`local | remote`

1086 1164 

1087Details1165Details

1088 1166 

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

1090 1168 

1091Key1169Key

1092 1170 

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

1094 1172 

1095Type / Values1173Type / Values

1096 1174 

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

1098 1176 

1099Details1177Details

1100 1178 

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

1102 1180 

1103Key1181Key

1104 1182 

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

1106 1184 

1107Type / Values1185Type / Values

1108 1186 

1110 1188 

1111Details1189Details

1112 1190 

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

1114 1192 

1115Key1193Key

1116 1194 

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

1118 1196 

1119Type / Values1197Type / Values

1120 1198 

1121`string (path)`1199`boolean`

1122 1200 

1123Details1201Details

1124 1202 

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

1126 1204 

1127Key1205Key

1128 1206 

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

1130 1208 

1131Type / Values1209Type / Values

1132 1210 

1133`integer`1211`array<string>`

1134 1212 

1135Details1213Details

1136 1214 

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

1138 1216 

1139Key1217Key

1140 1218 

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

1142 1220 

1143Type / Values1221Type / Values

1144 1222 

1145`string`1223`number`

1146 1224 

1147Details1225Details

1148 1226 

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

1150 1228 

1151Key1229Key

1152 1230 

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

1154 1232 

1155Type / Values1233Type / Values

1156 1234 

1157`auto | file | keyring`1235`number`

1158 1236 

1159Details1237Details

1160 1238 

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

1162 1240 

1163Key1241Key

1164 1242 

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

1166 1244 

1167Type / Values1245Type / Values

1168 1246 

1169`array<string>`1247`number`

1170 1248 

1171Details1249Details

1172 1250 

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

1174 1252 

1175Key1253Key

1176 1254 

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

1178 1256 

1179Type / Values1257Type / Values

1180 1258 

1182 1260 

1183Details1261Details

1184 1262 

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

1186 1264 

1187Key1265Key

1188 1266 

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

1190 1268 

1191Type / Values1269Type / Values

1192 1270 

1194 1272 

1195Details1273Details

1196 1274 

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

1198 1276 

1199Key1277Key

1200 1278 

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

1202 1280 

1203Type / Values1281Type / Values

1204 1282 

1205`string`1283`boolean`

1206 1284 

1207Details1285Details

1208 1286 

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

1211Key1289Key

1212 1290 

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

1214 1292 

1215Type / Values1293Type / Values

1216 1294 

1217`array<string>`1295`string`

1218 1296 

1219Details1297Details

1220 1298 

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

1222 1300 

1223Key1301Key

1224 1302 

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

1226 1304 

1227Type / Values1305Type / Values

1228 1306 

1230 1308 

1231Details1309Details

1232 1310 

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

1234 1312 

1235Key1313Key

1236 1314 

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

1238 1316 

1239Type / Values1317Type / Values

1240 1318 

1241`array<string>`1319`number`

1242 1320 

1243Details1321Details

1244 1322 

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

1246 1324 

1247Key1325Key

1248 1326 

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

1250 1328 

1251Type / Values1329Type / Values

1252 1330 

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

1254 1332 

1255Details1333Details

1256 1334 

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

1258 1336 

1259Key1337Key

1260 1338 

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

1262 1340 

1263Type / Values1341Type / Values

1264 1342 

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

1266 1344 

1267Details1345Details

1268 1346 

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

1270 1348 

1271Key1349Key

1272 1350 

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

1274 1352 

1275Type / Values1353Type / Values

1276 1354 

1277`array<string>`1355`number`

1278 1356 

1279Details1357Details

1280 1358 

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

1282 1360 

1283Key1361Key

1284 1362 

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

1286 1364 

1287Type / Values1365Type / Values

1288 1366 

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

1290 1368 

1291Details1369Details

1292 1370 

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

1294 1372