Codex CLI config.toml settings

Multi-agent settings and custom role declarations.

table

Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.

string (path)

Role guidance shown to Codex when choosing and spawning that agent type.

string

Default model for spawned agents. An explicit spawn model takes precedence.

string

Default reasoning effort for spawned agents.

string

Enable or disable multi-agent tools (default: true).

boolean

Record a model-visible message when an agent turn is interrupted (default: true).

boolean

Maximum number of spawned-agent threads that can be open concurrently, excluding the primary thread.

number

Legacy alias for agents.max_concurrent_threads_per_session.

number

Allow shell-based tools to use login-shell semantics.

boolean

Enable or disable analytics for this machine/profile.

boolean

Controls when Codex pauses for approval before executing commands.

on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }

When true, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

boolean

When true, prompts from the request_permissions tool are allowed to surface.

boolean

When true, approvals triggered by execpolicy prompt rules are allowed to surface.

boolean

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

boolean

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

boolean

Who reviews eligible approval prompts under on-request or granular approval policies.

user | auto_review

Default reviewer for app tool approval prompts unless overridden per app.

user | auto_review

Default approval behavior for app tools without per-app or per-tool overrides.

auto | prompt | writes | approve

Default allow/deny for app tools with destructive_hint = true.

boolean

Default app enabled state for all apps unless overridden per app.

boolean

Default allow/deny for app tools with open_world_hint = true.

boolean

Reviewer for this app's tool approval prompts.

user | auto_review

Default approval behavior for tools in this app unless a per-tool override exists.

auto | prompt | writes | approve

Default enabled state for tools in this app unless a per-tool override exists.

boolean

Allow or block tools in this app that advertise destructive_hint = true.

boolean

Enable or disable a specific app/connector by id (default: true).

boolean

Allow or block tools in this app that advertise open_world_hint = true.

boolean

Per-tool approval behavior override for a single app tool.

auto | prompt | writes | approve

Per-tool enabled override for an app tool (for example repos/list).

boolean

Additional local Markdown policy for automatic review, included alongside the main policy.

string

Local Markdown policy instructions for automatic review.

string

Maximum poll window in milliseconds for empty write_stdin polls (background terminal polling).

number

Set to false to restrict browser-history access.

boolean

Fallback browser-origin restrictions. Supports access, uploads, downloads, and full_cdp_access, each set to allow or deny.

table

Per-origin browser restrictions with the same fields as browser_use.default_origin_policy.

table

Override the base URL used during the ChatGPT login flow.

string

Check for Codex updates on startup (set to false only when updates are centrally managed).

boolean

Control where the CLI stores cached credentials.

file | keyring | auto | ephemeral

Inline override for the history compaction prompt.

string

Fallback native-app access policy for Computer Use.

allow | deny

Native macOS app access keyed by bundle identifier.

map<string, allow | deny>

Windows app identifiers that Computer Use can open without prompting.

array<string>

Packaged Windows app access keyed by Application User Model ID (AUMID).

map<string, allow | deny>

Windows executable access rules. Each rule requires publisher_name, product_name, and access (allow or deny); binary_name is optional.

array<table>

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

string

User-level only. Defines an additional **Open in** target for the ChatGPT desktop app.

table

Arguments inserted between the command and file input (default: []).

array<string>

Executable path or command name to detect and launch.

string

Bundled asset path, Base64-encoded data:image/... URL, file URI, or absolute local path for the handler icon.

string

How the app sends file input to the handler (default: path).

path | json_argument | json_stdin

Display name shown in **Open in** menus.

string

Offer the handler for files in SSH workspaces (default: false).

boolean

Additional developer instructions injected into the session (optional).

string

Legacy fallback for tui.disable_paste_burst.

boolean

Load the compaction prompt override from a file (experimental).

string (path)

Legacy name for enabling unified exec; prefer [features].unified_exec or codex --enable unified_exec.

boolean

Enable app (connector) integrations (stable; on by default).

boolean

Tool namespaces code mode can use only through direct tool calls.

array<string>

Enable code mode feature configuration. This feature is under development and off by default.

boolean

Tool namespaces code mode excludes from nested code-mode tool guidance and executor exposure.

array<string>

Experimental context-management setting.

boolean

Compress streaming request bodies with zstd when supported (stable; on by default).

boolean

Enable Fast mode controls advertised by the active model (stable; on by default), independently of features.ultrafast_mode.

boolean

Enable persisted goals and automatic continuation (stable; on by default).

boolean

Enable lifecycle hooks loaded from hooks.json or inline [hooks] config.

boolean

Enable Memories (off by default).

boolean

Enable multi-agent collaboration tools (spawn_agent, send_input, resume_agent, wait_agent, and close_agent) (stable; on by default).

boolean

Start the network proxy for sandboxed commands (experimental; off by default).

boolean | table

Allow broader local/private-network access.

