config-reference.md Codex Docs, 2026-02-27 18:15 UTC → 2026-04-14 18:31 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.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |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.personality` | `boolean` | Enable personality selection controls (stable; on by default). |54| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

170| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |209| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

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

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

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

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

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

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

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

178| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |220| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

179| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |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. |

180 223 

181Key224Key

182 225 

204 247 

205Key248Key

206 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 

207`agents.max_depth`274`agents.max_depth`

208 275 

209Type / Values276Type / Values

224 291 

225Details292Details

226 293 

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

228 295 

229Key296Key

230 297 

240 307 

241Key308Key

242 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 

243`approval_policy`322`approval_policy`

244 323 

245Type / Values324Type / Values

246 325 

247`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`

248 351 

249Details352Details

250 353 

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

252 355 

253Key356Key

254 357 

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

256 359 

257Type / Values360Type / Values

258 361 

260 363 

261Details364Details

262 365 

263When `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.

264 367 

265Key368Key

266 369 

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

268 371 

269Type / Values372Type / Values

270 373 

272 375 

273Details376Details

274 377 

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

276 379 

277Key380Key

278 381 

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

280 383 

281Type / Values384Type / Values

282 385 

284 387 

285Details388Details

286 389 

287When `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.

288 403 

289Key404Key

290 405 

456 571 

457Key572Key

458 573 

459`compact_prompt`574`commit_attribution`

460 575 

461Type / Values576Type / Values

462 577 

464 579 

465Details580Details

466 581 

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

468 583 

469Key584Key

470 585 

471`developer_instructions`586`compact_prompt`

472 587 

473Type / Values588Type / Values

474 589 

476 591 

477Details592Details

478 593 

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

480 595 

481Key596Key

482 597 

483`disable_paste_burst`598`default_permissions`

484 599 

485Type / Values600Type / Values

486 601 

487`boolean`602`string`

488 603 

489Details604Details

490 605 

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

492 607 

493Key608Key

494 609 

495`experimental_compact_prompt_file`610`developer_instructions`

496 611 

497Type / Values612Type / Values

498 613 

499`string (path)`614`string`

500 615 

501Details616Details

502 617 

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

504 619 

505Key620Key

506 621 

507`experimental_use_freeform_apply_patch`622`disable_paste_burst`

508 623 

509Type / Values624Type / Values

510 625 

512 627 

513Details628Details

514 629 

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

516 631 

517Key632Key

518 633 

519`experimental_use_unified_exec_tool`634`experimental_compact_prompt_file`

520 635 

521Type / Values636Type / Values

522 637 

523`boolean`638`string (path)`

524 639 

525Details640Details

526 641 

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

528 643 

529Key644Key

530 645 

531`features.apply_patch_freeform`646`experimental_use_unified_exec_tool`

532 647 

533Type / Values648Type / Values

534 649 

536 651 

537Details652Details

538 653 

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

540 655 

541Key656Key

542 657 

552 667 

553Key668Key

554 669 

555`features.apps_mcp_gateway`670`features.codex_hooks`

556 671 

557Type / Values672Type / Values

558 673 

560 675 

561Details676Details

562 677 

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

564 679 

565Key680Key

566 681 

567`features.child_agents_md`682`features.enable_request_compression`

568 683 

569Type / Values684Type / Values

570 685 

572 687 

573Details688Details

574 689 

575Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).690Compress streaming request bodies with zstd when supported (stable; on by default).

576 691 

577Key692Key

578 693 

579`features.collaboration_modes`694`features.fast_mode`

580 695 

581Type / Values696Type / Values

582 697 

584 699 

585Details700Details

586 701 

587Enable collaboration modes such as plan mode (stable; on by default).702Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

588 703 

589Key704Key

590 705 

596 711 

597Details712Details

598 713 

599Enable 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).

600 715 

601Key716Key

602 717 

612 727 

613Key728Key

614 729 

615`features.powershell_utf8`730`features.prevent_idle_sleep`

616 

617Type / Values

618 

619`boolean`

620 

621Details

622 

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

624 

625Key

626 

627`features.remote_models`

628 731 

629Type / Values732Type / Values

630 733 

632 735 

633Details736Details

634 737 

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

636 739 

637Key740Key

638 741 

639`features.request_rule`742`features.shell_snapshot`

640 743 

641Type / Values744Type / Values

642 745 

644 747 

645Details748Details

646 749 

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

648 751 

649Key752Key

650 753 

651`features.runtime_metrics`754`features.shell_tool`

652 755 

653Type / Values756Type / Values

654 757 

656 759 

657Details760Details

658 761 

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

660 763 

661Key764Key

662 765 

663`features.search_tool`766`features.skill_mcp_dependency_install`

664 767 

665Type / Values768Type / Values

666 769 

668 771 

669Details772Details

670 773 

671Enable `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).

