config-reference.md Codex Docs, 2026-02-23 18:27 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.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

128| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |188| `profiles.<name>.model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

150| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |216| `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`. |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. |

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

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

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

155| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |224| `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). |225| `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). |226| `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). |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). |

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

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

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

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

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

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

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

164 239 

165Key240Key

166 241 

188 263 

189Key264Key

190 265 

266`agents.<name>.nickname_candidates`

267 

268Type / Values

269 

270`array<string>`

271 

272Details

273 

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

275 

276Key

277 

278`agents.job_max_runtime_seconds`

279 

280Type / Values

281 

282`number`

283 

284Details

285 

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

287 

288Key

289 

290`agents.max_depth`

291 

292Type / Values

293 

294`number`

295 

296Details

297 

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

299 

300Key

301 

191`agents.max_threads`302`agents.max_threads`

192 303 

193Type / Values304Type / Values

196 307 

197Details308Details

198 309 

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

311 

312Key

313 

314`allow_login_shell`

315 

316Type / Values

317 

318`boolean`

319 

320Details

321 

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

323 

324Key

325 

326`analytics.enabled`

327 

328Type / Values

329 

330`boolean`

331 

332Details

333 

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

200 335 

201Key336Key

202 337 

204 339 

205Type / Values340Type / Values

206 341 

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

208 343 

209Details344Details

210 345 

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

212 347 

213Key348Key

214 349 

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

216 351 

217Type / Values352Type / Values

218 353 

219`unknown | user`354`boolean`

220 355 

221Details356Details

222 357 

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

224 359 

225Key360Key

226 361 

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

228 363 

229Type / Values364Type / Values

230 365 

232 367 

233Details368Details

234 369 

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

236 371 

237Key372Key

238 373 

239`chatgpt_base_url`374`approval_policy.granular.rules`

240 375 

241Type / Values376Type / Values

242 377 

243`string`378`boolean`

244 379 

245Details380Details

246 381 

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

248 383 

249Key384Key

250 385 

251`check_for_update_on_startup`386`approval_policy.granular.sandbox_approval`

252 387 

253Type / Values388Type / Values

254 389 

256 391 

257Details392Details

258 393 

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

260 395 

261Key396Key

262 397 

263`cli_auth_credentials_store`398`approval_policy.granular.skill_approval`

264 399 

265Type / Values400Type / Values

266 401 

267`file | keyring | auto`402`boolean`

268 403 

269Details404Details

270 405 

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

272 407 

273Key408Key

274 409 

275`compact_prompt`410`approvals_reviewer`

276 411 

277Type / Values412Type / Values

278 413 

279`string`414`user | auto_review`

280 415 

281Details416Details

282 417 

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

284 419 

285Key420Key

286 421 

287`developer_instructions`422`apps._default.destructive_enabled`

288 423 

289Type / Values424Type / Values

290 425 

291`string`426`boolean`

292 427 

293Details428Details

294 429 

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

296 431 

297Key432Key

298 433 

299`disable_paste_burst`434`apps._default.enabled`

300 435 

301Type / Values436Type / Values

302 437 

304 439 

305Details440Details

306 441 

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

308 443 

309Key444Key

310 445 

311`experimental_compact_prompt_file`446`apps._default.open_world_enabled`

312 447 

313Type / Values448Type / Values

314 449 

315`string (path)`450`boolean`

316 451 

317Details452Details

318 453 

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

455 

456Key

457 

458`apps.<id>.default_tools_approval_mode`

459 

460Type / Values

461 

462`auto | prompt | approve`

463 

464Details

465 

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

320 467 

321Key468Key

322 469 

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

324 471 

325Type / Values472Type / Values

326 473 

328 475 

329Details476Details

330 477 

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

332 479 

333Key480Key

334 481 

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

336 483 

337Type / Values484Type / Values

338 485 

340 487 

341Details488Details

342 489 

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

344 491 

345Key492Key

346 493 

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

348 495 

349Type / Values496Type / Values

350 497 

352 499 

353Details500Details

354 501 

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

356 503 

357Key504Key

358 505 

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

360 507 

361Type / Values508Type / Values

362 509 