boolean

Allow chaining through an upstream proxy from the environment.

boolean

Permit arbitrary Unix socket destinations instead of allowlist-only access.

boolean

Permit non-loopback listener addresses. Defaults to false; enabling it can expose proxy listeners beyond localhost.

boolean

Domain policy for sandboxed networking. Unset by default, which means no external destinations are allowed until you add allow rules.

map<string, allow | deny>

Expose SOCKS5 support. Defaults to true.

boolean

Allow UDP over SOCKS5. Defaults to true.

boolean

Start the sandboxed-command network proxy when command network access is enabled.

boolean

HTTP listener URL for sandboxed networking.

string

SOCKS5 listener URL. Defaults to "http://127.0.0.1:8081".

string

Unix socket policy for sandboxed networking.

map<string, allow | deny>

Removed feature flag. Accepted for compatibility and ignored.

boolean

Prefer MXC for local Windows execution when native capabilities and policy allow it; otherwise retain the configured legacy sandbox and setup.

boolean

Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

boolean

Enable the remote plugin catalog (stable; on by default).

boolean

Enable rollout budget tracking. This feature is under development and off by default.

boolean

Positive token limit for rollout budget tracking.

integer

Finite non-negative multiplier for prefill tokens in rollout budget accounting.

number

Positive token interval between rollout budget reminders.

integer

Finite non-negative multiplier for sampled tokens in rollout budget accounting.

number

Snapshot shell environment to speed up repeated commands (stable; on by default).

boolean

Enable command execution tools (stable; on by default).

boolean

Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

boolean

Enable Ultrafast mode controls (stable; on by default), independently of features.fast_mode.

boolean

Use resumable command execution (stable; enabled on all platforms).

boolean

Deprecated legacy toggle; prefer the top-level web_search setting.

boolean

Deprecated legacy toggle. When web_search is unset, true maps to web_search = "cached".

boolean

Deprecated legacy toggle. When web_search is unset, true maps to web_search = "live".

boolean

Enable feedback submission via /feedback across local clients (default: true).

boolean

URI scheme used to open citations from Codex output (default: vscode).

vscode | vscode-insiders | windsurf | cursor | none

Limit ChatGPT logins to a specific workspace identifier.

string (uuid)

Restrict Codex to a specific authentication method.

chatgpt | api

Suppress reasoning events in both the TUI and codex exec output.

boolean

If set, caps the history file size in bytes by dropping oldest entries.

number

Control whether Codex saves session transcripts to history.jsonl.

save-all | none

Lifecycle hooks configured inline in config.toml.

table

Matcher groups for hook events such as PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SessionStart, SessionEnd, SubagentStart, SubagentStop, UserPromptSubmit, Stop, or Interrupt.

array<table>

Hook handlers for a matcher group. Command and MCP tool hooks are supported while prompt and agent hook handlers are parsed but skipped.

array<table>

Approximate per-handler token threshold for saving oversized additionalContext to disk and showing the model a shorter preview.

integer

Run a command hook in the background without delaying the triggering operation.

boolean

Windows-only command override for command hooks.

string

Reserved for future use; prefer model_instructions_file or AGENTS.md.

string

Directory where Codex writes log files; defaults to $CODEX_HOME/log.

string (path)

Optional Git branch, tag, or commit for the marketplace.

string

Git repository location or local marketplace root directory.

string

Source kind for a configured plugin marketplace.

git | local

Optional sparse checkout paths for a Git marketplace.

array<string>

Optional global fixed port for the local HTTP callback server used during MCP OAuth login.

integer

Optional base callback URL for MCP OAuth login, such as a devbox ingress URL.

string

Preferred store for MCP OAuth credentials.

auto | file | keyring

Shared wait for optional MCP servers when building the initial tool catalog.

integer (milliseconds)

Arguments passed to the MCP stdio server command.

array<string>

Authentication fallback for an MCP HTTP server after configured bearer tokens and authorization headers.

oauth | chatgpt

Environment variable sourcing the bearer token for an MCP HTTP server.

string

Launcher command for an MCP stdio server.

string

Working directory for the MCP stdio server process.

string

Default approval behavior for MCP tools on this server unless a per-tool override exists.

auto | prompt | writes | approve

Deny list applied after enabled_tools for the MCP server.

array<string>

Disable an MCP server without removing its configuration.

boolean

Allow list of tool names exposed by the MCP server.

array<string>

Environment variables forwarded to the MCP stdio server.

map<string,string>

HTTP headers populated from environment variables for an MCP HTTP server.

map<string,string>

Additional environment variables to whitelist for an MCP stdio server.

array<string | { name = string, source = "local" | "remote" }>

Experimental placement for an MCP server.

local | remote

Static HTTP headers included with each MCP HTTP request.

map<string,string>

Local command that prints a JSON object of HTTP header names and values.

string (command)

