config-reference.md Codex Docs, 2026-02-19 20:53 UTC → 2026-05-02 06:45 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/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 

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

10| --- | --- | --- |12| --- | --- | --- |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

162 244 

163Key245Key

164 246 

186 268 

187Key269Key

188 270 

271`agents.<name>.nickname_candidates`

272 

273Type / Values

274 

275`array<string>`

276 

277Details

278 

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

280 

281Key

282 

283`agents.job_max_runtime_seconds`

284 

285Type / Values

286 

287`number`

288 

289Details

290 

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

292 

293Key

294 

295`agents.max_depth`

296 

297Type / Values

298 

299`number`

300 

301Details

302 

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

304 

305Key

306 

189`agents.max_threads`307`agents.max_threads`

190 308 

191Type / Values309Type / Values

194 312 

195Details313Details

196 314 

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

316 

317Key

318 

319`allow_login_shell`

320 

321Type / Values

322 

323`boolean`

324 

325Details

326 

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

328 

329Key

330 

331`analytics.enabled`

332 

333Type / Values

334 

335`boolean`

336 

337Details

338 

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

198 340 

199Key341Key

200 342 

202 344 

203Type / Values345Type / Values

204 346 

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

206 348 

207Details349Details

208 350 

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

210 352 

211Key353Key

212 354 

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

214 356 

215Type / Values357Type / Values

216 358 

217`unknown | user`359`boolean`

218 360 

219Details361Details

220 362 

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

222 364 

223Key365Key

224 366 

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

226 368 

227Type / Values369Type / Values

228 370 

230 372 

231Details373Details

232 374 

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

234 376 

235Key377Key

236 378 

237`chatgpt_base_url`379`approval_policy.granular.rules`

238 380 

239Type / Values381Type / Values

240 382 

241`string`383`boolean`

242 384 

243Details385Details

244 386 

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

246 388 

247Key389Key

248 390 

249`check_for_update_on_startup`391`approval_policy.granular.sandbox_approval`

250 392 

251Type / Values393Type / Values

252 394 

254 396 

255Details397Details

256 398 

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

258 400 

259Key401Key

260 402 

261`cli_auth_credentials_store`403`approval_policy.granular.skill_approval`

262 404 

263Type / Values405Type / Values

264 406 

265`file | keyring | auto`407`boolean`

266 408 

267Details409Details

268 410 

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

270 412 

271Key413Key

272 414 

273`compact_prompt`415`approvals_reviewer`

274 416 

275Type / Values417Type / Values

276 418 

277`string`419`user | auto_review`

278 420 

279Details421Details

280 422 

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

282 424 

283Key425Key

284 426 

285`developer_instructions`427`apps._default.destructive_enabled`

286 428 

287Type / Values429Type / Values

288 430 

289`string`431`boolean`

290 432 

291Details433Details

292 434 

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

294 436 

295Key437Key

296 438 

297`disable_paste_burst`439`apps._default.enabled`

298 440 

299Type / Values441Type / Values

300 442 

302 444 

303Details445Details

304 446 

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

306 448 

307Key449Key

308 450 

309`experimental_compact_prompt_file`451`apps._default.open_world_enabled`

310 452 

311Type / Values453Type / Values

312 454 

313`string (path)`455`boolean`

314 456 

315Details457Details

316 458 

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

460 

461Key

462 

463`apps.<id>.default_tools_approval_mode`

464 

465Type / Values

466 

467`auto | prompt | approve`

468 

469Details

470 

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

318 472 

319Key473Key

320 474 

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

322 476 

323Type / Values477Type / Values

324 478 

326 480 

327Details481Details

328 482 

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

330 484 

331Key485Key

332 486 

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

334 488 

335Type / Values489Type / Values

336 490 

338 492 

339Details493Details

340 494 

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

342 496 

343Key497Key

344 498 

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

346 500 

347Type / Values501Type / Values

348 502 

350 504 

351Details505Details

352 506 

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

354 508 

355Key509Key

356 510 

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

358 512 

359Type / Values513Type / Values

360 514 

362 516 

363Details517Details

364 518 

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

520 

521Key

522 

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

524 

525Type / Values

526 

527`auto | prompt | approve`

528 

529Details

530 

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

366 532 

367Key533Key

368 534 

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

370 536 

371Type / Values537Type / Values

372 538 

374 540 

375Details541Details

376 542 

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

544 

545Key

546 

547`auto_review.policy`

548 

549Type / Values

550 

551`string`

552 

553Details

554 

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

556 

557Key

558 

559`background_terminal_max_timeout`

560 

561Type / Values

562 

563`number`

564 

565Details

566 

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

568 

569Key

570 

571`chatgpt_base_url`

572 

573Type / Values

574 

575`string`

576 

577Details

578 

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

378 580 

379Key581Key

380 582 

