config-reference.md Codex Docs, 2026-03-05 18:41 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. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

48| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default). |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). |

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

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

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

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

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

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

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

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

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

58| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |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). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

168| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |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). |

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

182 223 

183Key224Key

184 225 

206 247 

207Key248Key

208 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 

209`agents.job_max_runtime_seconds`262`agents.job_max_runtime_seconds`

210 263 

211Type / Values264Type / Values

238 291 

239Details292Details

240 293 

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

242 295 

243Key296Key

244 297 

254 307 

255Key308Key

256 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 

257`approval_policy`322`approval_policy`

258 323 

259Type / Values324Type / Values

260 325 

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

262 351 

263Details352Details

264 353 

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

266 355 

267Key356Key

268 357 

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

270 359 

271Type / Values360Type / Values

272 361 

274 363 

275Details364Details

276 365 

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

278 367 

279Key368Key

280 369 

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

282 371 

283Type / Values372Type / Values

284 373 

286 375 

287Details376Details

288 377 

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

290 379 

291Key380Key

292 381 

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

294 383 

295Type / Values384Type / Values

296 385 

298 387 

299Details388Details

300 389 

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

302 403 

303Key404Key

304 405 

470 571 

471Key572Key

472 573 

473`compact_prompt`574`commit_attribution`

474 575 

475Type / Values576Type / Values

476 577 

478 579 

479Details580Details

480 581 

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

482 583 

483Key584Key

484 585 

485`developer_instructions`586`compact_prompt`

486 587 

487Type / Values588Type / Values

488 589 

490 591 

491Details592Details

492 593 

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

494 595 

495Key596Key

496 597 

497`disable_paste_burst`598`default_permissions`

498 599 

499Type / Values600Type / Values

500 601 

501`boolean`602`string`

502 603 

503Details604Details

504 605 

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

506 607 

507Key608Key

508 609 

509`experimental_compact_prompt_file`610`developer_instructions`

510 611 

511Type / Values612Type / Values

512 613 

513`string (path)`614`string`

514 615 

515Details616Details

516 617 

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

518 619 

519Key620Key

520 621 

521`experimental_use_freeform_apply_patch`622`disable_paste_burst`

522 623 

523Type / Values624Type / Values

524 625 

526 627 

527Details628Details

528 629 

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

530 631 

531Key632Key

532 633 

533`experimental_use_unified_exec_tool`634`experimental_compact_prompt_file`

534 635 

535Type / Values636Type / Values

536 637 

537`boolean`638`string (path)`

538 639 

539Details640Details

540 641 

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

542 643 

543Key644Key

544 645 

545`features.apply_patch_freeform`646`experimental_use_unified_exec_tool`

546 647 

547Type / Values648Type / Values

548 649 

550 651 

551Details652Details

552 653 

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

554 655 

555Key656Key

556 657 

566 667 

567Key668Key

568 669 

569`features.apps_mcp_gateway`670`features.codex_hooks`

570 671 

571Type / Values672Type / Values

572 673 

574 675 

575Details676Details

576 677 

577Route 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).

578 679 

579Key680Key

580 681 

581`features.child_agents_md`682`features.enable_request_compression`

582 683 

583Type / Values684Type / Values

584 685 

586 687 

587Details688Details

588 689 

589Append 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).

590 691 

591Key692Key

592 693 

593`features.collaboration_modes`694`features.fast_mode`

594 695 

595Type / Values696Type / Values

596 697 

598 699 

599Details700Details

600 701 

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

602 703 

603Key704Key

604 705 

610 711 

611Details712Details

612 713 

613Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default).714Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

614 715 

615Key716Key

616 717 

626 727 

627Key728Key

628 729 

629`features.powershell_utf8`730`features.prevent_idle_sleep`

630 

631Type / Values

632 

633`boolean`

634 

635Details

636 

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

638 

639Key

640 

641`features.remote_models`

642 731 

643Type / Values732Type / Values

