config-reference.md Codex Docs, 2026-03-13 18:15 UTC → 2026-04-08 18:32 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.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). |53| `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). |54| `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). |55| `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). |56| `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). |57| `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). |58| `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). |59| `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). |60| `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. |61| `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"`. |62| `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"`. |63| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |

106| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |91| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |

107| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |92| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |

108| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |93| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |

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

110| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |95| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |

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

112| `model_context_window` | `number` | Context window tokens available to the active model. |97| `model_context_window` | `number` | Context window tokens available to the active model. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

175| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |162| `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. |182| `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. |183| `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"`. |184| `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. |185| `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. |186| `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. |187| `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. |188| `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. |197| `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. |198| `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`. |199| `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. |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. |

214| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |201| `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). |202| `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). |203| `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. |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. |

224| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |211| `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. |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. |

226 214 

227Key215Key

228 216 

326 314 

327Type / Values315Type / Values

328 316 

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

330 318 

331Details319Details

332 320 

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

334 322 

335Key323Key

336 324 

337`approval_policy.reject.mcp_elicitations`325`approval_policy.granular.mcp_elicitations`

338 326 

339Type / Values327Type / Values

340 328 

342 330 

343Details331Details

344 332 

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

346 334 

347Key335Key

348 336 

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

350 338 

351Type / Values339Type / Values

352 340 

354 342 

355Details343Details

356 344 

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

358 346 

359Key347Key

360 348 

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

362 350 

363Type / Values351Type / Values

364 352 

366 354 

367Details355Details

368 356 

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

370 382 

371Key383Key

372 384 

562 574 

563Key575Key

564 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 

565`developer_instructions`589`developer_instructions`

566 590 

567Type / Values591Type / Values

622 646 

623Key647Key

624 648 

625`features.apps_mcp_gateway`649`features.codex_hooks`

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 650 

687Type / Values651Type / Values

688 652 

690 654 

691Details655Details

692 656 

693Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it.657Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).

694 658 

695Key659Key

696 660 

706 670 

707Key671Key

708 672 

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

722 674 

723Type / Values675Type / Values

730 682 

731Key683Key

732 684 

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`685`features.multi_agent`

758 686 

759Type / Values687Type / Values

762 690 

763Details691Details

764 692 

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

766 694 

767Key695Key

768 696 

778 706 

779Key707Key

780 708 

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

794 710 

795Type / Values711Type / Values

802 718 

803Key719Key

804 720 

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

878 722 

879Type / Values723Type / Values

898 742 

899Key743Key

900 744 

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

914 746 

915Type / Values747Type / Values

922 754 

923Key755Key

924 756 

925`features.sqlite`757`features.smart_approvals`

926 758 

927Type / Values759Type / Values

928 760 

930 762 

931Details763Details

932 764 

933Enable SQLite-backed state persistence (stable; on by default).765Route 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 766 

947Key767Key

948 768 

970 790 

971Key791Key

972 792 

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

986 794 

987Type / Values795Type / Values

1386 1194 

1387Details1195Details

1388 1196 

1389Model to use (e.g., `gpt-5-codex`).1197Model to use (e.g., `gpt-5.4`).

1390 1198 

1391Key1199Key

1392 1200 

1750 1558 

1751Key1559Key

1752 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 

1753`oss_provider`1573`oss_provider`

1754 1574 

1755Type / Values1575Type / Values

1966 1786 

1967Key1787Key

1968 1788 

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

1970 1790 

1971Type / Values1791Type / Values

1972 1792 

1973`string`1793`table`

1974 1794 

1975Details1795Details

1976 1796 

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

1978 1798 

1979Key1799Key

1980 1800 

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

1982 1802 

1983Type / Values1803Type / Values

1984 1804 

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

1986 1806 

1987Details1807Details

1988 1808 

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

1990 1810 

1991Key1811Key

1992 1812 

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

1994 1814 

1995Type / Values1815Type / Values

1996 1816 

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

1998 1818 

1999Details1819Details

2000 1820 

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

2002 1822 

2003Key1823Key

2004 1824 

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

2006 1826 

2007Type / Values1827Type / Values

2008 1828 

2010 1830 

2011Details1831Details

2012 1832 

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

2014 1834 

2015Key1835Key

2016 1836 

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

2018 1838 

2019Type / Values1839Type / Values

2020 1840 

2022 1842 

2023Details1843Details

2024 1844 

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

2026 1846 

2027Key1847Key

2028 1848 

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

2030 1850 

2031Type / Values1851Type / Values

2032 1852 

2034 1854 

2035Details1855Details

2036 1856 

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

2038 1858 

2039Key1859Key

2040 1860 

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

1862 

1863Type / Values

1864 

1865`array<string>`

1866 

1867Details

1868 

1869Allowlist of domains permitted through the managed proxy.

1870 

1871Key

1872 

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

2042 1874 

2043Type / Values1875Type / Values

2044 1876 

2046 1878 

2047Details1879Details

2048 1880 

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

2050 1882 

2051Key1883Key

2052 1884 

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

2054 1886 

2055Type / Values1887Type / Values

2056 1888 

2062 1894 

2063Key1895Key

2064 1896 

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

2066 1898 

2067Type / Values1899Type / Values

2068 1900 

2074 1906 

2075Key1907Key

2076 1908 

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

2078 1910 

2079Type / Values1911Type / Values

2080 1912 

2082 1914 

2083Details1915Details

2084 1916 

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

2086 1918 

2087Key1919Key

2088 1920 

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

2090 1922 

2091Type / Values1923Type / Values

2092 1924 

2098 1930 

2099Key1931Key

2100 1932 

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

2102 1934 

2103Type / Values1935Type / Values

2104 1936 

2106 1938 

2107Details1939Details

2108 1940 

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

2110 1942 

2111Key1943Key

2112 1944 

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

2114 1946 

2115Type / Values1947Type / Values

2116 1948 

2122 1954 

2123Key1955Key

2124 1956 

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

2126 1958 

2127Type / Values1959Type / Values

2128 1960 

2130 1962 

2131Details1963Details

2132 1964 

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

2134 1966 

2135Key1967Key

2136 1968 

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

2138 1970 

2139Type / Values1971Type / Values

2140 1972 

2142 1974 

2143Details1975Details

2144 1976 

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

2146 1978 

2147Key1979Key

2148 1980 

2454 2286 

2455Details2287Details

2456 2288 

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

2458 2290 

2459Key2291Key

2460 2292 

2630 2462 

2631Type / Values2463Type / Values

2632 2464 

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

2634 2466 

2635Details2467Details

2636 2468 

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

2638 2470 

2639Key2471Key

2640 2472 

2780 2612 

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

2782 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 

2783Expand to view all2627Expand to view all

2784 2628 

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

2804 2648 

2805| Key | Type / Values | Details |2649| Key | Type / Values | Details |

2806| --- | --- | --- |2650| --- | --- | --- |

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

2808| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2652| `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`. |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`. |

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

2831 2675 

2832Details2676Details

2833 2677 

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

2835 2679 

2836Key2680Key

2837 2681