config-reference.md Codex Docs, 2026-03-08 00:35 UTC → 2026-03-25 18:24 UTC

15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |

16| `agents.job_max_runtime_seconds` | `number` | Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker. |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| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

226 213 

227Key214Key

228 215 

294 281 

295Details282Details

296 283 

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

298 285 

299Key286Key

300 287 

326 313 

327Type / Values314Type / Values

328 315 

329`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 } }`

330 317 

331Details318Details

332 319 

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

334 321 

335Key322Key

336 323 

337`approval_policy.reject.mcp_elicitations`324`approval_policy.granular.mcp_elicitations`

338 325 

339Type / Values326Type / Values

340 327 

342 329 

343Details330Details

344 331 

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

346 333 

347Key334Key

348 335 

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

350 337 

351Type / Values338Type / Values

352 339 

354 341 

355Details342Details

356 343 

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

358 345 

359Key346Key

360 347 

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

362 349 

363Type / Values350Type / Values

364 351 

366 353 

367Details354Details

368 355 

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

370 381 

371Key382Key

372 383 

562 573 

563Key574Key

564 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 

565`developer_instructions`588`developer_instructions`

566 589 

567Type / Values590Type / Values

622 645 

623Key646Key

624 647 

625`features.apps_mcp_gateway`

626 

627Type / Values

628 

629`boolean`

630 

631Details

632 

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

634 

635Key

636 

637`features.artifact`

638 

639Type / Values

640 

641`boolean`

642 

643Details

644 

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

646 

647Key

648 

649`features.child_agents_md`

650 

651Type / Values

652 

653`boolean`

654 

655Details

656 

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

658 

659Key

660 

661`features.collaboration_modes`

662 

663Type / Values

664 

665`boolean`

666 

667Details

668 

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

670 

671Key

672 

673`features.default_mode_request_user_input`

674 

675Type / Values

676 

677`boolean`

678 

679Details

680 

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

682 

683Key

684 

685`features.elevated_windows_sandbox`

686 

687Type / Values

688 

689`boolean`

690 

691Details

692 

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

694 

695Key

696 

697`features.enable_request_compression`648`features.enable_request_compression`

698 649 

699Type / Values650Type / Values

706 657 

707Key658Key

708 659 

709`features.experimental_windows_sandbox`

710 

711Type / Values

712 

713`boolean`

714 

715Details

716 

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

718 

719Key

720 

721`features.fast_mode`660`features.fast_mode`

722 661 

723Type / Values662Type / Values

730 669 

731Key670Key

732 671 

733`features.image_detail_original`

734 

735Type / Values

736 

737`boolean`

738 

739Details

740 

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

742 

743Key

744 

745`features.image_generation`

746 

747Type / Values

748 

749`boolean`

750 

751Details

752 

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

754 

755Key

756 

757`features.multi_agent`672`features.multi_agent`

758 673 

759Type / Values674Type / Values

762 677 

763Details678Details

764 679 

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

766 681 

767Key682Key

768 683 

778 693 

779Key694Key

780 695 

781`features.powershell_utf8`

782 

783Type / Values

784 

785`boolean`

786 

787Details

788 

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

790 

791Key

792 

793`features.prevent_idle_sleep`696`features.prevent_idle_sleep`

794 697 

795Type / Values698Type / Values

802 705 

803Key706Key

804 707 

805`features.remote_models`

806 

807Type / Values

808 

809`boolean`

810 

811Details

812 

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

814 

815Key

816 

817`features.request_rule`

818 

819Type / Values

820 

821`boolean`

822 

823Details

824 

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

826 

827Key

828 

829`features.responses_websockets`

830 

831Type / Values

832 

833`boolean`

834 

835Details

836 

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

838 

839Key

840 

841`features.responses_websockets_v2`

842 

843Type / Values

844 

845`boolean`

846 

847Details

848 

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

850 

851Key

852 

853`features.runtime_metrics`

854 

855Type / Values

856 

857`boolean`

858 

859Details

860 

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

862 

863Key

864 

865`features.search_tool`

866 

867Type / Values

868 

869`boolean`

870 

871Details

872 

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

874 

875Key

876 

877`features.shell_snapshot`708`features.shell_snapshot`

878 709 

879Type / Values710Type / Values

898 729 

899Key730Key

900 731 

901`features.skill_env_var_dependency_prompt`

902 

903Type / Values

904 

905`boolean`

906 

907Details

908 

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

910 

911Key

912 

