config-reference.md Codex Docs, 2026-02-23 18:27 UTC → 2026-04-20 18:26 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. |

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>` | Additional environment variables to whitelist for an MCP stdio server. |

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

89| `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. |90| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |

91| `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. |92| `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. |93| `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. |94| `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. |95| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |

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

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

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

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

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

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

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

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

104| `memories.no_memories_if_mcp_or_web_search` | `boolean` | When `true`, threads that use MCP tool calls or web search are kept out of memory generation. Defaults to `false`. |

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

106| `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). |107| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |

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

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

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

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

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

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

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

118| `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. |119| `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. |120| `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. |121| `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). |128| `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). |129| `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). |130| `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). |131| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

132| `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). |133| `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. |134| `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. |135| `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`). |136| `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. |137| `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. |138| `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. |139| `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. |141| `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. |142| `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. |143| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |

144| `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). |145| `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`). |146| `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. |147| `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. |152| `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. |153| `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. |154| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |

155| `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. |156| `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. |157| `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. |158| `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. |160| `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. |161| `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. |162| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |

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

164| `permissions.<name>.filesystem.":project_roots".<subpath>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself. |

165| `permissions.<name>.filesystem.<path>` | `"read" | "write" | "none" | table` | Grant direct access for a path or special token, or scope nested entries under that root. |

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

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

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

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

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

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

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

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

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

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

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

177| `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`. |178| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |

179| `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`). |180| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

125| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |181| `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`. |182| `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`. |183| `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`. |184| `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). |

185| `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. |186| `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. |187| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |

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

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

190| `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"`). |191| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |

192| `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. |193| `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. |194| `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. |195| `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. |200| `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. |201| `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"`. |202| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |

203| `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. |204| `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. |205| `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. |206| `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. |211| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |

150| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |212| `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`. |213| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |

214| `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. |215| `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. |216| `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. |217| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

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

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

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

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

159| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |225| `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). |226| `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. |227| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

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

229| `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. |230| `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). |231| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

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

233| `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 234 

165Key235Key

166 236 

188 258 

189Key259Key

190 260 

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

192 262 

193Type / Values263Type / Values

194 264 

195`number`265`array<string>`

196 266 

197Details267Details

198 268 

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

200 270 

201Key271Key

202 272 

203`approval_policy`273`agents.job_max_runtime_seconds`

204 274 

205Type / Values275Type / Values

206 276 

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

208 278 

209Details279Details

210 280 

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.281Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.

212 282 

213Key283Key

214 284 

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

216 286 

217Type / Values287Type / Values

218 288 

219`unknown | user`289`number`

220 290 

221Details291Details

222 292 

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

224 294 

225Key295Key

226 296 

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

228 298 

229Type / Values299Type / Values

230 300 

231`boolean`301`number`

232 302 

233Details303Details

234 304 

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

236 306 

237Key307Key

238 308 

239`chatgpt_base_url`309`allow_login_shell`

240 310 

241Type / Values311Type / Values

242 312 

243`string`313`boolean`

244 314 

245Details315Details

246 316 

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

249Key319Key

250 320 

251`check_for_update_on_startup`321`analytics.enabled`

252 322 

253Type / Values323Type / Values

254 324 

256 326 

257Details327Details

258 328 

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

260 330 

261Key331Key

262 332 

263`cli_auth_credentials_store`333`approval_policy`

264 334 

265Type / Values335Type / Values

266 336 

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

268 338 

269Details339Details

270 340 

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

273Key343Key

274 344 

275`compact_prompt`345`approval_policy.granular.mcp_elicitations`

276 346 

277Type / Values347Type / Values

278 348 

279`string`349`boolean`

280 350 

281Details351Details

282 352 

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

284 354 

285Key355Key

286 356 

287`developer_instructions`357`approval_policy.granular.request_permissions`

288 358 

289Type / Values359Type / Values

290 360 

291`string`361`boolean`

292 362 

293Details363Details

294 364 

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

296 366 

297Key367Key

298 368 

299`disable_paste_burst`369`approval_policy.granular.rules`

300 370 

301Type / Values371Type / Values

302 372 

304 374 

305Details375Details

306 376 

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

308 378 

309Key379Key

310 380 

311`experimental_compact_prompt_file`381`approval_policy.granular.sandbox_approval`

312 382 

313Type / Values383Type / Values

314 384 

315`string (path)`385`boolean`

316 386 

317Details387Details

318 388 

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

320 390 

321Key391Key

322 392 

323`experimental_use_freeform_apply_patch`393`approval_policy.granular.skill_approval`

324 394 

325Type / Values395Type / Values

326 396 

328 398 

329Details399Details

330 400 

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

332 402 

333Key403Key

334 404 

335`experimental_use_unified_exec_tool`405`approvals_reviewer`

336 406 

337Type / Values407Type / Values

338 408 

339`boolean`409`user | guardian_subagent`

