config-reference.md Codex Docs, 2026-02-23 18:27 UTC → 2026-04-29 00:50 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 | auto_review` | Who reviews eligible approval prompts under `on-request` or granular approval policies. Defaults to `user`; `auto_review` uses the reviewer subagent. This setting doesn't change sandboxing or review actions already allowed inside the sandbox. |

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| `auto_review.policy` | `string` | Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored. |

39| `background_terminal_max_timeout` | `number` | Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key. |

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

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

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

43| `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. |44| `compact_prompt` | `string` | Inline override for the history compaction prompt. |

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

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

24| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |47| `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). |48| `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`. |49| `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). |50| `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). |51| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. |

31| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |52| `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). |53| `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). |54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |

34| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |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). |

35| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off 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`. |73| `hooks` | `table` | Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events. |

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

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

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. |76| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |

77| `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. |78| `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. |79| `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. |80| `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. |85| `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. |86| `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. |87| `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. |88| `mcp_servers.<id>.env_vars` | `array<string | { name = string, source = "local" | "remote" }>` | Additional environment variables to whitelist for an MCP stdio server. String entries default to `source = "local"`; use `source = "remote"` only with executor-backed remote stdio. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

91| `model_providers.<id>.requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). |130| `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). |131| `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). |132| `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). |133| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

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

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

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

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

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

113| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |154| `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. |155| `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. |156| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

195| `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. |196| `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. |197| `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. |198| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |

135| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers. |199| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers, including project-local config, hooks, and rules. |

136| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |200| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |

137| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |201| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |

138| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |202| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |

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

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

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

206| `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. |207| `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. |208| `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. |209| `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. |214| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |

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

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

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

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

155| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |223| `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). |224| `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). |225| `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). |226| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |

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

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

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

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

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

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

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

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

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

237| `windows.sandbox_private_desktop` | `boolean` | Run the final sandboxed child process on a private desktop by default on native Windows. Set `false` only for compatibility with the older `Winsta0\\Default` behavior. |

164 238 

165Key239Key

166 240 

188 262 

189Key263Key

190 264 

265`agents.<name>.nickname_candidates`

266 

267Type / Values

268 

269`array<string>`

270 

271Details

272 

273Optional pool of display nicknames for spawned agents in that role.

274 

275Key

276 

277`agents.job_max_runtime_seconds`

278 

279Type / Values

280 

281`number`

282 

283Details

284 

285Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.

286 

287Key

288 

289`agents.max_depth`

290 

291Type / Values

292 

293`number`

294 

295Details

296 

297Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).

298 

299Key

300 

191`agents.max_threads`301`agents.max_threads`

192 302 

193Type / Values303Type / Values

196 306 

197Details307Details

198 308 

199Maximum number of agent threads that can be open concurrently.309Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.

310 

311Key

312 

313`allow_login_shell`

314 

315Type / Values

316 

317`boolean`

318 

319Details

320 

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

322 

323Key

324 

325`analytics.enabled`

326 

327Type / Values

328 

329`boolean`

330 

331Details

332 

333Enable or disable analytics for this machine/profile. When unset, the client default applies.

200 334 

201Key335Key

202 336 

204 338 

205Type / Values339Type / Values

206 340 

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

208 342 

209Details343Details

210 344 

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

212 346 

213Key347Key

214 348 

215`apps.<id>.disabled_reason`349`approval_policy.granular.mcp_elicitations`

216 350 

217Type / Values351Type / Values

218 352 

219`unknown | user`353`boolean`

220 354 

221Details355Details

222 356 

223Optional reason attached when an app/connector is disabled.357When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

224 358 

225Key359Key

226 360 

227`apps.<id>.enabled`361`approval_policy.granular.request_permissions`

228 362 

229Type / Values363Type / Values

230 364 

232 366 

233Details367Details

234 368 

235Enable or disable a specific app/connector by id (default: true).369When `true`, prompts from the `request_permissions` tool are allowed to surface.

236 370 

237Key371Key

238 372 

239`chatgpt_base_url`373`approval_policy.granular.rules`

240 374 

241Type / Values375Type / Values

242 376 

243`string`377`boolean`

244 378 

245Details379Details

246 380 

247Override the base URL used during the ChatGPT login flow.381When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.

248 382 

249Key383Key

250 384 

251`check_for_update_on_startup`385`approval_policy.granular.sandbox_approval`

252 386 

253Type / Values387Type / Values

254 388 

256 390 

257Details391Details

258 392 

259Check for Codex updates on startup (set to false only when updates are centrally managed).393When `true`, sandbox escalation approval prompts are allowed to surface.

260 394 

261Key395Key

262 396 

263`cli_auth_credentials_store`397`approval_policy.granular.skill_approval`

264 398 

265Type / Values399Type / Values

266 400 

267`file | keyring | auto`401`boolean`

268 402 

269Details403Details

270 404 

271Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).405When `true`, skill-script approval prompts are allowed to surface.

272 406 

273Key407Key

274 408 

275`compact_prompt`409`approvals_reviewer`

276 410 

277Type / Values411Type / Values

278 412 

279`string`413`user | auto_review`

280 414 

281Details415Details

282 416 

283Inline override for the history compaction prompt.417Who reviews eligible approval prompts under `on-request` or granular approval policies. Defaults to `user`; `auto_review` uses the reviewer subagent. This setting doesn't change sandboxing or review actions already allowed inside the sandbox.

284 418 

285Key419Key

286 420 

287`developer_instructions`421`apps._default.destructive_enabled`

288 422 

289Type / Values423Type / Values

290 424 

291`string`425`boolean`

292 426 

293Details427Details

294 428 

295Additional developer instructions injected into the session (optional).429Default allow/deny for app tools with `destructive_hint = true`.

296 430 

297Key431Key

298 432 

299`disable_paste_burst`433`apps._default.enabled`

300 434 

301Type / Values435Type / Values

302 436 

304 438 

305Details439Details

306 440 

307Disable burst-paste detection in the TUI.441Default app enabled state for all apps unless overridden per app.

308 442 

309Key443Key

310 444 

311`experimental_compact_prompt_file`445`apps._default.open_world_enabled`

312 446 

313Type / Values447Type / Values

314 448 

315`string (path)`449`boolean`

316 450 

317Details451Details

318 452 

319Load the compaction prompt override from a file (experimental).453Default allow/deny for app tools with `open_world_hint = true`.

454 

455Key

456 

457`apps.<id>.default_tools_approval_mode`

458 

459Type / Values

460 

461`auto | prompt | approve`

462 

463Details

464 

465Default approval behavior for tools in this app unless a per-tool override exists.

320 466 

321Key467Key

322 468 

323`experimental_use_freeform_apply_patch`469`apps.<id>.default_tools_enabled`

324 470 

325Type / Values471Type / Values

326 472 

328 474 

329Details475Details

330 476 

331Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.477Default enabled state for tools in this app unless a per-tool override exists.

332 478 

333Key479Key

334 480 

335`experimental_use_unified_exec_tool`481`apps.<id>.destructive_enabled`

336 482 

337Type / Values483Type / Values

338 484 

340 486 

341Details487Details

342 488 

343Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.489Allow or block tools in this app that advertise `destructive_hint = true`.

344 490 

345Key491Key

346 492 

347`features.apply_patch_freeform`493`apps.<id>.enabled`

348 494 

349Type / Values495Type / Values

350 496 

352 498 

353Details499Details

354 500 

355Expose the freeform `apply_patch` tool (experimental).501Enable or disable a specific app/connector by id (default: true).

356 502 

357Key503Key

358 504 

359`features.apps`505`apps.<id>.open_world_enabled`

360 506 

361Type / Values507Type / Values

362 508 

364 510 

365Details511Details

366 512 

367Enable ChatGPT Apps/connectors support (experimental).513Allow or block tools in this app that advertise `open_world_hint = true`.

514 

515Key

516 

517`apps.<id>.tools.<tool>.approval_mode`

518 

519Type / Values

520 

521`auto | prompt | approve`

522 

523Details

524 

525Per-tool approval behavior override for a single app tool.

368 526 

369Key527Key

370 528 

371`features.apps_mcp_gateway`529`apps.<id>.tools.<tool>.enabled`

372 530 

373Type / Values531Type / Values

374 532 

376 534 

377Details535Details

378 536 

379Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).537Per-tool enabled override for an app tool (for example `repos/list`).

538 

539Key

540 

541`auto_review.policy`

542 

543Type / Values

544 

545`string`

546 

547Details

548 

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

550 

551Key

552 

553`background_terminal_max_timeout`

554 

555Type / Values

556 

557`number`

558 

559Details

560 

561Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.

562 

563Key

564 

565`chatgpt_base_url`

566 

567Type / Values

568 

569`string`

570 

571Details

572 

573Override the base URL used during the ChatGPT login flow.

380 574 

381Key575Key

382 576 

383`features.child_agents_md`577`check_for_update_on_startup`

384 578 

385Type / Values579Type / Values

386 580 

388 582 

389Details583Details

390 584 

391Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).585Check for Codex updates on startup (set to false only when updates are centrally managed).

586 

587Key

588 

589`cli_auth_credentials_store`

590 

591Type / Values

592 

593`file | keyring | auto`

594 

595Details

596 

597Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).

598 

599Key

600 

601`commit_attribution`

602 

603Type / Values

604 

605`string`

606 

607Details

608 

609Override the commit co-author trailer text. Set an empty string to disable automatic attribution.

610 

611Key

612 

613`compact_prompt`

614 

615Type / Values

616 

617`string`

618 

619Details

620 

621Inline override for the history compaction prompt.

622 

623Key

624 

625`default_permissions`

626 

627Type / Values

628 

629`string`

630 

631Details

632 

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

634 

635Key

636 

637`developer_instructions`

638 

639Type / Values

640 

641`string`

642 

643Details

644 

645Additional developer instructions injected into the session (optional).

392 646 

393Key647Key

394 648 

395`features.collaboration_modes`649`disable_paste_burst`

396 650 

397Type / Values651Type / Values

398 652 

400 654 

401Details655Details

402 656 

403Enable collaboration modes such as plan mode (stable; on by default).657Disable burst-paste detection in the TUI.

658 

659Key

660 

661`experimental_compact_prompt_file`

662 

663Type / Values

664 

665`string (path)`

666 

667Details

668 

669Load the compaction prompt override from a file (experimental).

404 670 

405Key671Key

406 672 

407`features.elevated_windows_sandbox`673`experimental_use_unified_exec_tool`

408 674 

409Type / Values675Type / Values

410 676 

412 678 

413Details679Details

414 680 

415Enable the elevated Windows sandbox pipeline (experimental).681Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

416 682 

417Key683Key

418 684 

419`features.experimental_windows_sandbox`685`features.apps`

420 686 

421Type / Values687Type / Values

422 688 

424 690 

425Details691Details

426 692 

427Run the Windows restricted-token sandbox (experimental).693Enable ChatGPT Apps/connectors support (experimental).

428 694 

429Key695Key

430 696 

431`features.multi_agent`697`features.codex_hooks`

432 698 

433Type / Values699Type / Values

434 700 

436 702 

437Details703Details

438 704 

439Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).705Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.

440 706 

441Key707Key

442 708 

443`features.personality`709`features.enable_request_compression`

444 710 

445Type / Values711Type / Values

446 712 

448 714 

449Details715Details

450 716 

451Enable personality selection controls (stable; on by default).717Compress streaming request bodies with zstd when supported (stable; on by default).

452 718 

453Key719Key

454 720 

455`features.powershell_utf8`721`features.fast_mode`

456 722 

457Type / Values723Type / Values

458 724 

460 726 

461Details727Details

462 728 

463Force PowerShell UTF-8 output (defaults to true).729Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

464 730 

465Key731Key

466 732 

467`features.remote_models`733`features.memories`

468 734 

469Type / Values735Type / Values

470 736 

472 738 

473Details739Details

474 740 

475Refresh remote model list before showing readiness (experimental).741Enable [Memories](https://developers.openai.com/codex/memories) (off by default).

476 742 

477Key743Key

478 744 

479`features.request_rule`745`features.multi_agent`

480 746 

481Type / Values747Type / Values

482 748 

484 750 

485Details751Details

486 752 

487Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).753Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

488 754 

489Key755Key

490 756 

491`features.runtime_metrics`757`features.personality`

492 758 

493Type / Values759Type / Values

494 760 

496 762 

497Details763Details

498 764 

499Show runtime metrics summary in TUI turn separators (experimental).765Enable personality selection controls (stable; on by default).

500 766 

501Key767Key

502 768 

503`features.search_tool`769`features.prevent_idle_sleep`

504 770 

505Type / Values771Type / Values

506 772 

508 774 

509Details775Details

510 776 

511Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).777Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

512 778 

513Key779Key

514 780 

520 786 

521Details787Details

522 788 

523Snapshot shell environment to speed up repeated commands (beta).789Snapshot shell environment to speed up repeated commands (stable; on by default).

524 790 

525Key791Key

526 792 

536 802 

537Key803Key

538 804 

539`features.unified_exec`805`features.skill_mcp_dependency_install`

806 

807Type / Values

808 

809`boolean`

810 

811Details

812 

813Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

814 

815Key

816 

817`features.undo`

540 818 

541Type / Values819Type / Values

542 820 

544 822 

545Details823Details

546 824 

547Use the unified PTY-backed exec tool (beta).825Enable undo support (stable; off by default).

548 826 

549Key827Key

550 828 

551`features.use_linux_sandbox_bwrap`829`features.unified_exec`

552 830 

553Type / Values831Type / Values

554 832 

556 834 

557Details835Details

558 836 

559Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).837Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

560 838 

561Key839Key

562 840 

680 958 

681Key959Key

682 960 

683`include_apply_patch_tool`961`hooks`

684 962 

685Type / Values963Type / Values

686 964 

687`boolean`965`table`

688 966 

689Details967Details

690 968 

691Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.969Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.

692 970 

693Key971Key

694 972 

728 1006 

729Key1007Key

730 1008 

1009`mcp_oauth_callback_url`

1010 

1011Type / Values

1012 

1013`string`

1014 

1015Details

1016 

1017Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.

1018 

1019Key

1020 

731`mcp_oauth_credentials_store`1021`mcp_oauth_credentials_store`

732 1022 

733Type / Values1023Type / Values

852 1142 

853Type / Values1143Type / Values

854 1144 

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

856 1146 

857Details1147Details

858 1148 

859Additional environment variables to whitelist for an MCP stdio server.1149Additional environment variables to whitelist for an MCP stdio server. String entries default to `source = "local"`; use `source = "remote"` only with executor-backed remote stdio.

860 1150 

861Key1151Key

862 1152 

863`mcp_servers.<id>.http_headers`1153`mcp_servers.<id>.experimental_environment`

864 1154 

865Type / Values1155Type / Values

866 1156 

867`map<string,string>`1157`local | remote`

868 1158 

869Details1159Details

870 1160 

871Static HTTP headers included with each MCP HTTP request.1161Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.

872 1162 

873Key1163Key

874 1164 

875`mcp_servers.<id>.required`1165`mcp_servers.<id>.http_headers`

876 1166 

877Type / Values1167Type / Values

878 1168 

879`boolean`1169`map<string,string>`

880 1170 

881Details1171Details

882 1172 

883When true, fail startup/resume if this enabled MCP server cannot initialize.1173Static HTTP headers included with each MCP HTTP request.

884 1174 

885Key1175Key

886 1176 

887`mcp_servers.<id>.startup_timeout_ms`1177`mcp_servers.<id>.oauth_resource`

888 1178 

889Type / Values1179Type / Values

890 1180 

891`number`1181`string`

892 1182 

893Details1183Details

894 1184 

895Alias for `startup_timeout_sec` in milliseconds.1185Optional RFC 8707 OAuth resource parameter to include during MCP login.

896 1186 

897Key1187Key

898 1188 

899`mcp_servers.<id>.startup_timeout_sec`1189`mcp_servers.<id>.required`

900 1190 

901Type / Values1191Type / Values

902 1192 

903`number`1193`boolean`

1194 

1195Details

1196 

1197When true, fail startup/resume if this enabled MCP server cannot initialize.

1198 

1199Key

1200 

1201`mcp_servers.<id>.scopes`

1202 

1203Type / Values

1204 

1205`array<string>`

1206 

1207Details

1208 

1209OAuth scopes to request when authenticating to that MCP server.

1210 

1211Key

1212 

1213`mcp_servers.<id>.startup_timeout_ms`

1214 

1215Type / Values

1216 

1217`number`

1218 

1219Details

1220 

1221Alias for `startup_timeout_sec` in milliseconds.

1222 

1223Key

1224 

1225`mcp_servers.<id>.startup_timeout_sec`

1226 

1227Type / Values

1228 

1229`number`

904 1230 

905Details1231Details

906 1232 

932 1258 

933Key1259Key

934 1260 

1261`memories.consolidation_model`

1262 

1263Type / Values

1264 

1265`string`

1266 

1267Details

1268 

1269Optional model override for global memory consolidation.

1270 

1271Key

1272 

1273`memories.disable_on_external_context`

1274 

1275Type / Values

1276 

1277`boolean`

1278 

1279Details

1280 

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

1282 

1283Key

1284 

1285`memories.extract_model`

1286 

1287Type / Values

1288 

1289`string`

1290 

1291Details

1292 

1293Optional model override for per-thread memory extraction.

1294 

1295Key

1296 

1297`memories.generate_memories`

1298 

1299Type / Values

1300 

1301`boolean`

1302 

1303Details

1304 

1305When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.

1306 

1307Key

1308 

1309`memories.max_raw_memories_for_consolidation`

1310 

1311Type / Values

1312 

1313`number`

1314 

1315Details

1316 

1317Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.

1318 

1319Key

1320 

1321`memories.max_rollout_age_days`

1322 

1323Type / Values

1324 

1325`number`

1326 

1327Details

1328 

1329Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.

1330 

1331Key

1332 

1333`memories.max_rollouts_per_startup`

1334 

1335Type / Values

1336 

1337`number`

1338 

1339Details

1340 

1341Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.

1342 

1343Key

1344 

1345`memories.max_unused_days`

1346 

1347Type / Values

1348 

1349`number`

1350 

1351Details

1352 

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

1354 

1355Key

1356 

1357`memories.min_rollout_idle_hours`

1358 

1359Type / Values

1360 

1361`number`

1362 

1363Details

1364 

1365Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.

1366 

1367Key

1368 

1369`memories.use_memories`

1370 

1371Type / Values

1372 

1373`boolean`

1374 

1375Details

1376 

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

1378 

1379Key

1380 

935`model`1381`model`

936 1382 

937Type / Values1383Type / Values

940 1386 

941Details1387Details

942 1388 

943Model to use (e.g., `gpt-5-codex`).1389Model to use (e.g., `gpt-5.5`).

944 1390 

945Key1391Key

946 1392 

956 1402 

957Key1403Key

958 1404 

1405`model_catalog_json`

1406 

1407Type / Values

1408 

1409`string (path)`

1410 

1411Details

1412 

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

1414 

1415Key

1416 

959`model_context_window`1417`model_context_window`

960 1418 

961Type / Values1419Type / Values

992 1450 

993Key1451Key

994 1452 

1453`model_providers.<id>`

1454 

1455Type / Values

1456 

1457`table`

1458 

1459Details

1460 

1461Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.

1462 

1463Key

1464 

1465`model_providers.<id>.auth`

1466 

1467Type / Values

1468 

1469`table`

1470 

1471Details

1472 

1473Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.

1474 

1475Key

1476 

1477`model_providers.<id>.auth.args`

1478 

1479Type / Values

1480 

1481`array<string>`

1482 

1483Details

1484 

1485Arguments passed to the token command.

1486 

1487Key

1488 

1489`model_providers.<id>.auth.command`

1490 

1491Type / Values

1492 

1493`string`

1494 

1495Details

1496 

1497Command to run when Codex needs a bearer token. The command must print the token to stdout.

1498 

1499Key

1500 

1501`model_providers.<id>.auth.cwd`

1502 

1503Type / Values

1504 

1505`string (path)`

1506 

1507Details

1508 

1509Working directory for the token command.

1510 

1511Key

1512 

1513`model_providers.<id>.auth.refresh_interval_ms`

1514 

1515Type / Values

1516 

1517`number`

1518 

1519Details

1520 

1521How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.

1522 

1523Key

1524 

1525`model_providers.<id>.auth.timeout_ms`

1526 

1527Type / Values

1528 

1529`number`

1530 

1531Details

1532 

1533Maximum token command runtime in milliseconds (default: 5000).

1534 

1535Key

1536 

995`model_providers.<id>.base_url`1537`model_providers.<id>.base_url`

996 1538 

997Type / Values1539Type / Values

1136 1678 

1137Key1679Key

1138 1680 

1681`model_providers.<id>.supports_websockets`

1682 

1683Type / Values

1684 

1685`boolean`

1686 

1687Details

1688 

1689Whether that provider supports the Responses API WebSocket transport.

1690 

1691Key

1692 

1139`model_providers.<id>.wire_api`1693`model_providers.<id>.wire_api`

1140 1694 

1141Type / Values1695Type / Values

1142 1696 

1143`chat | responses`1697`responses`

1144 1698 

1145Details1699Details

1146 1700 

1147Protocol used by the provider (defaults to `chat` if omitted).1701Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.

1148 1702 

1149Key1703Key

1150 1704 

1192 1746 

1193Details1747Details

1194 1748 

1195Control GPT-5 Responses API verbosity (defaults to `medium`).1749Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.

1196 1750 

1197Key1751Key

1198 1752 

1280 1834 

1281Key1835Key

1282 1836 

1837`openai_base_url`

1838 

1839Type / Values

1840 

1841`string`

1842 

1843Details

1844 

1845Base URL override for the built-in `openai` model provider.

1846 

1847Key

1848 

1283`oss_provider`1849`oss_provider`

1284 1850 

1285Type / Values1851Type / Values

1400 1966 

1401Key1967Key

1402 1968 

1969`otel.metrics_exporter`

1970 

1971Type / Values

1972 

1973`none | statsig | otlp-http | otlp-grpc`

1974 

1975Details

1976 

1977Select the OpenTelemetry metrics exporter (defaults to `statsig`).

1978 

1979Key

1980 

1403`otel.trace_exporter`1981`otel.trace_exporter`

1404 1982 

1405Type / Values1983Type / Values

1484 2062 

1485Key2063Key

1486 2064 

1487`personality`2065`permissions.<name>.filesystem`

1488 2066 

1489Type / Values2067Type / Values

1490 2068 

1491`none | friendly | pragmatic`2069`table`

1492 2070 

1493Details2071Details

1494 2072 

1495Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.2073Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.

1496 2074 

1497Key2075Key

1498 2076 

1499`profile`2077`permissions.<name>.filesystem.":project_roots".<subpath-or-glob>`

1500 2078 

1501Type / Values2079Type / Values

1502 2080 

1503`string`2081`"read" | "write" | "none"`

1504 2082 

1505Details2083Details

1506 2084 

1507Default profile applied at startup (equivalent to `--profile`).2085Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`.

1508 2086 

1509Key2087Key

1510 2088 

1511`profiles.<name>.*`2089`permissions.<name>.filesystem.<path-or-glob>`

1512 2090 

1513Type / Values2091Type / Values

1514 2092 

1515`various`2093`"read" | "write" | "none" | table`

1516 2094 

1517Details2095Details

1518 2096 

1519Profile-scoped overrides for any of the supported configuration keys.2097Grant 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.

1520 2098 

1521Key2099Key

1522 2100