Optional RFC 8707 OAuth resource parameter to include during MCP login.

string

Fixed OAuth callback listener port for this MCP server.

integer

Server-specific OAuth callback. Pre-registered clients reuse it when issuer identification is supported or the URL already ends in the server-specific callback ID.

string

Pre-registered OAuth client ID used for authorization and token exchange with this MCP server.

string

OAuth client secret for token exchange with a pre-registered client.

string

When true, fail startup/resume if this enabled MCP server cannot initialize.

boolean

OAuth scopes to request when authenticating to that MCP server.

array<string>

Alias for startup_timeout_sec in milliseconds.

number

Override the default 10s startup timeout for an MCP server.

number

Override the default 60s per-tool timeout for an MCP server.

number

Per-tool approval behavior override for one MCP tool on this server.

auto | prompt | writes | approve

Token budget for one MCP tool's output, before the standard 20% serialization allowance.

integer (positive)

Endpoint for an MCP streamable HTTP server.

string

Optional model override for global memory consolidation.

string

When true, threads that use external context such as MCP tool calls, web search, or tool search are kept out of memory generation.

boolean

Optional model override for per-thread memory extraction.

string

When false, newly created threads are not stored as memory-generation inputs.

boolean

Maximum recent raw memories retained for global consolidation.

number

Maximum age of threads considered for memory generation.

number

Maximum rollout candidates processed per startup pass.

number

Maximum days since a memory was last used before it becomes ineligible for consolidation.

number

Minimum remaining percentage required in Codex rate-limit windows before memory generation starts.

number

Minimum idle time before a thread is considered for memory generation.

number

When false, Codex skips injecting existing memories into future sessions.

boolean

Model to use (e.g., gpt-6.1-sol).

string

Token threshold that triggers automatic history compaction (unset uses model defaults).

number

Controls whether the auto-compaction threshold counts the full active context (total, the default) or only growth after the carried compaction-window prefix (body_after_prefix).

total | body_after_prefix

Optional path to a JSON model catalog loaded on startup.

string (path)

Context window tokens available to the active model.

number

Replacement for built-in instructions instead of AGENTS.md.

string (path)

Provider id from model_providers (default: openai).

string

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

table

Command-backed bearer token configuration for a custom provider.

table

Arguments passed to the token command.

array<string>

Command to run when Codex needs a bearer token.

string

Working directory for the token command.

string (path)

How often Codex proactively refreshes the token in milliseconds (default: 300000).

number

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

number

API base URL for the model provider.

string

Whether the provider's hosted web search can access the live web.

boolean

Provider compaction protocol. unsupported uses local compaction; v2 sends compaction triggers through Responses.

unsupported | v2

HTTP headers populated from environment variables when present.

map<string,string>

Environment variable supplying the provider API key.

string

Optional setup guidance for the provider API key.

string

Direct bearer token for the provider (discouraged; use env_key).

string

Static HTTP headers added to provider requests.

map<string,string>

Full URL for a Codex-native model catalog.

string

Display name for a custom model provider.

string

Extra query parameters appended to provider requests.

map<string,string>

Retry count for HTTP requests to the provider (default: 4).

number

The provider uses OpenAI authentication (defaults to false).

boolean

Idle timeout for SSE streams in milliseconds (default: 300000).

number

Retry count for SSE streaming interruptions (default: 5).

number

Advertise support for a compatible standalone web search endpoint (default: false).

boolean

Whether that provider supports the Responses API WebSocket transport.

boolean

Protocol used by the provider. responses is the only supported value, and it is the default when omitted.

responses

AWS profile name used by the built-in amazon-bedrock provider.

string

AWS region used by the built-in amazon-bedrock provider.

string

Reasoning effort advertised by the selected model, such as low, medium, high, xhigh, max, or ultra.

string

Select reasoning summary detail or disable summaries entirely.

auto | concise | detailed | none

Force Codex to send or not send reasoning metadata.

boolean

Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.

low | medium | high

Track acknowledgement of the full access warning prompt.

boolean

Track acknowledgement of the gpt-5.1-codex-max migration prompt.

boolean

Track acknowledgement of the GPT-5.1 migration prompt.

boolean

Track opt-out of the rate limit model switch reminder.

boolean

Track acknowledgement of the Windows world-writable directories warning.

boolean

Track acknowledged model migrations as old->new mappings.

map<string,string>

Command invoked for notifications; receives a JSON payload from Codex.

array<string>

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

string

Default local provider used when running with --oss (defaults to prompting if unset).

lmstudio | ollama

Environment tag applied to emitted OpenTelemetry events (default: dev).

string

Select the OpenTelemetry exporter and provide any endpoint metadata.

none | otlp-http | otlp-grpc

Exporter endpoint for OTEL logs.

string

Static headers included with OTEL exporter requests.

map<string,string>