340 410 

341Details411Details

342 412 

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

344 414 

345Key415Key

346 416 

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

348 418 

349Type / Values419Type / Values

350 420 

352 422 

353Details423Details

354 424 

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

356 426 

357Key427Key

358 428 

359`features.apps`429`apps._default.enabled`

360 430 

361Type / Values431Type / Values

362 432 

364 434 

365Details435Details

366 436 

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

368 438 

369Key439Key

370 440 

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

372 442 

373Type / Values443Type / Values

374 444 

376 446 

377Details447Details

378 448 

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

380 450 

381Key451Key

382 452 

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

384 454 

385Type / Values455Type / Values

386 456 

387`boolean`457`auto | prompt | approve`

388 458 

389Details459Details

390 460 

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

392 462 

393Key463Key

394 464 

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

396 466 

397Type / Values467Type / Values

398 468 

400 470 

401Details471Details

402 472 

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

404 474 

405Key475Key

406 476 

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

408 478 

409Type / Values479Type / Values

410 480 

412 482 

413Details483Details

414 484 

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

416 486 

417Key487Key

418 488 

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

420 490 

421Type / Values491Type / Values

422 492 

424 494 

425Details495Details

426 496 

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

428 498 

429Key499Key

430 500 

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

432 502 

433Type / Values503Type / Values

434 504 

436 506 

437Details507Details

438 508 

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

440 510 

441Key511Key

442 512 

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

444 514 

445Type / Values515Type / Values

446 516 

447`boolean`517`auto | prompt | approve`

448 518 

449Details519Details

450 520 

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

452 522 

453Key523Key

454 524 

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

456 526 

457Type / Values527Type / Values

458 528 

460 530 

461Details531Details

462 532 

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

464 534 

465Key535Key

466 536 

467`features.remote_models`537`background_terminal_max_timeout`

468 538 

469Type / Values539Type / Values

470 540 

471`boolean`541`number`

472 542 

473Details543Details

474 544 

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

476 546 

477Key547Key

478 548 

479`features.request_rule`549`chatgpt_base_url`

480 550 

481Type / Values551Type / Values

482 552 

483`boolean`553`string`

484 554 

485Details555Details

486 556 

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

488 558 

489Key559Key

490 560 

491`features.runtime_metrics`561`check_for_update_on_startup`

492 562 

493Type / Values563Type / Values

494 564 

496 566 

497Details567Details

498 568 

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

500 570 

501Key571Key

502 572 

503`features.search_tool`573`cli_auth_credentials_store`

504 574 

505Type / Values575Type / Values

506 576 

507`boolean`577`file | keyring | auto`

508 578 

509Details579Details

510 580 

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

512 582 

513Key583Key

514 584 

515`features.shell_snapshot`585`commit_attribution`

516 586 

517Type / Values587Type / Values

518 588 

519`boolean`589`string`

520 590 

521Details591Details

522 592 

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

524 594 

525Key595Key

526 596 

527`features.shell_tool`597`compact_prompt`

528 598 

529Type / Values599Type / Values

530 600 

531`boolean`601`string`

532 602 

533Details603Details

534 604 

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

536 606 

537Key607Key

538 608 

539`features.unified_exec`609`default_permissions`

540 610 

541Type / Values611Type / Values

542 612 

543`boolean`613`string`

544 614 

545Details615Details

546 616 

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

548 618 

549Key619Key

550 620 

551`features.use_linux_sandbox_bwrap`621`developer_instructions`

552 622 

553Type / Values623Type / Values

554 624 

555`boolean`625`string`

556 626 

557Details627Details

558 628 

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

560 630 

561Key631Key

562 632 

563`features.web_search`633`disable_paste_burst`

564 634 

565Type / Values635Type / Values

566 636 

568 638 

569Details639Details

570 640 

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

572 642 

573Key643Key

574 644 

575`features.web_search_cached`645`experimental_compact_prompt_file`

576 646 

577Type / Values647Type / Values

578 648 

579`boolean`649`string (path)`

580 650 

581Details651Details

582 652 

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

584 654 

585Key655Key

586 656 

587`features.web_search_request`657`experimental_use_unified_exec_tool`

588 658 

589Type / Values659Type / Values

590 660 

592 662 

593Details663Details

594 664 

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

596 666 

597Key667Key

598 668 

599`feedback.enabled`669`features.apps`

600 670 

601Type / Values671Type / Values

602 672 

604 674 

605Details675Details

606 676 

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

608 678 

609Key679Key

610 680 

611`file_opener`681`features.codex_hooks`

612 682 

613Type / Values683Type / Values

614 684 

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

616 686 

617Details687Details

618 688 

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

620 690 

621Key691Key

622 692 

623`forced_chatgpt_workspace_id`693`features.enable_request_compression`

624 694 

625Type / Values695Type / Values

626 696 

627`string (uuid)`697`boolean`

628 698 

