config-reference.md Codex Docs, 2026-02-20 12:16 UTC → 2026-04-29 12:40 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/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 

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

10| --- | --- | --- |12| --- | --- | --- |

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

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

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

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

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

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

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

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

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

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

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

22| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |47| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |

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

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

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

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

27| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |50| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |

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

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

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

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

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

33| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

95| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |138| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |

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

97| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |140| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |

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

99| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |142| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |

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

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

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

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

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

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

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

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

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

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

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

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

115| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |160| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

122| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |184| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

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

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

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

126| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |188| `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). |

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

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

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

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

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

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

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

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

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

131| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |198| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |

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

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

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

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

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

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

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

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

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

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

141| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |209| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |

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

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

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

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

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

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

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

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

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

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

153| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |224| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

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

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

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

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

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

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

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

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

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

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

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

161| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |236| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

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

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

162 239 

163Key240Key

164 241 

186 263 

187Key264Key

188 265 

266`agents.<name>.nickname_candidates`

267 

268Type / Values

269 

270`array<string>`

271 

272Details

273 

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

275 

276Key

277 

278`agents.job_max_runtime_seconds`

279 

280Type / Values

281 

282`number`

283 

284Details

285 

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

287 

288Key

289 

290`agents.max_depth`

291 

292Type / Values

293 

294`number`

295 

296Details

297 

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

299 

300Key

301 

189`agents.max_threads`302`agents.max_threads`

190 303 

191Type / Values304Type / Values

194 307 

195Details308Details

196 309 

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

311 

312Key

313 

314`allow_login_shell`

315 

316Type / Values

317 

318`boolean`

319 

320Details

321 

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

323 

324Key

325 

326`analytics.enabled`

327 

328Type / Values

329 

330`boolean`

331 

332Details

333 

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

198 335 

199Key336Key

200 337 

202 339 

203Type / Values340Type / Values

204 341 

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

206 343 

207Details344Details

208 345 

209Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.346Controls 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.

210 347 

211Key348Key

212 349 

213`apps.<id>.disabled_reason`350`approval_policy.granular.mcp_elicitations`

214 351 

215Type / Values352Type / Values

216 353 

217`unknown | user`354`boolean`

218 355 

219Details356Details

220 357 

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

222 359 

223Key360Key

224 361 

225`apps.<id>.enabled`362`approval_policy.granular.request_permissions`

226 363 

227Type / Values364Type / Values

228 365 

230 367 

231Details368Details

232 369 

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

234 371 

235Key372Key

236 373 

237`chatgpt_base_url`374`approval_policy.granular.rules`

238 375 

239Type / Values376Type / Values

240 377 

241`string`378`boolean`

242 379 

243Details380Details

244 381 

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

246 383 

247Key384Key

248 385 

249`check_for_update_on_startup`386`approval_policy.granular.sandbox_approval`

250 387 

251Type / Values388Type / Values

252 389 

254 391 

255Details392Details

256 393 

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

258 395 

259Key396Key

260 397 

261`cli_auth_credentials_store`398`approval_policy.granular.skill_approval`

262 399 

263Type / Values400Type / Values

264 401 

265`file | keyring | auto`402`boolean`

266 403 

267Details404Details

268 405 

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

270 407 

271Key408Key

272 409 

273`compact_prompt`410`approvals_reviewer`

274 411 

275Type / Values412Type / Values

276 413 

277`string`414`user | auto_review`

278 415 

279Details416Details

280 417 

281Inline override for the history compaction prompt.418Who 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.

282 419 

283Key420Key

284 421 

285`developer_instructions`422`apps._default.destructive_enabled`

286 423 

287Type / Values424Type / Values

288 425 

289`string`426`boolean`

290 427 

291Details428Details

292 429 

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

294 431 

295Key432Key

296 433 

297`disable_paste_burst`434`apps._default.enabled`

298 435 

299Type / Values436Type / Values

300 437 

302 439 

303Details440Details

304 441 

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

306 443 

307Key444Key

308 445 

309`experimental_compact_prompt_file`446`apps._default.open_world_enabled`

310 447 

311Type / Values448Type / Values

312 449 

313`string (path)`450`boolean`

314 451 

315Details452Details

316 453 

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

455 

456Key

457 

458`apps.<id>.default_tools_approval_mode`

459 

460Type / Values

461 

462`auto | prompt | approve`

463 

464Details

465 

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

318 467 

319Key468Key

320 469 

321`experimental_use_freeform_apply_patch`470`apps.<id>.default_tools_enabled`

322 471 

323Type / Values472Type / Values

324 473 

326 475 

327Details476Details

328 477 

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

330 479 

331Key480Key

332 481 

333`experimental_use_unified_exec_tool`482`apps.<id>.destructive_enabled`

334 483 

335Type / Values484Type / Values

336 485 

338 487 

339Details488Details

340 489 

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

342 491 

343Key492Key

344 493 

345`features.apply_patch_freeform`494`apps.<id>.enabled`

346 495 

347Type / Values496Type / Values

348 497 

350 499 

351Details500Details

352 501 

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

354 503 

355Key504Key

356 505 

357`features.apps`506`apps.<id>.open_world_enabled`

358 507 

359Type / Values508Type / Values

360 509 

362 511 

363Details512Details

364 513 

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

515 

516Key

517 

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

519 

520Type / Values

521 

522`auto | prompt | approve`

523 

524Details

525 

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

366 527 

367Key528Key

368 529 

369`features.apps_mcp_gateway`530`apps.<id>.tools.<tool>.enabled`

370 531 

371Type / Values532Type / Values

372 533 

374 535 

375Details536Details

376 537 

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

539 

540Key

541 

542`auto_review.policy`

543 

544Type / Values

545 

546`string`

547 

548Details

549 

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

551 

552Key

553 

554`background_terminal_max_timeout`

555 

556Type / Values

557 

558`number`

559 

560Details

561 

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

563 

564Key

565 

566`chatgpt_base_url`

567 

568Type / Values

569 

570`string`

571 

572Details

573 

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

378 575 

379Key576Key

380 577 

381`features.child_agents_md`578`check_for_update_on_startup`

382 579 

383Type / Values580Type / Values

384 581 

386 583 

387Details584Details

388 585 

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

587 

588Key

589 

590`cli_auth_credentials_store`

591 

592Type / Values

593 

594`file | keyring | auto`

595 

596Details

597 

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

599 

600Key

601 

602`commit_attribution`

603 

604Type / Values

605 

606`string`

607 

608Details

609 

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

611 

612Key

613 

614`compact_prompt`

615 

616Type / Values

617 

618`string`

619 

620Details

621 

622Inline override for the history compaction prompt.

623 

624Key

625 

626`default_permissions`

627 

628Type / Values

629 

630`string`

631 

632Details

633 

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

635 

636Key

637 

638`developer_instructions`

639 

640Type / Values

641 

642`string`

643 

644Details

645 

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

390 647 

391Key648Key

392 649 

393`features.collaboration_modes`650`disable_paste_burst`

394 651 

395Type / Values652Type / Values

396 653 

398 655 

399Details656Details

400 657 

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

659 

660Key

661 

662`experimental_compact_prompt_file`

663 

664Type / Values

665 

666`string (path)`

667 

668Details

669 

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

402 671 

403Key672Key

404 673 

405`features.elevated_windows_sandbox`674`experimental_use_unified_exec_tool`

406 675 

407Type / Values676Type / Values

408 677 

410 679 

411Details680Details

412 681 

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

414 683 

415Key684Key

416 685 

417`features.experimental_windows_sandbox`686`features.apps`

418 687 

419Type / Values688Type / Values

420 689 

422 691 

423Details692Details

424 693 

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

426 695 

427Key696Key

428 697 

429`features.multi_agent`698`features.codex_hooks`

430 699 

431Type / Values700Type / Values

432 701 

434 703 

435Details704Details

436 705 

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

438 707 

439Key708Key

440 709 

441`features.personality`710`features.enable_request_compression`

442 711 

443Type / Values712Type / Values

444 713 

446 715 

447Details716Details

448 717 

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

450 719 

451Key720Key

452 721 

453`features.powershell_utf8`722`features.fast_mode`

454 723 

455Type / Values724Type / Values

456 725 

458 727 

459Details728Details

460 729 

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

462 731 

463Key732Key

464 733 

465`features.remote_models`734`features.memories`

466 735 

467Type / Values736Type / Values

468 737 

470 739 

471Details740Details

472 741 

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

474 743 

475Key744Key

476 745 

477`features.request_rule`746`features.multi_agent`

478 747 

479Type / Values748Type / Values

480 749 

482 751 

483Details752Details

484 753 

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

486 755 

487Key756Key

488 757 

489`features.runtime_metrics`758`features.personality`

490 759 

491Type / Values760Type / Values

492 761 

494 763 

495Details764Details

496 765 

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

498 767 

499Key768Key

500 769 

501`features.search_tool`770`features.prevent_idle_sleep`

502 771 

503Type / Values772Type / Values

504 773 

506 775 

507Details776Details

508 777 

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

510 779 

511Key780Key

512 781 

518 787 

519Details788Details

520 789 

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

522 791 

523Key792Key

524 793 

534 803 

535Key804Key

536 805 

537`features.unified_exec`806`features.skill_mcp_dependency_install`

807 

808Type / Values

809 

810`boolean`

811 

812Details

813 

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

815 

816Key

817 

818`features.undo`

538 819 

539Type / Values820Type / Values

540 821 

542 823 

543Details824Details

544 825 

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

546 827 

547Key828Key

548 829 

549`features.use_linux_sandbox_bwrap`830`features.unified_exec`

550 831 

551Type / Values832Type / Values

552 833 

554 835 

555Details836Details

556 837 

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

558 839 

559Key840Key

560 841 

678 959 

679Key960Key

680 961 

681`include_apply_patch_tool`962`hooks`

682 963 

683Type / Values964Type / Values

684 965 

685`boolean`966`table`

686 967 

687Details968Details

688 969 

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

690 971 

691Key972Key

692 973 

726 1007 

727Key1008Key

728 1009 

1010`mcp_oauth_callback_url`

1011 

1012Type / Values

1013 

1014`string`

1015 

1016Details

1017 

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

1019 

1020Key

1021 

729`mcp_oauth_credentials_store`1022`mcp_oauth_credentials_store`

730 1023 

731Type / Values1024Type / Values

850 1143 

851Type / Values1144Type / Values

852 1145 

853`array<string>`1146`array<string | { name = string, source = "local" | "remote" }>`

854 1147 

855Details1148Details

856 1149 

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

858 1151 

859Key1152Key

860 1153 

861`mcp_servers.<id>.http_headers`1154`mcp_servers.<id>.experimental_environment`

862 1155 

863Type / Values1156Type / Values

864 1157 

865`map<string,string>`1158`local | remote`

866 1159 

867Details1160Details

868 1161 

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

870 1163 

871Key1164Key

872 1165 

873`mcp_servers.<id>.required`1166`mcp_servers.<id>.http_headers`

874 1167 

875Type / Values1168Type / Values

876 1169 

877`boolean`1170`map<string,string>`

878 1171 

879Details1172Details

880 1173 

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

882 1175 

883Key1176Key

884 1177 

885`mcp_servers.<id>.startup_timeout_ms`1178`mcp_servers.<id>.oauth_resource`

886 1179 

887Type / Values1180Type / Values

888 1181 

889`number`1182`string`

890 1183 

891Details1184Details

892 1185 

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

894 1187 

895Key1188Key

896 1189 

897`mcp_servers.<id>.startup_timeout_sec`1190`mcp_servers.<id>.required`

898 1191 

899Type / Values1192Type / Values

900 1193 

901`number`1194`boolean`

1195 

1196Details

1197 

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

1199 

1200Key

1201 

1202`mcp_servers.<id>.scopes`

1203 

1204Type / Values

1205 

1206`array<string>`

1207 

1208Details

1209 

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

1211 

1212Key

1213 

1214`mcp_servers.<id>.startup_timeout_ms`

1215 

1216Type / Values

1217 

1218`number`

1219 

1220Details

1221 

1222Alias for `startup_timeout_sec` in milliseconds.

1223 

1224Key

1225 

1226`mcp_servers.<id>.startup_timeout_sec`

1227 

1228Type / Values

1229 

1230`number`

902 1231 

903Details1232Details

904 1233 

930 1259 

931Key1260Key

932 1261 

1262`memories.consolidation_model`

1263 

1264Type / Values

1265 

1266`string`

1267 

1268Details

1269 

1270Optional model override for global memory consolidation.

1271 

1272Key

1273 

1274`memories.disable_on_external_context`

1275 

1276Type / Values

1277 

1278`boolean`

1279 

1280Details

1281 

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

1283 

1284Key

1285 

1286`memories.extract_model`

1287 

1288Type / Values

1289 

1290`string`

1291 

1292Details

1293 

1294Optional model override for per-thread memory extraction.

1295 

1296Key

1297 

1298`memories.generate_memories`

1299 

1300Type / Values

1301 

1302`boolean`

1303 

1304Details

1305 

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

1307 

1308Key

1309 

1310`memories.max_raw_memories_for_consolidation`

1311 

1312Type / Values

1313 

1314`number`

1315 

1316Details

1317 

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

1319 

1320Key

1321 

1322`memories.max_rollout_age_days`

1323 

1324Type / Values

1325 

1326`number`

1327 

1328Details

1329 

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

1331 

1332Key

1333 

1334`memories.max_rollouts_per_startup`

1335 

1336Type / Values

1337 

1338`number`

1339 

1340Details

1341 

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

1343 

1344Key

1345 

1346`memories.max_unused_days`

1347 

1348Type / Values

1349 

1350`number`

1351 

1352Details

1353 

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

1355 

1356Key

1357 

1358`memories.min_rate_limit_remaining_percent`

1359 

1360Type / Values

1361 

1362`number`

1363 

1364Details

1365 

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

1367 

1368Key

1369 

1370`memories.min_rollout_idle_hours`

1371 

1372Type / Values

1373 

1374`number`

1375 

1376Details

1377 

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

1379 

1380Key

1381 

1382`memories.use_memories`

1383 

1384Type / Values

1385 

1386`boolean`

1387 

1388Details

1389 

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

1391 

1392Key

1393 

933`model`1394`model`

934 1395 

935Type / Values1396Type / Values

938 1399 

939Details1400Details

940 1401 

941Model to use (e.g., `gpt-5-codex`).1402Model to use (e.g., `gpt-5.5`).

942 1403 

943Key1404Key

944 1405 

954 1415 

955Key1416Key

956 1417 

1418`model_catalog_json`

1419 

1420Type / Values

1421 

1422`string (path)`

1423 

1424Details

1425 

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

1427 

1428Key

1429 

957`model_context_window`1430`model_context_window`

958 1431 

959Type / Values1432Type / Values

990 1463 

991Key1464Key

992 1465 

1466`model_providers.<id>`

1467 

1468Type / Values

1469 

1470`table`

1471 

1472Details

1473 

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

1475 

1476Key

1477 

1478`model_providers.<id>.auth`

1479 

1480Type / Values

1481 

1482`table`

1483 

1484Details

1485 

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

1487 

1488Key

1489 

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

1491 

1492Type / Values

1493 

1494`array<string>`

1495 

1496Details

1497 

1498Arguments passed to the token command.

1499 

1500Key

1501 

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

1503 

1504Type / Values

1505 

1506`string`

1507 

1508Details

1509 

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

1511 

1512Key

1513 

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

1515 

1516Type / Values

1517 

1518`string (path)`

1519 

1520Details

1521 

1522Working directory for the token command.

1523 

1524Key

1525 

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

1527 

1528Type / Values

1529 

1530`number`

1531 

1532Details

1533 

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

1535 

1536Key

1537 

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

1539 

1540Type / Values

1541 

1542`number`

1543 

1544Details

1545 

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

1547 

1548Key

1549 

993`model_providers.<id>.base_url`1550`model_providers.<id>.base_url`

994 1551 

995Type / Values1552Type / Values

1134 1691 

1135Key1692Key

1136 1693 

1694`model_providers.<id>.supports_websockets`

1695 

1696Type / Values

1697 

1698`boolean`

1699 

1700Details

1701 

1702Whether that provider supports the Responses API WebSocket transport.

1703 

1704Key

1705 

1137`model_providers.<id>.wire_api`1706`model_providers.<id>.wire_api`

1138 1707 

1139Type / Values1708Type / Values

1140 1709 

1141`chat | responses`1710`responses`

1142 1711 

1143Details1712Details

1144 1713 

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

1146 1715 

1147Key1716Key

1148 1717 

1190 1759 

1191Details1760Details

1192 1761 

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

1194 1763 

1195Key1764Key

1196 1765 

1278 1847 

1279Key1848Key

1280 1849 

1850`openai_base_url`

1851 

1852Type / Values

1853 

1854`string`

1855 

1856Details

1857 

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

1859 

1860Key

1861 

1281`oss_provider`1862`oss_provider`

1282 1863 

1283Type / Values1864Type / Values

1398 1979 

1399Key1980Key

1400 1981 

1982`otel.metrics_exporter`

1983 

1984Type / Values

1985 

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

1987 

1988Details

1989 

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

1991 

1992Key

1993 

1401`otel.trace_exporter`1994`otel.trace_exporter`

1402 1995 

1403Type / Values1996Type / Values

1482 2075 

1483Key2076Key

1484 2077 

1485`personality`2078`permissions.<name>.filesystem`

1486 2079 

1487Type / Values2080Type / Values

1488 2081 

1489`none | friendly | pragmatic`2082`table`

2083 

2084Details

2085 

2086Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.

2087 

2088Key

2089 

2090`permissions.<name>.filesystem.":project_roots".<subpath-or-glob>`

2091 

2092Type / Values

2093 

2094`"read" | "write" | "none"`

2095 

2096Details

2097 

2098Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`.

2099 

2100Key

2101 

2102`permissions.<name>.filesystem.<path-or-glob>`

2103 

2104Type / Values

2105 

2106`"read" | "write" | "none" | table`

2107 

2108Details

2109 

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

2111 

2112Key

2113 

2114`permissions.<name>.filesystem.glob_scan_max_depth`

2115 

2116Type / Values

2117 

2118`number`

2119 

2120Details

2121 

2122Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set.

2123 

2124Key

2125 

2126`permissions.<name>.network.allow_local_binding`

2127 

2128Type / Values

2129 

2130`boolean`

2131 

2132Details

2133 

2134Permit local bind/listen operations through the managed proxy.

2135 

2136Key

2137 

2138`permissions.<name>.network.allow_upstream_proxy`

2139 

2140Type / Values

2141 

2142`boolean`

2143 

2144Details

2145