config-reference.md Codex Docs, 2026-03-07 00:33 UTC → 2026-04-25 06:37 UTC

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

48| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default). |54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

91| `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_rollout_idle_hours` | `number` | Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`. |

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

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

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

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

94| `model_context_window` | `number` | Context window tokens available to the active model. |111| `model_context_window` | `number` | Context window tokens available to the active model. |

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

96| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |113| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

112| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |137| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |

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

114| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |139| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |

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

116| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |141| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |

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

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

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

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

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

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

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

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

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

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

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

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

132| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |159| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

139| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |183| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

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

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

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

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

144| `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). |187| `profiles.<name>.model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |

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

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

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

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

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

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

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

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

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

149| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |197| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |

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

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

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

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

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

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

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

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

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

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

159| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |208| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |

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

168| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |217| `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. |218| `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. |219| `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. |220| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

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

222| `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. |223| `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). |224| `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). |225| `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). |226| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |

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

228| `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. |229| `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). |230| `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. |231| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

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

233| `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. |234| `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). |235| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

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

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

182 238 

183Key239Key

184 240 

206 262 

207Key263Key

208 264 

265`agents.<name>.nickname_candidates`

266 

267Type / Values

268 

269`array<string>`

270 

271Details

272 

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

274 

275Key

276 

209`agents.job_max_runtime_seconds`277`agents.job_max_runtime_seconds`

210 278 

211Type / Values279Type / Values

238 306 

239Details307Details

240 308 

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

242 310 

243Key311Key

244 312 

254 322 

255Key323Key

256 324 

325`analytics.enabled`

326 

327Type / Values

328 

329`boolean`

330 

331Details

332 

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

334 

335Key

336 

257`approval_policy`337`approval_policy`

258 338 

259Type / Values339Type / Values

260 340 

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

342 

343Details

344 

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

346 

347Key

348 

349`approval_policy.granular.mcp_elicitations`

350 

351Type / Values

352 

353`boolean`

354 

355Details

356 

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

358 

359Key

360 

361`approval_policy.granular.request_permissions`

362 

363Type / Values

364 

365`boolean`

262 366 

263Details367Details

264 368 

265Controls 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.369When `true`, prompts from the `request_permissions` tool are allowed to surface.

266 370 

267Key371Key

268 372 

269`approval_policy.reject.mcp_elicitations`373`approval_policy.granular.rules`

270 374 

271Type / Values375Type / Values

272 376 

274 378 

275Details379Details

276 380 

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

278 382 

279Key383Key

280 384 

281`approval_policy.reject.rules`385`approval_policy.granular.sandbox_approval`

282 386 

283Type / Values387Type / Values

284 388 

286 390 

287Details391Details

288 392 

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

290 394 

291Key395Key

292 396 

293`approval_policy.reject.sandbox_approval`397`approval_policy.granular.skill_approval`

294 398 

295Type / Values399Type / Values

296 400 

298 402 

299Details403Details

300 404 

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

406 

407Key

408 

409`approvals_reviewer`

410 

411Type / Values

412 

413`user | auto_review`

414 

415Details

416 

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

302 418 

303Key419Key

304 420 

422 538 

423Key539Key

424 540 

541`auto_review.policy`

542 

543Type / Values

544 

545`string`

546 

547Details

548 

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

550 

551Key

552 

425`background_terminal_max_timeout`553`background_terminal_max_timeout`

426 554 

427Type / Values555Type / Values

470 598 

471Key599Key

472 600 

473`compact_prompt`601`commit_attribution`

474 602 

475Type / Values603Type / Values

476 604 

478 606 

479Details607Details

480 608 

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

482 610 

483Key611Key

484 612 

485`developer_instructions`613`compact_prompt`

486 614 

487Type / Values615Type / Values

488 616 

490 618 

491Details619Details

492 620 

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

494 622 

495Key623Key

496 624 

497`disable_paste_burst`625`default_permissions`

498 626 

499Type / Values627Type / Values

500 628 

501`boolean`629`string`

502 630 

503Details631Details

504 632 

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

506 634 

507Key635Key

508 636 

509`experimental_compact_prompt_file`637`developer_instructions`

510 638 

511Type / Values639Type / Values

512 640 

513`string (path)`641`string`

514 642 

515Details643Details

516 644 

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

518 646 

519Key647Key

520 648 

521`experimental_use_freeform_apply_patch`649`disable_paste_burst`

522 650 

523Type / Values651Type / Values

524 652 

526 654 

527Details655Details

528 656 

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

530 658 

531Key659Key

532 660 

533`experimental_use_unified_exec_tool`661`experimental_compact_prompt_file`

534 662 

535Type / Values663Type / Values

536 664 

537`boolean`665`string (path)`

538 666 

539Details667Details

540 668 

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

542 670 

543Key671Key

544 672 

545`features.apply_patch_freeform`673`experimental_use_unified_exec_tool`

546 674 

547Type / Values675Type / Values

548 676 

550 678 

551Details679Details

552 680 

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

554 682 

555Key683Key

556 684 

566 694 

567Key695Key

568 696 

569`features.apps_mcp_gateway`697`features.codex_hooks`

570 

571Type / Values

572 

573`boolean`

574 

575Details

576 

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

578 

579Key

580 

581`features.child_agents_md`

582 698 

583Type / Values699Type / Values

584 700 

586 702 

587Details703Details

588 704 

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

590 706 

591Key707Key

592 708 

593`features.collaboration_modes`709`features.enable_request_compression`

594 710 

595Type / Values711Type / Values

596 712 

598 714 

599Details715Details

600 716 

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

602 718 

603Key719Key

604 720 

605`features.multi_agent`721`features.fast_mode`

606 722 

607Type / Values723Type / Values

608 724 

610 726 

611Details727Details

612 728 

613Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default).729Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

614 730 

615Key731Key

616 732 

617`features.personality`733`features.memories`

618 734 

619Type / Values735Type / Values

620 736 

622 738 

623Details739Details

624 740 

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

626 742 

627Key743Key

628 744 

629`features.powershell_utf8`745`features.multi_agent`

630 746 

631Type / Values747Type / Values

632 748 

634 750 

635Details751Details

636 752 

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

638 754 

639Key755Key

640 756 

641`features.remote_models`757`features.personality`

642 758 

643Type / Values759Type / Values

644 760 

646 762 

647Details763Details

648 764 

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

650 766 

651Key767Key

652 768 

653`features.request_rule`769`features.prevent_idle_sleep`

654 770 

655Type / Values771Type / Values

656 772 

658 774 

659Details775Details

660 776 

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

662 778 

663Key779Key

664 780 

665`features.runtime_metrics`781`features.shell_snapshot`

666 782 

667Type / Values783Type / Values

668 784 

670 786 

671Details787Details

672 788 

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

674 790 

675Key791Key

676 792 

677`features.search_tool`793`features.shell_tool`

678 794 

679Type / Values795Type / Values

680 796 

682 798 

683Details799Details

684 800 

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

686 802 

687Key803Key

688 804 

689`features.shell_snapshot`805`features.skill_mcp_dependency_install`

690 806 

691Type / Values807Type / Values

692 808 

694 810 

695Details811Details

696 812 

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

698 814 

699Key815Key

700 816 

701`features.shell_tool`817`features.undo`

702 818 

703Type / Values819Type / Values

704 820 

706 822 

707Details823Details

708 824 

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

710 826 

711Key827Key

712 828 

718 834 

719Details835Details

720 836 

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

722 

723Key

724 

725`features.use_linux_sandbox_bwrap`

726 

727Type / Values

728 

729`boolean`

730 

731Details

732 

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

734 838 

735Key839Key

736 840 

854 958 

855Key959Key

856 960 

857`include_apply_patch_tool`961`hooks`

858 962 

859Type / Values963Type / Values

860 964 

861`boolean`965`table`

862 966 

863Details967Details

864 968 

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

866 970 

867Key971Key

868 972 

1038 1142 

1039Type / Values1143Type / Values

1040 1144 

1041`array<string>`1145`array<string | { name = string, source = "local" | "remote" }>`

1146 

1147Details

1148 

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

1150 

1151Key

1152 

1153`mcp_servers.<id>.experimental_environment`

1154 

1155Type / Values

1156 

1157`local | remote`

1042 1158 

1043Details1159Details

1044 1160 

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

1046 1162 

1047Key1163Key

1048 1164 

1058 1174 

1059Key1175Key

1060 1176 

1177`mcp_servers.<id>.oauth_resource`

1178 

1179Type / Values

1180 

1181`string`

1182 

1183Details

1184 

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

1186 

1187Key

1188 

1061`mcp_servers.<id>.required`1189`mcp_servers.<id>.required`

1062 1190 

1063Type / Values1191Type / Values

1070 1198 

1071Key1199Key

1072 1200 

1201`mcp_servers.<id>.scopes`

1202 

1203Type / Values

1204 

1205`array<string>`

1206 

1207Details

1208 

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

1210 

1211Key

1212 

1073`mcp_servers.<id>.startup_timeout_ms`1213`mcp_servers.<id>.startup_timeout_ms`

1074 1214 

1075Type / Values1215Type / Values

1118 1258 

1119Key1259Key

1120 1260 

1121`model`1261`memories.consolidation_model`

1122 1262 

1123Type / Values1263Type / Values

1124 1264 

1126 1266 

1127Details1267Details

1128 1268 

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

1130 1270 

1131Key1271Key

1132 1272 

1133`model_auto_compact_token_limit`1273`memories.disable_on_external_context`

1134 1274 

1135Type / Values1275Type / Values

1136 1276 

1137`number`1277`boolean`

1138 1278 

1139Details1279Details

1140 1280 

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

1142 1282 

1143Key1283Key

1144 1284 

1145`model_catalog_json`1285`memories.extract_model`

1146 1286 

1147Type / Values1287Type / Values

1148 1288 

1149`string (path)`1289`string`

1150 1290 

1151Details1291Details

1152 1292 

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

1154 1294 

1155Key1295Key

1156 1296 

1157`model_context_window`1297`memories.generate_memories`

1158 1298 

1159Type / Values1299Type / Values

1160 1300 

1161`number`1301`boolean`

1162 1302 

1163Details1303Details

1164 1304 

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

1166 1306 

1167Key1307Key

1168 1308 

1169`model_instructions_file`1309`memories.max_raw_memories_for_consolidation`

1170 1310 

1171Type / Values1311Type / Values

1172 1312 

1173`string (path)`1313`number`

1174 1314 

1175Details1315Details

1176 1316 

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

1178 1318 

1179Key1319Key

1180 1320 

1181`model_provider`1321`memories.max_rollout_age_days`

1182 1322 

1183Type / Values1323Type / Values

1184 1324 

1185`string`1325`number`

1186 1326 

1187Details1327Details

1188 1328 

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

1190 1330 

1191Key1331Key

1192 1332 

1193`model_providers.<id>.base_url`1333`memories.max_rollouts_per_startup`

1194 1334 

1195Type / Values1335Type / Values

1196 1336 

1197`string`1337`number`

1198 1338 

1199Details1339Details

1200 1340 

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

1202 1342 

1203Key1343Key

1204 1344 

1205`model_providers.<id>.env_http_headers`1345`memories.max_unused_days`

1206 1346 

1207Type / Values1347Type / Values

1208 1348 

1209`map<string,string>`1349`number`

1210 1350 

1211Details1351Details

1212 1352 

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

1214 1354 

1215Key1355Key

1216 1356 

1217`model_providers.<id>.env_key`1357`memories.min_rollout_idle_hours`

1218 1358 

1219Type / Values1359Type / Values

1220 1360 

1221`string`1361`number`

1222 1362 

1223Details1363Details

1224 1364 

1225Environment variable supplying the provider API key.1365Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.

1226 1366 

1227Key1367Key

1228 1368 

1229`model_providers.<id>.env_key_instructions`1369`memories.use_memories`

1230 1370 

1231Type / Values1371Type / Values

1232 1372 

1233`string`1373`boolean`

1234 1374 

1235Details1375Details

1236 1376 

1237Optional setup guidance for the provider API key.1377When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.

1238 1378 

1239Key1379Key

1240 1380 

1241`model_providers.<id>.experimental_bearer_token`1381`model`

1242 1382 

1243Type / Values1383Type / Values

1244 1384 

1246 1386 

1247Details1387Details

1248 1388 

1249Direct bearer token for the provider (discouraged; use `env_key`).1389Model to use (e.g., `gpt-5.5`).

1250 1390 

1251Key1391Key

1252 1392 

1253`model_providers.<id>.http_headers`1393`model_auto_compact_token_limit`

1254 1394 

1255Type / Values1395Type / Values

1256 1396 

1257`map<string,string>`1397`number`

1258 1398 

1259Details1399Details

1260 1400 

1261Static HTTP headers added to provider requests.1401Token threshold that triggers automatic history compaction (unset uses model defaults).

1262 1402 

1263Key1403Key

1264 1404 

1265`model_providers.<id>.name`1405`model_catalog_json`

1266 1406 

1267Type / Values1407Type / Values

1268 1408 

1269`string`1409`string (path)`

1270 1410 

1271Details1411Details

1272 1412 

1273Display name for a custom model provider.1413Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.

1274 1414 

1275Key1415Key

1276 1416 

1277`model_providers.<id>.query_params`1417`model_context_window`

1278 1418 

1279Type / Values1419Type / Values

1280 1420 

1281`map<string,string>`1421`number`

1282 1422 

1283Details1423Details

1284 1424 

1285Extra query parameters appended to provider requests.1425Context window tokens available to the active model.

1286 1426 

1287Key1427Key

1288 1428 

1289`model_providers.<id>.request_max_retries`1429`model_instructions_file`

1290 1430 

1291Type / Values1431Type / Values

1292 1432 

1293`number`1433`string (path)`

1294 1434 

1295Details1435Details

1296 1436 

1297Retry count for HTTP requests to the provider (default: 4).1437Replacement for built-in instructions instead of `AGENTS.md`.

1298 1438 

1299Key1439Key

1300 1440 

1301`model_providers.<id>.requires_openai_auth`1441`model_provider`

1302 1442 

1303Type / Values1443Type / Values

1304 1444 

1305`boolean`1445`string`

1306 1446 

1307Details1447Details

1308 1448 

1309The provider uses OpenAI authentication (defaults to false).1449Provider id from `model_providers` (default: `openai`).

1310 1450 

1311Key1451Key

1312 1452 

1313`model_providers.<id>.stream_idle_timeout_ms`1453`model_providers.<id>`

1314 1454 

1315Type / Values1455Type / Values

1316 1456 

1317`number`1457`table`

1318 1458 

1319Details1459Details

1320 1460 

1321Idle timeout for SSE streams in milliseconds (default: 300000).1461Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.

1322 1462 

1323Key1463Key

1324 1464 

1325`model_providers.<id>.stream_max_retries`1465`model_providers.<id>.auth`

1326 1466 

1327Type / Values1467Type / Values

1328 1468 

1329`number`1469`table`

1330 1470 

1331Details1471Details

1332 1472 

1333Retry count for SSE streaming interruptions (default: 5).1473Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.

1334 1474 

1335Key1475Key

1336 1476 

1337`model_providers.<id>.wire_api`1477`model_providers.<id>.auth.args`

1338 1478 

1339Type / Values1479Type / Values

1340 1480 

1341`chat | responses`1481`array<string>`

1342 1482 

1343Details1483Details

1344 1484 

1345Protocol used by the provider (defaults to `chat` if omitted).1485Arguments passed to the token command.

1346 1486 

1347Key1487Key

1348 1488 

1349`model_reasoning_effort`1489`model_providers.<id>.auth.command`

1350 1490 

1351Type / Values1491Type / Values

1352 1492 

1353`minimal | low | medium | high | xhigh`1493`string`

1354 1494 

1355Details1495Details

1356 1496 

1357Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).1497Command to run when Codex needs a bearer token. The command must print the token to stdout.

1358 1498 

1359Key1499Key

1360 1500 

1361`model_reasoning_summary`1501`model_providers.<id>.auth.cwd`

1362 1502 

1363Type / Values1503Type / Values

1364 1504 

1365`auto | concise | detailed | none`1505`string (path)`

1366 1506 

1367Details1507Details

1368 1508 

1369Select reasoning summary detail or disable summaries entirely.1509Working directory for the token command.

1370 1510 

1371Key1511Key

1372 1512 

1373`model_supports_reasoning_summaries`1513`model_providers.<id>.auth.refresh_interval_ms`

1374 1514 

1375Type / Values1515Type / Values

1376 1516 

1377`boolean`1517`number`

1378 1518 

1379Details1519Details

1380 1520 

1381Force Codex to send or not send reasoning metadata.1521How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.

1382 1522 

1383Key1523Key

1384 1524 

1385`model_verbosity`1525`model_providers.<id>.auth.timeout_ms`

1386 1526 

1387Type / Values1527Type / Values

1388 1528 

1389`low | medium | high`1529`number`

1390 1530 

1391Details1531Details

1392 1532 

1393Control GPT-5 Responses API verbosity (defaults to `medium`).1533Maximum token command runtime in milliseconds (default: 5000).

1394 1534 

1395Key1535Key

1396 1536 

1397`notice.hide_full_access_warning`1537`model_providers.<id>.base_url`

1398 1538 

1399Type / Values1539Type / Values

1400 1540 

1401`boolean`1541`string`

1402 1542 

1403Details1543Details

1404 1544 

1405Track acknowledgement of the full access warning prompt.1545API base URL for the model provider.

1406 1546 

1407Key1547Key

1408 1548 

1409`notice.hide_gpt-5.1-codex-max_migration_prompt`1549`model_providers.<id>.env_http_headers`

1410 1550 

1411Type / Values1551Type / Values

1412 1552 

1413`boolean`1553`map<string,string>`

1414 1554 

1415Details1555Details

1416 1556 

1417Track acknowledgement of the gpt-5.1-codex-max migration prompt.1557HTTP headers populated from environment variables when present.

1558 

1559Key

1560 

1561`model_providers.<id>.env_key`

1562 

1563Type / Values

1564 

1565`string`

1566 

1567Details

1568 

1569Environment variable supplying the provider API key.

1570 

1571Key

1572 

1573`model_providers.<id>.env_key_instructions`

1574 

1575Type / Values

1576 

1577`string`

1578 

1579Details

1580 

1581Optional setup guidance for the provider API key.

1582 

1583Key

1584 

1585`model_providers.<id>.experimental_bearer_token`

1586 

1587Type / Values

1588 

1589`string`

1590 

1591Details

1592 

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

1594 

1595Key

1596 

1597`model_providers.<id>.http_headers`

1598 

1599Type / Values

1600 

1601`map<string,string>`

1602 

1603Details

1604 

1605Static HTTP headers added to provider requests.

1606 

1607Key

1608 

1609`model_providers.<id>.name`

1610 

1611Type / Values

1612 

1613`string`

1614 

1615Details

1616 

1617Display name for a custom model provider.

1618 

1619Key

1620 

1621`model_providers.<id>.query_params`

1622 

1623Type / Values

1624 

1625`map<string,string>`

1626 

1627Details

1628 

1629Extra query parameters appended to provider requests.

1630 

1631Key

1632 

1633`model_providers.<id>.request_max_retries`

1634 

1635Type / Values

1636 

1637`number`

1638 

1639Details

1640 

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

1642 

1643Key

1644 

1645`model_providers.<id>.requires_openai_auth`

1646 

1647Type / Values

1648 

1649`boolean`

1650 

1651Details

1652 

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

1654 

1655Key

1656 

1657`model_providers.<id>.stream_idle_timeout_ms`

1658 

1659Type / Values

1660 

1661`number`

1662 

1663Details

1664 

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

1666 

1667Key

1668 

1669`model_providers.<id>.stream_max_retries`

1670 

1671Type / Values

1672 

1673`number`

1674 

1675Details

1676 

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

1678 

1679Key

1680 

1681`model_providers.<id>.supports_websockets`

1682 

1683Type / Values

1684 

1685`boolean`

1686 

1687Details

1688 

1689Whether that provider supports the Responses API WebSocket transport.

1690 

1691Key

1692 

1693`model_providers.<id>.wire_api`

1694 

1695Type / Values

1696 

1697`responses`

1698 

1699Details

1700 

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

1702 

1703Key

1704 

1705`model_reasoning_effort`

1706 

1707Type / Values

1708 

1709`minimal | low | medium | high | xhigh`

1710 

1711Details

1712 

1713Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).

1714 

1715Key

1716 

1717`model_reasoning_summary`

1718 

1719Type / Values

1720 

1721`auto | concise | detailed | none`

1722 

1723Details