Protocol used by the OTLP/HTTP exporter.

binary | json

CA certificate path for OTEL exporter TLS.

string

Client certificate path for OTEL exporter TLS.

string

Client private key path for OTEL exporter TLS.

string

Opt in to exporting raw user prompts with OpenTelemetry logs.

boolean

Select the OpenTelemetry metrics exporter (defaults to statsig).

none | statsig | otlp-http | otlp-grpc

Select the OpenTelemetry trace exporter and provide any endpoint metadata.

none | otlp-http | otlp-grpc

Trace exporter endpoint for OTEL logs.

string

Static headers included with OTEL trace exporter requests.

map<string,string>

Protocol used by the OTLP/HTTP trace exporter.

binary | json

CA certificate path for OTEL trace exporter TLS.

string

Client certificate path for OTEL trace exporter TLS.

string

Client private key path for OTEL trace exporter TLS.

string

Human-readable description for this named profile.

string

Optional parent profile applied before this named profile.

string

Named filesystem permission profile. Each key is an absolute path or special token such as :minimal or :workspace_roots.

table

Scoped filesystem access relative to each effective workspace root.

"read" | "write" | "deny"

Grant direct access for a path, glob pattern, or special token, or scope nested entries under that root.

"read" | "write" | "deny" | table

Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup.

number

Permit broader local/private-network access through sandboxed networking.

boolean

Allow sandboxed networking to chain through another upstream proxy.

boolean

Allow arbitrary Unix socket destinations instead of the default restricted set.

boolean

Permit non-loopback bind addresses for sandboxed networking listeners.

boolean

Domain rules for sandboxed commands. Enforced only when features.network_proxy or enabled administrator-managed networking requirements activate the proxy.

table

Allow or deny an exact host or scoped wildcard pattern such as *.example.com or **.example.com.

allow | deny

Expose SOCKS5 support when this permissions profile enables sandboxed networking.

boolean

Allow UDP over the SOCKS5 listener when enabled.

boolean

Enable network access for commands in this permission profile.

boolean

Network proxy mode used for subprocess traffic.

limited | full

HTTP listener URL used when this permissions profile enables sandboxed networking.

string

SOCKS5 proxy endpoint used by this permissions profile.

string

Unix socket allowlist overrides for sandboxed networking.

table

Add an absolute Unix socket path to the effective allowlist with allow, or reject it with deny.

allow | deny

Profile-defined workspace roots that receive :workspace_roots filesystem rules alongside the session's runtime workspace roots.

table

Opt a path into the profile's workspace root set when true.

boolean

Deprecated compatibility setting. friendly and pragmatic no longer select a style.

none | friendly | pragmatic

Plan-mode-specific reasoning override using a level supported by the selected model.

string

Enable or disable a local-marketplace plugin using a plugin-name@marketplace-name key.

boolean

Default approval behavior for tools on a plugin-provided MCP server.

auto | prompt | writes | approve

Deny list applied after enabled_tools for a plugin-provided MCP server.

array<string>

Enable or disable an MCP server bundled by an installed plugin without changing the plugin manifest.

boolean

Allow list of tools exposed from a plugin-provided MCP server.

array<string>

Per-tool approval behavior override for a plugin-provided MCP tool.

auto | prompt | writes | approve

Additional filenames to try when AGENTS.md is missing.

array<string>

Maximum bytes read from AGENTS.md when building project instructions.

number

List of project root marker filenames; used when searching parent directories for the project root.

array<string>

Mark a project or worktree as trusted or untrusted ("trusted" | "untrusted"). Untrusted projects skip project-scoped .codex/ layers, including project-local config, hooks, and rules.

string

Optional model override used by /review (defaults to the current session model).

string

Sandbox policy for filesystem and network access during command execution.

read-only | workspace-write | danger-full-access

Exclude /tmp from writable roots in workspace-write mode.

boolean

Exclude $TMPDIR from writable roots in workspace-write mode.

boolean

Allow outbound network access inside the workspace-write sandbox.

boolean

Additional writable roots when sandbox_mode = "workspace-write".

array<string>

Preferred service tier for new turns. Use fast or another tier advertised by the active model; fast maps to the request value priority.

string

Legacy environment-variable exclusion patterns.

array<string>

Use the user shell profile when spawning subprocesses.

boolean

Canonical case-insensitive environment-variable pattern filters.

map<string, include | exclude>

Keep variables containing KEY, SECRET, or TOKEN before other filters run (default: true).

boolean

Legacy allowlist of environment-variable patterns.

array<string>

Baseline environment inheritance when spawning subprocesses.

all | core | none

Explicit environment values injected after exclusions; include filters can still remove them.

map<string,string>

Surface raw reasoning content when the active model emits it.

boolean

Per-skill enablement overrides stored in config.toml.

array<object>

Enable or disable the referenced skill.

boolean

