config-reference.md Codex Docs, 2026-03-18 00:36 UTC → 2026-04-16 00:46 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. |

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

25| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |28| `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. |29| `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`. |30| `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). |41| `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. |42| `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. |43| `compact_prompt` | `string` | Inline override for the history compaction prompt. |

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

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

42| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |46| `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). |47| `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`. |48| `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). |49| `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). |50| `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). |51| `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). |52| `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). |53| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |

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). |54| `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). |55| `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). |56| `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). |57| `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). |58| `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). |59| `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). |60| `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). |61| `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. |62| `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"`. |63| `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"`. |64| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |

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

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

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

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

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

110| `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. |97| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |

111| `model_context_window` | `number` | Context window tokens available to the active model. |98| `model_context_window` | `number` | Context window tokens available to the active model. |

112| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |99| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |

113| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |100| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |

101| `model_providers.<id>` | `table` | Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden. |

102| `model_providers.<id>.auth` | `table` | Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`. |

103| `model_providers.<id>.auth.args` | `array<string>` | Arguments passed to the token command. |

104| `model_providers.<id>.auth.command` | `string` | Command to run when Codex needs a bearer token. The command must print the token to stdout. |

105| `model_providers.<id>.auth.cwd` | `string (path)` | Working directory for the token command. |

106| `model_providers.<id>.auth.refresh_interval_ms` | `number` | How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry. |

107| `model_providers.<id>.auth.timeout_ms` | `number` | Maximum token command runtime in milliseconds (default: 5000). |

114| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |108| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |

115| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |109| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |

116| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |110| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |

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

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

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

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

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

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

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

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

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

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

157| `permissions.network.admin_url` | `string` | Admin endpoint for the managed network proxy. |152| `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. |153| `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. |154| `permissions.<name>.filesystem.<path>` | `"read" | "write" | "none" | table` | Grant direct access for a path or special token, or scope nested entries under that root. |

160| `permissions.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |155| `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. |156| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

162| `permissions.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |157| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

163| `permissions.network.dangerously_allow_non_loopback_admin` | `boolean` | Permit non-loopback bind addresses for the managed proxy admin listener. |158| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

164| `permissions.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |159| `permissions.<name>.network.domains` | `map<string, allow | deny>` | Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values. |

165| `permissions.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |160| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |

166| `permissions.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener from the managed network proxy. |161| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

167| `permissions.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |162| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |

168| `permissions.network.enabled` | `boolean` | Enable the managed network proxy configuration for subprocesses. |163| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |

169| `permissions.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |164| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |

170| `permissions.network.proxy_url` | `string` | HTTP proxy endpoint used by the managed network proxy. |165| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |

171| `permissions.network.socks_url` | `string` | SOCKS5 proxy endpoint used by the managed network proxy. |166| `permissions.<name>.network.unix_sockets` | `map<string, allow | none>` | Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values. |

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

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. |168| `plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default. |

174| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |169| `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. |189| `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. |190| `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"`. |191| `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. |192| `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. |193| `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. |194| `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. |195| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |

208| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |203| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |

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

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

206| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

211| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |207| `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. |208| `tools.web_search` | `boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }` | Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location. |

213| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |209| `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). |210| `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). |211| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

218| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |214| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |

219| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |215| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |

220| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |216| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

217| `tui.terminal_title` | `array<string> | null` | Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates. |

221| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |218| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |

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. |219| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |

223| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |220| `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. |221| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |

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

225 223 

226Key224Key

227 225 

325 323 

326Type / Values324Type / Values

327 325 

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

329 327 

330Details328Details

331 329 

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.330Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.

333 331 

334Key332Key

335 333 

336`approval_policy.reject.mcp_elicitations`334`approval_policy.granular.mcp_elicitations`

337 335 

338Type / Values336Type / Values

339 337 

341 339 

342Details340Details

343 341 

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

345 343 

346Key344Key

347 345 

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

349 347 

350Type / Values348Type / Values

351 349 

353 351 

354Details352Details

355 353 

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

357 355 

358Key356Key

359 357 

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

361 359 

362Type / Values360Type / Values

363 361 

365 363 

366Details364Details

367 365 

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

367 

368Key

369 

370`approval_policy.granular.sandbox_approval`

371 

372Type / Values

373 

374`boolean`

375 

376Details

377 

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

379 

380Key

381 

382`approval_policy.granular.skill_approval`

383 

384Type / Values

385 

386`boolean`

387 

388Details

389 

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

391 

392Key

393 

394`approvals_reviewer`

395 

396Type / Values

397 

398`user | guardian_subagent`

399 

400Details

401 

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

369 403 

370Key404Key

371 405 

561 595 

562Key596Key

563 597 

598`default_permissions`

599 

600Type / Values

601 

602`string`

603 

604Details

605 

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

607 

608Key

609 

564`developer_instructions`610`developer_instructions`

565 611 

566Type / Values612Type / Values

621 667 

622Key668Key

623 669 