644 733 

646 735 

647Details736Details

648 737 

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

650 739 

651Key740Key

652 741 

653`features.request_rule`742`features.shell_snapshot`

654 743 

655Type / Values744Type / Values

656 745 

658 747 

659Details748Details

660 749 

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

662 751 

663Key752Key

664 753 

665`features.runtime_metrics`754`features.shell_tool`

666 755 

667Type / Values756Type / Values

668 757 

670 759 

671Details760Details

672 761 

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

674 763 

675Key764Key

676 765 

677`features.search_tool`766`features.skill_mcp_dependency_install`

678 767 

679Type / Values768Type / Values

680 769 

682 771 

683Details772Details

684 773 

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

686 775 

687Key776Key

688 777 

689`features.shell_snapshot`778`features.smart_approvals`

690 779 

691Type / Values780Type / Values

692 781 

694 783 

695Details784Details

696 785 

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

698 787 

699Key788Key

700 789 

701`features.shell_tool`790`features.undo`

702 791 

703Type / Values792Type / Values

704 793 

706 795 

707Details796Details

708 797 

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

710 799 

711Key800Key

712 801 

718 807 

719Details808Details

720 809 

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

722 

723Key

724 

725`features.use_linux_sandbox_bwrap`

726 

727Type / Values

728 

729`boolean`

730 

731Details

732 

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

734 811 

735Key812Key

736 813 

854 931 

855Key932Key

856 933 

857`include_apply_patch_tool`

858 

859Type / Values

860 

861`boolean`

862 

863Details

864 

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

866 

867Key

868 

869`instructions`934`instructions`

870 935 

871Type / Values936Type / Values

1058 1123 

1059Key1124Key

1060 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 

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

1062 1139 

1063Type / Values1140Type / Values

1070 1147 

1071Key1148Key

1072 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 

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

1074 1163 

1075Type / Values1164Type / Values

1126 1215 

1127Details1216Details

1128 1217 

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

1130 1219 

1131Key1220Key

1132 1221 

1190 1279 

1191Key1280Key

1192 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 

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

1194 1367 

1195Type / Values1368Type / Values

1334 1507 

1335Key1508Key

1336 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 

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

1338 1523 

1339Type / Values1524Type / Values

1340 1525 

1341`chat | responses`1526`responses`

1342 1527 

1343Details1528Details

1344 1529 

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

1346 1531 

1347Key1532Key

1348 1533 

1390 1575 

1391Details1576Details

1392 1577 

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

1394 1579 

1395Key1580Key

1396 1581 

1478 1663 

1479Key1664Key

1480 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 

1481`oss_provider`1678`oss_provider`

1482 1679 

1483Type / Values1680Type / Values

1598 1795 

1599Key1796Key

1600 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 

1601`otel.trace_exporter`1810`otel.trace_exporter`

1602 1811 

1603Type / Values1812Type / Values

1682 1891 

1683Key1892Key

1684 1893 

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

1686 1895 

1687Type / Values1896Type / Values

1688 1897 

1689`none | friendly | pragmatic`1898`table`

1690 1899 

1691Details1900Details

1692 1901 