Path to a skill folder containing SKILL.md.

string (path)

Token budget for the available-skills catalog.

integer (positive)

Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.

string (path)

Suppress the warning that appears when under-development feature flags are enabled.

boolean

Token budget for storing individual tool/function outputs in history.

number

Disable suggestions for specific discoverable connectors or plugins.

array<table>

Allow tool suggestions for additional discoverable connectors or plugins.

array<table>

Enable the local-image attachment tool view_image.

boolean

Optional web search tool configuration. The object form can set search context size, allowed search domains, and approximate user location.

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

TUI-specific options such as enabling inline desktop notifications.

table

Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).

auto | always | never

Enable terminal animations (welcome screen, shimmer, spinner) (default: true).

boolean

Generate automatic conversation recaps while the terminal is unfocused (default: true).

boolean

Disable burst-paste detection in the TUI (default: false).

boolean

Keyboard shortcut binding for a TUI action. Supported contexts include global, chat, composer, editor, vim_normal, vim_operator, vim_text_object, pager, list, and approval.

string | array<string>

Unbind the action in that keymap context. Key names use normalized strings such as ctrl-a, shift-enter, page-down, or minus.

empty array

Internal startup-tooltip state keyed by model slug.

integer

Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus.

unfocused | always

Notification method for terminal notifications (default: auto).

auto | osc9 | bel

Enable TUI notifications; optionally restrict to specific event types.

boolean | array<string>

Start the TUI in raw scrollback mode for copy-friendly terminal selection (default: false).

boolean

Working directory to use when resuming or forking a session.

current | session

Show informational notices about connected app-server version differences (default: true).

boolean

Show onboarding tooltips in the TUI welcome screen (default: true).

boolean

Ordered list of TUI footer status-line item identifiers. null disables the status line.

array<string> | null

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

array<string> | null

Syntax-highlighting theme override (kebab-case theme name).

string

Start the composer in Vim normal mode instead of insert mode (default: false). You can still toggle it per session with /vim.

boolean

Web search mode (default: "cached"; cached uses an OpenAI-maintained index without external web access; indexed permits external access only when gated by the search index; if you use --yolo or another full access sandbox setting, it defaults to "live").

disabled | cached | indexed | live

Track Windows onboarding acknowledgement (Windows only).

boolean

Native Windows sandbox implementation. Explicit mxc selection fails when MXC is unavailable or prohibited by managed requirements.

mxc | elevated | unelevated

requirements.toml: Managed developer instructions added as a separate developer message. Codex rejects instructions that exceed a limit of 10,000 estimated tokens, including context markers.

string

requirements.toml: Set to false to disable Appshots for managed users.

boolean

requirements.toml: Set to false to block both agent-driven Browser Use and native-app Computer Use.

boolean

requirements.toml: Enforce whether shell tools can start a login shell.

boolean

requirements.toml: When true, Codex skips user, project, session, and plugin hooks while still allowing managed hooks from requirements.toml and other managed config layers.

boolean

requirements.toml: Set to false to disable device remote control for managed users.

boolean

requirements.toml: Allowed approval policies, such as on-request, never, and granular.

array<string>

requirements.toml: Allowed values for approvals_reviewer, such as user and auto_review.

array<string>

requirements.toml: Restrict ChatGPT login, including Codex access tokens, to the listed workspace IDs.

array<string>

requirements.toml: Allow chatgpt, api, or both. If omitted, this setting doesn't restrict login methods.

array<string>

requirements.toml: Complete list of allowed permission profiles.

table<boolean>

requirements.toml: Allow or deny a built-in or custom permission profile defined in a loaded config or requirements source.

boolean

requirements.toml: Allowed values for sandbox_mode.

array<string>

requirements.toml: Allowed values for web_search (disabled, cached, indexed, live).

array<string>

requirements.toml: Managed desktop application requirements.

table

requirements.toml: Destination restrictions for desktop app network requests, separate from command networking and browser origin rules.

table

requirements.toml: Exact domain rules for desktop app requests.

table<allow | deny>

requirements.toml: Allow or deny an exact domain. Use domain names without URL schemes, ports, or wildcards.

allow | deny

requirements.toml: Defaults to true when the table is present. When true, external desktop app requests require an explicitly allowed domain.

boolean

requirements.toml: Managed app requirements keyed by app identifier.

table

requirements.toml: Set to false to disable an app. A disabled requirement remains restrictive when multiple requirements sources are merged.

boolean

requirements.toml: Set the managed approval mode for one app tool.

auto | prompt | writes | approve

requirements.toml: Managed automatic-review requirements.

table

requirements.toml: Full model slugs for which Codex ignores allow prefix rules in command execution policy.

array<string>

requirements.toml: Model slugs that must use automatic review.

array<string>

requirements.toml: Managed requirements for agent-driven Browser Use.

table