629Details699Details

630 700 

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

632 702 

633Key703Key

634 704 

635`forced_login_method`705`features.fast_mode`

636 706 

637Type / Values707Type / Values

638 708 

639`chatgpt | api`709`boolean`

640 710 

641Details711Details

642 712 

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

644 714 

645Key715Key

646 716 

647`hide_agent_reasoning`717`features.guardian_approval`

648 718 

649Type / Values719Type / Values

650 720 

652 722 

653Details723Details

654 724 

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

656 726 

657Key727Key

658 728 

659`history.max_bytes`729`features.memories`

660 730 

661Type / Values731Type / Values

662 732 

663`number`733`boolean`

664 734 

665Details735Details

666 736 

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

668 738 

669Key739Key

670 740 

671`history.persistence`741`features.multi_agent`

672 742 

673Type / Values743Type / Values

674 744 

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

676 746 

677Details747Details

678 748 

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

680 750 

681Key751Key

682 752 

683`include_apply_patch_tool`753`features.personality`

684 754 

685Type / Values755Type / Values

686 756 

688 758 

689Details759Details

690 760 

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

692 762 

693Key763Key

694 764 

695`instructions`765`features.prevent_idle_sleep`

696 766 

697Type / Values767Type / Values

698 768 

699`string`769`boolean`

700 770 

701Details771Details

702 772 

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

704 774 

705Key775Key

706 776 

707`log_dir`777`features.shell_snapshot`

708 778 

709Type / Values779Type / Values

710 780 

711`string (path)`781`boolean`

712 782 

713Details783Details

714 784 

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

716 786 

717Key787Key

718 788 

719`mcp_oauth_callback_port`789`features.shell_tool`

720 790 

721Type / Values791Type / Values

722 792 

723`integer`793`boolean`

724 794 

725Details795Details

726 796 

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

728 798 

729Key799Key

730 800 

731`mcp_oauth_credentials_store`801`features.skill_mcp_dependency_install`

732 802 

733Type / Values803Type / Values

734 804 

735`auto | file | keyring`805`boolean`

736 806 

737Details807Details

738 808 

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

740 810 

741Key811Key

742 812 

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

744 814 

745Type / Values815Type / Values

746 816 

747`array<string>`817`boolean`

748 818 

749Details819Details

750 820 

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

752 822 

753Key823Key

754 824 

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

756 826 

757Type / Values827Type / Values

758 828 

759`string`829`boolean`

760 830 

761Details831Details

762 832 

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

764 834 

765Key835Key

766 836 

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

768 838 

769Type / Values839Type / Values

770 840 

771`string`841`boolean`

772 842 

773Details843Details

774 844 

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

776 846 

777Key847Key

778 848 

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

780 850 

781Type / Values851Type / Values

782 852 

783`string`853`boolean`

784 854 

785Details855Details

786 856 

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

788 858 

789Key859Key

790 860 

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

792 862 

793Type / Values863Type / Values

794 864 

795`array<string>`865`boolean`

796 866 

797Details867Details

798 868 

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

800 870 

801Key871Key

802 872 

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

804 874 

805Type / Values875Type / Values

806 876 

808 878 

809Details879Details

810 880 

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

812 882 

813Key883Key

814 884 

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

816 886 

817Type / Values887Type / Values

818 888 

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

820 890 

821Details891Details

822 892 

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

824 894 

825Key895Key

826 896 

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

828 898 

829Type / Values899Type / Values

830 900 

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

832 902 

833Details903Details

834 904 

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

836 906 

837Key907Key

838 908 

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

840 910 

841Type / Values911Type / Values

842 912 

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

844 914 

845Details915Details

846 916 

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

848 918 

849Key919Key

850 920 

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

852 922 

853Type / Values923Type / Values

854 924 

855`array<string>`925`boolean`

856 926 

857Details927Details

858 928 

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

860 930 

861Key931Key

862 932 

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

864 934 

865Type / Values935Type / Values

866 936 

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

868 938 

869Details939Details

870 940 

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

872 942 

873Key943Key

874 944 

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

876 946 

877Type / Values947Type / Values

878 948 

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

880 950 

881Details951Details

882 952 

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

884 954 

885Key955Key

886 956 

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

888 958 

889Type / Values959Type / Values

890 960 

891`number`961`string`

892 962 

893Details963Details

894 964 

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

896 966 

897Key967Key

898 968 

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

900 970 

901Type / Values971Type / Values

902 972 

903`number`973`string (path)`

904 974 

905Details975Details

906 976 

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

908 978 

909Key979Key

910 980 

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

912 982 

913Type / Values983Type / Values

914 984 

915`number`985`integer`

916 986 

917Details987Details

918 988 

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

921Key991Key

922 992 

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

924 994 

925Type / Values995Type / Values

926 996 

928 998 

929Details999Details

930 1000 

931Endpoint for an MCP streamable HTTP server.1001Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.