config-reference.md Codex Docs, 2026-02-24 00:33 UTC → 2026-05-02 00:48 UTC

6 6 

7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.

8 8 

9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).

10 10 

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

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

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

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

15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |

16| `agents.job_max_runtime_seconds` | `number` | Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker. |

15| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

47| `features.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). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

181 244 

182Key245Key

183 246 

205 268 

206Key269Key

207 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 

208`agents.max_depth`295`agents.max_depth`

209 296 

210Type / Values297Type / Values

225 312 

226Details313Details

227 314 

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

229 316 

230Key317Key

231 318 

241 328 

242Key329Key

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

340 

341Key

342 

244`approval_policy`343`approval_policy`

245 344 

246Type / Values345Type / Values

247 346 

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

348 

349Details

350 

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.

352 

353Key

354 

355`approval_policy.granular.mcp_elicitations`

356 

357Type / Values

358 

359`boolean`

360 

361Details

362 

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

364 

365Key

366 

367`approval_policy.granular.request_permissions`

368 

369Type / Values

370 

371`boolean`

249 372 

250Details373Details

251 374 

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

253 376 

254Key377Key

255 378 

256`approval_policy.reject.mcp_elicitations`379`approval_policy.granular.rules`

257 380 

258Type / Values381Type / Values

259 382 

261 384 

262Details385Details

263 386 

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

265 388 

266Key389Key

267 390 

268`approval_policy.reject.rules`391`approval_policy.granular.sandbox_approval`

269 392 

270Type / Values393Type / Values

271 394 

273 396 

274Details397Details

275 398 

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

277 400 

278Key401Key

279 402 

280`approval_policy.reject.sandbox_approval`403`approval_policy.granular.skill_approval`

281 404 

282Type / Values405Type / Values

283 406 

285 408 

286Details409Details

287 410 

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

412 

413Key

414 

415`approvals_reviewer`

416 

417Type / Values

418 

419`user | auto_review`

420 

421Details

422 

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.

289 424 

290Key425Key

291 426 

409 544 

410Key545Key

411 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 

412`background_terminal_max_timeout`559`background_terminal_max_timeout`

413 560 

414Type / Values561Type / Values

457 604 

458Key605Key

459 606 

460`compact_prompt`607`commit_attribution`

461 608 

462Type / Values609Type / Values

463 610 

465 612 

466Details613Details

467 614 

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

469 616 

470Key617Key

471 618 

472`developer_instructions`619`compact_prompt`

473 620 

474Type / Values621Type / Values

475 622 

477 624 

478Details625Details

479 626 

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

481 628 

482Key629Key

483 630 

484`disable_paste_burst`631`default_permissions`

485 632 

486Type / Values633Type / Values

487 634 

488`boolean`635`string`

489 636 

490Details637Details

491 638 

492Disable burst-paste detection in the TUI.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.

493 640 

494Key641Key

495 642 

496`experimental_compact_prompt_file`643`developer_instructions`

497 644 

498Type / Values645Type / Values

499 646 

500`string (path)`647`string`

501 648 

502Details649Details

503 650 

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

505 652 

506Key653Key

507 654 

508`experimental_use_freeform_apply_patch`655`disable_paste_burst`

509 656 

510Type / Values657Type / Values

511 658 

513 660 

514Details661Details

515 662 

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

517 664 

518Key665Key

519 666 

520`experimental_use_unified_exec_tool`667`experimental_compact_prompt_file`

521 668 

522Type / Values669Type / Values

523 670 

524`boolean`671`string (path)`

525 672 

526Details673Details

527 674 

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

529 676 

530Key677Key

531 678 

532`features.apply_patch_freeform`679`experimental_use_unified_exec_tool`

533 680 

534Type / Values681Type / Values

535 682 

537 684 

538Details685Details

539 686 

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

541 688 

542Key689Key

543 690 

553 700 

554Key701Key

555 702 

556`features.apps_mcp_gateway`703`features.codex_hooks`

557 

558Type / Values

559 

560`boolean`

561 

562Details

563 

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

565 

566Key

567 

568`features.child_agents_md`

569 704 

570Type / Values705Type / Values

571 706 

573 708 

574Details709Details

575 710 

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

577 712 

578Key713Key

579 714 

580`features.collaboration_modes`715`features.enable_request_compression`

581 716 

582Type / Values717Type / Values

583 718 

585 720 

586Details721Details

587 722 

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

589 724 

590Key725Key

591 726 

592`features.elevated_windows_sandbox`727`features.fast_mode`

593 728 

594Type / Values729Type / Values

595 730 

597 732 

598Details733Details

599 734 

600Enable the elevated Windows sandbox pipeline (experimental).735Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

601 736 

602Key737Key

603 738 

604`features.experimental_windows_sandbox`739`features.memories`

605 740 

606Type / Values741Type / Values

607 742 

609 744 

610Details745Details

611 746 

612Run the Windows restricted-token sandbox (experimental).747Enable [Memories](https://developers.openai.com/codex/memories) (off by default).

613 748 

614Key749Key

615 750 

621 756 

622Details757Details

623 758 

624Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).759Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

625 760 

626Key761Key

627 762 

637 772 

638Key773Key

639 774 

640`features.powershell_utf8`775`features.prevent_idle_sleep`

641 

642Type / Values

643 

644`boolean`

645 

646Details

647 

648Force PowerShell UTF-8 output (defaults to true).

649 

650Key

651 

652`features.remote_models`

653 

654Type / Values

655 

656`boolean`

657 

658Details

659 

660Refresh remote model list before showing readiness (experimental).

661 

662Key

663 

664`features.request_rule`

665 776 

666Type / Values777Type / Values

667 778 

669 780 

670Details781Details

671 782 

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

673 784 

674Key785Key

675 786 

676`features.runtime_metrics`787`features.shell_snapshot`

677 788 

678Type / Values789Type / Values

679 790 

681 792 

682Details793Details

683 794 

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

685 796 

686Key797Key

687 798 

688`features.search_tool`799`features.shell_tool`

689 800 

690Type / Values801Type / Values

691 802 

693 804 

694Details805Details

695 806 

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

697 808 

698Key809Key

699 810 

700`features.shell_snapshot`811`features.skill_mcp_dependency_install`

701 812 

702Type / Values813Type / Values

703 814 

705 816 

706Details817Details

707 818 

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

709 820 

710Key821Key

711 822 

712`features.shell_tool`823`features.undo`

713 824 

714Type / Values825Type / Values

715 826 

717 828 

718Details829Details

719 830 

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

721 832 

722Key833Key

723 834 

729 840 

730Details841Details

731 842 

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

733 

734Key

735 

736`features.use_linux_sandbox_bwrap`

737 

738Type / Values

739 

740`boolean`

741 

742Details

743 

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

745 844 

746Key845Key

747 846 

865 964 

866Key965Key

867 966 

868`include_apply_patch_tool`967`hooks`

869 968 

870Type / Values969Type / Values

871 970 

872`boolean`971`table`

873 972 

874Details973Details

875 974 

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

877 976 

878Key977Key

879 978 

1049 1148 

1050Type / Values1149Type / Values

1051 1150 

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

1053 1152 

1054Details1153Details

1055 1154 

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

1156 

1157Key

1158 

1159`mcp_servers.<id>.experimental_environment`

1160 

1161Type / Values

1162 

1163`local | remote`

1164 

1165Details

1166 

1167Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.

1057 1168 

1058Key1169Key

1059 1170 

1069 1180 

1070Key1181Key

1071 1182 

1183`mcp_servers.<id>.oauth_resource`

1184 

1185Type / Values

1186 

1187`string`

1188 

1189Details

1190 

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

1192 

1193Key

1194 

1072`mcp_servers.<id>.required`1195`mcp_servers.<id>.required`

1073 1196 

1074Type / Values1197Type / Values

1081 1204 

1082Key1205Key

1083 1206 

1207`mcp_servers.<id>.scopes`

1208 

1209Type / Values

1210 

1211`array<string>`

1212 

1213Details

1214 

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

1216 

1217Key

1218 

1084`mcp_servers.<id>.startup_timeout_ms`1219`mcp_servers.<id>.startup_timeout_ms`

1085 1220 

1086Type / Values1221Type / Values

1129 1264 

1130Key1265Key

1131 1266 

1132`model`1267`memories.consolidation_model`

1133 1268 

1134Type / Values1269Type / Values

1135 1270 

1137 1272 

1138Details1273Details

1139 1274 

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

1141 1276 

1142Key1277Key

1143 1278 

1144`model_auto_compact_token_limit`1279`memories.disable_on_external_context`

1145 1280 

1146Type / Values1281Type / Values

1147 1282 

1148`number`1283`boolean`

1149 1284 

1150Details1285Details

1151 1286 

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

1153 1288 

1154Key1289Key

1155 1290 

1156`model_catalog_json`1291`memories.extract_model`

1157 1292 

1158Type / Values1293Type / Values

1159 1294 

1160`string (path)`1295`string`

1161 1296 

1162Details1297Details

1163 1298 

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

1165 1300 

1166Key1301Key

1167 1302 

1168`model_context_window`1303`memories.generate_memories`

1169 1304 

1170Type / Values1305Type / Values

1171 1306 

1172`number`1307`boolean`

1173 1308 

1174Details1309Details

1175 1310 

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

1177 1312 

1178Key1313Key

1179 1314 

1180`model_instructions_file`1315`memories.max_raw_memories_for_consolidation`

1181 1316 

1182Type / Values1317Type / Values

1183 1318 

1184`string (path)`1319`number`

1185 1320 

1186Details1321Details

1187 1322 

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

1189 1324 

1190Key1325Key

1191 1326 

1192`model_provider`1327`memories.max_rollout_age_days`

1193 1328 

1194Type / Values1329Type / Values

1195 1330 

1196`string`1331`number`

1197 1332 

1198Details1333Details

1199 1334 

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

1201 1336 

1202Key1337Key

1203 1338 

1204`model_providers.<id>.base_url`1339`memories.max_rollouts_per_startup`

1205 1340 

1206Type / Values1341Type / Values

1207 1342 

1208`string`1343`number`

1209 1344 

1210Details1345Details

1211 1346 

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

1213 1348 

1214Key1349Key

1215 1350 

1216`model_providers.<id>.env_http_headers`1351`memories.max_unused_days`

1217 1352 

1218Type / Values1353Type / Values

1219 1354 

1220`map<string,string>`1355`number`

1221 1356 

1222Details1357Details

1223 1358 

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

1225 1360 

1226Key1361Key

1227 1362 

1228`model_providers.<id>.env_key`1363`memories.min_rate_limit_remaining_percent`

1229 1364 

1230Type / Values1365Type / Values

1231 1366 

1232`string`1367`number`

1233 1368 

1234Details1369Details

1235 1370 

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

1237 1372 

1238Key1373Key

1239 1374 

1240`model_providers.<id>.env_key_instructions`1375`memories.min_rollout_idle_hours`

1241 1376 

1242Type / Values1377Type / Values

1243 1378 

1244`string`1379`number`

1245 1380 

1246Details1381Details

1247 1382 

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

1249 1384 

1250Key1385Key

1251 1386 

1252`model_providers.<id>.experimental_bearer_token`1387`memories.use_memories`

1253 1388 

1254Type / Values1389Type / Values

1255 1390 

1256`string`1391`boolean`

1257 1392 

1258Details1393Details

1259 1394 

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

1261 1396 

1262Key1397Key

1263 1398 

1264`model_providers.<id>.http_headers`1399`model`

1265 1400 

1266Type / Values1401Type / Values

1267 1402 

1268`map<string,string>`1403`string`

1269 1404 

1270Details1405Details

1271 1406 

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

1273 1408 

1274Key1409Key

1275 1410 

1276`model_providers.<id>.name`1411`model_auto_compact_token_limit`

1277 1412 

1278Type / Values1413Type / Values

1279 1414 

1280`string`1415`number`

1281 1416 

1282Details1417Details

1283 1418 

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

1285 1420 

1286Key1421Key

1287 1422 

1288`model_providers.<id>.query_params`1423`model_catalog_json`

1289 1424 

1290Type / Values1425Type / Values

1291 1426 

1292`map<string,string>`1427`string (path)`

1293 1428 

1294Details1429Details

1295 1430 

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

1297 1432 

1298Key1433Key

1299 1434 

1300`model_providers.<id>.request_max_retries`1435`model_context_window`

1301 1436 

1302Type / Values1437Type / Values

1303 1438 

1305 1440 

1306Details1441Details

1307 1442 

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

1309 1444 

1310Key1445Key

1311 1446 

1312`model_providers.<id>.requires_openai_auth`1447`model_instructions_file`

1313 1448 

1314Type / Values1449Type / Values

1315 1450 

1316`boolean`1451`string (path)`

1317 1452 

1318Details1453Details

1319 1454 

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

1321 1456 

1322Key1457Key

1323 1458 

1324`model_providers.<id>.stream_idle_timeout_ms`1459`model_provider`

1325 1460 

1326Type / Values1461Type / Values

1327 1462 

1328`number`1463`string`

1329 1464 

1330Details1465Details

1331 1466 

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

1333 1468 

1334Key1469Key

1335 1470 

1336`model_providers.<id>.stream_max_retries`1471`model_providers.<id>`

1337 1472 

1338Type / Values1473Type / Values

1339 1474 

1340`number`1475`table`

1341 1476 

1342Details1477Details

1343 1478 

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

1345 1480 

1346Key1481Key

1347 1482 

1348`model_providers.<id>.wire_api`1483`model_providers.<id>.auth`

1349 1484 

1350Type / Values1485Type / Values

1351 1486 

1352`chat | responses`1487`table`

1353 1488 

1354Details1489Details

1355 1490 

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

1357 1492 

1358Key1493Key

1359 1494 

1360`model_reasoning_effort`1495`model_providers.<id>.auth.args`

1361 1496 

1362Type / Values1497Type / Values

1363 1498 

1364`minimal | low | medium | high | xhigh`1499`array<string>`

1365 1500 

1366Details1501Details

1367 1502 

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

1369 1504 

1370Key1505Key

1371 1506 

1372`model_reasoning_summary`1507`model_providers.<id>.auth.command`

1373 1508 

1374Type / Values1509Type / Values

1375 1510 

1376`auto | concise | detailed | none`1511`string`

1377 1512 

1378Details1513Details

1379 1514 

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

1381 1516 

1382Key1517Key

1383 1518 

1384`model_supports_reasoning_summaries`1519`model_providers.<id>.auth.cwd`

1385 1520 

1386Type / Values1521Type / Values

1387 1522 

1388`boolean`1523`string (path)`

1389 1524 

1390Details1525Details

1391 1526 

1392Force Codex to send or not send reasoning metadata.1527Working directory for the token command.

1393 1528 

1394Key1529Key

1395 1530 

1396`model_verbosity`1531`model_providers.<id>.auth.refresh_interval_ms`

1397 1532 

1398Type / Values1533Type / Values

1399 1534 

1400`low | medium | high`1535`number`

1401 1536 

1402Details1537Details

1403 1538 

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

1405 1540 

1406Key1541Key

1407 1542 

1408`notice.hide_full_access_warning`1543`model_providers.<id>.auth.timeout_ms`

1409 1544 

1410Type / Values1545Type / Values

1411 1546 

1412`boolean`1547`number`

1413 1548 

1414Details1549Details

1415 1550 

1416Track acknowledgement of the full access warning prompt.1551Maximum token command runtime in milliseconds (default: 5000).

1417 1552 

1418Key1553Key

1419 1554 

1420`notice.hide_gpt-5.1-codex-max_migration_prompt`1555`model_providers.<id>.base_url`

1421 1556 

1422Type / Values1557Type / Values

1423 1558 

1424`boolean`1559`string`

1425 1560 

1426Details1561Details

1427 1562 

1428Track acknowledgement of the gpt-5.1-codex-max migration prompt.1563API base URL for the model provider.

1429 1564 

1430Key1565Key

1431 1566 

1432`notice.hide_gpt5_1_migration_prompt`1567`model_providers.<id>.env_http_headers`

1433 1568 

1434Type / Values1569Type / Values

1435 1570 

1436`boolean`1571`map<string,string>`

1437 1572 

1438Details1573Details

1439 1574 

1440Track acknowledgement of the GPT-5.1 migration prompt.1575HTTP headers populated from environment variables when present.

1441 1576 

1442Key1577Key

1443 1578 

1444`notice.hide_rate_limit_model_nudge`1579`model_providers.<id>.env_key`

1445 1580 

1446Type / Values1581Type / Values

1447 1582 

1448`boolean`1583`string`

1449 1584 

1450Details1585Details

1451 1586 

1452Track opt-out of the rate limit model switch reminder.1587Environment variable supplying the provider API key.

1453 1588 

1454Key1589Key

1455 1590 

1456`notice.hide_world_writable_warning`1591`model_providers.<id>.env_key_instructions`

1457 1592 

1458Type / Values1593Type / Values

1459 1594 

1460`boolean`1595`string`

1461 1596 

1462Details1597Details

1463 1598 

1464Track acknowledgement of the Windows world-writable directories warning.1599Optional setup guidance for the provider API key.

1465 1600 

1466Key1601Key

1467 1602 

1468`notice.model_migrations`1603`model_providers.<id>.experimental_bearer_token`

1469 1604 

1470Type / Values1605Type / Values

1471 1606 

1472`map<string,string>`1607`string`

1473 1608 

1474Details1609Details

1475 1610 

1476Track acknowledged model migrations as old->new mappings.1611Direct bearer token for the provider (discouraged; use `env_key`).

1477 1612 

1478Key1613Key

1479 1614 

1480`notify`1615`model_providers.<id>.http_headers`

1481 1616 

1482Type / Values1617Type / Values

1483 1618 

1484`array<string>`1619`map<string,string>`

1485 1620 

1486Details1621Details

1487 1622 

1488Command invoked for notifications; receives a JSON payload from Codex.1623Static HTTP headers added to provider requests.