requirements.toml: Set to false to prevent Browser Use from creating or honoring Always allow approvals that cover every site, such as allowing downloads from any site.

boolean

requirements.toml: Set to false to prevent Browser Use from reading browser history.

boolean

requirements.toml: Set to true to opt the desktop app's built-in browser into site tools (WebMCP).

boolean

requirements.toml: Fallback for each Browser Use setting when no matching entry under browser_use.origins defines it.

table

requirements.toml: Use deny to block Browser Use on origins that use the fallback.

allow | deny

requirements.toml: Set how long a non-persistent site-access approval lasts: turn limits it to the current turn, and thread keeps it for the rest of the current thread.

turn | thread

requirements.toml: Use deny to skip automatic review on origins that use the fallback and ask the user for approval instead.

allow | deny

requirements.toml: Use deny to block Browser Use downloads on origins that use the fallback.

allow | deny

requirements.toml: Use deny to block full Chrome DevTools Protocol (CDP) access on origins that use the fallback.

allow | deny

requirements.toml: Set to false to prevent Browser Use from saving or honoring an Always allow approval on origins that use the fallback.

boolean

requirements.toml: Use deny to block Browser Use uploads on origins that use the fallback.

allow | deny

requirements.toml: Set to true to skip automatic review for Browser Use and ask the user for approval instead.

boolean

requirements.toml: Origin-specific Browser Use policies. Keys use <scheme>://<host-pattern>[:<port>] with http or https.

map<string, table>

requirements.toml: Policy for origins matching this pattern.

table

requirements.toml: Use deny to block Browser Use on matching origins.

allow | deny

requirements.toml: Set how long a non-persistent site-access approval for matching origins lasts: turn limits it to the current turn, and thread keeps it for the rest of the current thread.

turn | thread

requirements.toml: Use deny to skip automatic review on matching origins and ask the user for approval instead.

allow | deny

requirements.toml: Use deny to block Browser Use downloads on matching origins.

allow | deny

requirements.toml: Use deny to block full Chrome DevTools Protocol (CDP) access on matching origins.

allow | deny

requirements.toml: Set to false to prevent Browser Use from saving or honoring an Always allow approval on matching origins.

boolean

requirements.toml: Use deny to block Browser Use uploads on matching origins.

allow | deny

requirements.toml: Enforce the ChatGPT service base URL before authentication and cloud-policy retrieval.

string

requirements.toml: Enforce whether Codex checks for updates when it starts.

boolean

requirements.toml: Enforce the CLI credential store before authentication loads.

file | keyring | auto | ephemeral

requirements.toml: Managed requirements for agent-driven work in native desktop apps.

table

requirements.toml: Set to false to prevent users from enabling Locked Use on a managed macOS device.

boolean

requirements.toml: Set to false to remove the option to save app approvals across sessions.

boolean

requirements.toml: Fallback access for native apps that do not match a platform-specific rule.

allow | deny

requirements.toml: Computer Use app rules for macOS.

table

requirements.toml: Map exact macOS bundle identifiers to allow or deny.

map<string, allow | deny>

requirements.toml: Use deny to block the exact bundle identifier.

allow | deny

requirements.toml: Computer Use app rules for packaged and unpackaged Windows apps.

table

requirements.toml: Map exact, registered Application User Model IDs (AUMIDs) for signed packaged apps to allow or deny.

map<string, allow | deny>

requirements.toml: Use deny to block the exact packaged-app identity.

allow | deny

requirements.toml: Rules for signed, unpackaged Windows executables.

array<table>

requirements.toml: Required access decision for matching executables.

allow | deny

requirements.toml: Optional OriginalFilename from the executable's signed version information.

string

requirements.toml: Required exact ProductName from the executable's signed version information.

string

requirements.toml: Required exact publisher name from the executable's trusted signing certificate, formatted as a Windows X.500 distinguished name.

string

requirements.toml: Managed default permission profile. The profile must be allowed by allowed_permission_profiles.

string

requirements.toml: Require Codex service traffic to use a supported data residency.

string

requirements.toml: Administrator-managed network requirements for sandboxed local commands, enforced from requirements.toml.

table

requirements.toml: Permit broader local/private-network access for sandboxed networking.

boolean

requirements.toml: Allow sandboxed networking to chain through an upstream proxy from the environment.

boolean

requirements.toml: Administrator allow rules for sandboxed-command networking while the managed network proxy is enabled.

array<string>

requirements.toml: Permit arbitrary Unix socket destinations instead of allowlist-only access.

boolean

requirements.toml: Permit non-loopback listener addresses for [experimental_network] requirements.

boolean

requirements.toml: List-shaped administrator deny rules for sandboxed networking.

array<string>

requirements.toml: Map-shaped administrator domain policy for sandboxed networking.

map<string, allow | deny>

requirements.toml: Allow or deny sandboxed network access for the matching domain pattern.

allow | deny