672 775 

673Key776Key

674 777 

675`features.shell_snapshot`778`features.smart_approvals`

676 779 

677Type / Values780Type / Values

678 781 

680 783 

681Details784Details

682 785 

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

684 787 

685Key788Key

686 789 

687`features.shell_tool`790`features.undo`

688 791 

689Type / Values792Type / Values

690 793 

692 795 

693Details796Details

694 797 

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

696 799 

697Key800Key

698 801 

704 807 

705Details808Details

706 809 

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

708 

709Key

710 

711`features.use_linux_sandbox_bwrap`

712 

713Type / Values

714 

715`boolean`

716 

717Details

718 

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

720 811 

721Key812Key

722 813 

840 931 

841Key932Key

842 933 

843`include_apply_patch_tool`

844 

845Type / Values

846 

847`boolean`

848 

849Details

850 

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

852 

853Key

854 

855`instructions`934`instructions`

856 935 

857Type / Values936Type / Values

1044 1123 

1045Key1124Key

1046 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 

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

1048 1139 

1049Type / Values1140Type / Values

1056 1147 

1057Key1148Key

1058 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 

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

1060 1163 

1061Type / Values1164Type / Values

1112 1215 

1113Details1216Details

1114 1217 

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

1116 1219 

1117Key1220Key

1118 1221 

1176 1279 

1177Key1280Key

1178 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 

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

1180 1367 

1181Type / Values1368Type / Values

1320 1507 

1321Key1508Key

1322 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 

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

1324 1523 

1325Type / Values1524Type / Values

1326 1525 

1327`chat | responses`1526`responses`

1328 1527 

1329Details1528Details

1330 1529 

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

1332 1531 

1333Key1532Key

1334 1533 

1376 1575 

1377Details1576Details

1378 1577 

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

1380 1579 

1381Key1580Key

1382 1581 

1464 1663 

1465Key1664Key

1466 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 

1467`oss_provider`1678`oss_provider`

1468 1679 

1469Type / Values1680Type / Values

1584 1795 

1585Key1796Key

1586 1797 

1798`otel.metrics_exporter`

1799 

1800Type / Values

1801 

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

1803 

1804Details

1805 

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

1807 

1808Key

1809 

1587`otel.trace_exporter`1810`otel.trace_exporter`

1588 1811 

1589Type / Values1812Type / Values

1668 1891 

1669Key1892Key

1670 1893 

1671`personality`1894`permissions.<name>.filesystem`

1672 1895 

1673Type / Values1896Type / Values

1674 1897 

1675`none | friendly | pragmatic`1898`table`

1676 1899 

1677Details1900Details

1678 1901 

1679Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.1902Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.

1680 1903 

1681Key1904Key

1682 1905 

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

1684 1907 

1685Type / Values1908Type / Values

1686 1909 

1687`string`1910`"read" | "write" | "none"`

1688 1911 

1689Details1912Details

1690 1913 

1691Default profile applied at startup (equivalent to `--profile`).1914Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself.

1692 1915 

1693Key1916Key

1694 1917 

1695`profiles.<name>.*`1918`permissions.<name>.filesystem.<path>`

1696 1919 

1697Type / Values1920Type / Values

1698 1921 

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

1700 1923 

1701Details1924Details

1702 1925 

1703Profile-scoped overrides for any of the supported configuration keys.1926Grant direct access for a path or special token, or scope nested entries under that root.

1704 1927 

1705Key1928Key

1706 1929 

1707`profiles.<name>.experimental_use_freeform_apply_patch`1930`permissions.<name>.network.allow_local_binding`

1708 1931 

1709Type / Values1932Type / Values

1710 1933 

1712 1935 

1713Details1936Details

1714 1937 

1715Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.1938Permit local bind/listen operations through the managed proxy.

1716 1939 

1717Key1940Key

1718 1941 

1719`profiles.<name>.experimental_use_unified_exec_tool`1942`permissions.<name>.network.allow_upstream_proxy`

1720 1943 

1721Type / Values1944Type / Values