624`features.apps_mcp_gateway`670`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 

638Type / Values

639 

640`boolean`

641 

642Details

643 

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

645 

646Key

647 

648`features.child_agents_md`

649 

650Type / Values

651 

652`boolean`

653 

654Details

655 

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

657 

658Key

659 

660`features.collaboration_modes`

661 

662Type / Values

663 

664`boolean`

665 

666Details

667 

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

669 

670Key

671 

672`features.default_mode_request_user_input`

673 

674Type / Values

675 

676`boolean`

677 

678Details

679 

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

681 

682Key

683 

684`features.elevated_windows_sandbox`

685 671 

686Type / Values672Type / Values

687 673 

689 675 

690Details676Details

691 677 

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

693 679 

694Key680Key

695 681 

705 691 

706Key692Key

707 693 

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

721 695 

722Type / Values696Type / Values

729 703 

730Key704Key

731 705 

732`features.image_detail_original`706`features.multi_agent`

733 

734Type / Values

735 

736`boolean`

737 

738Details

739 

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

741 

742Key

743 

744`features.image_generation`

745 707 

746Type / Values708Type / Values

747 709 

749 711 

750Details712Details

751 713 

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

753 715 

754Key716Key

755 717 

765 727 

766Key728Key

767 729 

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

781 731 

782Type / Values732Type / Values

789 739 

790Key740Key

791 741 

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

865 743 

866Type / Values744Type / Values

885 763 

886Key764Key

887 765 

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

901 767 

902Type / Values768Type / Values

909 775 

910Key776Key

911 777 

912`features.sqlite`778`features.smart_approvals`

913 779 

914Type / Values780Type / Values

915 781 

917 783 

918Details784Details

919 785 

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

921 

922Key

923 

924`features.steer`

925 

926Type / Values

927 

928`boolean`

929 

930Details

931 

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

933 787 

934Key788Key

935 789 

957 811 

958Key812Key

959 813 

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

973 815 

974Type / Values816Type / Values

1373 1215 

1374Details1216Details

1375 1217 

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

1377 1219 

1378Key1220Key

1379 1221 

1437 1279 

1438Key1280Key

1439 1281 

1282`model_providers.<id>`

1283 

1284Type / Values

1285 

1286`table`

1287 

1288Details

1289 

1290Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.

1291 

1292Key

1293 

1294`model_providers.<id>.auth`

1295 

1296Type / Values

1297 

1298`table`

1299 

1300Details

1301 

1302Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.

1303 

1304Key

1305 

1306`model_providers.<id>.auth.args`

1307 

1308Type / Values

1309 

1310`array<string>`

1311 

1312Details

1313 

1314Arguments passed to the token command.

1315 

1316Key

1317 

1318`model_providers.<id>.auth.command`

1319 

1320Type / Values

1321 

1322`string`

1323 

1324Details

1325 

1326Command to run when Codex needs a bearer token. The command must print the token to stdout.

1327 

1328Key

1329 

1330`model_providers.<id>.auth.cwd`

1331 

1332Type / Values

1333 

1334`string (path)`

1335 

1336Details

1337 

1338Working directory for the token command.

1339 

1340Key

1341 

1342`model_providers.<id>.auth.refresh_interval_ms`

1343 

1344Type / Values

1345 

1346`number`

1347 

1348Details

1349 

1350How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.

1351 

1352Key

1353 

1354`model_providers.<id>.auth.timeout_ms`

1355 

1356Type / Values

1357 

1358`number`

1359 

1360Details

1361 

1362Maximum token command runtime in milliseconds (default: 5000).

1363 

1364Key

1365 

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

1441 1367 

1442Type / Values1368Type / Values

1737 1663 

1738Key1664Key

1739 1665 

1666`openai_base_url`

1667 

1668Type / Values

1669 

1670`string`

1671 

1672Details

1673 

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

1675 

1676Key

1677 

1740`oss_provider`1678`oss_provider`

1741 1679 

1742Type / Values1680Type / Values

1953 1891 

1954Key1892Key

1955 1893 

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

1957 1895 

1958Type / Values1896Type / Values

1959 1897 

1960`string`1898`table`

1961 1899 

1962Details1900Details

1963 1901 

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

1965 1903 

1966Key1904Key

1967 1905 

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

1969 1907 

1970Type / Values1908Type / Values

1971 1909 

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

1973 1911 

1974Details1912Details

1975 1913 

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

1977 1915 

1978Key1916Key

1979 1917 

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

1981 1919 

1982Type / Values1920Type / Values

1983 1921 

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

1985 1923 

1986Details1924Details

1987 1925 

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

1989 1927 

1990Key1928Key

1991 1929 

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

1993 1931 

1994Type / Values1932Type / Values

1995 1933 

1997 1935 

1998Details1936Details

1999 1937 

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

2001 1939 

2002Key1940Key

2003 1941 

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

2005 1943 

2006Type / Values1944Type / Values

2007 1945 

2008`array<string>`1946`boolean`

2009 1947 

2010Details1948Details

2011 1949 

2012Allowlist of domains permitted through the managed proxy.1950Allow the managed proxy to chain to another upstream proxy.

2013 1951 

2014Key1952Key

2015 1953 

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

2017 1955 

2018Type / Values1956Type / Values

2019 1957 

2025 1963 

2026Key1964Key

2027 1965 

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

2029 1967 

2030Type / Values1968Type / Values

2031 1969 

2033 1971 

2034Details1972Details

2035 1973 

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

2037 1975 

2038Key1976Key

2039 1977 

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

2041 1979 

2042Type / Values1980Type / Values

2043 1981 

2044`boolean`1982`map<string, allow | deny>`

2045 1983 

2046Details1984Details

2047 1985 

2048Permit non-loopback bind addresses for the managed proxy listener.1986Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values.

2049 1987 

2050Key1988Key

2051 1989 

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

2053 1991 

2054Type / Values1992Type / Values

2055 1993 

2056`array<string>`1994`boolean`

2057 1995 

2058Details1996Details

2059 1997 

2060Denylist of domains blocked by the managed proxy.1998Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.

2061 1999 

2062Key2000Key

2063 2001 

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

2065 2003 

2066Type / Values2004Type / Values

2067 2005 

2069 2007 

2070Details2008Details

2071 2009 

2072Expose a SOCKS5 listener from the managed network proxy.2010Allow UDP over the SOCKS5 listener when enabled.

2073 2011 

2074Key2012Key

2075 2013 

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

2077 2015 

2078Type / Values2016Type / Values

2079 2017 

2081 2019 

2082Details2020Details

2083 2021 

2084Allow UDP over the SOCKS5 listener when enabled.2022Enable network access for this named permissions profile.

2085 2023 

2086Key2024Key

2087 2025 

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

2089 2027 

2090Type / Values2028Type / Values

2091 2029 

2092`boolean`2030`limited | full`

2093 2031 

2094Details2032Details

2095 2033 

2096Enable the managed network proxy configuration for subprocesses.2034Network proxy mode used for subprocess traffic.

2097 2035 

2098Key2036Key

2099 2037 

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

2101 2039 

2102Type / Values2040Type / Values

2103 2041 

2104`limited | full`2042`string`

2105 2043 

2106Details2044Details

2107 2045 

2108Network proxy mode used for subprocess traffic.2046HTTP proxy endpoint used when this permissions profile enables the managed network proxy.

2109 2047 

2110Key2048Key

2111 2049 

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

2113 2051 

2114Type / Values2052Type / Values

2115 2053 

2117 2055 

2118Details2056Details

2119 2057 

2120HTTP proxy endpoint used by the managed network proxy.2058SOCKS5 proxy endpoint used by this permissions profile.

2121 2059 

2122Key2060Key

2123 2061 

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

2125 2063 

2126Type / Values2064Type / Values

2127 2065 

2128`string`2066`map<string, allow | none>`

2129 2067 

2130Details2068Details

2131 2069 

2132SOCKS5 proxy endpoint used by the managed network proxy.2070Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values.

2133 2071 

2134Key2072Key

2135 2073 

2441 2379 

2442Details2380Details

2443 2381 

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

2445 2383 

2446Key2384Key

2447 2385 

2601 2539 

2602Key2540Key

2603 2541 

2542`tool_suggest.discoverables`

2543 

2544Type / Values

2545 

2546`array<table>`

2547 

2548Details

2549 

2550Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.

2551 

2552Key

2553 

2604`tools.view_image`2554`tools.view_image`

2605 2555 

2606Type / Values2556Type / Values

2617 2567 

2618Type / Values2568Type / Values

2619 2569 

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

2621 2571 

2622Details2572Details

2623 2573 

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

2626Key2576Key

2627 2577 

2721 2671 

2722Key2672Key

2723 2673 

2674`tui.terminal_title`

2675 

2676Type / Values

2677 

2678`array<string> | null`

2679 

2680Details

2681 

2682Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates.

2683 

2684Key

2685 

2724`tui.theme`2686`tui.theme`

2725 2687 

2726Type / Values2688Type / Values

2767 2729 

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

2769 2731 

2732Key

2733 

2734`windows.sandbox_private_desktop`

2735 

2736Type / Values

2737 

2738`boolean`

2739 

2740Details

2741 

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

2743 

2770Expand to view all2744Expand to view all

2771 2745 

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

2791 2765 

2792| Key | Type / Values | Details |2766| Key | Type / Values | Details |

2793| --- | --- | --- |2767| --- | --- | --- |

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

2769| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer` (for example `user` and `guardian_subagent`). |

2795| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2770| `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`. |2771| `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. |2772| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |

2818 2793 

2819Details2794Details

2820 2795 

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

2797 

2798Key

2799 

2800`allowed_approvals_reviewers`

2801 

2802Type / Values

2803 

2804`array<string>`

2805 

2806Details

2807 

2808Allowed values for `approvals_reviewer` (for example `user` and `guardian_subagent`).

2822 2809 

2823Key2810Key

2824 2811