requirements.toml: Enable sandboxed networking requirements.

boolean

requirements.toml: Loopback HTTP listener port to use for [experimental_network] requirements.

integer

requirements.toml: When networking requirements are enabled and this is true, ordinary user configuration and per-domain approvals cannot expand the managed proxy allowlist.

boolean

requirements.toml: Loopback SOCKS5 listener port to use for [experimental_network] requirements.

integer

requirements.toml: Administrator-managed Unix socket allowlist for sandboxed networking on macOS.

map<string, allow | deny>

requirements.toml: On macOS, allow adds an absolute Unix socket path to the allowlist; deny leaves it out.

allow | deny

requirements.toml: Pinned feature values. Use canonical names from config.toml for runtime features; documented app-only requirement keys are also supported here.

table

requirements.toml: Require a documented runtime or app feature to stay enabled or disabled.

boolean

requirements.toml: Pin Apps integration availability on or off for managed users.

boolean

requirements.toml: Set to false in requirements.toml to disable agent-driven Browser Use.

boolean

requirements.toml: Set to false in requirements.toml to prevent Codex from operating supported browsers through the ChatGPT browser extension, including existing tabs and signed-in sessions.

boolean

requirements.toml: Set to false in requirements.toml to disable full Chrome DevTools Protocol access in the local runtime, including Browser Developer mode, and prevent the ChatGPT desktop app from enabling the corresponding setting.

boolean

requirements.toml: Set to false in requirements.toml to disable Computer Use, Record & Replay, and related install or enablement flows.

boolean

requirements.toml: Pin the canonical fast_mode feature on or off for managed users.

boolean

requirements.toml: Pin Guardian approval availability on or off for managed users.

boolean

requirements.toml: Set to false in requirements.toml to disable the built-in browser pane that users open and control directly.

boolean

requirements.toml: Set to false to hide ChatGPT and ChatGPT Work conversation screens and related cloud automation UI in the ChatGPT desktop app.

boolean

requirements.toml: Set to false to disable in-app dictation in the desktop app.

boolean

requirements.toml: Set to false to disable local scheduled tasks in the desktop app.

boolean

requirements.toml: Set to false in requirements.toml to disable in-app updates.

boolean

requirements.toml: Pin Memories availability on or off for managed users.

boolean

requirements.toml: Pin multi-agent availability on or off for managed users.

boolean

requirements.toml: Set to false in cloud-managed requirements.toml to disable workspace sharing for locally built plugins.

boolean

requirements.toml: Pin plugin availability on or off for managed users.

boolean

requirements.toml: Set to false to disable the experimental /voice command in the Codex CLI.

boolean

requirements.toml: Pin remote plugin catalog availability on or off for managed users.

boolean

requirements.toml: Pin bundled workspace-dependency runtime availability on or off for managed users.

boolean

requirements.toml: Managed feedback settings.

table

requirements.toml: Enforce whether users can submit feedback across Codex clients.

boolean

requirements.toml: Additional managed Markdown policy for automatic review, included alongside the main policy.

string

requirements.toml: Managed Markdown policy instructions for automatic review.

string

requirements.toml: Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline [hooks] in config.toml.

table

requirements.toml: Matcher groups for a hook event such as PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SessionStart, SessionEnd, SubagentStart, SubagentStop, UserPromptSubmit, or Stop.

array<table>

requirements.toml: Hook handlers for a matcher group. Command and MCP tool hooks are supported while prompt and agent hook handlers are parsed but skipped.

array<table>

requirements.toml: Approximate per-handler token threshold for saving oversized additionalContext to disk and showing the model a shorter preview.

integer

requirements.toml: Run a command hook in the background without delaying the triggering operation.

boolean

requirements.toml: Windows-only command override for command hooks.

string

requirements.toml: Directory containing managed hook scripts on macOS and Linux.

string (absolute path)

requirements.toml: Directory containing managed hook scripts on Windows.

string (absolute path)

requirements.toml: Requirements for the built-in browser pane.

table

requirements.toml: Set to false to prevent users from importing settings or browsing data from an external browser into the built-in browser.

boolean

requirements.toml: Enforce the directory where Codex writes local log files.

string (path)

requirements.toml: Admin requirements for plugin marketplace sources.

table

requirements.toml: Allowed marketplace sources keyed by administrator-chosen rule name.

table

requirements.toml: One allowed source rule. The final source value after requirements merge determines which sibling fields Codex interprets.

table

requirements.toml: Regular expression required when source = "host_pattern".

string

requirements.toml: Local marketplace directory required when source = "local".

string (absolute path)

requirements.toml: Optional exact Git ref for a git rule.

string

requirements.toml: Marketplace source matcher type. Use git for one repository, host_pattern for Git hosts matched by regular expression, or local for one directory.

git | host_pattern | local

requirements.toml: Git repository URL required when source = "git".