364 511 

365Details512Details

366 513 

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

515 

516Key

517 

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

519 

520Type / Values

521 

522`auto | prompt | approve`

523 

524Details

525 

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

368 527 

369Key528Key

370 529 

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

372 531 

373Type / Values532Type / Values

374 533 

376 535 

377Details536Details

378 537 

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

539 

540Key

541 

542`auto_review.policy`

543 

544Type / Values

545 

546`string`

547 

548Details

549 

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

551 

552Key

553 

554`background_terminal_max_timeout`

555 

556Type / Values

557 

558`number`

559 

560Details

561 

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

563 

564Key

565 

566`chatgpt_base_url`

567 

568Type / Values

569 

570`string`

571 

572Details

573 

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

380 575 

381Key576Key

382 577 

383`features.child_agents_md`578`check_for_update_on_startup`

384 579 

385Type / Values580Type / Values

386 581 

388 583 

389Details584Details

390 585 

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

587 

588Key

589 

590`cli_auth_credentials_store`

591 

592Type / Values

593 

594`file | keyring | auto`

595 

596Details

597 

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

599 

600Key

601 

602`commit_attribution`

603 

604Type / Values

605 

606`string`

607 

608Details

609 

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

611 

612Key

613 

614`compact_prompt`

615 

616Type / Values

617 

618`string`

619 

620Details

621 

622Inline override for the history compaction prompt.

623 

624Key

625 

626`default_permissions`

627 

628Type / Values

629 

630`string`

631 

632Details

633 

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

635 

636Key

637 

638`developer_instructions`

639 

640Type / Values

641 

642`string`

643 

644Details

645 

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

392 647 

393Key648Key

394 649 

395`features.collaboration_modes`650`disable_paste_burst`

396 651 

397Type / Values652Type / Values

398 653 

400 655 

401Details656Details

402 657 

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

659 

660Key

661 

662`experimental_compact_prompt_file`

663 

664Type / Values

665 

666`string (path)`

667 

668Details

669 

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

404 671 

405Key672Key

406 673 

407`features.elevated_windows_sandbox`674`experimental_use_unified_exec_tool`

408 675 

409Type / Values676Type / Values

410 677 

412 679 

413Details680Details

414 681 

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

416 683 

417Key684Key

418 685 

419`features.experimental_windows_sandbox`686`features.apps`

420 687 

421Type / Values688Type / Values

422 689 

424 691 

425Details692Details

426 693 

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

428 695 

429Key696Key

430 697 

431`features.multi_agent`698`features.codex_hooks`

432 699 

433Type / Values700Type / Values

434 701 

436 703 

437Details704Details

438 705 

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

440 707 

441Key708Key

442 709 

443`features.personality`710`features.enable_request_compression`

444 711 

445Type / Values712Type / Values

446 713 

448 715 

449Details716Details

450 717 

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

452 719 

453Key720Key

454 721 

455`features.powershell_utf8`722`features.fast_mode`

456 723 

457Type / Values724Type / Values

458 725 

460 727 

461Details728Details

462 729 

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

464 731 

465Key732Key

466 733 

467`features.remote_models`734`features.memories`

468 735 

469Type / Values736Type / Values

470 737 

472 739 

473Details740Details

474 741 

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

476 743 

477Key744Key

478 745 

479`features.request_rule`746`features.multi_agent`

480 747 

481Type / Values748Type / Values

482 749 

484 751 

485Details752Details

486 753 

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

488 755 

489Key756Key

490 757 

491`features.runtime_metrics`758`features.personality`

492 759 

493Type / Values760Type / Values

494 761 

496 763 

497Details764Details

498 765 

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

500 767 

501Key768Key

502 769 

503`features.search_tool`770`features.prevent_idle_sleep`

504 771 

505Type / Values772Type / Values

506 773 

508 775 

509Details776Details

510 777 

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

512 779 

513Key780Key

514 781 

520 787 

521Details788Details

522 789 

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

524 791 

525Key792Key

526 793 

536 803 

537Key804Key

538 805 

539`features.unified_exec`806`features.skill_mcp_dependency_install`

807 

808Type / Values

809 

