config-reference.md Codex Docs, 2026-03-17 00:33 UTC → 2026-03-31 06:35 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). |49| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |

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). |50| `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). |51| `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). |52| `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). |53| `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). |54| `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). |55| `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). |56| `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). |57| `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). |58| `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). |59| `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). |60| `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. |61| `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"`. |62| `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"`. |63| `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. |122| `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. |123| `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. |124| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |

125| `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). |126| `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`). |127| `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. |128| `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. |141| `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. |142| `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. |143| `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. |144| `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. |145| `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. |146| `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. |147| `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. |148| `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. |149| `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. |150| `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. |151| `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. |152| `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. |153| `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. |154| `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. |155| `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. |156| `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. |157| `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. |158| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |

159| `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`. |160| `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. |161| `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`). |162| `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. |182| `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. |183| `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"`. |184| `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. |185| `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. |186| `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. |187| `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. |188| `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. |197| `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. |198| `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`. |199| `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. |200| `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. |201| `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). |202| `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). |203| `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. |210| `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). |211| `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. |212| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |

213| `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 214 

226Key215Key

227 216 

325 314 

326Type / Values315Type / Values

327 316 

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

329 318 

330Details319Details

331 320 

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.321Controls 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 322 

334Key323Key

335 324 

336`approval_policy.reject.mcp_elicitations`325`approval_policy.granular.mcp_elicitations`

337 326 

338Type / Values327Type / Values

339 328 

341 330 

342Details331Details

343 332 

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

345 334 

346Key335Key

347 336 

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

349 338 

350Type / Values339Type / Values

351 340 

353 342 

354Details343Details

355 344 

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

357 346 

358Key347Key

359 348 

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

361 350 

362Type / Values351Type / Values

363 352 

365 354 

366Details355Details

367 356 

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

358 

359Key

360 

361`approval_policy.granular.sandbox_approval`

362 

363Type / Values

364 

365`boolean`

366 

367Details

368 

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

370 

371Key

372 

373`approval_policy.granular.skill_approval`

374 

375Type / Values

376 

377`boolean`

378 

379Details

380 

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

369 382 

370Key383Key

371 384 

561 574 

562Key575Key

563 576 

577`default_permissions`

578 

579Type / Values

580 

581`string`

582 

583Details

584 

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

586 

587Key

588 

564`developer_instructions`589`developer_instructions`

565 590 

566Type / Values591Type / Values

621 646 

622Key647Key

623 648 

624`features.apps_mcp_gateway`649`features.codex_hooks`

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 650 

638Type / Values651Type / Values

639 652 

641 654 

642Details655Details

643 656 

644Enable native artifact tools such as slides and spreadsheets (under development).657Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).

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 658 

694Key659Key

695 660 

705 670 

706Key671Key

707 672 

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`673`features.fast_mode`

721 674 

722Type / Values675Type / Values

729 682 

730Key683Key

731 684 

732`features.image_detail_original`685`features.multi_agent`

733 686 

734Type / Values687Type / Values

735 688 

737 690 

738Details691Details

739 692 

740Allow image outputs with `detail = "original"` on supported models (under development).693Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

741 

742Key

743 

744`features.image_generation`

745 

746Type / Values

747 

748`boolean`

749 

750Details

751 

752Enable the built-in image generation tool (under development).

753 694 

754Key695Key

755 696 

765 706 

766Key707Key

767 708 

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`709`features.prevent_idle_sleep`

781 710 

782Type / Values711Type / Values

789 718 

790Key719Key

791 720 

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`721`features.shell_snapshot`

865 722 

866Type / Values723Type / Values

885 742 

886Key743Key

887 744 

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`745`features.skill_mcp_dependency_install`

901 746 

902Type / Values747Type / Values

909 754 

910Key755Key

911 756 

912`features.sqlite`757`features.smart_approvals`

913 

914Type / Values

915 

916`boolean`

917 

918Details

919 

920Enable SQLite-backed state persistence (stable; on by default).

921 

922Key

923 

924`features.steer`

925 758 

926Type / Values759Type / Values

927 760 

929 762 

930Details763Details

931 764 

932Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.765Route eligible approval requests through the guardian reviewer subagent (experimental; off by default).

933 766 

934Key767Key

935 768 

957 790 

958Key791Key

959 792 

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`793`features.web_search`

973 794 

974Type / Values795Type / Values

1737 1558 

1738Key1559Key

1739 1560 

