config-reference.md Codex Docs, 2026-02-19 20:37 UTC → 2026-05-02 00:48 UTC

1# Configuration Reference1# Configuration Reference

2 2 

3Complete reference for Codex config.toml and requirements.toml

4 

5Use this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with [Config basics](https://developers.openai.com/codex/config-basic) and [Advanced Config](https://developers.openai.com/codex/config-advanced).3Use this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with [Config basics](https://developers.openai.com/codex/config-basic) and [Advanced Config](https://developers.openai.com/codex/config-advanced).

6 4 

7## `config.toml`5## `config.toml`

8 6 

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

10 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 

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

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

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

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

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

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

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

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

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

20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |

21| `approval_policy` | `untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |

22| `approval_policy.granular.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected. |

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

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

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

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

27| `approvals_reviewer` | `user | auto_review` | Who reviews eligible approval prompts under `on-request` or granular approval policies. Defaults to `user`; `auto_review` uses the reviewer subagent. This setting doesn't change sandboxing or review actions already allowed inside the sandbox. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

45| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. Built-ins are `:read-only`, `:workspace`, and `:danger-no-sandbox`; custom profile names require matching `[permissions.<name>]` tables. |

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

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

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

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

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

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

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

30| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |51| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. |

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

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

33| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |

34| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |55| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |

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

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

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

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

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

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

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

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

43| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |59| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |

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

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

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

46| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |63| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |

47| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |64| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |

48| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |65| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |

53| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |70| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |

54| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |71| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |

55| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |72| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |

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

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

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

59| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |76| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

136| `model_providers.amazon-bedrock.aws.profile` | `string` | AWS profile name used by the built-in `amazon-bedrock` provider. |

137| `model_providers.amazon-bedrock.aws.region` | `string` | AWS region used by the built-in `amazon-bedrock` provider. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

224| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

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

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

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

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

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

158| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |230| `tui.keymap.<context>.<action>` | `string | array<string>` | Keyboard shortcut binding for a TUI action. Supported contexts include `global`, `chat`, `composer`, `editor`, `pager`, `list`, and `approval`; context-specific bindings override `tui.keymap.global`. |

231| `tui.keymap.<context>.<action> = []` | `empty array` | Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, or `page-down`. |

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

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

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

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

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

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

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

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

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

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

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

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

164 244 

165Key245Key

166 246 

188 268 

189Key269Key

190 270 

271`agents.<name>.nickname_candidates`

272 

273Type / Values

274 

275`array<string>`

276 

277Details

278 

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

280 

281Key

282 

283`agents.job_max_runtime_seconds`

284 

285Type / Values

286 

287`number`

288 

289Details

290 

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

292 

293Key

294 

295`agents.max_depth`

296 

297Type / Values

298 

299`number`

300 

301Details

302 

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

304 

305Key

306 

191`agents.max_threads`307`agents.max_threads`

192 308 

193Type / Values309Type / Values

196 312 

197Details313Details

198 314 

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

316 

317Key

318 

319`allow_login_shell`

320 

321Type / Values

322 

323`boolean`

324 

325Details

326 

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

328 

329Key

330 

331`analytics.enabled`

332 

333Type / Values

334 

335`boolean`

336 

337Details

338 

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

200 340 

201Key341Key

202 342 

204 344 

205Type / Values345Type / Values

206 346 

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

208 348 

209Details349Details

210 350 

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

212 352 

213Key353Key

214 354 

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

216 356 

217Type / Values357Type / Values

218 358 

219`unknown | user`359`boolean`

220 360 

221Details361Details

222 362 

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

224 364 

225Key365Key

226 366 

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

228 368 

229Type / Values369Type / Values

230 370 

232 372 

233Details373Details

234 374 

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

236 376 

237Key377Key

238 378 

239`chatgpt_base_url`379`approval_policy.granular.rules`

240 380 

241Type / Values381Type / Values

242 382 

243`string`383`boolean`

244 384 

245Details385Details

246 386 

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

248 388 

249Key389Key

250 390 

251`check_for_update_on_startup`391`approval_policy.granular.sandbox_approval`

252 392 

253Type / Values393Type / Values

254 394 

256 396 

257Details397Details

258 398 

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

260 400 

261Key401Key

262 402 

263`cli_auth_credentials_store`403`approval_policy.granular.skill_approval`

264 404 

265Type / Values405Type / Values

266 406 

267`file | keyring | auto`407`boolean`

268 408 

269Details409Details

270 410 

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

272 412 

273Key413Key

274 414 

275`compact_prompt`415`approvals_reviewer`

276 416 

277Type / Values417Type / Values

278 418 

279`string`419`user | auto_review`

280 420 

281Details421Details

282 422 

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

284 424 

285Key425Key

286 426 

287`developer_instructions`427`apps._default.destructive_enabled`

288 428 

289Type / Values429Type / Values

290 430 

291`string`431`boolean`

292 432 

293Details433Details

294 434 

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

296 436 

297Key437Key

298 438 

299`disable_paste_burst`439`apps._default.enabled`

300 440 

301Type / Values441Type / Values

302 442 

304 444 

305Details445Details

306 446 

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

308 448 

309Key449Key

310 450 

311`experimental_compact_prompt_file`451`apps._default.open_world_enabled`

312 452 

313Type / Values453Type / Values

314 454 

315`string (path)`455`boolean`

316 456 

317Details457Details

318 458 

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

460 

461Key

462 

463`apps.<id>.default_tools_approval_mode`

464 

465Type / Values

466 

467`auto | prompt | approve`

468 

469Details

470 

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

320 472 

321Key473Key

322 474 

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

324 476 

325Type / Values477Type / Values

326 478 

328 480 

329Details481Details

330 482 

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

332 484 

333Key485Key

334 486 

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

336 488 

337Type / Values489Type / Values

338 490 

340 492 

341Details493Details

342 494 

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

344 496 

345Key497Key

346 498 

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

348 500 

349Type / Values501Type / Values

350 502 

352 504 

353Details505Details

354 506 

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

356 508 

357Key509Key

358 510 

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

360 512 

361Type / Values513Type / Values

362 514 

364 516 

365Details517Details

366 518 

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

520 

521Key

522 

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

524 

525Type / Values

526 

527`auto | prompt | approve`

528 

529Details

530 

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

368 532 

369Key533Key

370 534 

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

372 536 

373Type / Values537Type / Values

374 538 

376 540 

377Details541Details

378 542 

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

544 

545Key

546 

547`auto_review.policy`

548 

549Type / Values

550 

551`string`

552 

553Details

554 

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

556 

557Key

558 

559`background_terminal_max_timeout`

560 

561Type / Values

562 

563`number`

564 

565Details

566 

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

568 

569Key

570 

571`chatgpt_base_url`

572 

573Type / Values

574 

575`string`

576 

577Details

578 

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

380 580 

381Key581Key

382 582 

383`features.child_agents_md`583`check_for_update_on_startup`

384 584 

385Type / Values585Type / Values

386 586 

388 588 

389Details589Details

390 590 

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

592 

593Key

594 

595`cli_auth_credentials_store`

596 

597Type / Values

598 

599`file | keyring | auto`

600 

601Details

602 

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

604 

605Key

606 

607`commit_attribution`

608 

609Type / Values

610 

611`string`

612 

613Details

614 

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

616 

617Key

618 

619`compact_prompt`

620 

621Type / Values

622 

623`string`

624 

625Details

626 

627Inline override for the history compaction prompt.

628 

629Key

630 

631`default_permissions`

632 

633Type / Values

634 

635`string`

636 

637Details

638 

639Name of the default permissions profile to apply to sandboxed tool calls. Built-ins are `:read-only`, `:workspace`, and `:danger-no-sandbox`; custom profile names require matching `[permissions.<name>]` tables.

640 

641Key

642 

643`developer_instructions`

644 

645Type / Values

646 

647`string`

648 

649Details

650 

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

392 652 

393Key653Key

394 654 

395`features.collaboration_modes`655`disable_paste_burst`

396 656 

397Type / Values657Type / Values

398 658 

400 660 

401Details661Details

402 662 

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

664 

665Key

666 

667`experimental_compact_prompt_file`

668 

669Type / Values

670 

671`string (path)`

672 

673Details

674 

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

404 676 

405Key677Key

406 678 

407`features.elevated_windows_sandbox`679`experimental_use_unified_exec_tool`

408 680 

409Type / Values681Type / Values

410 682 

412 684 

413Details685Details

414 686 

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

416 688 

417Key689Key

418 690 

419`features.experimental_windows_sandbox`691`features.apps`

420 692 

421Type / Values693Type / Values

422 694 

424 696 

425Details697Details

426 698 

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

428 700 

429Key701Key

430 702 

431`features.multi_agent`703`features.codex_hooks`

432 704 

433Type / Values705Type / Values

434 706 

436 708 

437Details709Details

438 710 

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

440 712 

441Key713Key

442 714 

443`features.personality`715`features.enable_request_compression`

444 716 

445Type / Values717Type / Values

446 718 

448 720 

449Details721Details

450 722 

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

452 724 

453Key725Key

454 726 

455`features.powershell_utf8`727`features.fast_mode`

456 728 

457Type / Values729Type / Values

458 730 

460 732 

461Details733Details

462 734 

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

464 736 

465Key737Key

466 738 

467`features.remote_models`739`features.memories`

468 740 

469Type / Values741Type / Values

470 742 

472 744 

473Details745Details

474 746 

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

476 748 

477Key749Key

478 750 

479`features.request_rule`751`features.multi_agent`

480 752 

481Type / Values753Type / Values

482 754 

484 756 

485Details757Details

486 758 

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

488 760 

489Key761Key

490 762 

491`features.runtime_metrics`763`features.personality`

492 764 

493Type / Values765Type / Values

494 766 

496 768 

497Details769Details

498 770 

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

500 772 

501Key773Key

502 774 

503`features.search_tool`775`features.prevent_idle_sleep`

504 776 

505Type / Values777Type / Values

506 778 

508 780 

509Details781Details

510 782 

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

512 784 

513Key785Key

514 786 

520 792 

521Details793Details

522 794 

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

524 796 

525Key797Key

526 798 

536 808 

537Key809Key

538 810 

539`features.unified_exec`811`features.skill_mcp_dependency_install`

812 

813Type / Values

814 

815`boolean`

816 

817Details

818 

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

820 

821Key

822 

823`features.undo`

540 824 

541Type / Values825Type / Values

542 826 

544 828 

545Details829Details

546 830 

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

548 832 

549Key833Key

550 834 

551`features.use_linux_sandbox_bwrap`835`features.unified_exec`

552 836 

553Type / Values837Type / Values

554 838 

556 840 

557Details841Details

558 842 

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

560 844 

561Key845Key

562 846 

680 964 

681Key965Key

682 966 

683`include_apply_patch_tool`967`hooks`

684 968 

685Type / Values969Type / Values

686 970 

687`boolean`971`table`

688 972 

689Details973Details

690 974 

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

692 976 

693Key977Key

694 978 

728 1012 

729Key1013Key

730 1014 

1015`mcp_oauth_callback_url`

1016 

1017Type / Values

1018 

1019`string`

1020 

1021Details

1022 

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

1024 

1025Key

1026 

731`mcp_oauth_credentials_store`1027`mcp_oauth_credentials_store`

732 1028 

733Type / Values1029Type / Values

852 1148 

853Type / Values1149Type / Values

854 1150 

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

856 1152 

857Details1153Details

858 1154 

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

860 1156 

861Key1157Key

862 1158 

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

864 1160 

865Type / Values1161Type / Values

866 1162 

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

868 1164 

869Details1165Details

870 1166 

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

872 1168 

873Key1169Key

874 1170 

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

876 1172 

877Type / Values1173Type / Values

878 1174 

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

880 1176 

881Details1177Details

882 1178 

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

884 1180 

885Key1181Key

886 1182 

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

888 1184 

889Type / Values1185Type / Values

890 1186 

891`number`1187`string`

892 1188 

893Details1189Details

894 1190 

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

896 1192 

897Key1193Key

898 1194 

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

900 1196 

901Type / Values1197Type / Values

902 1198 

903`number`1199`boolean`

904 

905Details

906 

907Override the default 10s startup timeout for an MCP server.

908 

909Key

910 

911`mcp_servers.<id>.tool_timeout_sec`

912 

913Type / Values

914 

915`number`

916 1200 

917Details1201Details

918 1202 

919Override the default 60s per-tool timeout for an MCP server.1203When true, fail startup/resume if this enabled MCP server cannot initialize.

920 1204 

921Key1205Key

922 1206 

923`mcp_servers.<id>.url`1207`mcp_servers.<id>.scopes`

924 1208 

925Type / Values1209Type / Values

926 1210 

927`string`1211`array<string>`

928 1212 

929Details1213Details

930 1214 

931Endpoint for an MCP streamable HTTP server.1215OAuth scopes to request when authenticating to that MCP server.

932 1216 

933Key1217Key

934 1218 

935`model`1219`mcp_servers.<id>.startup_timeout_ms`

936 1220 

937Type / Values1221Type / Values

938 1222 

939`string`1223`number`

940 1224 

941Details1225Details

942 1226 

943Model to use (e.g., `gpt-5-codex`).1227Alias for `startup_timeout_sec` in milliseconds.

944 1228 

945Key1229Key

946 1230 

947`model_auto_compact_token_limit`1231`mcp_servers.<id>.startup_timeout_sec`

948 1232 

949Type / Values1233Type / Values

950 1234 

952 1236 

953Details1237Details

954 1238 

955Token threshold that triggers automatic history compaction (unset uses model defaults).1239Override the default 10s startup timeout for an MCP server.

956 1240 

957Key1241Key

958 1242 

959`model_context_window`1243`mcp_servers.<id>.tool_timeout_sec`

960 1244 

961Type / Values1245Type / Values

962 1246 

964 1248 

965Details1249Details

966 1250 

967Context window tokens available to the active model.1251Override the default 60s per-tool timeout for an MCP server.

968 1252 

969Key1253Key

970 1254 

971`model_instructions_file`1255`mcp_servers.<id>.url`

972 1256 

973Type / Values1257Type / Values

974 1258 

975`string (path)`1259`string`

976 1260 

977Details1261Details

978 1262 

979Replacement for built-in instructions instead of `AGENTS.md`.1263Endpoint for an MCP streamable HTTP server.

980 1264 

981Key1265Key

982 1266 

983`model_provider`1267`memories.consolidation_model`

984 1268 

985Type / Values1269Type / Values

986 1270 

988 1272 

989Details1273Details

990 1274 

991Provider id from `model_providers` (default: `openai`).1275Optional model override for global memory consolidation.

992 1276 

993Key1277Key

994 1278 

995`model_providers.<id>.base_url`1279`memories.disable_on_external_context`

996 1280 

997Type / Values1281Type / Values

998 1282 

999`string`1283`boolean`

1000 1284 

1001Details1285Details

1002 1286 

1003API base URL for the model provider.1287When `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`.

1004 1288 

1005Key1289Key

1006 1290 

1007`model_providers.<id>.env_http_headers`1291`memories.extract_model`

1008 1292 

1009Type / Values1293Type / Values

1010 1294 

1011`map<string,string>`1295`string`

1012 1296 

1013Details1297Details

1014 1298 

1015HTTP headers populated from environment variables when present.1299Optional model override for per-thread memory extraction.

1016 1300 

1017Key1301Key

1018 1302 

1019`model_providers.<id>.env_key`1303`memories.generate_memories`

1020 1304 

1021Type / Values1305Type / Values

1022 1306 

1023`string`1307`boolean`

1024 1308 

1025Details1309Details

1026 1310 

1027Environment variable supplying the provider API key.1311When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.

1028 1312 

1029Key1313Key

1030 1314 

1031`model_providers.<id>.env_key_instructions`1315`memories.max_raw_memories_for_consolidation`

1032 1316 

1033Type / Values1317Type / Values

1034 1318 

1035`string`1319`number`

1036 1320 

1037Details1321Details

1038 1322 

1039Optional setup guidance for the provider API key.1323Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.

1040 1324 

1041Key1325Key

1042 1326 

1043`model_providers.<id>.experimental_bearer_token`1327`memories.max_rollout_age_days`

1044 1328 

1045Type / Values1329Type / Values

1046 1330 

1047`string`1331`number`

1048 1332 

1049Details1333Details

1050 1334 

1051Direct bearer token for the provider (discouraged; use `env_key`).1335Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.

1052 1336 

1053Key1337Key

1054 1338 

1055`model_providers.<id>.http_headers`1339`memories.max_rollouts_per_startup`

1056 1340 

1057Type / Values1341Type / Values

1058 1342 

1059`map<string,string>`1343`number`

1060 1344 

1061Details1345Details

1062 1346 

1063Static HTTP headers added to provider requests.1347Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.

1064 1348 

1065Key1349Key

1066 1350 

1067`model_providers.<id>.name`1351`memories.max_unused_days`

1068 1352 

1069Type / Values1353Type / Values

1070 1354 

1071`string`1355`number`

1072 1356 

1073Details1357Details

1074 1358 

1075Display name for a custom model provider.1359Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.

1076 1360 

1077Key1361Key

1078 1362 

1079`model_providers.<id>.query_params`1363`memories.min_rate_limit_remaining_percent`

1080 1364 

1081Type / Values1365Type / Values

1082 1366 

1083`map<string,string>`1367`number`

1084 1368 

1085Details1369Details

1086 1370 

1087Extra query parameters appended to provider requests.1371Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`.

1088 1372 

1089Key1373Key

1090 1374 

1091`model_providers.<id>.request_max_retries`1375`memories.min_rollout_idle_hours`

1092 1376 

1093Type / Values1377Type / Values

1094 1378 

1096 1380 

1097Details1381Details

1098 1382 

1099Retry count for HTTP requests to the provider (default: 4).1383Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.

1100 1384 

1101Key1385Key

1102 1386 

1103`model_providers.<id>.requires_openai_auth`1387`memories.use_memories`

1104 1388 

1105Type / Values1389Type / Values

1106 1390 

1108 1392 

1109Details1393Details

1110 1394 

1111The provider uses OpenAI authentication (defaults to false).1395When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.

1112 1396 

1113Key1397Key

1114 1398 

1115`model_providers.<id>.stream_idle_timeout_ms`1399`model`

1116 1400 

1117Type / Values1401Type / Values

1118 1402 

1119`number`1403`string`

1120 1404 

1121Details1405Details

1122 1406 

1123Idle timeout for SSE streams in milliseconds (default: 300000).1407Model to use (e.g., `gpt-5.5`).

1124 1408 

1125Key1409Key

1126 1410 

1127`model_providers.<id>.stream_max_retries`1411`model_auto_compact_token_limit`

1128 1412 

1129Type / Values1413Type / Values

1130 1414 

1132 1416 

1133Details1417Details

1134 1418 

1135Retry count for SSE streaming interruptions (default: 5).1419Token threshold that triggers automatic history compaction (unset uses model defaults).