810`boolean`

811 

812Details

813 

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

815 

816Key

817 

818`features.undo`

540 819 

541Type / Values820Type / Values

542 821 

544 823 

545Details824Details

546 825 

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

548 827 

549Key828Key

550 829 

551`features.use_linux_sandbox_bwrap`830`features.unified_exec`

552 831 

553Type / Values832Type / Values

554 833 

556 835 

557Details836Details

558 837 

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

560 839 

561Key840Key

562 841 

680 959 

681Key960Key

682 961 

683`include_apply_patch_tool`962`hooks`

684 963 

685Type / Values964Type / Values

686 965 

687`boolean`966`table`

688 967 

689Details968Details

690 969 

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

692 971 

693Key972Key

694 973 

728 1007 

729Key1008Key

730 1009 

1010`mcp_oauth_callback_url`

1011 

1012Type / Values

1013 

1014`string`

1015 

1016Details

1017 

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

1019 

1020Key

1021 

731`mcp_oauth_credentials_store`1022`mcp_oauth_credentials_store`

732 1023 

733Type / Values1024Type / Values

852 1143 

853Type / Values1144Type / Values

854 1145 

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

856 1147 

857Details1148Details

858 1149 

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

860 1151 

861Key1152Key

862 1153 

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

864 1155 

865Type / Values1156Type / Values

866 1157 

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

868 1159 

869Details1160Details

870 1161 

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

872 1163 

873Key1164Key

874 1165 

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

876 1167 

877Type / Values1168Type / Values

878 1169 

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

880 1171 

881Details1172Details

882 1173 

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

884 1175 

885Key1176Key

886 1177 

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

888 1179 

889Type / Values1180Type / Values

890 1181 

891`number`1182`string`

892 1183 

893Details1184Details

894 1185 

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

896 1187 

897Key1188Key

898 1189 

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

900 1191 

901Type / Values1192Type / Values

902 1193 

903`number`1194`boolean`

1195 

1196Details

1197 

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

1199 

1200Key

1201 

1202`mcp_servers.<id>.scopes`

1203 

1204Type / Values

1205 

1206`array<string>`

1207 

1208Details

1209 

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

1211 

1212Key

1213 

1214`mcp_servers.<id>.startup_timeout_ms`

1215 

1216Type / Values

1217 

1218`number`

1219 

1220Details

1221 

1222Alias for `startup_timeout_sec` in milliseconds.

1223 

1224Key

1225 

1226`mcp_servers.<id>.startup_timeout_sec`

1227 

1228Type / Values

1229 

1230`number`

904 1231 

905Details1232Details

906 1233 

932 1259 

933Key1260Key

934 1261 

1262`memories.consolidation_model`

1263 

1264Type / Values

1265 

1266`string`

1267 

1268Details

1269 

1270Optional model override for global memory consolidation.

1271 

1272Key

1273 

1274`memories.disable_on_external_context`

1275 

1276Type / Values

1277 

1278`boolean`

1279 

1280Details

1281 

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

1283 

1284Key

1285 

1286`memories.extract_model`

1287 

1288Type / Values

1289 

1290`string`

1291 

1292Details

1293 

1294Optional model override for per-thread memory extraction.

1295 

1296Key

1297 

1298`memories.generate_memories`

1299 

1300Type / Values

1301 

1302`boolean`

1303 

1304Details

1305 

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

1307 

1308Key

1309 

1310`memories.max_raw_memories_for_consolidation`

1311 

1312Type / Values

1313 

1314`number`

1315 

1316Details

1317 

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

1319 

1320Key

1321 

1322`memories.max_rollout_age_days`

1323 

1324Type / Values

1325 

1326`number`

1327 

1328Details

1329 

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

1331 

1332Key

1333 

1334`memories.max_rollouts_per_startup`

1335 

1336Type / Values

1337 

1338`number`

1339 

1340Details

1341 

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

1343 

1344Key

1345 

1346`memories.max_unused_days`

1347 

1348Type / Values

1349 

1350`number`

1351 

1352Details

1353 

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

1355 

1356Key

1357 

1358`memories.min_rate_limit_remaining_percent`

1359 