1722 1945 

1724 1947 

1725Details1948Details

1726 1949 

1727Legacy name for enabling unified exec; prefer `[features].unified_exec`.1950Allow the managed proxy to chain to another upstream proxy.

1728 1951 

1729Key1952Key

1730 1953 

1731`profiles.<name>.include_apply_patch_tool`1954`permissions.<name>.network.dangerously_allow_all_unix_sockets`

1732 1955 

1733Type / Values1956Type / Values

1734 1957 

1736 1959 

1737Details1960Details

1738 1961 

1739Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.1962Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.

1740 1963 

1741Key1964Key

1742 1965 

1743`profiles.<name>.model_catalog_json`1966`permissions.<name>.network.dangerously_allow_non_loopback_proxy`

1744 1967 

1745Type / Values1968Type / Values

1746 1969 

1747`string (path)`1970`boolean`

1748 1971 

1749Details1972Details

1750 1973 

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

2074`personality`

2075 

2076Type / Values

2077 

2078`none | friendly | pragmatic`

2079 

2080Details

2081 

2082Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.

2083 

2084Key

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 

2098`profile`

2099 

2100Type / Values

2101 

2102`string`

2103 

2104Details

2105 

2106Default profile applied at startup (equivalent to `--profile`).

2107 

2108Key

2109 

2110`profiles.<name>.*`

2111 

2112Type / Values

2113 

2114`various`

2115 

2116Details

2117 

2118Profile-scoped overrides for any of the supported configuration keys.

2119 

2120Key

2121 

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

2123 

2124Type / Values

2125 

2126`boolean`

2127 

2128Details

2129 

2130Profile-scoped analytics enablement override.

2131 

2132Key

2133 

2134`profiles.<name>.experimental_use_unified_exec_tool`

2135 

2136Type / Values

2137 

2138`boolean`

2139 

2140Details

2141 

2142Legacy name for enabling unified exec; prefer `[features].unified_exec`.

2143 

2144Key

2145 

2146`profiles.<name>.model_catalog_json`

2147 

2148Type / Values

2149 

2150`string (path)`

2151 

2152Details

2153 

2154Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).

2155 

2156Key

2157 

2158`profiles.<name>.model_instructions_file`

2159 

2160Type / Values

2161 

2162`string (path)`

2163 

2164Details

2165 

2166Profile-scoped replacement for the built-in instruction file.

1752 2167 

1753Key2168Key

1754 2169 

1776 2191 

1777Key2192Key

1778 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 

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

1780 2231 

1781Type / Values2232Type / Values

1788 2239 

1789Key2240Key

1790 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 

1791`project_doc_fallback_filenames`2254`project_doc_fallback_filenames`

1792 2255 

1793Type / Values2256Type / Values

1908 2371 

1909Key2372Key

1910 2373 

2374`service_tier`

2375 

2376Type / Values

2377 

2378`flex | fast`

2379 

2380Details

2381 

2382Preferred service tier for new turns.

2383 

2384Key

2385 

1911`shell_environment_policy.exclude`2386`shell_environment_policy.exclude`

1912 2387 

1913Type / Values2388Type / Values

2028 2503 

2029Key2504Key

2030 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 

2031`suppress_unstable_features_warning`2518`suppress_unstable_features_warning`

2032 2519 

2033Type / Values2520Type / Values

2052 2539 

2053Key2540Key

2054 2541 

2055`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`

2056 2555 

2057Type / Values2556Type / Values

2058 2557 

2060 2559 

2061Details2560Details

2062 2561 

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

2064 2575 

2065Key2576Key

2066 2577 

2100 2611 

2101Key2612Key

2102 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 

2103`tui.notification_method`2626`tui.notification_method`

2104 2627 

2105Type / Values2628Type / Values

2148 2671 

2149Key2672Key

2150 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 

2151`web_search`2698`web_search`

2152 2699 

2153Type / Values2700Type / Values

2182 2729 

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

2184 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 

2185Expand to view all2744Expand to view all

2186 2745 

2187You 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).

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

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

2203 2762 

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

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

2765 

2204| Key | Type / Values | Details |2766| Key | Type / Values | Details |

2205| --- | --- | --- |2767| --- | --- | --- |

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

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

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

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

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

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

2228 2793 

2229Details2794Details

2230 2795 

2231Allowed 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`).

2232 2809 

2233Key2810Key

2234 2811 

2256 2833 

2257Key2834Key

2258 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