config-reference.md Codex Docs, 2026-02-24 00:33 UTC → 2026-04-16 00:46 UTC

6 6 

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

8 8 

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

10 10 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

27| `approvals_reviewer` | `user | guardian_subagent` | Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

44| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |50| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |

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

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

47| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |53| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |

48| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |

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

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

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

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

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

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

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

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

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

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

59| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |59| `features.smart_approvals` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). |

60| `features.undo` | `boolean` | Enable undo support (stable; off by default). |

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

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

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

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

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

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

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

70| `include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |

71| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |72| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |

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

73| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |74| `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. |

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

85| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |86| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |

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

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

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

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

88| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |91| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |

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

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

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

92| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |95| `model` | `string` | Model to use (e.g., `gpt-5.4`). |

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

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

95| `model_context_window` | `number` | Context window tokens available to the active model. |98| `model_context_window` | `number` | Context window tokens available to the active model. |

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

97| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |100| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

113| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |124| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |

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

115| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |126| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |

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

117| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |128| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |

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

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

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

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

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

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

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

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

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

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

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

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

133| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |146| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |

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

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

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

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

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

153| `permissions.<name>.filesystem.":project_roots".<subpath>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself. |

154| `permissions.<name>.filesystem.<path>` | `"read" | "write" | "none" | table` | Grant direct access for a path or special token, or scope nested entries under that root. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

150| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |183| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |

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

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

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

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

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

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

160| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |194| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |

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

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

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

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

203| `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. |204| `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. |205| `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. |206| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

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