381`features.child_agents_md`583`check_for_update_on_startup`

382 584 

383Type / Values585Type / Values

384 586 

386 588 

387Details589Details

388 590 

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

592 

593Key

594 

595`cli_auth_credentials_store`

596 

597Type / Values

598 

599`file | keyring | auto`

600 

601Details

602 

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

604 

605Key

606 

607`commit_attribution`

608 

609Type / Values

610 

611`string`

612 

613Details

614 

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

616 

617Key

618 

619`compact_prompt`

620 

621Type / Values

622 

623`string`

624 

625Details

626 

627Inline override for the history compaction prompt.

628 

629Key

630 

631`default_permissions`

632 

633Type / Values

634 

635`string`

636 

637Details

638 

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

640 

641Key

642 

643`developer_instructions`

644 

645Type / Values

646 

647`string`

648 

649Details

650 

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

390 652 

391Key653Key

392 654 

393`features.collaboration_modes`655`disable_paste_burst`

394 656 

395Type / Values657Type / Values

396 658 

398 660 

399Details661Details

400 662 

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

664 

665Key

666 

667`experimental_compact_prompt_file`

668 

669Type / Values

670 

671`string (path)`

672 

673Details

674 

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

402 676 

403Key677Key

404 678 

405`features.elevated_windows_sandbox`679`experimental_use_unified_exec_tool`

406 680 

407Type / Values681Type / Values

408 682 

410 684 

411Details685Details

412 686 

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

414 688 

415Key689Key

416 690 

417`features.experimental_windows_sandbox`691`features.apps`

418 692 

419Type / Values693Type / Values

420 694 

422 696 

423Details697Details

424 698 

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

426 700 

427Key701Key

428 702 

429`features.multi_agent`703`features.codex_hooks`

430 704 

431Type / Values705Type / Values

432 706 

434 708 

435Details709Details

436 710 

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

438 712 

439Key713Key

440 714 

441`features.personality`715`features.enable_request_compression`

442 716 

443Type / Values717Type / Values

444 718 

446 720 

447Details721Details

448 722 

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

450 724 

451Key725Key

452 726 

453`features.powershell_utf8`727`features.fast_mode`

454 728 

455Type / Values729Type / Values

456 730 

458 732 

459Details733Details

460 734 

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

462 736 

463Key737Key

464 738 

465`features.remote_models`739`features.memories`

466 740 

467Type / Values741Type / Values

468 742 

470 744 

471Details745Details

472 746 

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

474 748 

475Key749Key

476 750 

477`features.request_rule`751`features.multi_agent`

478 752 

479Type / Values753Type / Values

480 754 

482 756 

483Details757Details

484 758 

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

486 760 

487Key761Key

488 762 

489`features.runtime_metrics`763`features.personality`

490 764 

491Type / Values765Type / Values

492 766 

494 768 

495Details769Details

496 770 

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

498 772 

499Key773Key

500 774 

501`features.search_tool`775`features.prevent_idle_sleep`

502 776 

503Type / Values777Type / Values

504 778 

506 780 

507Details781Details

508 782 

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

510 784 

511Key785Key

512 786 

518 792 

519Details793Details

520 794 

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

522 796 

523Key797Key

524 798 

534 808 

535Key809Key

536 810 

537`features.unified_exec`811`features.skill_mcp_dependency_install`

812 

813Type / Values

814 

815`boolean`

816 

817Details

818 

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

820 

821Key

822 

823`features.undo`

538 824 

539Type / Values825Type / Values

540 826 

542 828 

543Details829Details

544 830 

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

546 832 

547Key833Key

548 834 

549`features.use_linux_sandbox_bwrap`835`features.unified_exec`

550 836 

551Type / Values837Type / Values

552 838 

554 840 

555Details841Details

556 842 

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

558 844 

559Key845Key

560 846 

678 964 

679Key965Key

680 966 

681`include_apply_patch_tool`967`hooks`

682 968 

683Type / Values969Type / Values

684 970 

685`boolean`971`table`

686 972 

687Details973Details

688 974 

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

690 976 

691Key977Key

692 978 

726 1012 

727Key1013Key

728 1014 

1015`mcp_oauth_callback_url`

1016 

1017Type / Values

1018 

1019`string`

1020 

1021Details

1022 

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

1024 

1025Key

1026 

729`mcp_oauth_credentials_store`1027`mcp_oauth_credentials_store`

730 1028 

731Type / Values1029Type / Values

850 1148 

851Type / Values1149Type / Values

852 1150 

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

854 1152 

855Details1153Details

856 1154 

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

858 1156 

859Key1157Key

860 1158 

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

862 1160 

863Type / Values1161Type / Values

864 1162 

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

866 1164 

867Details1165Details

868 1166 

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

870 1168 

871Key1169Key

872 1170 

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

874 1172 

875Type / Values1173Type / Values

