config-reference.md Codex Docs, 2026-02-27 18:15 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/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.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |

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| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |

16| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |

17| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |19| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |

18| `approval_policy` | `untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |

19| `approval_policy.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |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. |

20| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |22| `approval_policy.granular.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected. |

21| `approval_policy.reject.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are auto-rejected. |23| `approval_policy.granular.request_permissions` | `boolean` | When `true`, prompts from the `request_permissions` tool are allowed to surface. |

24| `approval_policy.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. |

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

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

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

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

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

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

38| `auto_review.policy` | `string` | Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

47| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |

55| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

142| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |

143| `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_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. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

180 239 

181Key240Key

182 241 

204 263 

205Key264Key

206 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 

207`agents.max_depth`290`agents.max_depth`

208 291 

209Type / Values292Type / Values

224 307 

225Details308Details

226 309 

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

228 311 

229Key312Key

230 313 

240 323 

241Key324Key

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

335 

336Key

337 

243`approval_policy`338`approval_policy`

244 339 

245Type / Values340Type / Values

246 341 

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

343 

344Details

345 

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.

347 

348Key

349 

350`approval_policy.granular.mcp_elicitations`

351 

352Type / Values

353 

354`boolean`

355 

356Details

357 

358When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

359 

360Key

361 

362`approval_policy.granular.request_permissions`

363 

364Type / Values

365 

366`boolean`

248 367 

249Details368Details

250 369 

251Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.370When `true`, prompts from the `request_permissions` tool are allowed to surface.

252 371 

253Key372Key

254 373 

255`approval_policy.reject.mcp_elicitations`374`approval_policy.granular.rules`

256 375 

257Type / Values376Type / Values

258 377 

260 379 

261Details380Details

262 381 

263When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.382When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.

264 383 

265Key384Key

266 385 

267`approval_policy.reject.rules`386`approval_policy.granular.sandbox_approval`

268 387 

269Type / Values388Type / Values

270 389 

272 391 

273Details392Details

274 393 

275When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.394When `true`, sandbox escalation approval prompts are allowed to surface.

276 395 

277Key396Key

278 397 

279`approval_policy.reject.sandbox_approval`398`approval_policy.granular.skill_approval`

280 399 

281Type / Values400Type / Values

282 401 

284 403 

285Details404Details

286 405 

287When `true`, sandbox escalation approval prompts are auto-rejected.406When `true`, skill-script approval prompts are allowed to surface.

407 

408Key

409 

410`approvals_reviewer`

411 

412Type / Values

413 

414`user | auto_review`

415 

416Details

417 

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.

288 419 

289Key420Key

290 421 

408 539 

409Key540Key

410 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 

411`background_terminal_max_timeout`554`background_terminal_max_timeout`

412 555 

413Type / Values556Type / Values

456 599 

457Key600Key

458 601 

459`compact_prompt`602`commit_attribution`

460 603 

461Type / Values604Type / Values

462 605 

464 607 

465Details608Details

466 609 

467Inline override for the history compaction prompt.610Override the commit co-author trailer text. Set an empty string to disable automatic attribution.

468 611 

469Key612Key

470 613 

471`developer_instructions`614`compact_prompt`

472 615 

473Type / Values616Type / Values

474 617 

476 619 

477Details620Details

478 621 

479Additional developer instructions injected into the session (optional).622Inline override for the history compaction prompt.

480 623 

481Key624Key

482 625 

483`disable_paste_burst`626`default_permissions`

484 627 

485Type / Values628Type / Values

486 629 

487`boolean`630`string`

488 631 

489Details632Details

490 633 

491Disable burst-paste detection in the TUI.634Name of the default permissions profile to apply to sandboxed tool calls.

492 635 

493Key636Key

494 637 

495`experimental_compact_prompt_file`638`developer_instructions`

496 639 

497Type / Values640Type / Values

498 641 

499`string (path)`642`string`

500 643 

501Details644Details

502 645 

503Load the compaction prompt override from a file (experimental).646Additional developer instructions injected into the session (optional).

504 647 

505Key648Key

506 649 

507`experimental_use_freeform_apply_patch`650`disable_paste_burst`

508 651 

509Type / Values652Type / Values

510 653 

512 655 

513Details656Details

514 657 

515Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.658Disable burst-paste detection in the TUI.

