config-reference.md Codex Docs, 2026-02-19 20:37 UTC → 2026-04-15 06:44 UTC

1# Configuration Reference1# Configuration Reference

2 2 

3Complete reference for Codex config.toml and requirements.toml

4 

5Use this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with [Config basics](https://developers.openai.com/codex/config-basic) and [Advanced Config](https://developers.openai.com/codex/config-advanced).3Use this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with [Config basics](https://developers.openai.com/codex/config-basic) and [Advanced Config](https://developers.openai.com/codex/config-advanced).

6 4 

7## `config.toml`5## `config.toml`

8 6 

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

10 8 

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

10 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

60| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |76| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

128| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |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. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

164 223 

165Key224Key

166 225 

188 247 

189Key248Key

190 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 

274`agents.max_depth`

275 

276Type / Values

277 

278`number`

279 

280Details

281 

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

283 

284Key

285 

191`agents.max_threads`286`agents.max_threads`

192 287 

193Type / Values288Type / Values

196 291 

197Details292Details

198 293 

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

200 295 

201Key296Key

202 297 

203`approval_policy`298`allow_login_shell`

204 299 

205Type / Values300Type / Values

206 301 

207`untrusted | on-request | never`302`boolean`

208 303 

209Details304Details

210 305 

211Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.306Allow 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.

212 307 

213Key308Key

214 309 

215`apps.<id>.disabled_reason`310`analytics.enabled`

216 311 

217Type / Values312Type / Values

218 313 

219`unknown | user`314`boolean`

220 315 

221Details316Details

222 317 

223Optional reason attached when an app/connector is disabled.318Enable or disable analytics for this machine/profile. When unset, the client default applies.

224 319 

225Key320Key

226 321 

227`apps.<id>.enabled`322`approval_policy`

323 

324Type / Values

325 

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`

228 335 

229Type / Values336Type / Values

230 337 

232 339 

233Details340Details

234 341 

235Enable or disable a specific app/connector by id (default: true).342When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

236 343 

237Key344Key

238 345 

239`chatgpt_base_url`346`approval_policy.granular.request_permissions`

240 347 

241Type / Values348Type / Values

242 349 

243`string`350`boolean`

244 351 

245Details352Details

246 353 

247Override the base URL used during the ChatGPT login flow.354When `true`, prompts from the `request_permissions` tool are allowed to surface.

248 355 

249Key356Key

250 357 

251`check_for_update_on_startup`358`approval_policy.granular.rules`

252 359 

253Type / Values360Type / Values

254 361 

256 363 

257Details364Details

258 365 

259Check for Codex updates on startup (set to false only when updates are centrally managed).366When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.

260 367 

261Key368Key

262 369 

263`cli_auth_credentials_store`370`approval_policy.granular.sandbox_approval`

264 371 

265Type / Values372Type / Values

266 373 

267`file | keyring | auto`374`boolean`

268 375 

269Details376Details

270 377 

271Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).378When `true`, sandbox escalation approval prompts are allowed to surface.

272 379 

273Key380Key

274 381 

275`compact_prompt`382`approval_policy.granular.skill_approval`

276 383 

277Type / Values384Type / Values

278 385 

279`string`386`boolean`

280 387 

281Details388Details

282 389 

283Inline override for the history compaction prompt.390When `true`, skill-script approval prompts are allowed to surface.

284 391 

285Key392Key

286 393 

287`developer_instructions`394`approvals_reviewer`

288 395 

289Type / Values396Type / Values

290 397 

291`string`398`user | guardian_subagent`

292 399 

293Details400Details

294 401 

295Additional developer instructions injected into the session (optional).402Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent.

296 403 

297Key404Key

298 405 

299`disable_paste_burst`406`apps._default.destructive_enabled`

300 407 

301Type / Values408Type / Values

302 409 

304 411 

305Details412Details

306 413 

307Disable burst-paste detection in the TUI.414Default allow/deny for app tools with `destructive_hint = true`.

308 415 

309Key416Key

310 417 

311`experimental_compact_prompt_file`418`apps._default.enabled`

312 419 

313Type / Values420Type / Values

314 421 

315`string (path)`422`boolean`

316 423 

317Details424Details

318 425 

319Load the compaction prompt override from a file (experimental).426Default app enabled state for all apps unless overridden per app.

320 427 

321Key428Key

322 429 

323`experimental_use_freeform_apply_patch`430`apps._default.open_world_enabled`

324 431 

325Type / Values432Type / Values

326 433 

328 435 

329Details436Details

330 437 

331Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.438Default allow/deny for app tools with `open_world_hint = true`.

332 439 

333Key440Key

334 441 

335`experimental_use_unified_exec_tool`442`apps.<id>.default_tools_approval_mode`

443 

444Type / Values

445 

446`auto | prompt | approve`

447 

448Details

449 

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

451 

452Key

453 

454`apps.<id>.default_tools_enabled`

336 455 

337Type / Values456Type / Values

338 457 

340 459 

341Details460Details

342 461 

343Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.462Default enabled state for tools in this app unless a per-tool override exists.

344 463 

345Key464Key

346 465 

347`features.apply_patch_freeform`466`apps.<id>.destructive_enabled`

348 467 

349Type / Values468Type / Values

350 469 

352 471 

353Details472Details

354 473 

355Expose the freeform `apply_patch` tool (experimental).474Allow or block tools in this app that advertise `destructive_hint = true`.

356 475 

357Key476Key

358 477 

359`features.apps`478`apps.<id>.enabled`

360 479 

361Type / Values480Type / Values

362 481 

364 483 

365Details484Details

366 485 

367Enable ChatGPT Apps/connectors support (experimental).486Enable or disable a specific app/connector by id (default: true).

368 487 

369Key488Key

370 489 

371`features.apps_mcp_gateway`490`apps.<id>.open_world_enabled`

372 491 

373Type / Values492Type / Values

374 493 

376 495 

377Details496Details

378 497 

379Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).498Allow or block tools in this app that advertise `open_world_hint = true`.

499 

500Key

501 

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

503 

504Type / Values

505 

506`auto | prompt | approve`

507 

508Details

509 

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

380 511 

381Key512Key

382 513 

383`features.child_agents_md`514`apps.<id>.tools.<tool>.enabled`

384 515 

385Type / Values516Type / Values

386 517 

388 519 

389Details520Details

390 521 

391Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).522Per-tool enabled override for an app tool (for example `repos/list`).

523 

524Key

525 

526`background_terminal_max_timeout`

527 

528Type / Values

529 

530`number`

531 

532Details

533 

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

535 

536Key

537 

538`chatgpt_base_url`

539 

540Type / Values

541 

542`string`

543 

544Details

545 

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

392 547 

393Key548Key

394 549 

395`features.collaboration_modes`550`check_for_update_on_startup`

396 551 

397Type / Values552Type / Values

398 553 

400 555 

401Details556Details

402 557 

403Enable collaboration modes such as plan mode (stable; on by default).558Check for Codex updates on startup (set to false only when updates are centrally managed).

559 

560Key

561 

562`cli_auth_credentials_store`

563 

564Type / Values

565 

566`file | keyring | auto`

567 

568Details

569 

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

571 

572Key

573 

574`commit_attribution`

575 

576Type / Values

577 

578`string`

579 

580Details

581 

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

583 

584Key

585 

586`compact_prompt`

587 

588Type / Values

589 

590`string`

591 

592Details

593 

594Inline override for the history compaction prompt.

595 

596Key

597 

598`default_permissions`

599 

600Type / Values

601 

602`string`

603 

604Details

605 

606Name of the default permissions profile to apply to sandboxed tool calls.

607 

608Key

609 

610`developer_instructions`

611 

612Type / Values

613 

614`string`

615 

616Details

617 

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

404 619 

405Key620Key

406 621 

407`features.elevated_windows_sandbox`622`disable_paste_burst`

408 623 

409Type / Values624Type / Values

410 625 

412 627 

413Details628Details

414 629 

415Enable the elevated Windows sandbox pipeline (experimental).630Disable burst-paste detection in the TUI.

631 

632Key

633 

634`experimental_compact_prompt_file`

635 

636Type / Values

637 

638`string (path)`

639 

640Details

641 

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

416 643 

417Key644Key

418 645 

419`features.experimental_windows_sandbox`646`experimental_use_unified_exec_tool`

420 647 

421Type / Values648Type / Values

422 649 

424 651 

425Details652Details

426 653 

427Run the Windows restricted-token sandbox (experimental).654Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

428 655 

429Key656Key

430 657 

431`features.multi_agent`658`features.apps`

432 659 

433Type / Values660Type / Values

434 661 

436 663 

437Details664Details

438 665 

439Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).666Enable ChatGPT Apps/connectors support (experimental).

440 667 

441Key668Key

442 669 

443`features.personality`670`features.codex_hooks`

444 671 

445Type / Values672Type / Values

446 673 

448 675 

449Details676Details

450 677 

451Enable personality selection controls (stable; on by default).678Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).

452 679 

453Key680Key

454 681 

455`features.powershell_utf8`682`features.enable_request_compression`

456 683 

457Type / Values684Type / Values

458 685 

460 687 

461Details688Details

462 689 

463Force PowerShell UTF-8 output (defaults to true).690Compress streaming request bodies with zstd when supported (stable; on by default).

464 691 

465Key692Key

466 693 

467`features.remote_models`694`features.fast_mode`

468 695 

469Type / Values696Type / Values

470 697 

472 699 

473Details700Details

474 701 

475Refresh remote model list before showing readiness (experimental).702Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

476 703 

477Key704Key

478 705 

479`features.request_rule`706`features.multi_agent`

480 707 

481Type / Values708Type / Values

482 709 

484 711 

485Details712Details

486 713 

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

488 715 

489Key716Key

490 717 

491`features.runtime_metrics`718`features.personality`

492 719 

493Type / Values720Type / Values

494 721 

496 723 

497Details724Details

498 725 

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

500 727 

501Key728Key

502 729 

503`features.search_tool`730`features.prevent_idle_sleep`

504 731 

505Type / Values732Type / Values

506 733 

508 735 

509Details736Details

510 737 

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

512 739 

513Key740Key

514 741 

520 747 

521Details748Details

522 749 

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

524 751 

525Key752Key

526 753 

536 763 

537Key764Key

538 765 

539`features.unified_exec`766`features.skill_mcp_dependency_install`

767 

768Type / Values

769 

770`boolean`

771 

772Details

773 

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

775 

776Key

777 

778`features.smart_approvals`

779 

780Type / Values

781 

782`boolean`

783 

784Details

785 

786Route eligible approval requests through the guardian reviewer subagent (experimental; off by default).

787 

788Key

789 

790`features.undo`

540 791 

541Type / Values792Type / Values

542 793 

544 795 

545Details796Details

546 797 

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

548 799 

549Key800Key

550 801 

551`features.use_linux_sandbox_bwrap`802`features.unified_exec`

552 803 

553Type / Values804Type / Values

554 805 

556 807 

557Details808Details

558 809 

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

560 811 

561Key812Key

562 813 

680 931 

681Key932Key

682 933 

683`include_apply_patch_tool`

684 

685Type / Values

686 

687`boolean`

688 

689Details

690 

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

692 

693Key

694 

695`instructions`934`instructions`

696 935 

697Type / Values936Type / Values

728 967 

729Key968Key

730 969 

970`mcp_oauth_callback_url`

971 

972Type / Values

973 

974`string`

975 

976Details

977 

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

979 

980Key

981 

731`mcp_oauth_credentials_store`982`mcp_oauth_credentials_store`

732 983 

733Type / Values984Type / Values

872 1123 

873Key1124Key

874 1125 

875`mcp_servers.<id>.required`1126`mcp_servers.<id>.oauth_resource`

876 1127 

877Type / Values1128Type / Values

878 1129 

879`boolean`1130`string`

880 1131 

881Details1132Details

882 1133 

883When true, fail startup/resume if this enabled MCP server cannot initialize.1134Optional RFC 8707 OAuth resource parameter to include during MCP login.

884 1135 

885Key1136Key

886 1137 

887`mcp_servers.<id>.startup_timeout_ms`1138`mcp_servers.<id>.required`

888 1139 

889Type / Values1140Type / Values

890 1141 

891`number`1142`boolean`

892 1143 

893Details1144Details

894 1145 

895Alias for `startup_timeout_sec` in milliseconds.1146When true, fail startup/resume if this enabled MCP server cannot initialize.

896 1147 

897Key1148Key

898 1149 

899`mcp_servers.<id>.startup_timeout_sec`1150`mcp_servers.<id>.scopes`

900 1151 

901Type / Values1152Type / Values

902 1153 

903`number`1154`array<string>`

904 1155 

905Details1156Details

906 1157 

907Override the default 10s startup timeout for an MCP server.1158OAuth scopes to request when authenticating to that MCP server.

908 1159 

909Key1160Key

910 1161 

911`mcp_servers.<id>.tool_timeout_sec`1162`mcp_servers.<id>.startup_timeout_ms`

1163 

1164Type / Values

1165 

1166`number`

1167 

1168Details

1169 

1170Alias for `startup_timeout_sec` in milliseconds.

1171 

1172Key

1173 

1174`mcp_servers.<id>.startup_timeout_sec`

1175 

1176Type / Values

1177 

1178`number`

1179 

1180Details

1181 

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

1183 

1184Key

1185 

1186`mcp_servers.<id>.tool_timeout_sec`

912 1187 

913Type / Values1188Type / Values

914 1189 

940 1215 

941Details1216Details

942 1217 

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

944 1219 

945Key1220Key

946 1221 

956 1231 

957Key1232Key

958 1233 

1234`model_catalog_json`

1235 

1236Type / Values

1237 

1238`string (path)`

1239 

1240Details

1241 

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

1243 

1244Key

1245 

959`model_context_window`1246`model_context_window`

960 1247 

961Type / Values1248Type / Values

992 1279 

993Key1280Key

994 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 

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

996 1367 

997Type / Values1368Type / Values

1136 1507 

1137Key1508Key

1138 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 

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

1140 1523 

1141Type / Values1524Type / Values

1142 1525 

1143`chat | responses`1526`responses`

1144 1527 

1145Details1528Details

1146 1529 

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

1148 1531 

1149Key1532Key

1150 1533 

1192 1575 

1193Details1576Details

1194 1577 

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

1196 1579 

1197Key1580Key

1198 1581 

1280 1663 

1281Key1664Key

1282 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 

1283`oss_provider`1678`oss_provider`

1284 1679 

1285Type / Values1680Type / Values

1400 1795 

1401Key1796Key

1402 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 

1403`otel.trace_exporter`1810`otel.trace_exporter`

1404 1811 

1405Type / Values1812Type / Values

1484 1891 

1485Key1892Key

1486 1893 

1894`permissions.<name>.filesystem`

1895 

1896Type / Values

1897 

1898`table`

1899 

1900Details

1901 

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

1903 

1904Key

1905 

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

1907 

1908Type / Values

1909 

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

1911 

1912Details

1913 

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

1915 

1916Key

1917 

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

1919 

1920Type / Values

1921 

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

1923 

1924Details

1925 

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

1927 

1928Key

1929 

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

1931 

1932Type / Values

1933 

1934`boolean`

1935 

1936Details

1937 

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

1939 

1940Key

1941 

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

1943 

1944Type / Values

1945 

1946`boolean`

1947 

1948Details

1949 

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

1951 

1952Key

1953 

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

1955 

1956Type / Values

1957 

1958`boolean`

1959 

1960Details

1961 

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

1963 

1964Key

1965 

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

1967 

1968Type / Values

1969 

1970`boolean`

1971 

1972Details

1973 

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

1975 

1976Key

1977 

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

1979 

1980Type / Values

1981 

1982`map<string, allow | deny>`

1983 

1984Details

1985 

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

1987 

1988Key

1989 

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

1991 

1992Type / Values

1993 

1994`boolean`

1995 

1996Details

1997 

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

1999 

2000Key

2001 

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

2003 

2004Type / Values

2005 

2006`boolean`

2007 

2008Details

2009 

2010Allow UDP over the SOCKS5 listener when enabled.

2011 

2012Key

2013 

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

2015 

2016Type / Values

2017 

2018`boolean`

2019 

2020Details

2021 

2022Enable network access for this named permissions profile.

2023 

2024Key

2025 

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

2027 

2028Type / Values

2029 

2030`limited | full`

2031 

2032Details

2033 

2034Network proxy mode used for subprocess traffic.

2035 

2036Key

2037 

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

2039 

2040Type / Values

2041 

2042`string`

2043 

2044Details

2045 

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

2047 

2048Key

2049 

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

2051 

2052Type / Values

2053 

2054`string`

2055 

2056Details

2057 

2058SOCKS5 proxy endpoint used by this permissions profile.

2059 

2060Key

2061 

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

2063 

2064Type / Values

2065 

2066`map<string, allow | none>`

2067 

2068Details

2069 

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

2071 

2072Key

2073 

1487`personality`2074`personality`

1488 2075 

1489Type / Values2076Type / Values

1496 2083 

1497Key2084Key

1498 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 

1499`profile`2098`profile`

1500 2099 

1501Type / Values2100Type / Values

1520 2119 

1521Key2120Key

1522 2121 

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

1524 2123 

1525Type / Values2124Type / Values

1526 2125 

1528 2127 

1529Details2128Details

1530 2129 

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

1532 2131 

1533Key2132Key

1534 2133 

1544 2143 

1545Key2144Key

1546 2145 

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

1548 2147 

1549Type / Values2148Type / Values

1550 2149 

1551`boolean`2150`string (path)`

1552 2151 

1553Details2152Details

1554 2153 

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

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.

1556 2167 

1557Key2168Key

1558 2169 

1580 2191 

1581Key2192Key

1582 2193 

2194`profiles.<name>.plan_mode_reasoning_effort`