876 1174 

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

878 1176 

879Details1177Details

880 1178 

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

882 1180 

883Key1181Key

884 1182 

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

886 1184 

887Type / Values1185Type / Values

888 1186 

889`number`1187`string`

890 1188 

891Details1189Details

892 1190 

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

894 1192 

895Key1193Key

896 1194 

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

898 1196 

899Type / Values1197Type / Values

900 1198 

901`number`1199`boolean`

902 

903Details

904 

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

906 

907Key

908 

909`mcp_servers.<id>.tool_timeout_sec`

910 

911Type / Values

912 

913`number`

914 1200 

915Details1201Details

916 1202 

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

918 1204 

919Key1205Key

920 1206 

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

922 1208 

923Type / Values1209Type / Values

924 1210 

925`string`1211`array<string>`

926 1212 

927Details1213Details

928 1214 

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

930 1216 

931Key1217Key

932 1218 

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

934 1220 

935Type / Values1221Type / Values

936 1222 

937`string`1223`number`

938 1224 

939Details1225Details

940 1226 

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

942 1228 

943Key1229Key

944 1230 

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

946 1232 

947Type / Values1233Type / Values

948 1234 

950 1236 

951Details1237Details

952 1238 

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

954 1240 

955Key1241Key

956 1242 

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

958 1244 

959Type / Values1245Type / Values

960 1246 

962 1248 

963Details1249Details

964 1250 

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

966 1252 

967Key1253Key

968 1254 

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

970 1256 

971Type / Values1257Type / Values

972 1258 

973`string (path)`1259`string`

974 1260 

975Details1261Details

976 1262 

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

978 1264 

979Key1265Key

980 1266 

981`model_provider`1267`memories.consolidation_model`

982 1268 

983Type / Values1269Type / Values

984 1270 

986 1272 

987Details1273Details

988 1274 

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

990 1276 

991Key1277Key

992 1278 

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

994 1280 

995Type / Values1281Type / Values

996 1282 

997`string`1283`boolean`

998 1284 

999Details1285Details

1000 1286 

1001API base URL for the model provider.1287When `true`, threads that use external context such as MCP tool calls, web search, or tool search are kept out of memory generation. Defaults to `false`. Legacy alias: `memories.no_memories_if_mcp_or_web_search`.

1002 1288 

1003Key1289Key

1004 1290 

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

1006 1292 

1007Type / Values1293Type / Values

1008 1294 

1009`map<string,string>`1295`string`

1010 1296 

1011Details1297Details

1012 1298 

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

1014 1300 

1015Key1301Key

1016 1302 

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

1018 1304 

1019Type / Values1305Type / Values

1020 1306 

1021`string`1307`boolean`

1022 1308 

1023Details1309Details

1024 1310 

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

1026 1312 

1027Key1313Key

1028 1314 

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

1030 1316 

1031Type / Values1317Type / Values

1032 1318 

1033`string`1319`number`

1034 1320 

1035Details1321Details

1036 1322 

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

1038 1324 

1039Key1325Key

1040 1326 

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

1042 1328 

1043Type / Values1329Type / Values

1044 1330 

1045`string`1331`number`

1046 1332 

1047Details1333Details

1048 1334 

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

1050 1336 

1051Key1337Key

1052 1338 

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

1054 1340 

1055Type / Values1341Type / Values

1056 1342 

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

1058 1344 

1059Details1345Details

1060 1346 

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

1062 1348 

1063Key1349Key

1064 1350 

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

1066 1352 

1067Type / Values1353Type / Values

1068 1354 

1069`string`1355`number`

1070 1356 

1071Details1357Details

1072 1358 

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

1074 1360 

1075Key1361Key

1076 1362 

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

1078 1364 

1079Type / Values1365Type / Values

1080 1366 

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

1082 1368 

1083Details1369Details

1084 1370 

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

1086 1372 

1087Key1373Key

1088 1374 

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

1090 1376 

1091Type / Values1377Type / Values

1092 1378 

1094 1380 

1095Details1381Details

1096 1382 

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

1098 1384 

1099Key1385Key

1100 1386 

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

1102 1388 

1103Type / Values1389Type / Values

1104 1390 

1106 1392 

1107Details1393Details

1108 1394 

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

1110 1396 

1111Key1397Key

1112 1398 

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

1114 1400 

1115Type / Values1401Type / Values

1116 1402 

1117`number`1403`string`

1118 1404 

1119Details1405Details

1120 1406 

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

1122 1408 

1123Key1409Key

1124 1410 

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

1126 1412 

1127Type / Values1413Type / Values

1128 1414 

1130 1416 

1131Details1417Details

1132 1418 

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

1134 1420 

1135Key1421Key

1136 1422 

1137`model_providers.<id>.wire_api`1423`model_catalog_json`

1138 1424 

1139Type / Values1425Type / Values