516 659 

517Key660Key

518 661 

519`experimental_use_unified_exec_tool`662`experimental_compact_prompt_file`

520 663 

521Type / Values664Type / Values

522 665 

523`boolean`666`string (path)`

524 667 

525Details668Details

526 669 

527Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.670Load the compaction prompt override from a file (experimental).

528 671 

529Key672Key

530 673 

531`features.apply_patch_freeform`674`experimental_use_unified_exec_tool`

532 675 

533Type / Values676Type / Values

534 677 

536 679 

537Details680Details

538 681 

539Expose the freeform `apply_patch` tool (experimental).682Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

540 683 

541Key684Key

542 685 

552 695 

553Key696Key

554 697 

555`features.apps_mcp_gateway`698`features.codex_hooks`

556 

557Type / Values

558 

559`boolean`

560 

561Details

562 

563Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).

564 

565Key

566 

567`features.child_agents_md`

568 699 

569Type / Values700Type / Values

570 701 

572 703 

573Details704Details

574 705 

575Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).706Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.

576 707 

577Key708Key

578 709 

579`features.collaboration_modes`710`features.enable_request_compression`

580 711 

581Type / Values712Type / Values

582 713 

584 715 

585Details716Details

586 717 

587Enable collaboration modes such as plan mode (stable; on by default).718Compress streaming request bodies with zstd when supported (stable; on by default).

588 719 

589Key720Key

590 721 

591`features.multi_agent`722`features.fast_mode`

592 723 

593Type / Values724Type / Values

594 725 

596 727 

597Details728Details

598 729 

599Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).730Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

600 731 

601Key732Key

602 733 

603`features.personality`734`features.memories`

604 735 

605Type / Values736Type / Values

606 737 

608 739 

609Details740Details

610 741 

611Enable personality selection controls (stable; on by default).742Enable [Memories](https://developers.openai.com/codex/memories) (off by default).

612 743 

613Key744Key

614 745 

615`features.powershell_utf8`746`features.multi_agent`

616 747 

617Type / Values748Type / Values

618 749 

620 751 

621Details752Details

622 753 

623Force PowerShell UTF-8 output (defaults to true).754Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

624 755 

625Key756Key

626 757 

627`features.remote_models`758`features.personality`

628 759 

629Type / Values760Type / Values

630 761 

632 763 

633Details764Details

634 765 

635Refresh remote model list before showing readiness (experimental).766Enable personality selection controls (stable; on by default).

636 767 

637Key768Key

638 769 

639`features.request_rule`770`features.prevent_idle_sleep`

640 771 

641Type / Values772Type / Values

642 773 

644 775 

645Details776Details

646 777 

647Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).778Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

648 779 

649Key780Key

650 781 

651`features.runtime_metrics`782`features.shell_snapshot`

652 783 

653Type / Values784Type / Values

654 785 

656 787 

657Details788Details

658 789 

659Show runtime metrics summary in TUI turn separators (experimental).790Snapshot shell environment to speed up repeated commands (stable; on by default).

660 791 

661Key792Key

662 793 

663`features.search_tool`794`features.shell_tool`

664 795 

665Type / Values796Type / Values

666 797 

668 799 

669Details800Details

670 801 

671Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).802Enable the default `shell` tool for running commands (stable; on by default).

672 803 

673Key804Key

674 805 

675`features.shell_snapshot`806`features.skill_mcp_dependency_install`

676 807 

677Type / Values808Type / Values

678 809 

680 811 

681Details812Details

682 813 

683Snapshot shell environment to speed up repeated commands (beta).814Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

684 815 

685Key816Key

686 817 

687`features.shell_tool`818`features.undo`

688 819 

689Type / Values820Type / Values

690 821 

692 823 

693Details824Details

694 825 

695Enable the default `shell` tool for running commands (stable; on by default).826Enable undo support (stable; off by default).

696 827 

697Key828Key

698 829 

704 835 

705Details836Details

706 837 

707Use the unified PTY-backed exec tool (beta).838Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

708 

709Key

710 

711`features.use_linux_sandbox_bwrap`

712 

713Type / Values

714 

715`boolean`

716 

717Details

718 

719Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).

720 839 

721Key840Key

722 841 

840 959 

841Key960Key

842 961 

843`include_apply_patch_tool`962`hooks`