208| `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. |209| `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). |210| `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). |211| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

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

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

176| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |214| `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). |215| `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. |216| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

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

218| `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. |219| `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). |220| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

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

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

181 223 

182Key224Key

183 225 

205 247 

206Key248Key

207 249 

250`agents.<name>.nickname_candidates`

251 

252Type / Values

253 

254`array<string>`

255 

256Details

257 

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

259 

260Key

261 

262`agents.job_max_runtime_seconds`

263 

264Type / Values

265 

266`number`

267 

268Details

269 

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

271 

272Key

273 

208`agents.max_depth`274`agents.max_depth`

209 275 

210Type / Values276Type / Values

225 291 

226Details292Details

227 293 

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

229 295 

230Key296Key

231 297 

241 307 

242Key308Key

243 309 

310`analytics.enabled`

311 

312Type / Values

313 

314`boolean`

315 

316Details

317 

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

319 

320Key

321 

244`approval_policy`322`approval_policy`

245 323 

246Type / Values324Type / Values

247 325 

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

327 

328Details

329 

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

331 

332Key

333 

334`approval_policy.granular.mcp_elicitations`

335 

336Type / Values

337 

338`boolean`

339 

340Details

341 

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

343 

344Key

345 

346`approval_policy.granular.request_permissions`

347 

348Type / Values

349 

350`boolean`

249 351 

250Details352Details

251 353 

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

253 355 

254Key356Key

255 357 

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

257 359 

258Type / Values360Type / Values

259 361 

261 363 

262Details364Details

263 365 

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

265 367 

266Key368Key

267 369 

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

269 371 

270Type / Values372Type / Values

271 373 

273 375 

274Details376Details

275 377 

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

277 379 

278Key380Key

279 381 

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

281 383 

282Type / Values384Type / Values

283 385 

285 387 

286Details388Details

287 389 

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

391 

392Key

393 

394`approvals_reviewer`

395 

396Type / Values

397 

398`user | guardian_subagent`

399 

400Details

401 

402Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent.

289 403 

290Key404Key

291 405 

457 571 

458Key572Key

459 573 

460`compact_prompt`574`commit_attribution`

461 575 

462Type / Values576Type / Values

463 577 

465 579 

466Details580Details

467 581 

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

469 583 

470Key584Key

471 585 

472`developer_instructions`586`compact_prompt`

473 587 

474Type / Values588Type / Values

475 589 

477 591 

478Details592Details

479 593 

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

481 595 

482Key596Key

483 597 

484`disable_paste_burst`598`default_permissions`

485 599 

486Type / Values600Type / Values

487 601 

488`boolean`602`string`

489 603 

490Details604Details

491 605 

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

493 607 

494Key608Key

495 609 

496`experimental_compact_prompt_file`610`developer_instructions`

497 611 

498Type / Values612Type / Values

499 613 

500`string (path)`614`string`

501 615 

502Details616Details

503 617 

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

505 619 

506Key620Key

507 621 

508`experimental_use_freeform_apply_patch`622`disable_paste_burst`

509 623 

510Type / Values624Type / Values

511 625 

513 627 

514Details628Details

515 629 

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

517 631 

518Key632Key

519 633 

520`experimental_use_unified_exec_tool`634`experimental_compact_prompt_file`

521 635 

522Type / Values636Type / Values

523 637 

524`boolean`638`string (path)`

525 639 

526Details640Details

527 641 

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

529 643 

530Key644Key

531 645 

532`features.apply_patch_freeform`646`experimental_use_unified_exec_tool`

533 647 

534Type / Values648Type / Values

535 649 

537 651 

538Details652Details

539 653 

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

541 655 

542Key656Key

543 657 

553 667 

554Key668Key

555 669 

556`features.apps_mcp_gateway`670`features.codex_hooks`

557 

558Type / Values

559 

560`boolean`

561 

562Details

563 

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

565 

566Key

567 

568`features.child_agents_md`

569 

570Type / Values

571 

572`boolean`

573 

574Details

575 

576Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).

577 

578Key

579 

580`features.collaboration_modes`

581 671 

582Type / Values672Type / Values

583 673 

585 675 

586Details676Details

587 677 

588Enable collaboration modes such as plan mode (stable; on by default).678Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).

589 679 

590Key680Key

591 681 

592`features.elevated_windows_sandbox`682`features.enable_request_compression`

593 683 

594Type / Values684Type / Values

595 685 

597 687 

598Details688Details

599 689 

600Enable the elevated Windows sandbox pipeline (experimental).690Compress streaming request bodies with zstd when supported (stable; on by default).

601 691 

602Key692Key

603 693 

604`features.experimental_windows_sandbox`694`features.fast_mode`

605 695 

606Type / Values696Type / Values

607 697 

609 699 

610Details700Details

611 701 

612Run the Windows restricted-token sandbox (experimental).702Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

613 703 

614Key704Key

615 705 

621 711 

622Details712Details

623 713 

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

625 715 

626Key716Key

627 717 

637 727 

638Key728Key

639 729 

640`features.powershell_utf8`730`features.prevent_idle_sleep`

641 

642Type / Values

643 

644`boolean`

645 

646Details

647 

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

649 

650Key

651 

652`features.remote_models`

653 731 

654Type / Values732Type / Values

655 733 

657 735 

658Details736Details

659 737 

660Refresh remote model list before showing readiness (experimental).738Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

661 739 

662Key740Key

663 741 

664`features.request_rule`742`features.shell_snapshot`

665 743 

666Type / Values744Type / Values

667 745 

669 747 

670Details748Details

671 749 

672Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).750Snapshot shell environment to speed up repeated commands (stable; on by default).

673 751 

674Key752Key

675 753 

676`features.runtime_metrics`754`features.shell_tool`

677 755 

678Type / Values756Type / Values

679 757 

681 759 

682Details760Details

683 761 

684Show runtime metrics summary in TUI turn separators (experimental).762Enable the default `shell` tool for running commands (stable; on by default).

685 763 

686Key764Key

687 765 

688`features.search_tool`766`features.skill_mcp_dependency_install`

689 767 

690Type / Values768Type / Values

691 769 

693 771 

694Details772Details

695 773 

696Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).774Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

697 775 

698Key776Key

699 777 

700`features.shell_snapshot`778`features.smart_approvals`

701 779 

702Type / Values780Type / Values

703 781 

705 783 

706Details784Details

707 785 

708Snapshot shell environment to speed up repeated commands (beta).786Route eligible approval requests through the guardian reviewer subagent (experimental; off by default).

709 787 

710Key788Key

711 789 

712`features.shell_tool`790`features.undo`

713 791 

714Type / Values792Type / Values

715 793 

717 795 

718Details796Details

719 797 

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

721 799 

722Key800Key

723 801 

729 807 

730Details808Details

731 809 

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

733 

734Key

735 

736`features.use_linux_sandbox_bwrap`

737 

738Type / Values

739 

740`boolean`

741 

742Details

743 

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

745 811 

746Key812Key

747 813 

865 931 

866Key932Key

867 933 

868`include_apply_patch_tool`

869 

870Type / Values

871 

872`boolean`

873 

874Details

875 

876Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.

877 

878Key

879 

880`instructions`934`instructions`

881 935 

882Type / Values936Type / Values

1069 1123 

1070Key1124Key

1071 1125 

1126`mcp_servers.<id>.oauth_resource`

1127 

1128Type / Values

1129 

1130`string`

1131 

1132Details

1133 

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

1135 

1136Key

1137 

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

1073 1139 

1074Type / Values1140Type / Values

1081 1147 

1082Key1148Key

1083 1149 

1150`mcp_servers.<id>.scopes`

1151 

1152Type / Values

1153 

1154`array<string>`

1155 

1156Details

1157 

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

1159 

1160Key

1161 

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

1085 1163 

1086Type / Values1164Type / Values

1137 1215 

1138Details1216Details

1139 1217 

1140Model to use (e.g., `gpt-5-codex`).1218Model to use (e.g., `gpt-5.4`).

1141 1219 

1142Key1220Key

1143 1221 

1201 1279 

1202Key1280Key

1203 1281 

1282`model_providers.<id>`

1283 

1284Type / Values

1285 

1286`table`

1287 

1288Details

1289 

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

1291 

1292Key

1293 

1294`model_providers.<id>.auth`

1295 

1296Type / Values

1297 

1298`table`

1299 

1300Details

1301 

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

1303 

1304Key

1305 

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

1307 

1308Type / Values

1309 

1310`array<string>`

1311 

1312Details

1313 

1314Arguments passed to the token command.

1315 

1316Key

1317 

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

1319 

1320Type / Values

1321 

1322`string`

1323 

1324Details

1325 

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

1327 

1328Key

1329 

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

1331 

1332Type / Values

1333 

1334`string (path)`

1335 

1336Details

1337 

1338Working directory for the token command.

1339 

1340Key

1341 

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

1343 

1344Type / Values

1345 

1346`number`

1347 

1348Details

1349 

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

1351 

1352Key

1353 

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

1355 

1356Type / Values

1357 

1358`number`

1359 

1360Details

1361 

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

1363 

1364Key

1365 

1204`model_providers.<id>.base_url`1366`model_providers.<id>.base_url`

1205 1367 

1206Type / Values1368Type / Values

1345 1507 

1346Key1508Key

1347 1509 

1510`model_providers.<id>.supports_websockets`

1511 

1512Type / Values

1513 

1514`boolean`

1515 

1516Details

1517 

1518Whether that provider supports the Responses API WebSocket transport.

1519 

1520Key

1521 

1348`model_providers.<id>.wire_api`1522`model_providers.<id>.wire_api`

1349 1523 

1350Type / Values1524Type / Values

1351 1525 

1352`chat | responses`1526`responses`

1353 1527 

1354Details1528Details

1355 1529 

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

1357 1531 

1358Key1532Key

1359 1533 

1401 1575 

1402Details1576Details

1403 1577 

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

1405 1579 

1406Key1580Key

1407 1581 

1489 1663 

1490Key1664Key

1491 1665 

1666`openai_base_url`

1667 

1668Type / Values

1669 

1670`string`

1671 

1672Details

1673 

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

1675 

1676Key

1677 

1492`oss_provider`1678`oss_provider`

1493 1679 

1494Type / Values1680Type / Values

1609 1795 

1610Key1796Key

1611 1797 

1612`otel.trace_exporter`1798`otel.metrics_exporter`

1613 1799 

1614Type / Values1800Type / Values

1615 1801 

1616`none | otlp-http | otlp-grpc`1802`none | statsig | otlp-http | otlp-grpc`

1617 1803 

1618Details1804Details

1619 1805 

1620Select the OpenTelemetry trace exporter and provide any endpoint metadata.1806Select the OpenTelemetry metrics exporter (defaults to `statsig`).

1621 1807 

1622Key1808Key

1623 1809 

1624`otel.trace_exporter.<id>.endpoint`1810`otel.trace_exporter`

1811 

1812Type / Values

1813 

1814`none | otlp-http | otlp-grpc`

1815 

1816Details

1817 

1818Select the OpenTelemetry trace exporter and provide any endpoint metadata.

1819 

1820Key

1821 

1822`otel.trace_exporter.<id>.endpoint`

1625 1823 

1626Type / Values1824Type / Values

1627 1825 

1693 1891 

1694Key1892Key

1695 1893 

1894`permissions.<name>.filesystem`

1895 

1896Type / Values

1897 

1898`table`

1899 

1900Details

1901 

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

1903 

1904Key

1905 

1906`permissions.<name>.filesystem.":project_roots".<subpath>`

1907 

1908Type / Values

1909 

1910`"read" | "write" | "none"`

1911 

1912Details

1913 

1914Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself.

1915 

1916Key

1917 

1918`permissions.<name>.filesystem.<path>`

1919 

1920Type / Values

1921 

1922`"read" | "write" | "none" | table`

1923 

1924Details

1925 

1926Grant direct access for a path or special token, or scope nested entries under that root.

1927 

1928Key

1929 

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

1931 

1932Type / Values

1933 

1934`boolean`

1935 

1936Details

1937 

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

1939 

1940Key

1941 

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

1943 

1944Type / Values

1945 

1946`boolean`

1947 

1948Details

1949 

1950Allow the managed proxy to chain to another upstream proxy.

1951 

1952Key

1953 

1954`permissions.<name>.network.dangerously_allow_all_unix_sockets`

1955 

1956Type / Values

1957 

1958`boolean`

1959 

1960Details

1961 

1962Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.

1963 

1964Key

1965 

1966`permissions.<name>.network.dangerously_allow_non_loopback_proxy`

1967 

1968Type / Values

1969 

1970`boolean`

1971 

1972Details

1973 

1974Permit non-loopback bind addresses for the managed proxy listener.

1975 

1976Key

1977 

1978`permissions.<name>.network.domains`

1979 

1980Type / Values

1981 

1982`map<string, allow | deny>`

1983 

1984Details

1985 

1986Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values.

1987 

1988Key

1989 

1990`permissions.<name>.network.enable_socks5`

1991 

1992Type / Values

1993 

1994`boolean`

1995 

1996Details

1997 

1998Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.

1999 

2000Key

2001 

2002`permissions.<name>.network.enable_socks5_udp`

2003 

2004Type / Values

2005 

2006`boolean`

2007 

2008Details

2009 

2010Allow UDP over the SOCKS5 listener when enabled.

2011 

2012Key

2013 

2014`permissions.<name>.network.enabled`

2015 

2016Type / Values

2017 

2018`boolean`

2019 

2020Details

2021 

2022Enable network access for this named permissions profile.

2023 

2024Key

2025 

2026`permissions.<name>.network.mode`

2027 

2028Type / Values

2029 

2030`limited | full`

2031 

2032Details

2033 

2034Network proxy mode used for subprocess traffic.

2035 

2036Key

2037 

2038`permissions.<name>.network.proxy_url`

2039 

2040Type / Values

2041 

2042`string`

2043 

2044Details

2045 

2046HTTP proxy endpoint used when this permissions profile enables the managed network proxy.

2047 

2048Key

2049 

2050`permissions.<name>.network.socks_url`

2051 

2052Type / Values

2053 

2054`string`

2055 

2056Details

2057 

2058SOCKS5 proxy endpoint used by this permissions profile.

2059 

2060Key

2061 

2062`permissions.<name>.network.unix_sockets`

2063 

2064Type / Values

2065 

2066`map<string, allow | none>`

2067 

2068Details

2069 

2070Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values.

2071 

2072Key

2073 

1696`personality`2074`personality`

1697 2075 

1698Type / Values2076Type / Values

1705 2083 

1706Key2084Key

1707 2085 

2086`plan_mode_reasoning_effort`

2087 

2088Type / Values

2089 

2090`none | minimal | low | medium | high | xhigh`

2091 

2092Details

2093 

2094Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default.

2095 

2096Key

2097 

1708`profile`2098`profile`

1709 2099 

1710Type / Values2100Type / Values

1729 2119 

1730Key2120Key

1731 2121 

1732`profiles.<name>.experimental_use_freeform_apply_patch`2122`profiles.<name>.analytics.enabled`

1733 2123 

1734Type / Values2124Type / Values

1735 2125 

1737 2127 

1738Details2128Details

1739 2129 

1740Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.2130Profile-scoped analytics enablement override.

1741 2131 

1742Key2132Key

1743 2133 

1753 2143 

1754Key2144Key

1755 2145 

1756`profiles.<name>.include_apply_patch_tool`2146`profiles.<name>.model_catalog_json`

1757 2147 

1758Type / Values2148Type / Values

1759 2149 

1760`boolean`2150`string (path)`

1761 2151 

1762Details2152Details

1763 2153 

1764Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.2154Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).

1765 2155 

1766Key2156Key

1767 2157 

1768`profiles.<name>.model_catalog_json`2158`profiles.<name>.model_instructions_file`

1769 2159 

1770Type / Values2160Type / Values

1771 2161 

1773 2163 

1774Details2164Details

1775 2165 

1776Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).2166Profile-scoped replacement for the built-in instruction file.

1777 2167 

1778Key2168Key

1779 2169 

1801 2191 

1802Key2192Key

1803 2193 

2194`profiles.<name>.plan_mode_reasoning_effort`

2195 

2196Type / Values

2197 

2198`none | minimal | low | medium | high | xhigh`

2199 

2200Details

2201 

2202Profile-scoped Plan-mode reasoning override.

2203 

2204Key

2205 

2206`profiles.<name>.service_tier`

2207 

2208Type / Values

2209 

2210`flex | fast`

2211 

2212Details

2213 

2214Profile-scoped service tier preference for new turns.

2215 

2216Key

2217 

2218`profiles.<name>.tools_view_image`

2219 

2220Type / Values

2221 

2222`boolean`

2223 

2224Details

2225 

2226Enable or disable the `view_image` tool in that profile.

2227 

2228Key

2229 

1804`profiles.<name>.web_search`2230`profiles.<name>.web_search`

1805 2231 

1806Type / Values2232Type / Values

1813 2239 

1814Key2240Key

1815 2241 

2242`profiles.<name>.windows.sandbox`

2243 

2244Type / Values

2245 

2246`unelevated | elevated`

2247 

2248Details

2249 

2250Profile-scoped Windows sandbox mode override.

2251 

2252Key

2253 

1816`project_doc_fallback_filenames`2254`project_doc_fallback_filenames`

1817 2255 

1818Type / Values2256Type / Values

1933 2371 

1934Key2372Key

1935 2373 

2374`service_tier`

2375 

2376Type / Values

2377 

2378`flex | fast`

2379 

2380Details

2381 

2382Preferred service tier for new turns.

2383 

2384Key

2385 

1936`shell_environment_policy.exclude`2386`shell_environment_policy.exclude`

1937 2387 

1938Type / Values2388Type / Values

2053 2503 

2054Key2504Key

2055 2505 

2506`sqlite_home`

2507 

2508Type / Values

2509 

2510`string (path)`

2511 

2512Details

2513 

2514Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.

2515 

2516Key

2517 

2056`suppress_unstable_features_warning`2518`suppress_unstable_features_warning`

2057 2519 

2058Type / Values2520Type / Values

2077 2539 

2078Key2540Key

2079 2541 

2080`tools.web_search`2542`tool_suggest.discoverables`

2543 

2544Type / Values

2545 

2546`array<table>`

2547 

2548Details

2549 

2550Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.

2551 

2552Key

2553 

2554`tools.view_image`

2081 2555 

2082Type / Values2556Type / Values

2083 2557 

2085 2559 

2086Details2560Details

2087 2561 

2088Deprecated legacy toggle for web search; prefer the top-level `web_search` setting.2562Enable the local-image attachment tool `view_image`.

2563 

2564Key

2565 

2566`tools.web_search`

2567 

2568Type / Values

2569 

2570`boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }`

2571 

2572Details

2573 

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

2089 2575 

2090Key2576Key

2091 2577 

2125 2611 

2126Key2612Key

2127 2613 

2614`tui.model_availability_nux.<model>`

2615 

2616Type / Values

2617 

2618`integer`

2619 

2620Details

2621 

2622Internal startup-tooltip state keyed by model slug.

2623 

2624Key

2625 

2128`tui.notification_method`2626`tui.notification_method`

2129 2627 

2130Type / Values2628Type / Values

2173 2671 

2174Key2672Key

2175 2673 

2674`tui.terminal_title`

2675 

2676Type / Values

2677 

2678`array<string> | null`

2679 

2680Details

2681 

2682Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates.

2683 

2684Key

2685 

2686`tui.theme`

2687 

2688Type / Values

2689 

2690`string`

2691 

2692Details

2693 

2694Syntax-highlighting theme override (kebab-case theme name).

2695 

2696Key

2697 

2176`web_search`2698`web_search`

2177 2699 

2178Type / Values2700Type / Values

2195 2717 

2196Track Windows onboarding acknowledgement (Windows only).2718Track Windows onboarding acknowledgement (Windows only).

2197 2719 

2720Key

2721 

2722`windows.sandbox`

2723 

2724Type / Values

2725 

2726`unelevated | elevated`

2727 

2728Details

2729 

2730Windows-only native sandbox mode when running Codex natively on Windows.

2731 

2732Key

2733 

2734`windows.sandbox_private_desktop`

2735 

2736Type / Values

2737 

2738`boolean`

2739 

2740Details

2741 

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

2743 

2198Expand to view all2744Expand to view all

2199 2745 

2200You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).2746You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).

2214For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched2760For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched

2215requirements. See the security page for precedence details.2761requirements. See the security page for precedence details.

2216 2762 

2763Use `[features]` in `requirements.toml` to pin feature flags by the same

2764canonical keys that `config.toml` uses. Omitted keys remain unconstrained.

2765 

2217| Key | Type / Values | Details |2766| Key | Type / Values | Details |

2218| --- | --- | --- |2767| --- | --- | --- |

2219| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`). |2768| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). |

2769| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer` (for example `user` and `guardian_subagent`). |

2220| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2770| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |

2221| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |2771| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |

2772| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |

2773| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |

2222| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |2774| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |

2223| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |2775| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |

2224| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |2776| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |

2241 2793 

2242Details2794Details

2243 2795 

2244Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`).2796Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`).

2797 

2798Key

2799 

2800`allowed_approvals_reviewers`

2801 

2802Type / Values

2803 

2804`array<string>`

2805 

2806Details

2807 

2808Allowed values for `approvals_reviewer` (for example `user` and `guardian_subagent`).

2245 2809 

2246Key2810Key

2247 2811 

2269 2833 

2270Key2834Key

2271 2835 

2836`features`

2837 

2838Type / Values

2839 

2840`table`

2841 

2842Details

2843 

2844Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.

2845 

2846Key

2847 

2848`features.<name>`

2849 

2850Type / Values

2851 

2852`boolean`

2853 

2854Details

2855 

2856Require a specific canonical feature key to stay enabled or disabled.

2857 

2858Key

2859 

2272`mcp_servers`2860`mcp_servers`

2273 2861 

2274Type / Values2862Type / Values