config-reference.md Codex Docs, 2026-03-18 00:36 UTC → 2026-05-02 00:48 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.personality` | `boolean` | Enable personality selection controls (stable; on by default). |56| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

107| `memories.min_rollout_idle_hours` | `number` | Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`. |

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

109| `model` | `string` | Model to use (e.g., `gpt-5.5`). |

109| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |110| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |

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

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

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

113| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |114| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |

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

116| `model_providers.<id>.auth` | `table` | Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`. |

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

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

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

120| `model_providers.<id>.auth.refresh_interval_ms` | `number` | How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry. |

121| `model_providers.<id>.auth.timeout_ms` | `number` | Maximum token command runtime in milliseconds (default: 5000). |

114| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |122| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |

115| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |123| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |

116| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |124| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

174| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |186| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

187| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |199| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |

188| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |200| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |

189| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |201| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |

190| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers. |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. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

213| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |227| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

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

215| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |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`. |

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

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

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

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

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

221| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |239| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |

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

223| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |241| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

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

225 244 

226Key245Key

227 246 

325 344 

326Type / Values345Type / Values

327 346 

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

329 348 

330Details349Details

331 350 

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

333 352 

334Key353Key

335 354 

336`approval_policy.reject.mcp_elicitations`355`approval_policy.granular.mcp_elicitations`

337 356 

338Type / Values357Type / Values

339 358 

341 360 

342Details361Details

343 362 

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

345 364 

346Key365Key

347 366 

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

349 368 

350Type / Values369Type / Values

351 370 

353 372 

354Details373Details

355 374 

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

357 376 

358Key377Key

359 378 

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

361 380 

362Type / Values381Type / Values

363 382 

365 384 

366Details385Details

367 386 

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

369 424 

370Key425Key

371 426 

489 544 

490Key545Key

491 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 

492`background_terminal_max_timeout`559`background_terminal_max_timeout`

493 560 

494Type / Values561Type / Values

561 628 

562Key629Key

563 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 

564`developer_instructions`643`developer_instructions`

565 644 

566Type / Values645Type / Values

621 700 

622Key701Key

623 702 

624`features.apps_mcp_gateway`703`features.codex_hooks`

625 704 

626Type / Values705Type / Values

627 706 

629 708 

630Details709Details

631 710 

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

633 712 

634Key713Key

635 714 

636`features.artifact`715`features.enable_request_compression`

637 716 

638Type / Values717Type / Values

639 718 

641 720 

642Details721Details

643 722 

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

645 724 

646Key725Key

647 726 

648`features.child_agents_md`727`features.fast_mode`

649 728 

650Type / Values729Type / Values

651 730 

653 732 

654Details733Details

655 734 

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

657 736 

658Key737Key

659 738 

660`features.collaboration_modes`739`features.memories`

661 740 

662Type / Values741Type / Values

663 742 

665 744 

666Details745Details

667 746 

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

669 748 

670Key749Key

671 750 

672`features.default_mode_request_user_input`751`features.multi_agent`

673 752 

674Type / Values753Type / Values

675 754 

677 756 

678Details757Details

679 758 

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

681 760 

682Key761Key

683 762 

684`features.elevated_windows_sandbox`763`features.personality`

685 764 

686Type / Values765Type / Values

687 766 

689 768 

690Details769Details

691 770 

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

693 772 

694Key773Key

695 774 

696`features.enable_request_compression`775`features.prevent_idle_sleep`

697 776 

698Type / Values777Type / Values

699 778 

701 780 

702Details781Details

703 782 

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

705 784 

706Key785Key

707 786 

708`features.experimental_windows_sandbox`787`features.shell_snapshot`

709 788 

710Type / Values789Type / Values

711 790 

713 792 

714Details793Details

715 794 

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

717 796 

718Key797Key

719 798 

720`features.fast_mode`799`features.shell_tool`

721 800 

722Type / Values801Type / Values

723 802 

725 804 

726Details805Details

727 806 

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

729 808 

730Key809Key

731 810 

732`features.image_detail_original`811`features.skill_mcp_dependency_install`

733 812 

734Type / Values813Type / Values

735 814 

737 816 

738Details817Details

739 818 

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

741 820 

742Key821Key

743 822 

744`features.image_generation`823`features.undo`

745 824 

746Type / Values825Type / Values

747 826 

749 828 

750Details829Details

751 830 

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

753 832 

754Key833Key

755 834 

756`features.personality`835`features.unified_exec`

757 836 

758Type / Values837Type / Values

759 838 

761 840 

762Details841Details

763 842 

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

765 844 

766Key845Key

767 846 

768`features.powershell_utf8`847`features.web_search`

769 848 

770Type / Values849Type / Values

771 850 

773 852 

774Details853Details

775 854 

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

777 856 

778Key857Key

779 858 