844 963 

845Type / Values964Type / Values

846 965 

847`boolean`966`table`

848 967 

849Details968Details

850 969 

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

852 971 

853Key972Key

854 973 

1024 1143 

1025Type / Values1144Type / Values

1026 1145 

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

1147 

1148Details

1149 

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.

1151 

1152Key

1153 

1154`mcp_servers.<id>.experimental_environment`

1155 

1156Type / Values

1157 

1158`local | remote`

1028 1159 

1029Details1160Details

1030 1161 

1031Additional environment variables to whitelist for an MCP stdio server.1162Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.

1032 1163 

1033Key1164Key

1034 1165 

1044 1175 

1045Key1176Key

1046 1177 

1178`mcp_servers.<id>.oauth_resource`

1179 

1180Type / Values

1181 

1182`string`

1183 

1184Details

1185 

1186Optional RFC 8707 OAuth resource parameter to include during MCP login.

1187 

1188Key

1189 

1047`mcp_servers.<id>.required`1190`mcp_servers.<id>.required`

1048 1191 

1049Type / Values1192Type / Values

1056 1199 

1057Key1200Key

1058 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 

1059`mcp_servers.<id>.startup_timeout_ms`1214`mcp_servers.<id>.startup_timeout_ms`

1060 1215 

1061Type / Values1216Type / Values

1104 1259 

1105Key1260Key

1106 1261 

1107`model`1262`memories.consolidation_model`

1108 1263 

1109Type / Values1264Type / Values

1110 1265 

1112 1267 

1113Details1268Details

1114 1269 

1115Model to use (e.g., `gpt-5-codex`).1270Optional model override for global memory consolidation.

1116 1271 

1117Key1272Key

1118 1273 

1119`model_auto_compact_token_limit`1274`memories.disable_on_external_context`

1120 1275 

1121Type / Values1276Type / Values

1122 1277 

1123`number`1278`boolean`

1124 1279 

1125Details1280Details

1126 1281 

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

1128 1283 

1129Key1284Key

1130 1285 

1131`model_catalog_json`1286`memories.extract_model`

1132 1287 

1133Type / Values1288Type / Values

1134 1289 

1135`string (path)`1290`string`

1136 1291 

1137Details1292Details

1138 1293 

1139Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.1294Optional model override for per-thread memory extraction.

1140 1295 

1141Key1296Key

1142 1297 

1143`model_context_window`1298`memories.generate_memories`

1144 1299 

1145Type / Values1300Type / Values

1146 1301 

1147`number`1302`boolean`

1148 1303 

1149Details1304Details

1150 1305 

1151Context window tokens available to the active model.1306When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.

1152 1307 

1153Key1308Key

1154 1309 

1155`model_instructions_file`1310`memories.max_raw_memories_for_consolidation`

1156 1311 

1157Type / Values1312Type / Values

1158 1313 

1159`string (path)`1314`number`

1160 1315 

1161Details1316Details

1162 1317 

1163Replacement for built-in instructions instead of `AGENTS.md`.1318Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.

1164 1319 

1165Key1320Key

1166 1321 

1167`model_provider`1322`memories.max_rollout_age_days`

1168 1323 

1169Type / Values1324Type / Values

1170 1325 

1171`string`1326`number`

1172 1327 

1173Details1328Details

1174 1329 

1175Provider id from `model_providers` (default: `openai`).1330Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.

1176 1331 

1177Key1332Key

1178 1333 

1179`model_providers.<id>.base_url`1334`memories.max_rollouts_per_startup`

1180 1335 

1181Type / Values1336Type / Values

1182 1337 

1183`string`1338`number`

1184 1339 

1185Details1340Details

1186 1341 

1187API base URL for the model provider.1342Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.

1188 1343 

1189Key1344Key

1190 1345 

1191`model_providers.<id>.env_http_headers`1346`memories.max_unused_days`

1192 1347 

1193Type / Values1348Type / Values

1194 1349 

1195`map<string,string>`1350`number`

1196 1351 

1197Details1352Details

1198 1353 

1199HTTP headers populated from environment variables when present.1354Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.

1200 1355 

1201Key1356Key

1202 1357 

1203`model_providers.<id>.env_key`1358`memories.min_rate_limit_remaining_percent`

1204 1359 

1205Type / Values1360Type / Values