913`features.skill_mcp_dependency_install`732`features.skill_mcp_dependency_install`

914 733 

915Type / Values734Type / Values

922 741 

923Key742Key

924 743 

925`features.sqlite`744`features.smart_approvals`

926 745 

927Type / Values746Type / Values

928 747 

930 749 

931Details750Details

932 751 

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

934 

935Key

936 

937`features.steer`

938 

939Type / Values

940 

941`boolean`

942 

943Details

944 

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

946 753 

947Key754Key

948 755 

970 777 

971Key778Key

972 779 

973`features.use_linux_sandbox_bwrap`

974 

975Type / Values

976 

977`boolean`

978 

979Details

980 

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

982 

983Key

984 

985`features.web_search`780`features.web_search`

986 781 

987Type / Values782Type / Values

1750 1545 

1751Key1546Key

1752 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 

1753`oss_provider`1560`oss_provider`

1754 1561 

1755Type / Values1562Type / Values

1966 1773 

1967Key1774Key

1968 1775 

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

1970 1777 

1971Type / Values1778Type / Values

1972 1779 

1973`string`1780`table`

1974 1781 

1975Details1782Details

1976 1783 

1977Admin 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`.

1978 1785 

1979Key1786Key

1980 1787 

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

1982 1789 

1983Type / Values1790Type / Values

1984 1791 

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

1986 1793 

1987Details1794Details

1988 1795 

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

1990 1797 

1991Key1798Key

1992 1799 

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

1994 1801 

1995Type / Values1802Type / Values

1996 1803 

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

1998 1805 

1999Details1806Details

2000 1807 

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

2002 1809 

2003Key1810Key

2004 1811 

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

2006 1813 

2007Type / Values1814Type / Values

2008 1815 

2010 1817 

2011Details1818Details

2012 1819 

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

2014 1821 

2015Key1822Key

2016 1823 

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

2018 1825 

2019Type / Values1826Type / Values

2020 1827 

2022 1829 

2023Details1830Details

2024 1831 

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

2026 1833 

2027Key1834Key

2028 1835 

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

2030 1837 

2031Type / Values1838Type / Values

2032 1839 

2034 1841 

2035Details1842Details

2036 1843 

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

2038 1845 

2039Key1846Key

2040 1847 

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

2042 1861 

2043Type / Values1862Type / Values

2044 1863 

2046 1865 

2047Details1866Details

2048 1867 

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

2050 1869 

2051Key1870Key

2052 1871 

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

2054 1873 

2055Type / Values1874Type / Values

2056 1875 

2062 1881 

2063Key1882Key

2064 1883 

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

2066 1885 

2067Type / Values1886Type / Values

2068 1887 

2074 1893 

2075Key1894Key

2076 1895 

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

2078 1897 

2079Type / Values1898Type / Values

2080 1899 

2082 1901 

2083Details1902Details

2084 1903 

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

2086 1905 

2087Key1906Key

2088 1907 

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

2090 1909 

2091Type / Values1910Type / Values

2092 1911 

2098 1917 

2099Key1918Key

2100 1919 

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

2102 1921 

2103Type / Values1922Type / Values

2104 1923 

2106 1925 

2107Details1926Details

2108 1927 

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

2110 1929 

2111Key1930Key

2112 1931 

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

2114 1933 

2115Type / Values1934Type / Values

2116 1935 

2122 1941 

2123Key1942Key

2124 1943 

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

2126 1945 

2127Type / Values1946Type / Values

2128 1947 

2130 1949 

2131Details1950Details

2132 1951 

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

2134 1953 

2135Key1954Key

2136 1955 

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

2138 1957 

2139Type / Values1958Type / Values

2140 1959 

2142 1961 

2143Details1962Details

2144 1963 

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

2146 1965 

2147Key1966Key

2148 1967 

2454 2273 

2455Details2274Details

2456 2275 

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

2458 2277 

2459Key2278Key

2460 2279 

2630 2449 

2631Type / Values2450Type / Values

2632 2451 

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

2634 2453 

2635Details2454Details

2636 2455 

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

2638 2457 

2639Key2458Key

2640 2459 

2780 2599 

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

2782 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 

2783Expand to view all2614Expand to view all

2784 2615 

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

2804 2635 

2805| Key | Type / Values | Details |2636| Key | Type / Values | Details |

2806| --- | --- | --- |2637| --- | --- | --- |

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

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

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

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

2831 2662 

2832Details2663Details

2833 2664 

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

2835 2666 

2836Key2667Key

2837 2668