780`features.prevent_idle_sleep`859`features.web_search_cached`

781 860 

782Type / Values861Type / Values

783 862 

785 864 

786Details865Details

787 866 

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

789 868 

790Key869Key

791 870 

792`features.remote_models`871`features.web_search_request`

793 872 

794Type / Values873Type / Values

795 874 

797 876 

798Details877Details

799 878 

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

801 880 

802Key881Key

803 882 

804`features.request_rule`883`feedback.enabled`

805 884 

806Type / Values885Type / Values

807 886 

809 888 

810Details889Details

811 890 

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

813 892 

814Key893Key

815 894 

816`features.responses_websockets`895`file_opener`

817 896 

818Type / Values897Type / Values

819 898 

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

821 900 

822Details901Details

823 902 

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

825 904 

826Key905Key

827 906 

828`features.responses_websockets_v2`907`forced_chatgpt_workspace_id`

829 908 

830Type / Values909Type / Values

831 910 

832`boolean`911`string (uuid)`

833 912 

834Details913Details

835 914 

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

837 916 

838Key917Key

839 918 

840`features.runtime_metrics`919`forced_login_method`

841 920 

842Type / Values921Type / Values

843 922 

844`boolean`923`chatgpt | api`

845 924 

846Details925Details

847 926 

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

849 928 

850Key929Key

851 930 

852`features.search_tool`931`hide_agent_reasoning`

853 932 

854Type / Values933Type / Values

855 934 

857 936 

858Details937Details

859 938 

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

861 940 

862Key941Key

863 942 

864`features.shell_snapshot`943`history.max_bytes`

865 944 

866Type / Values945Type / Values

867 946 

868`boolean`947`number`

869 948 

870Details949Details

871 950 

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

873 952 

874Key953Key

875 954 

876`features.shell_tool`955`history.persistence`

877 956 

878Type / Values957Type / Values

879 958 

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

881 960 

882Details961Details

883 962 

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

885 964 

886Key965Key

887 966 

888`features.skill_env_var_dependency_prompt`967`hooks`

889 968 

890Type / Values969Type / Values

891 970 

892`boolean`971`table`

893 972 

894Details973Details

895 974 

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

897 976 

898Key977Key

899 978 

900`features.skill_mcp_dependency_install`979`instructions`

901 980 

902Type / Values981Type / Values

903 982 

904`boolean`983`string`

905 984 

906Details985Details

907 986 

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

909 988 

910Key989Key

911 990 

912`features.sqlite`991`log_dir`

913 992 

914Type / Values993Type / Values

915 994 

916`boolean`995`string (path)`

917 996 

918Details997Details

919 998 

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

921 1000 

922Key1001Key

923 1002 

924`features.steer`1003`mcp_oauth_callback_port`

925 1004 

926Type / Values1005Type / Values

927 1006 

928`boolean`1007`integer`

929 1008 

930Details1009Details

931 1010 

932Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.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.

933 1012 

934Key1013Key

935 1014 

936`features.undo`1015`mcp_oauth_callback_url`

937 1016 

938Type / Values1017Type / Values

939 1018 

940`boolean`1019`string`

941 1020 

942Details1021Details

943 1022 

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

945 1024 

946Key1025Key

947 1026 

948`features.unified_exec`1027`mcp_oauth_credentials_store`

949 1028 

950Type / Values1029Type / Values

951 1030 

952`boolean`1031`auto | file | keyring`

953 1032 

954Details1033Details

955 1034 

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

957 1036 

958Key1037Key

959 1038 

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

961 1040 

962Type / Values1041Type / Values

963 1042 

964`boolean`1043`array<string>`

965 1044 

966Details1045Details

967 1046 

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

969 1048 

970Key1049Key

971 1050 

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

973 1052 

974Type / Values1053Type / Values

975 1054 

976`boolean`1055`string`

977 1056 

978Details1057Details

979 1058 

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

981 1060 

982Key1061Key

983 1062 

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

985 1064 

986Type / Values1065Type / Values

987 1066 

988`boolean`1067`string`

989 1068 

990Details1069Details

991 1070 

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

993 1072 

994Key1073Key

995 1074 

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

997 1076 

998Type / Values1077Type / Values

999 1078 

1000`boolean`1079`string`

1001 1080 

1002Details1081Details

1003 1082 

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

1005 1084 

1006Key1085Key

1007 1086 

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

1088 

1089Type / Values

1090 

1091`array<string>`

1092 

1093Details

1094 

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

1096 

1097Key

1098 

1099`mcp_servers.<id>.enabled`

1009 1100 

1010Type / Values1101Type / Values

1011 1102 

1013 1104 

1014Details1105Details

1015 1106 

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

1017 1108 

1018Key1109Key

1019 1110 

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

1021 1112 

1022Type / Values1113Type / Values

1023 1114 

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

1025 1116 

1026Details1117Details