1206 1361 

1207`string`1362`number`

1208 1363 

1209Details1364Details

1210 1365 

1211Environment variable supplying the provider API key.1366Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`.

1212 1367 

1213Key1368Key

1214 1369 

1215`model_providers.<id>.env_key_instructions`1370`memories.min_rollout_idle_hours`

1216 1371 

1217Type / Values1372Type / Values

1218 1373 

1219`string`1374`number`

1220 1375 

1221Details1376Details

1222 1377 

1223Optional setup guidance for the provider API key.1378Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.

1224 1379 

1225Key1380Key

1226 1381 

1227`model_providers.<id>.experimental_bearer_token`1382`memories.use_memories`

1228 1383 

1229Type / Values1384Type / Values

1230 1385 

1231`string`1386`boolean`

1232 1387 

1233Details1388Details

1234 1389 

1235Direct bearer token for the provider (discouraged; use `env_key`).1390When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.

1236 1391 

1237Key1392Key

1238 1393 

1239`model_providers.<id>.http_headers`1394`model`

1240 1395 

1241Type / Values1396Type / Values

1242 1397 

1243`map<string,string>`1398`string`

1244 1399 

1245Details1400Details

1246 1401 

1247Static HTTP headers added to provider requests.1402Model to use (e.g., `gpt-5.5`).

1248 1403 

1249Key1404Key

1250 1405 

1251`model_providers.<id>.name`1406`model_auto_compact_token_limit`

1252 1407 

1253Type / Values1408Type / Values

1254 1409 

1255`string`1410`number`

1256 1411 

1257Details1412Details

1258 1413 

1259Display name for a custom model provider.1414Token threshold that triggers automatic history compaction (unset uses model defaults).

1260 1415 

1261Key1416Key

1262 1417 

1263`model_providers.<id>.query_params`1418`model_catalog_json`

1264 1419 

1265Type / Values1420Type / Values

1266 1421 

1267`map<string,string>`1422`string (path)`

1268 1423 

1269Details1424Details

1270 1425 

1271Extra query parameters appended to provider requests.1426Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.

1272 1427 

1273Key1428Key

1274 1429 

1275`model_providers.<id>.request_max_retries`1430`model_context_window`

1276 1431 

1277Type / Values1432Type / Values

1278 1433 

1280 1435 

1281Details1436Details

1282 1437 

1283Retry count for HTTP requests to the provider (default: 4).1438Context window tokens available to the active model.

1284 1439 

1285Key1440Key

1286 1441 

1287`model_providers.<id>.requires_openai_auth`1442`model_instructions_file`

1288 1443 

1289Type / Values1444Type / Values

1290 1445 

1291`boolean`1446`string (path)`

1292 1447 

1293Details1448Details

1294 1449 

1295The provider uses OpenAI authentication (defaults to false).1450Replacement for built-in instructions instead of `AGENTS.md`.

1296 1451 

1297Key1452Key

1298 1453 

1299`model_providers.<id>.stream_idle_timeout_ms`1454`model_provider`

1300 1455 

1301Type / Values1456Type / Values

1302 1457 

1303`number`1458`string`

1304 1459 

1305Details1460Details

1306 1461 

1307Idle timeout for SSE streams in milliseconds (default: 300000).1462Provider id from `model_providers` (default: `openai`).

1308 1463 

1309Key1464Key

1310 1465 

1311`model_providers.<id>.stream_max_retries`1466`model_providers.<id>`

1312 1467 

1313Type / Values1468Type / Values

1314 1469 

1315`number`1470`table`

1316 1471 

1317Details1472Details

1318 1473 

1319Retry count for SSE streaming interruptions (default: 5).1474Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.

1320 1475 

1321Key1476Key

1322 1477 

1323`model_providers.<id>.wire_api`1478`model_providers.<id>.auth`

1324 1479 

1325Type / Values1480Type / Values

1326 1481 

1327`chat | responses`1482`table`

1328 1483 

1329Details1484Details

1330 1485 

1331Protocol used by the provider (defaults to `chat` if omitted).1486Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.

1332 1487 

1333Key1488Key

1334 1489 

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

1336 1491 

1337Type / Values1492Type / Values

1338 1493 

1339`minimal | low | medium | high | xhigh`1494`array<string>`

1340 1495 

1341Details1496Details

1342 1497 

1343Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).1498Arguments passed to the token command.

1344 1499 

1345Key1500Key

1346 1501 

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

1348 1503 

1349Type / Values1504Type / Values

1350 1505 

1351`auto | concise | detailed | none`1506`string`

1352 1507 

1353Details1508Details

1354 1509 

1355Select reasoning summary detail or disable summaries entirely.1510Command to run when Codex needs a bearer token. The command must print the token to stdout.

1356 1511 

1357Key1512Key

1358 1513 

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

1360 1515 

1361Type / Values1516Type / Values

1362 1517 

1363`boolean`1518`string (path)`

1364 1519 

1365Details1520Details

1366 1521 

1367Force Codex to send or not send reasoning metadata.1522Working directory for the token command.

1368 1523 

1369Key1524Key

1370 1525 

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

1372 1527 

1373Type / Values1528Type / Values

1374 1529 

1375`low | medium | high`1530`number`

1376 1531 

1377Details1532Details

1378 1533 

1379Control GPT-5 Responses API verbosity (defaults to `medium`).1534How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.

1380 1535 

1381Key1536Key

1382 1537 

1383`notice.hide_full_access_warning`1538`model_providers.<id>.auth.timeout_ms`

1384 1539 

1385Type / Values1540Type / Values

1386 1541 

1387`boolean`1542`number`

1543 

1544Details

1545 

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

1547 

1548Key

1549 

1550`model_providers.<id>.base_url`

1551 

1552Type / Values

1553 

1554`string`

1555 

1556Details

1557 

1558API base URL for the model provider.

1559 

1560Key

1561 

1562`model_providers.<id>.env_http_headers`

1563 

1564Type / Values

1565 

1566`map<string,string>`

1567 

1568Details

1569 

1570HTTP headers populated from environment variables when present.

1571 

1572Key

1573 

1574`model_providers.<id>.env_key`

1575 

1576Type / Values

1577 

1578`string`

1579 

1580Details

1581 

1582Environment variable supplying the provider API key.

1583 

1584Key

1585 

1586`model_providers.<id>.env_key_instructions`

1587 

1588Type / Values

1589 

1590`string`

1591 

1592Details

1593 

1594Optional setup guidance for the provider API key.

1595 

1596Key

1597 

1598`model_providers.<id>.experimental_bearer_token`

1599 

1600Type / Values

1601 

1602`string`

1603 

1604Details

1605 

1606Direct bearer token for the provider (discouraged; use `env_key`).

1607 

1608Key

1609 

1610`model_providers.<id>.http_headers`

1611 

1612Type / Values

1613 

1614`map<string,string>`

1615 

1616Details

1617 

1618Static HTTP headers added to provider requests.

1619 

1620Key

1621 

1622`model_providers.<id>.name`

1623 

1624Type / Values

1625 

1626`string`

1627 

1628Details

1629 

1630Display name for a custom model provider.

1631 

1632Key

1633 

1634`model_providers.<id>.query_params`

1635 

1636Type / Values

1637 

1638`map<string,string>`

1639 

1640Details

1641 

1642Extra query parameters appended to provider requests.

1643 

1644Key

1645 

1646`model_providers.<id>.request_max_retries`

1647 

1648Type / Values

1649 

1650`number`

1651 

1652Details

1653 

1654Retry count for HTTP requests to the provider (default: 4).

1655 

1656Key

1657 

1658`model_providers.<id>.requires_openai_auth`

1659 

1660Type / Values

1661 

1662`boolean`

1663 

1664Details

1665 

1666The provider uses OpenAI authentication (defaults to false).

1667 

1668Key

1669 

1670`model_providers.<id>.stream_idle_timeout_ms`

1671 

1672Type / Values

1673 

1674`number`

1675 

1676Details

1677 

1678Idle timeout for SSE streams in milliseconds (default: 300000).

1679 

1680Key

1681 

1682`model_providers.<id>.stream_max_retries`

1683 

1684Type / Values

1685 

1686`number`

1687 

1688Details

1689 

1690Retry count for SSE streaming interruptions (default: 5).

1691 

1692Key

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 

1706`model_providers.<id>.wire_api`

1707 

1708Type / Values

1709 

1710`responses`

1711 

1712Details

1713 

1714Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.

1715