config-reference.md Codex Docs, 2026-03-18 00:36 UTC → 2026-03-18 12:23 UTC

18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |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. |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. |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 | { 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. |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.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |22| `approval_policy.granular.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected. |

23| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules 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.reject.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are auto-rejected. |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. |

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

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

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

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

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

40| `compact_prompt` | `string` | Inline override for the history compaction prompt. |42| `compact_prompt` | `string` | Inline override for the history compaction prompt. |

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

41| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |44| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |

42| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |45| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |

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

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

45| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |48| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |

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

47| `features.artifact` | `boolean` | Enable native artifact tools such as slides and spreadsheets (under development). |

48| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |

49| `features.collaboration_modes` | `boolean` | Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key. |

50| `features.default_mode_request_user_input` | `boolean` | Allow `request_user_input` in default collaboration mode (under development; off by default). |

51| `features.elevated_windows_sandbox` | `boolean` | Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it. |

52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |49| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

53| `features.experimental_windows_sandbox` | `boolean` | Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it. |

54| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |50| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |

55| `features.image_detail_original` | `boolean` | Allow image outputs with `detail = "original"` on supported models (under development). |51| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |

56| `features.image_generation` | `boolean` | Enable the built-in image generation tool (under development). |

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

58| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere. |

59| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |53| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |

60| `features.remote_models` | `boolean` | Legacy toggle for an older remote-model readiness flow. Current builds do not use it. |

61| `features.request_rule` | `boolean` | Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset. |

62| `features.responses_websockets` | `boolean` | Prefer the Responses API WebSocket transport for supported providers (under development). |

63| `features.responses_websockets_v2` | `boolean` | Enable Responses API WebSocket v2 mode (under development). |

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

65| `features.search_tool` | `boolean` | Legacy toggle for an older Apps discovery flow. Current builds do not use it. |

66| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |54| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |

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

68| `features.skill_env_var_dependency_prompt` | `boolean` | Prompt for missing skill environment-variable dependencies (under development). |

69| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |56| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |

70| `features.sqlite` | `boolean` | Enable SQLite-backed state persistence (stable; on by default). |57| `features.smart_approvals` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). |

71| `features.steer` | `boolean` | Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior. |

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

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

74| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |

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

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

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

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

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

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

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

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

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

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

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

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

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

157| `permissions.network.admin_url` | `string` | Admin endpoint for the managed network proxy. |143| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |

158| `permissions.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |144| `permissions.<name>.filesystem.":project_roots".<subpath>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself. |

159| `permissions.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |145| `permissions.<name>.filesystem.<path>` | `"read" | "write" | "none" | table` | Grant direct access for a path or special token, or scope nested entries under that root. |

160| `permissions.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |146| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

161| `permissions.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |147| `permissions.<name>.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |

162| `permissions.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |148| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

163| `permissions.network.dangerously_allow_non_loopback_admin` | `boolean` | Permit non-loopback bind addresses for the managed proxy admin listener. |149| `permissions.<name>.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |

164| `permissions.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |150| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

165| `permissions.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |151| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

166| `permissions.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener from the managed network proxy. |152| `permissions.<name>.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |

167| `permissions.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |153| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |

168| `permissions.network.enabled` | `boolean` | Enable the managed network proxy configuration for subprocesses. |154| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

169| `permissions.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |155| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |

170| `permissions.network.proxy_url` | `string` | HTTP proxy endpoint used by the managed network proxy. |156| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |

171| `permissions.network.socks_url` | `string` | SOCKS5 proxy endpoint used by the managed network proxy. |157| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |

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

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

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

174| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |161| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

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

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

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

197| `service_tier` | `flex | fast` | Preferred service tier for new turns. `fast` is honored only when the `features.fast_mode` gate is enabled. |184| `service_tier` | `flex | fast` | Preferred service tier for new turns. |

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

199| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |186| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |

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

209| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |196| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |

210| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |197| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |

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

212| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |199| `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. |

213| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |200| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

214| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |201| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |

215| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |202| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

222| `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. |209| `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. |

223| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |210| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

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

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

225 213 

226Key214Key

227 215 

325 313 

326Type / Values314Type / Values

327 315 

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

329 317 

330Details318Details

331 319 

332Controls 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.320Controls 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.

333 321 

334Key322Key

335 323 

336`approval_policy.reject.mcp_elicitations`324`approval_policy.granular.mcp_elicitations`

337 325 

338Type / Values326Type / Values

339 327 

341 329 

342Details330Details

343 331 

344When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.332When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

345 333 

346Key334Key

347 335 

348`approval_policy.reject.rules`336`approval_policy.granular.request_permissions`

349 337 

350Type / Values338Type / Values

351 339 

353 341 

354Details342Details

355 343 

356When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.344When `true`, prompts from the `request_permissions` tool are allowed to surface.

357 345 

358Key346Key

359 347 

360`approval_policy.reject.sandbox_approval`348`approval_policy.granular.rules`

361 349 

362Type / Values350Type / Values

363 351 

365 353 

366Details354Details

367 355 

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

357 

358Key

359 

360`approval_policy.granular.sandbox_approval`

361 

362Type / Values

363 

364`boolean`

365 

366Details

367 

368When `true`, sandbox escalation approval prompts are allowed to surface.

369 

370Key

371 

372`approval_policy.granular.skill_approval`

373 

374Type / Values

375 

376`boolean`

377 

378Details

379 

380When `true`, skill-script approval prompts are allowed to surface.

369 381 

370Key382Key

371 383 

561 573 

562Key574Key

563 575 

576`default_permissions`

577 

578Type / Values

579 

580`string`

581 

582Details

583 

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

585 

586Key

587 

564`developer_instructions`588`developer_instructions`

565 589 

566Type / Values590Type / Values

621 645 

622Key646Key

623 647 

624`features.apps_mcp_gateway`

625 

626Type / Values

627 

628`boolean`

629 

630Details

631 

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

633 

634Key

635 

636`features.artifact`

637 

638Type / Values

639 

640`boolean`

641 

642Details

643 

644Enable native artifact tools such as slides and spreadsheets (under development).

645 

646Key

647 

648`features.child_agents_md`

649 

650Type / Values

651 

652`boolean`

653 

654Details

655 

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

657 

658Key

659 

660`features.collaboration_modes`

661 

662Type / Values

663 

664`boolean`

665 

666Details

667 

668Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key.

669 

670Key

671 

672`features.default_mode_request_user_input`

673 

674Type / Values

675 

676`boolean`

677 

678Details

679 

680Allow `request_user_input` in default collaboration mode (under development; off by default).

681 

682Key

683 

684`features.elevated_windows_sandbox`

685 

686Type / Values

687 

688`boolean`

689 

690Details

691 

692Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it.

693 

694Key

695 

696`features.enable_request_compression`648`features.enable_request_compression`

697 649 

698Type / Values650Type / Values

705 657 

706Key658Key

707 659 

708`features.experimental_windows_sandbox`

709 

710Type / Values

711 

712`boolean`

713 

714Details

715 

716Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it.

717 

718Key

719 

720`features.fast_mode`660`features.fast_mode`

721 661 

722Type / Values662Type / Values

729 669 

730Key670Key

731 671 

732`features.image_detail_original`672`features.multi_agent`

733 

734Type / Values

735 

736`boolean`

737 

738Details

739 

740Allow image outputs with `detail = "original"` on supported models (under development).

741 

742Key

743 

744`features.image_generation`

745 673 

746Type / Values674Type / Values

747 675 

749 677 

750Details678Details

751 679 

752Enable the built-in image generation tool (under development).680Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

753 681 

754Key682Key

755 683 

765 693 

766Key694Key

767 695 

768`features.powershell_utf8`

769 

770Type / Values

771 

772`boolean`

773 

774Details

775 

776Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.

777 

778Key

779 

780`features.prevent_idle_sleep`696`features.prevent_idle_sleep`

781 697 

782Type / Values698Type / Values

789 705 

790Key706Key

791 707 

792`features.remote_models`

793 

794Type / Values

795 

796`boolean`

797 

798Details

799 

800Legacy toggle for an older remote-model readiness flow. Current builds do not use it.

801 

802Key

803 

804`features.request_rule`

805 

806Type / Values

807 

808`boolean`

809 

810Details

811 

812Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.

813 

814Key

815 

816`features.responses_websockets`

817 

818Type / Values

819 

820`boolean`

821 

822Details

823 

824Prefer the Responses API WebSocket transport for supported providers (under development).

825 

826Key

827 

828`features.responses_websockets_v2`

829 

830Type / Values

831 

832`boolean`

833 

834Details

835 

836Enable Responses API WebSocket v2 mode (under development).

837 

838Key

839 

840`features.runtime_metrics`

841 

842Type / Values

843 

844`boolean`

845 

846Details

847 

848Show runtime metrics summary in TUI turn separators (experimental).

849 

850Key

851 

852`features.search_tool`

853 

854Type / Values

855 

856`boolean`

857 

858Details

859 

860Legacy toggle for an older Apps discovery flow. Current builds do not use it.

861 

862Key

863 

864`features.shell_snapshot`708`features.shell_snapshot`

865 709 

866Type / Values710Type / Values

885 729 

886Key730Key

887 731 

888`features.skill_env_var_dependency_prompt`

889 

890Type / Values

891 

892`boolean`

893 

894Details

895 

896Prompt for missing skill environment-variable dependencies (under development).

897 

898Key

899 

900`features.skill_mcp_dependency_install`732`features.skill_mcp_dependency_install`

901 733 

902Type / Values734Type / Values

909 741 

910Key742Key

911 743 

912`features.sqlite`744`features.smart_approvals`

913 745 

914Type / Values746Type / Values

915 747 

917 749 

918Details750Details

919 751 

920Enable SQLite-backed state persistence (stable; on by default).752Route eligible approval requests through the guardian reviewer subagent (experimental; off by default).

921 

922Key

923 

924`features.steer`

925 

926Type / Values

927 

928`boolean`

929 

930Details

931 

932Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.

933 753 

934Key754Key

935 755 

957 777 

958Key778Key

959 779 

960`features.use_linux_sandbox_bwrap`

961 

962Type / Values

963 

964`boolean`

965 

966Details

967 

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

969 

970Key

971 

972`features.web_search`780`features.web_search`

973 781 

974Type / Values782Type / Values

1737 1545 

1738Key1546Key

1739 1547 

1548`openai_base_url`

1549 

1550Type / Values

1551 

1552`string`

1553 

1554Details

1555 

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

1557 

1558Key

1559 

1740`oss_provider`1560`oss_provider`

1741 1561 

1742Type / Values1562Type / Values

1953 1773 

1954Key1774Key

1955 1775 

1956`permissions.network.admin_url`1776`permissions.<name>.filesystem`

1957 1777 

1958Type / Values1778Type / Values

1959 1779 

1960`string`1780`table`

1961 1781 

1962Details1782Details

1963 1783 

1964Admin endpoint for the managed network proxy.1784Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.

1965 1785 

1966Key1786Key

1967 1787 

1968`permissions.network.allow_local_binding`1788`permissions.<name>.filesystem.":project_roots".<subpath>`

1969 1789 

1970Type / Values1790Type / Values

1971 1791 

1972`boolean`1792`"read" | "write" | "none"`

1973 1793 

1974Details1794Details

1975 1795 

1976Permit local bind/listen operations through the managed proxy.1796Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself.

1977 1797 

1978Key1798Key

1979 1799 

1980`permissions.network.allow_unix_sockets`1800`permissions.<name>.filesystem.<path>`

1981 1801 

1982Type / Values1802Type / Values

1983 1803 

1984`array<string>`1804`"read" | "write" | "none" | table`

1985 1805 

1986Details1806Details

1987 1807 

1988Allowlist of Unix socket paths permitted through the managed proxy.1808Grant direct access for a path or special token, or scope nested entries under that root.

1989 1809 

1990Key1810Key

1991 1811 

1992`permissions.network.allow_upstream_proxy`1812`permissions.<name>.network.allow_local_binding`

1993 1813 

1994Type / Values1814Type / Values

1995 1815 

1997 1817 

1998Details1818Details

1999 1819 

2000Allow the managed proxy to chain to another upstream proxy.1820Permit local bind/listen operations through the managed proxy.

2001 1821 

2002Key1822Key

2003 1823 

2004`permissions.network.allowed_domains`1824`permissions.<name>.network.allow_unix_sockets`

2005 1825 

2006Type / Values1826Type / Values

2007 1827 

2009 1829 

2010Details1830Details

2011 1831 

2012Allowlist of domains permitted through the managed proxy.1832Allowlist of Unix socket paths permitted through the managed proxy.

2013 1833 

2014Key1834Key

2015 1835 

2016`permissions.network.dangerously_allow_all_unix_sockets`1836`permissions.<name>.network.allow_upstream_proxy`

2017 1837 

2018Type / Values1838Type / Values

2019 1839 

2021 1841 

2022Details1842Details

2023 1843 

2024Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.1844Allow the managed proxy to chain to another upstream proxy.

2025 1845 

2026Key1846Key

2027 1847 

2028`permissions.network.dangerously_allow_non_loopback_admin`1848`permissions.<name>.network.allowed_domains`

1849 

1850Type / Values

1851 

1852`array<string>`

1853 

1854Details

1855 

1856Allowlist of domains permitted through the managed proxy.

1857 

1858Key

1859 

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

2029 1861 

2030Type / Values1862Type / Values

2031 1863 

2033 1865 

2034Details1866Details

2035 1867 

2036Permit non-loopback bind addresses for the managed proxy admin listener.1868Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.

2037 1869 

2038Key1870Key

2039 1871 

2040`permissions.network.dangerously_allow_non_loopback_proxy`1872`permissions.<name>.network.dangerously_allow_non_loopback_proxy`

2041 1873 

2042Type / Values1874Type / Values

2043 1875 

2049 1881 

2050Key1882Key

2051 1883 

2052`permissions.network.denied_domains`1884`permissions.<name>.network.denied_domains`

2053 1885 

2054Type / Values1886Type / Values

2055 1887 

2061 1893 

2062Key1894Key

2063 1895 

2064`permissions.network.enable_socks5`1896`permissions.<name>.network.enable_socks5`

2065 1897 

2066Type / Values1898Type / Values

2067 1899 

2069 1901 

2070Details1902Details

2071 1903 

2072Expose a SOCKS5 listener from the managed network proxy.1904Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.

2073 1905 

2074Key1906Key

2075 1907 

2076`permissions.network.enable_socks5_udp`1908`permissions.<name>.network.enable_socks5_udp`

2077 1909 

2078Type / Values1910Type / Values

2079 1911 

2085 1917 

2086Key1918Key

2087 1919 

2088`permissions.network.enabled`1920`permissions.<name>.network.enabled`

2089 1921 

2090Type / Values1922Type / Values

2091 1923 

2093 1925 

2094Details1926Details

2095 1927 

2096Enable the managed network proxy configuration for subprocesses.1928Enable network access for this named permissions profile.

2097 1929 

2098Key1930Key

2099 1931 

2100`permissions.network.mode`1932`permissions.<name>.network.mode`

2101 1933 

2102Type / Values1934Type / Values

2103 1935 

2109 1941 

2110Key1942Key

2111 1943 

2112`permissions.network.proxy_url`1944`permissions.<name>.network.proxy_url`

2113 1945 

2114Type / Values1946Type / Values

2115 1947 

2117 1949 

2118Details1950Details

2119 1951 

2120HTTP proxy endpoint used by the managed network proxy.1952HTTP proxy endpoint used when this permissions profile enables the managed network proxy.

2121 1953 

2122Key1954Key

2123 1955 

2124`permissions.network.socks_url`1956`permissions.<name>.network.socks_url`

2125 1957 

2126Type / Values1958Type / Values

2127 1959 

2129 1961 

2130Details1962Details

2131 1963 

2132SOCKS5 proxy endpoint used by the managed network proxy.1964SOCKS5 proxy endpoint used by this permissions profile.

2133 1965 

2134Key1966Key

2135 1967 

2441 2273 

2442Details2274Details

2443 2275 

2444Preferred service tier for new turns. `fast` is honored only when the `features.fast_mode` gate is enabled.2276Preferred service tier for new turns.

2445 2277 

2446Key2278Key

2447 2279 

2617 2449 

2618Type / Values2450Type / Values

2619 2451 

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

2621 2453 

2622Details2454Details

2623 2455 

2624Deprecated legacy toggle for web search; prefer the top-level `web_search` setting.2456Optional 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.

2625 2457 

2626Key2458Key

2627 2459 

2767 2599 

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

2769 2601 

2602Key

2603 

2604`windows.sandbox_private_desktop`

2605 

2606Type / Values

2607 

2608`boolean`

2609 

2610Details

2611 

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

2613 

2770Expand to view all2614Expand to view all

2771 2615 

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

2791 2635 

2792| Key | Type / Values | Details |2636| Key | Type / Values | Details |

2793| --- | --- | --- |2637| --- | --- | --- |

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

2795| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2639| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |

2796| `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`. |2640| `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`. |

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

2818 2662 

2819Details2663Details

2820 2664 

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

2822 2666 

2823Key2667Key

2824 2668