1693Default 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`.

1694 1903 

1695Key1904Key

1696 1905 

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

1698 1907 

1699Type / Values1908Type / Values

1700 1909 

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

1702 1911 

1703Details1912Details

1704 1913 

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

1706 1915 

1707Key1916Key

1708 1917 

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

1710 1919 

1711Type / Values1920Type / Values

1712 1921 

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

1714 1923 

1715Details1924Details

1716 1925 

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

1718 1927 

1719Key1928Key

1720 1929 

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

1722 1931 

1723Type / Values1932Type / Values

1724 1933 

1726 1935 

1727Details1936Details

1728 1937 

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

1730 1939 

1731Key1940Key

1732 1941 

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

1734 1943 

1735Type / Values1944Type / Values

1736 1945 

1738 1947 

1739Details1948Details

1740 1949 

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

1742 1951 

1743Key1952Key

1744 1953 

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

1746 1955 

1747Type / Values1956Type / Values

1748 1957 

1750 1959 

1751Details1960Details

1752 1961 

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

1754 1963 

1755Key1964Key

1756 1965 

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

1758 1967 

1759Type / Values1968Type / Values

1760 1969 

1761`string (path)`1970`boolean`

1762 1971 

1763Details1972Details

1764 1973 

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

1766 1975 

1767Key1976Key

1768 1977 

1769`profiles.<name>.oss_provider`1978`permissions.<name>.network.domains`

1770 1979 

1771Type / Values1980Type / Values

1772 1981 

1773`lmstudio | ollama`1982`map<string, allow | deny>`

1774 1983 

1775Details1984Details

1776 1985 

1777Profile-scoped OSS provider for `--oss` sessions.1986Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values.

1778 1987 

1779Key1988Key

1780 1989 

1781`profiles.<name>.personality`1990`permissions.<name>.network.enable_socks5`

1782 1991 

1783Type / Values1992Type / Values

1784 1993 

1785`none | friendly | pragmatic`1994`boolean`

1786 1995 

1787Details1996Details

1788 1997 

1789Profile-scoped communication style override for supported models.1998Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.

1790 1999 

1791Key2000Key

1792 2001 

1793`profiles.<name>.web_search`2002`permissions.<name>.network.enable_socks5_udp`

1794 2003 

1795Type / Values2004Type / Values

1796 2005 

1797`disabled | cached | live`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.

2167 

2168Key

2169 

2170`profiles.<name>.oss_provider`

2171 

2172Type / Values

2173 

2174`lmstudio | ollama`

2175 

2176Details

2177 

2178Profile-scoped OSS provider for `--oss` sessions.

2179 

2180Key

2181 

2182`profiles.<name>.personality`

2183 

2184Type / Values

2185 

2186`none | friendly | pragmatic`

2187 

2188Details

2189 

2190Profile-scoped communication style override for supported models.

2191 

2192Key

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 

2230`profiles.<name>.web_search`

2231 

2232Type / Values

2233 

2234`disabled | cached | live`

1798 2235 

1799Details2236Details

1800 2237 

1802 2239 

1803Key2240Key

1804 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 

1805`project_doc_fallback_filenames`2254`project_doc_fallback_filenames`

1806 2255 

1807Type / Values2256Type / Values

1922 2371 

1923Key2372Key

1924 2373 

2374`service_tier`

2375 

2376Type / Values

2377 

2378`flex | fast`

2379 

2380Details

2381 

2382Preferred service tier for new turns.

2383 

2384Key

2385 

1925`shell_environment_policy.exclude`2386`shell_environment_policy.exclude`

1926 2387 

1927Type / Values2388Type / Values

2078 2539 

2079Key2540Key

2080 2541 

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

2082 2555 

2083Type / Values2556Type / Values

2084 2557 

2086 2559 

2087Details2560Details

2088 2561 

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

2090 2575 

2091Key2576Key

2092 2577 

2126 2611 

2127Key2612Key

2128 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 

2129`tui.notification_method`2626`tui.notification_method`

2130 2627 

2131Type / Values2628Type / Values

2174 2671 

2175Key2672Key

2176 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 

2177`web_search`2698`web_search`

2178 2699 

2179Type / Values2700Type / Values

2208 2729 

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

2210 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 

2211Expand to view all2744Expand to view all

2212 2745 

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

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

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

2229 2762 

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

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

2765 

2230| Key | Type / Values | Details |2766| Key | Type / Values | Details |

2231| --- | --- | --- |2767| --- | --- | --- |

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

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

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

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

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

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

2254 2793 

2255Details2794Details

2256 2795 

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

2258 2809 

2259Key2810Key

2260 2811 

2282 2833 

2283Key2834Key

2284 2835 

2836`features`