1561`openai_base_url`

1562 

1563Type / Values

1564 

1565`string`

1566 

1567Details

1568 

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

1570 

1571Key

1572 

1740`oss_provider`1573`oss_provider`

1741 1574 

1742Type / Values1575Type / Values

1953 1786 

1954Key1787Key

1955 1788 

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

1957 1790 

1958Type / Values1791Type / Values

1959 1792 

1960`string`1793`table`

1961 1794 

1962Details1795Details

1963 1796 

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

1965 1798 

1966Key1799Key

1967 1800 

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

1969 1802 

1970Type / Values1803Type / Values

1971 1804 

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

1973 1806 

1974Details1807Details

1975 1808 

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

1977 1810 

1978Key1811Key

1979 1812 

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

1981 1814 

1982Type / Values1815Type / Values

1983 1816 

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

1985 1818 

1986Details1819Details

1987 1820 

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

1989 1822 

1990Key1823Key

1991 1824 

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

1993 1826 

1994Type / Values1827Type / Values

1995 1828 

1997 1830 

1998Details1831Details

1999 1832 

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

2001 1834 

2002Key1835Key

2003 1836 

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

2005 1838 

2006Type / Values1839Type / Values

2007 1840 

2009 1842 

2010Details1843Details

2011 1844 

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

2013 1846 

2014Key1847Key

2015 1848 

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

2017 1850 

2018Type / Values1851Type / Values

2019 1852 

2021 1854 

2022Details1855Details

2023 1856 

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

1858 

1859Key

1860 

1861`permissions.<name>.network.allowed_domains`

1862 

1863Type / Values

1864 

1865`array<string>`

1866 

1867Details

1868 

1869Allowlist of domains permitted through the managed proxy.

2025 1870 

2026Key1871Key

2027 1872 

2028`permissions.network.dangerously_allow_non_loopback_admin`1873`permissions.<name>.network.dangerously_allow_all_unix_sockets`

2029 1874 

2030Type / Values1875Type / Values

2031 1876 

2033 1878 

2034Details1879Details

2035 1880 

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

2037 1882 

2038Key1883Key

2039 1884 

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

2041 1886 

2042Type / Values1887Type / Values

2043 1888 

2049 1894 

2050Key1895Key

2051 1896 

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

2053 1898 

2054Type / Values1899Type / Values

2055 1900 

2061 1906 

2062Key1907Key

2063 1908 

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

2065 1910 

2066Type / Values1911Type / Values

2067 1912 

2069 1914 

2070Details1915Details

2071 1916 

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

2073 1918 

2074Key1919Key

2075 1920 

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

2077 1922 

2078Type / Values1923Type / Values

2079 1924 

2085 1930 

2086Key1931Key

2087 1932 

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

2089 1934 

2090Type / Values1935Type / Values

2091 1936 

2093 1938 

2094Details1939Details

2095 1940 

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

2097 1942 

2098Key1943Key

2099 1944 

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

2101 1946 

2102Type / Values1947Type / Values

2103 1948 

2109 1954 

2110Key1955Key

2111 1956 

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

2113 1958 

2114Type / Values1959Type / Values

2115 1960 

2117 1962 

2118Details1963Details

2119 1964 

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

2121 1966 

2122Key1967Key

2123 1968 

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

2125 1970 

2126Type / Values1971Type / Values

2127 1972 

2129 1974 

2130Details1975Details

2131 1976 

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

2133 1978 

2134Key1979Key

2135 1980 

2441 2286 

2442Details2287Details

2443 2288 

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

2445 2290 

2446Key2291Key

2447 2292 

2617 2462 

2618Type / Values2463Type / Values

2619 2464 

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

2621 2466 

2622Details2467Details

2623 2468 

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

2626Key2471Key

2627 2472 

2767 2612 

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

2769 2614 

2615Key

2616 

2617`windows.sandbox_private_desktop`

2618 

2619Type / Values

2620 

2621`boolean`

2622 

2623Details

2624 

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

2626 

2770Expand to view all2627Expand to view all

2771 2628 

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

2791 2648 

2792| Key | Type / Values | Details |2649| Key | Type / Values | Details |

2793| --- | --- | --- |2650| --- | --- | --- |

2794| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`). |2651| `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`. |2652| `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`. |2653| `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. |2654| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |

2818 2675 

2819Details2676Details

2820 2677 

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

2822 2679 

2823Key2680Key

2824 2681