1360Type / Values

1361 

1362`number`

1363 

1364Details

1365 

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

1367 

1368Key

1369 

1370`memories.min_rollout_idle_hours`

1371 

1372Type / Values

1373 

1374`number`

1375 

1376Details

1377 

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

1379 

1380Key

1381 

1382`memories.use_memories`

1383 

1384Type / Values

1385 

1386`boolean`

1387 

1388Details

1389 

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

1391 

1392Key

1393 

935`model`1394`model`

936 1395 

937Type / Values1396Type / Values

940 1399 

941Details1400Details

942 1401 

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

944 1403 

945Key1404Key

946 1405 

956 1415 

957Key1416Key

958 1417 

1418`model_catalog_json`

1419 

1420Type / Values

1421 

1422`string (path)`

1423 

1424Details

1425 

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

1427 

1428Key

1429 

959`model_context_window`1430`model_context_window`

960 1431 

961Type / Values1432Type / Values

992 1463 

993Key1464Key

994 1465 

1466`model_providers.<id>`

1467 

1468Type / Values

1469 

1470`table`

1471 

1472Details

1473 

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

1475 

1476Key

1477 

1478`model_providers.<id>.auth`

1479 

1480Type / Values

1481 

1482`table`

1483 

1484Details

1485 

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

1487 

1488Key

1489 

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

1491 

1492Type / Values

1493 

1494`array<string>`

1495 

1496Details

1497 

1498Arguments passed to the token command.

1499 

1500Key

1501 

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

1503 

1504Type / Values

1505 

1506`string`

1507 

1508Details

1509 

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

1511 

1512Key

1513 

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

1515 

1516Type / Values

1517 

1518`string (path)`

1519 

1520Details

1521 

1522Working directory for the token command.

1523 

1524Key

1525 

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

1527 

1528Type / Values

1529 

1530`number`

1531 

1532Details

1533 

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

1535 

1536Key

1537 

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

1539 

1540Type / Values

1541 

1542`number`

1543 

1544Details

1545 

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

1547 

1548Key

1549 

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

996 1551 

997Type / Values1552Type / Values

1136 1691 

1137Key1692Key

1138 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 

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

1140 1707 

1141Type / Values1708Type / Values

1142 1709 

1143`chat | responses`1710`responses`

1144 1711 

1145Details1712Details

1146 1713 

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

1148 1715 

1149Key1716Key

1150 1717 

1192 1759 

1193Details1760Details

1194 1761 

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

1196 1763 

1197Key1764Key

1198 1765 

1280 1847 

1281Key1848Key

1282 1849 

1850`openai_base_url`

1851 

1852Type / Values

1853 

1854`string`

1855 

1856Details

1857 

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

1859 

1860Key

1861 

1283`oss_provider`1862`oss_provider`

1284 1863 

1285Type / Values1864Type / Values

1400 1979 

1401Key1980Key

1402 1981 

1982`otel.metrics_exporter`

1983 

1984Type / Values

1985 

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

1987 

1988Details

1989 

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

1991 

1992Key

1993 

1403`otel.trace_exporter`1994`otel.trace_exporter`

1404 1995 

1405Type / Values1996Type / Values

1484 2075 

1485Key2076Key

1486 2077 

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

1488 2079 

1489Type / Values2080Type / Values

1490 2081 

1491`none | friendly | pragmatic`2082`table`

2083 

2084Details

2085 

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

2087 

2088Key

2089 

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

2091 

2092Type / Values

2093 

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

2095 

2096Details

2097 

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

2099 

2100Key

2101 

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

2103 

2104Type / Values

2105 

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

2107 

2108Details

2109 

2110Grant direct access for a path, glob pattern, or special token, or scope nested entries under that root. Use `"none"` to deny reads for matching paths.

2111 

2112Key

2113 

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

2115 

2116Type / Values

2117 

2118`number`

2119 

2120Details

2121 

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

2123 

2124Key

2125 

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

2127 

2128Type / Values

2129 

2130`boolean`

2131 

2132Details

2133 

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

2135 

2136Key

2137 

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

2139 

2140Type / Values

2141 

2142`boolean`

2143