1027 1118 

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

1029 1120 

1030Key1121Key

1031 1122 

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

1033 1124 

1034Type / Values1125Type / Values

1035 1126 

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

1037 1128 

1038Details1129Details

1039 1130 

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

1041 1132 

1042Key1133Key

1043 1134 

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

1045 1136 

1046Type / Values1137Type / Values

1047 1138 

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

1049 1140 

1050Details1141Details

1051 1142 

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

1053 1144 

1054Key1145Key

1055 1146 

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

1057 1148 

1058Type / Values1149Type / Values

1059 1150 

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

1061 1152 

1062Details1153Details

1063 1154 

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

1065 1156 

1066Key1157Key

1067 1158 

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

1069 1160 

1070Type / Values1161Type / Values

1071 1162 

1072`number`1163`local | remote`

1073 1164 

1074Details1165Details

1075 1166 

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

1077 1168 

1078Key1169Key

1079 1170 

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

1081 1172 

1082Type / Values1173Type / Values

1083 1174 

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

1085 1176 

1086Details1177Details

1087 1178 

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

1089 1180 

1090Key1181Key

1091 1182 

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

1093 1184 

1094Type / Values1185Type / Values

1095 1186 

1097 1188 

1098Details1189Details

1099 1190 

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

1101 1192 

1102Key1193Key

1103 1194 

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

1105 1196 

1106Type / Values1197Type / Values

1107 1198 

1108`string (path)`1199`boolean`

1109 1200 

1110Details1201Details

1111 1202 

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

1113 1204 

1114Key1205Key

1115 1206 

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

1117 1208 

1118Type / Values1209Type / Values

1119 1210 

1120`integer`1211`array<string>`

1121 1212 

1122Details1213Details

1123 1214 

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

1125 1216 

1126Key1217Key

1127 1218 

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

1129 1220 

1130Type / Values1221Type / Values

1131 1222 

1132`string`1223`number`

1133 1224 

1134Details1225Details

1135 1226 

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

1137 1228 

1138Key1229Key

1139 1230 

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

1141 1232 

1142Type / Values1233Type / Values

1143 1234 

1144`auto | file | keyring`1235`number`

1145 1236 

1146Details1237Details

1147 1238 

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

1149 1240 

1150Key1241Key

1151 1242 

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

1153 1244 

1154Type / Values1245Type / Values

1155 1246 

1156`array<string>`1247`number`

1157 1248 

1158Details1249Details

1159 1250 

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

1161 1252 

1162Key1253Key

1163 1254 

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

1165 1256 

1166Type / Values1257Type / Values

1167 1258 

1169 1260 

1170Details1261Details

1171 1262 

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

1173 1264 

1174Key1265Key

1175 1266 

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

1177 1268 

1178Type / Values1269Type / Values

1179 1270 

1181 1272 

1182Details1273Details

1183 1274 

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

1185 1276 

1186Key1277Key

1187 1278 

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

1189 1280 

1190Type / Values1281Type / Values

1191 1282 

1192`string`1283`boolean`

1193 1284 

1194Details1285Details

1195 1286 

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

1197 1288 

1198Key1289Key

1199 1290 

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

1201 1292 

1202Type / Values1293Type / Values

1203 1294 

1204`array<string>`1295`string`

1205 1296 

1206Details1297Details

1207 1298 

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

1209 1300 

1210Key1301Key

1211 1302 

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

1213 1304 

1214Type / Values1305Type / Values

1215 1306 

1217 1308 

1218Details1309Details

1219 1310 

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

1221 1312 

1222Key1313Key

1223 1314 

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

1225 1316 

1226Type / Values1317Type / Values

1227 1318 

1228`array<string>`1319`number`

1229 1320 

1230Details1321Details

1231 1322 

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

1233 1324 

1234Key1325Key

1235 1326 

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

1237 1328 

1238Type / Values1329Type / Values

1239 1330 

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

1241 1332 

1242Details1333Details

1243 1334 

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

1245 1336 

1246Key1337Key

1247 1338 

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

1249 1340 

1250Type / Values1341Type / Values

1251 1342 

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

1253 1344 

1254Details1345Details

1255 1346 

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

1257 1348 

1258Key1349Key

1259 1350 

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

1261 1352 

1262Type / Values1353Type / Values

1263 1354 

1264`array<string>`1355`number`

1265 1356 

1266Details1357Details

1267 1358 

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

1269 1360 

1270Key1361Key

1271 1362 

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

1273 1364 

1274Type / Values1365Type / Values

1275 1366 

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

1277 1368 

1278Details1369Details

1279 1370 

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

1281 1372 

1282Key1373Key

1283 1374 

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

1285 1376 

1286Type / Values1377Type / Values

1287 1378 

1288`string`1379`number`

1289 1380 

1290Details1381Details

1291 1382 

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