config-reference.md Codex Docs, 2026-02-23 18:27 UTC → 2026-04-23 00:46 UTC

6 6 

7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.

8 8 

9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).

10 10 

11| Key | Type / Values | Details |11| Key | Type / Values | Details |

12| --- | --- | --- |12| --- | --- | --- |

13| `agents.<name>.config_file` | `string (path)` | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |13| `agents.<name>.config_file` | `string (path)` | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |

14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |

15| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |

16| `approval_policy` | `untrusted | on-request | never` | Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |16| `agents.job_max_runtime_seconds` | `number` | Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker. |

17| `apps.<id>.disabled_reason` | `unknown | user` | Optional reason attached when an app/connector is disabled. |17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |

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

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 | { 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.granular.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected. |

23| `approval_policy.granular.request_permissions` | `boolean` | When `true`, prompts from the `request_permissions` tool are allowed to surface. |

24| `approval_policy.granular.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface. |

25| `approval_policy.granular.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are allowed to surface. |

26| `approval_policy.granular.skill_approval` | `boolean` | When `true`, skill-script approval prompts are allowed to surface. |

27| `approvals_reviewer` | `user | guardian_subagent` | Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent. |

28| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |

29| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |

30| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |

31| `apps.<id>.default_tools_approval_mode` | `auto | prompt | approve` | Default approval behavior for tools in this app unless a per-tool override exists. |

32| `apps.<id>.default_tools_enabled` | `boolean` | Default enabled state for tools in this app unless a per-tool override exists. |

33| `apps.<id>.destructive_enabled` | `boolean` | Allow or block tools in this app that advertise `destructive_hint = true`. |

18| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |34| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |

35| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |

36| `apps.<id>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. |

37| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |

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

19| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |39| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |

20| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |40| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |

21| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |41| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |

42| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |

22| `compact_prompt` | `string` | Inline override for the history compaction prompt. |43| `compact_prompt` | `string` | Inline override for the history compaction prompt. |

44| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. |

23| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |45| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |

24| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |46| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |

25| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |47| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |

26| `experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`. |

27| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |48| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |

28| `features.apply_patch_freeform` | `boolean` | Expose the freeform `apply_patch` tool (experimental). |

29| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |49| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |

30| `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). |50| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |

31| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |51| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

32| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |52| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |

33| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |53| `features.guardian_approval` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). Use with `approvals_reviewer = "guardian_subagent"`. |

34| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |

35| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |55| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |

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

37| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |57| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |

38| `features.remote_models` | `boolean` | Refresh remote model list before showing readiness (experimental). |58| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |

39| `features.request_rule` | `boolean` | Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default). |

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

41| `features.search_tool` | `boolean` | Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental). |

42| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (beta). |

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

44| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (beta). |60| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |

45| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |61| `features.undo` | `boolean` | Enable undo support (stable; off by default). |

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

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

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

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

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

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

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

56| `include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |

57| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |73| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |

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

59| `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. |75| `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_url` | `string` | Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port. |

60| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |77| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |

61| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |78| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |

62| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |79| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |

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

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

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

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

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

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

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

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

92| `mcp_servers.<id>.scopes` | `array<string>` | OAuth scopes to request when authenticating to that MCP server. |

73| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |93| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |

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

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

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

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

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

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

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

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

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

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

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

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

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

107| `model` | `string` | Model to use (e.g., `gpt-5.4`). |

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

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

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

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

81| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |112| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |

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

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

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

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

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

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

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

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

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

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

91| `model_providers.<id>.requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). |129| `model_providers.<id>.requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). |

92| `model_providers.<id>.stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). |130| `model_providers.<id>.stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). |

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

94| `model_providers.<id>.wire_api` | `chat | responses` | Protocol used by the provider (defaults to `chat` if omitted). |132| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

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

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

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

97| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |136| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |

98| `model_verbosity` | `low | medium | high` | Control GPT-5 Responses API verbosity (defaults to `medium`). |137| `model_verbosity` | `low | medium | high` | Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used. |

99| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |138| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |

100| `notice.hide_gpt-5.1-codex-max_migration_prompt` | `boolean` | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |139| `notice.hide_gpt-5.1-codex-max_migration_prompt` | `boolean` | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |

101| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |140| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |

103| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |142| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |

104| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |143| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |

105| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |144| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |

145| `openai_base_url` | `string` | Base URL override for the built-in `openai` model provider. |

106| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |146| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |

107| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |147| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |

108| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |148| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |

113| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |153| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |

114| `otel.exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL exporter TLS. |154| `otel.exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL exporter TLS. |

115| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |155| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |

156| `otel.metrics_exporter` | `none | statsig | otlp-http | otlp-grpc` | Select the OpenTelemetry metrics exporter (defaults to `statsig`). |

116| `otel.trace_exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |157| `otel.trace_exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |

117| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |158| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |

118| `otel.trace_exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL trace exporter requests. |159| `otel.trace_exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL trace exporter requests. |

120| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |161| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |

121| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |162| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |

122| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |163| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |

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

165| `permissions.<name>.filesystem.":project_roots".<subpath-or-glob>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`. |

166| `permissions.<name>.filesystem.<path-or-glob>` | `"read" | "write" | "none" | table` | Grant direct access for a path, glob pattern, or special token, or scope nested entries under that root. Use `"none"` to deny reads for matching paths. |

167| `permissions.<name>.filesystem.glob_scan_max_depth` | `number` | Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set. |

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

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

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

171| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

172| `permissions.<name>.network.domains` | `map<string, allow | deny>` | Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values. |

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

174| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

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

176| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |

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

178| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |

179| `permissions.<name>.network.unix_sockets` | `map<string, allow | none>` | Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values. |

123| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |180| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |

181| `plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default. |

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

125| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |183| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |

126| `profiles.<name>.experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |184| `profiles.<name>.analytics.enabled` | `boolean` | Profile-scoped analytics enablement override. |

127| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |185| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |

128| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |186| `profiles.<name>.model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |

187| `profiles.<name>.model_instructions_file` | `string (path)` | Profile-scoped replacement for the built-in instruction file. |

129| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |188| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |

130| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |189| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |

190| `profiles.<name>.plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Profile-scoped Plan-mode reasoning override. |

191| `profiles.<name>.service_tier` | `flex | fast` | Profile-scoped service tier preference for new turns. |

192| `profiles.<name>.tools_view_image` | `boolean` | Enable or disable the `view_image` tool in that profile. |

131| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |193| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |

194| `profiles.<name>.windows.sandbox` | `unelevated | elevated` | Profile-scoped Windows sandbox mode override. |

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

133| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |196| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |

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

139| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |202| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |

140| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |203| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |

141| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |204| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |

205| `service_tier` | `flex | fast` | Preferred service tier for new turns. |

142| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |206| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |

143| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |207| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |

144| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |208| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |

149| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |213| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |

150| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |214| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |

151| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |215| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |

216| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |

152| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |217| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |

153| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |218| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |

154| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |219| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

220| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |

221| `tools.web_search` | `boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }` | Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location. |

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

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

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

158| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |225| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |

226| `tui.notification_condition` | `unfocused | always` | Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`. |

227| `tui.notification_method` | `auto | osc9 | bel` | Notification method for terminal notifications (default: auto). |

159| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |228| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |

160| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |229| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |

161| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |230| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

231| `tui.terminal_title` | `array<string> | null` | Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates. |

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

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

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

235| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |

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

164 237 

165Key238Key

166 239 

188 261 

189Key262Key

190 263 

191`agents.max_threads`264`agents.<name>.nickname_candidates`

192 265 

193Type / Values266Type / Values

194 267 

195`number`268`array<string>`

196 269 

197Details270Details

198 271 

199Maximum number of agent threads that can be open concurrently.272Optional pool of display nicknames for spawned agents in that role.

200 273 

201Key274Key

202 275 

203`approval_policy`276`agents.job_max_runtime_seconds`

204 277 

205Type / Values278Type / Values

206 279 

207`untrusted | on-request | never`280`number`

208 281 

209Details282Details

210 283 

211Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.284Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.

212 285 

213Key286Key

214 287 

215`apps.<id>.disabled_reason`288`agents.max_depth`

216 289 

217Type / Values290Type / Values

218 291 

219`unknown | user`292`number`

220 293 

221Details294Details

222 295 

223Optional reason attached when an app/connector is disabled.296Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).

224 297 

225Key298Key

226 299 

227`apps.<id>.enabled`300`agents.max_threads`

228 301 

229Type / Values302Type / Values

230 303 

231`boolean`304`number`

232 305 

233Details306Details

234 307 

235Enable or disable a specific app/connector by id (default: true).308Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.

236 309 

237Key310Key

238 311 

239`chatgpt_base_url`312`allow_login_shell`

240 313 

241Type / Values314Type / Values

242 315 

243`string`316`boolean`

244 317 

245Details318Details

246 319 

247Override the base URL used during the ChatGPT login flow.320Allow 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.

248 321 

249Key322Key

250 323 

251`check_for_update_on_startup`324`analytics.enabled`

252 325 

253Type / Values326Type / Values

254 327 

256 329 

257Details330Details

258 331 

259Check for Codex updates on startup (set to false only when updates are centrally managed).332Enable or disable analytics for this machine/profile. When unset, the client default applies.

260 333 

261Key334Key

262 335 

263`cli_auth_credentials_store`336`approval_policy`

264 337 

265Type / Values338Type / Values

266 339 

267`file | keyring | auto`340`untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }`

268 341 

269Details342Details

270 343 

271Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).344Controls 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.

272 345 

273Key346Key

274 347 

275`compact_prompt`348`approval_policy.granular.mcp_elicitations`

276 349 

277Type / Values350Type / Values

278 351 

279`string`352`boolean`

280 353 

281Details354Details

282 355 

283Inline override for the history compaction prompt.356When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

284 357 

285Key358Key

286 359 

287`developer_instructions`360`approval_policy.granular.request_permissions`

288 361 

289Type / Values362Type / Values

290 363 

291`string`364`boolean`

292 365 

293Details366Details

294 367 

295Additional developer instructions injected into the session (optional).368When `true`, prompts from the `request_permissions` tool are allowed to surface.

296 369 

297Key370Key

298 371 

299`disable_paste_burst`372`approval_policy.granular.rules`

300 373 

301Type / Values374Type / Values

302 375 

304 377 

305Details378Details

306 379 

307Disable burst-paste detection in the TUI.380When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.

308 381 

309Key382Key

310 383 

311`experimental_compact_prompt_file`384`approval_policy.granular.sandbox_approval`

312 385 

313Type / Values386Type / Values

314 387 

315`string (path)`388`boolean`

316 389 

317Details390Details

318 391 

319Load the compaction prompt override from a file (experimental).392When `true`, sandbox escalation approval prompts are allowed to surface.

320 393 

321Key394Key

322 395 

323`experimental_use_freeform_apply_patch`396`approval_policy.granular.skill_approval`

324 397 

325Type / Values398Type / Values

326 399 

328 401 

329Details402Details

330 403 

331Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.404When `true`, skill-script approval prompts are allowed to surface.

332 405 

333Key406Key

334 407 

335`experimental_use_unified_exec_tool`408`approvals_reviewer`

336 409 

337Type / Values410Type / Values

338 411 

339`boolean`412`user | guardian_subagent`

340 413 

341Details414Details

342 415 

343Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.416Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent.

344 417 

345Key418Key

346 419 

347`features.apply_patch_freeform`420`apps._default.destructive_enabled`

348 421 

349Type / Values422Type / Values

350 423 

352 425 

353Details426Details

354 427 

355Expose the freeform `apply_patch` tool (experimental).428Default allow/deny for app tools with `destructive_hint = true`.

356 429 

357Key430Key

358 431 

359`features.apps`432`apps._default.enabled`

360 433 

361Type / Values434Type / Values

362 435 

364 437 

365Details438Details

366 439 

367Enable ChatGPT Apps/connectors support (experimental).440Default app enabled state for all apps unless overridden per app.

368 441 

369Key442Key

370 443 

371`features.apps_mcp_gateway`444`apps._default.open_world_enabled`

372 445 

373Type / Values446Type / Values

374 447 

376 449 

377Details450Details

378 451 

379Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).452Default allow/deny for app tools with `open_world_hint = true`.

380 453 

381Key454Key

382 455 

383`features.child_agents_md`456`apps.<id>.default_tools_approval_mode`

384 457 

385Type / Values458Type / Values

386 459 

387`boolean`460`auto | prompt | approve`

388 461 

389Details462Details

390 463 

391Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).464Default approval behavior for tools in this app unless a per-tool override exists.

392 465 

393Key466Key

394 467 

395`features.collaboration_modes`468`apps.<id>.default_tools_enabled`

396 469 

397Type / Values470Type / Values

398 471 

400 473 

401Details474Details

402 475 

403Enable collaboration modes such as plan mode (stable; on by default).476Default enabled state for tools in this app unless a per-tool override exists.

404 477 

405Key478Key

406 479 

407`features.elevated_windows_sandbox`480`apps.<id>.destructive_enabled`

408 481 

409Type / Values482Type / Values

410 483 

412 485 

413Details486Details

414 487 

415Enable the elevated Windows sandbox pipeline (experimental).488Allow or block tools in this app that advertise `destructive_hint = true`.

416 489 

417Key490Key

418 491 

419`features.experimental_windows_sandbox`492`apps.<id>.enabled`

420 493 

421Type / Values494Type / Values

422 495 

424 497 

425Details498Details

426 499 

427Run the Windows restricted-token sandbox (experimental).500Enable or disable a specific app/connector by id (default: true).

428 501 

429Key502Key

430 503 

431`features.multi_agent`504`apps.<id>.open_world_enabled`

432 505 

433Type / Values506Type / Values

434 507 

436 509 

437Details510Details

438 511 

439Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).512Allow or block tools in this app that advertise `open_world_hint = true`.

440 513 

441Key514Key

442 515 

443`features.personality`516`apps.<id>.tools.<tool>.approval_mode`

444 517 

445Type / Values518Type / Values

446 519 

447`boolean`520`auto | prompt | approve`

448 521 

449Details522Details

450 523 

451Enable personality selection controls (stable; on by default).524Per-tool approval behavior override for a single app tool.

452 525 

453Key526Key

454 527 

455`features.powershell_utf8`528`apps.<id>.tools.<tool>.enabled`

456 529 

457Type / Values530Type / Values

458 531 

460 533 

461Details534Details

462 535 

463Force PowerShell UTF-8 output (defaults to true).536Per-tool enabled override for an app tool (for example `repos/list`).

464 537 

465Key538Key

466 539 

467`features.remote_models`540`background_terminal_max_timeout`

468 541 

469Type / Values542Type / Values

470 543 

471`boolean`544`number`

472 545 

473Details546Details

474 547 

475Refresh remote model list before showing readiness (experimental).548Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.

476 549 

477Key550Key

478 551 

479`features.request_rule`552`chatgpt_base_url`

480 553 

481Type / Values554Type / Values

482 555 

483`boolean`556`string`

484 557 

485Details558Details

486 559 

487Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).560Override the base URL used during the ChatGPT login flow.

488 561 

489Key562Key

490 563 

491`features.runtime_metrics`564`check_for_update_on_startup`

492 565 

493Type / Values566Type / Values

494 567 

496 569 

497Details570Details

498 571 

499Show runtime metrics summary in TUI turn separators (experimental).572Check for Codex updates on startup (set to false only when updates are centrally managed).

500 573 

501Key574Key

502 575 

503`features.search_tool`576`cli_auth_credentials_store`

504 577 

505Type / Values578Type / Values

506 579 

507`boolean`580`file | keyring | auto`

508 581 

509Details582Details

510 583 

511Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).584Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).

512 585 

513Key586Key

514 587 

515`features.shell_snapshot`588`commit_attribution`

516 589 

517Type / Values590Type / Values

518 591 

519`boolean`592`string`

520 593 

521Details594Details

522 595 

523Snapshot shell environment to speed up repeated commands (beta).596Override the commit co-author trailer text. Set an empty string to disable automatic attribution.

524 597 

525Key598Key

526 599 

527`features.shell_tool`600`compact_prompt`

528 601 

529Type / Values602Type / Values

530 603 

531`boolean`604`string`

532 605 

533Details606Details

534 607 

535Enable the default `shell` tool for running commands (stable; on by default).608Inline override for the history compaction prompt.

536 609 

537Key610Key

538 611 

539`features.unified_exec`612`default_permissions`

540 613 

541Type / Values614Type / Values

542 615 

543`boolean`616`string`

544 617 

545Details618Details

546 619 

547Use the unified PTY-backed exec tool (beta).620Name of the default permissions profile to apply to sandboxed tool calls.

548 621 

549Key622Key

550 623 

551`features.use_linux_sandbox_bwrap`624`developer_instructions`

552 625 

553Type / Values626Type / Values

554 627 

555`boolean`628`string`

556 629 

557Details630Details

558 631 

559Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).632Additional developer instructions injected into the session (optional).

560 633 

561Key634Key

562 635 

563`features.web_search`636`disable_paste_burst`

564 637 

565Type / Values638Type / Values

566 639 

568 641 

569Details642Details

570 643 

571Deprecated legacy toggle; prefer the top-level `web_search` setting.644Disable burst-paste detection in the TUI.

572 645 

573Key646Key

574 647 

575`features.web_search_cached`648`experimental_compact_prompt_file`

576 649 

577Type / Values650Type / Values

578 651 

579`boolean`652`string (path)`

580 653 

581Details654Details

582 655 

583Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.656Load the compaction prompt override from a file (experimental).

584 657 

585Key658Key

586 659 

587`features.web_search_request`660`experimental_use_unified_exec_tool`

588 661 

589Type / Values662Type / Values

590 663 

592 665 

593Details666Details

594 667 

595Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.668Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

596 669 

597Key670Key

598 671 

599`feedback.enabled`672`features.apps`

600 673 

601Type / Values674Type / Values

602 675 

604 677 

605Details678Details

606 679 

607Enable feedback submission via `/feedback` across Codex surfaces (default: true).680Enable ChatGPT Apps/connectors support (experimental).

608 681 

609Key682Key

610 683 

611`file_opener`684`features.codex_hooks`

612 685 

613Type / Values686Type / Values

614 687 

615`vscode | vscode-insiders | windsurf | cursor | none`688`boolean`

616 689 

617Details690Details

618 691 

619URI scheme used to open citations from Codex output (default: `vscode`).692Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).

620 693 

621Key694Key

622 695 

623`forced_chatgpt_workspace_id`696`features.enable_request_compression`

624 697 

625Type / Values698Type / Values

626 699 

627`string (uuid)`700`boolean`

628 701 

629Details702Details

630 703 

631Limit ChatGPT logins to a specific workspace identifier.704Compress streaming request bodies with zstd when supported (stable; on by default).

632 705 

633Key706Key

634 707 

635`forced_login_method`708`features.fast_mode`

636 709 

637Type / Values710Type / Values

638 711 

639`chatgpt | api`712`boolean`

640 713 

641Details714Details

642 715 

643Restrict Codex to a specific authentication method.716Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

644 717 

645Key718Key

646 719 

647`hide_agent_reasoning`720`features.guardian_approval`

648 721 

649Type / Values722Type / Values

650 723 

652 725 

653Details726Details

654 727 

655Suppress reasoning events in both the TUI and `codex exec` output.728Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). Use with `approvals_reviewer = "guardian_subagent"`.

656 729 

657Key730Key

658 731 

659`history.max_bytes`732`features.memories`

660 733 

661Type / Values734Type / Values

662 735 

663`number`736`boolean`

664 737 

665Details738Details

666 739 

667If set, caps the history file size in bytes by dropping oldest entries.740Enable [Memories](https://developers.openai.com/codex/memories) (off by default).

668 741 

669Key742Key

670 743 

671`history.persistence`744`features.multi_agent`

672 745 

673Type / Values746Type / Values

674 747 

675`save-all | none`748`boolean`

676 749 

677Details750Details

678 751 

679Control whether Codex saves session transcripts to history.jsonl.752Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

680 753 

681Key754Key

682 755 

683`include_apply_patch_tool`756`features.personality`

684 757 

685Type / Values758Type / Values

686 759 

688 761 

689Details762Details

690 763 

691Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.764Enable personality selection controls (stable; on by default).

692 765 

693Key766Key

694 767 

695`instructions`768`features.prevent_idle_sleep`

696 769 

697Type / Values770Type / Values

698 771 

699`string`772`boolean`

700 773 

701Details774Details

702 775 

703Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.776Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

704 777 

705Key778Key

706 779 

707`log_dir`780`features.shell_snapshot`

708 781 

709Type / Values782Type / Values

710 783 

711`string (path)`784`boolean`

712 785 

713Details786Details

714 787 

715Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.788Snapshot shell environment to speed up repeated commands (stable; on by default).

716 789 

717Key790Key

718 791 

719`mcp_oauth_callback_port`792`features.shell_tool`

720 793 

721Type / Values794Type / Values

722 795 

723`integer`796`boolean`

724 797 

725Details798Details

726 799 

727Optional 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.800Enable the default `shell` tool for running commands (stable; on by default).

728 801 

729Key802Key

730 803 

731`mcp_oauth_credentials_store`804`features.skill_mcp_dependency_install`

732 805 

733Type / Values806Type / Values

734 807 

735`auto | file | keyring`808`boolean`

736 809 

737Details810Details

738 811 

739Preferred store for MCP OAuth credentials.812Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

740 813 

741Key814Key

742 815 

743`mcp_servers.<id>.args`816`features.undo`

744 817 

745Type / Values818Type / Values

746 819 

747`array<string>`820`boolean`

748 821 

749Details822Details

750 823 

751Arguments passed to the MCP stdio server command.824Enable undo support (stable; off by default).

752 825 

753Key826Key

754 827 

755`mcp_servers.<id>.bearer_token_env_var`828`features.unified_exec`

756 829 

757Type / Values830Type / Values

758 831 

759`string`832`boolean`

760 833 

761Details834Details

762 835 

763Environment variable sourcing the bearer token for an MCP HTTP server.836Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

764 837 

765Key838Key

766 839 

767`mcp_servers.<id>.command`840`features.web_search`

768 841 

769Type / Values842Type / Values

770 843 

771`string`844`boolean`

772 845 

773Details846Details

774 847 

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

776 849 

777Key850Key

778 851 

779`mcp_servers.<id>.cwd`852`features.web_search_cached`

780 853 

781Type / Values854Type / Values

782 855 

783`string`856`boolean`

784 857 

785Details858Details

786 859 

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

788 861 

789Key862Key

790 863 

791`mcp_servers.<id>.disabled_tools`864`features.web_search_request`

792 865 

793Type / Values866Type / Values

794 867 

795`array<string>`868`boolean`

796 869 

797Details870Details

798 871 

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

800 873 

801Key874Key

802 875 

803`mcp_servers.<id>.enabled`876`feedback.enabled`

804 877 

805Type / Values878Type / Values

806 879 

808 881 

809Details882Details

810 883 

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

812 885 

813Key886Key

814 887 

815`mcp_servers.<id>.enabled_tools`888`file_opener`

816 889 

817Type / Values890Type / Values

818 891 

819`array<string>`892`vscode | vscode-insiders | windsurf | cursor | none`

820 893 

821Details894Details

822 895 

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

824 897 

825Key898Key

826 899 

827`mcp_servers.<id>.env`900`forced_chatgpt_workspace_id`

828 901 

829Type / Values902Type / Values

830 903 

831`map<string,string>`904`string (uuid)`

832 905 

833Details906Details

834 907 

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

836 909 

837Key910Key

838 911 

839`mcp_servers.<id>.env_http_headers`912`forced_login_method`

840 913 

841Type / Values914Type / Values

842 915 

843`map<string,string>`916`chatgpt | api`

844 917 

845Details918Details

846 919 

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

848 921 

849Key922Key

850 923 

851`mcp_servers.<id>.env_vars`924`hide_agent_reasoning`

852 925 

853Type / Values926Type / Values

854 927 

855`array<string>`928`boolean`

856 929 

857Details930Details

858 931 

859Additional environment variables to whitelist for an MCP stdio server.932Suppress reasoning events in both the TUI and `codex exec` output.

860 933 

861Key934Key

862 935 

863`mcp_servers.<id>.http_headers`936`history.max_bytes`

864 937 

865Type / Values938Type / Values

866 939 

867`map<string,string>`940`number`

868 941 

869Details942Details

870 943 

871Static HTTP headers included with each MCP HTTP request.944If set, caps the history file size in bytes by dropping oldest entries.

872 945 

873Key946Key

874 947 

875`mcp_servers.<id>.required`948`history.persistence`

876 949 

877Type / Values950Type / Values

878 951 

879`boolean`952`save-all | none`

880 953 

881Details954Details

882 955 

883When true, fail startup/resume if this enabled MCP server cannot initialize.956Control whether Codex saves session transcripts to history.jsonl.

884 957 

885Key958Key

886 959 

887`mcp_servers.<id>.startup_timeout_ms`960`instructions`

888 961 

889Type / Values962Type / Values

890 963 

891`number`964`string`

892 965 

893Details966Details

894 967 

895Alias for `startup_timeout_sec` in milliseconds.968Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.

896 969 

897Key970Key

898 971 

899`mcp_servers.<id>.startup_timeout_sec`972`log_dir`

900 973 

901Type / Values974Type / Values

902 975 

903`number`976`string (path)`

904 977 

905Details978Details

906 979 

907Override the default 10s startup timeout for an MCP server.980Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.

908 981 

909Key982Key

910 983 

911`mcp_servers.<id>.tool_timeout_sec`984`mcp_oauth_callback_port`

912 985 

913Type / Values986Type / Values

914 987 

915`number`988`integer`

916 989 

917Details990Details

918 991 

919Override the default 60s per-tool timeout for an MCP server.992Optional 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.

920 993 

921Key994Key

922 995 

923`mcp_servers.<id>.url`996`mcp_oauth_callback_url`

924 997 

925Type / Values998Type / Values

926 999