string

requirements.toml: When true, require configured marketplace sources to match allowed_sources for marketplace add, plugin install, refresh, and runtime loading.

boolean

requirements.toml: Allowlist of MCP servers that may be enabled.

table

requirements.toml: Identity rule for a single MCP server. Set either command (stdio) or url (streamable HTTP).

table

requirements.toml: Allow an MCP stdio server by exact command string, or use a matcher table to require an exact executable and ordered argument matchers.

string | table

requirements.toml: Ordered argument matchers for a stdio server.

array<table>

requirements.toml: Regular expression used by a regex argument matcher.

string

requirements.toml: Match operation for this argument position.

exact | prefix | regex

requirements.toml: Value used by an exact or prefix argument matcher.

string

requirements.toml: Executable that the stdio server's configured command must match exactly.

string

requirements.toml: Allow an MCP streamable HTTP server by exact URL string, or use an exact, prefix, or regex value matcher table.

string | table

requirements.toml: Regular expression used by a regex URL matcher.

string

requirements.toml: Match operation for the configured MCP server URL.

exact | prefix | regex

requirements.toml: Value used by an exact or prefix URL matcher.

string

requirements.toml: Enforce the JSON model catalog Codex uses at startup.

string (path)

requirements.toml: Enforce the model provider ID, overriding local and session configuration.

string

requirements.toml: Managed model provider definitions. Each entry replaces the complete configured provider with the same ID; fields aren't merged with the user's definition.

map<string, table>

requirements.toml: Complete managed provider definition. Uses the same provider fields as config.toml, including name, base_url, authentication, and transport settings.

table

requirements.toml: Contains the [models.new_thread] table.

table

requirements.toml: Optional defaults to apply when a new local thread starts.

table

requirements.toml: Default model for new threads. An explicit override of either the model or reasoning effort causes both fields to be ignored.

string

requirements.toml: Default reasoning effort for new threads.

string

requirements.toml: Default service tier for new threads. An explicit service-tier override causes this field to be ignored.

string

requirements.toml: Admin-defined permission profiles keyed by profile name.

table

requirements.toml: Admin-defined permission profile. The name can't start with :, use the reserved name filesystem, or duplicate a profile from a loaded config.

table

requirements.toml: Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config.

array<string>

requirements.toml: Plugin-specific MCP server allowlists keyed by plugin identifier.

table

requirements.toml: Allowlist for MCP servers bundled with one plugin.

table

requirements.toml: Identity rule for one plugin-bundled MCP server. Set either command (stdio) or url (streamable HTTP).

table

requirements.toml: Allow a plugin's stdio MCP server by exact command string, or use a matcher table to require an exact executable and ordered argument matchers.

string | table

requirements.toml: Ordered argument matchers for a plugin-bundled stdio server.

array<table>

requirements.toml: Regular expression used by a regex argument matcher.

string

requirements.toml: Match operation for this argument position.

exact | prefix | regex

requirements.toml: Value used by an exact or prefix argument matcher.

string

requirements.toml: Executable that the plugin-bundled stdio server's configured command must match exactly.

string

requirements.toml: Allow a plugin's streamable HTTP MCP server by exact URL string, or use an exact, prefix, or regex value matcher table.

string | table

requirements.toml: Regular expression used by a regex URL matcher.

string

requirements.toml: Match operation for the plugin-bundled MCP server URL.

exact | prefix | regex

requirements.toml: Value used by an exact or prefix URL matcher.

string

requirements.toml: Host-specific sandbox requirements. The first entry whose hostname_patterns match the resolved host name overrides top-level allowed_sandbox_modes for that requirements source.

array<table>

requirements.toml: Allowed sandbox modes to apply when this host-specific entry matches.

array<string>

requirements.toml: Case-insensitive host name patterns. Supports * for any sequence of characters and ? for one character.

array<string>

requirements.toml: Admin-enforced command rules merged with .rules files. Requirements rules must be restrictive.

table

requirements.toml: List of enforced prefix rules. Each rule must include pattern and decision.

array<table>

requirements.toml: Required. Requirements rules can only prompt or forbid (not allow).

prompt | forbidden

requirements.toml: Optional non-empty rationale surfaced in approval prompts or rejection messages.

string

requirements.toml: Command prefix expressed as pattern tokens. Each token sets either token or any_of.

array<table>

requirements.toml: A list of allowed alternative tokens at this position.

array<string>

requirements.toml: A single literal token at this position.

string

requirements.toml: Enforce the directory where Codex stores SQLite-backed runtime state.

string (path)

requirements.toml: Native Windows sandbox requirements.

table

requirements.toml: Set to false to prohibit both explicit MXC selection and automatic selection through features.prefer_mxc.

boolean

requirements.toml: Allowed legacy native Windows sandbox implementations (elevated and unelevated). The list must not be empty.

array<string>