Configuration Reference

Use this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with Config basics and Advanced Config.

`config.toml`

User-level configuration lives in ~/.codex/config.toml. You can also add project-scoped overrides in .codex/config.toml files. Codex loads project-scoped config files only when you trust the project.

Project-scoped config can't override machine-local provider, auth, host-owned app request metadata, notification, configuration profile selection, or telemetry routing keys. Codex ignores openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url, and otel when they appear in a project-local .codex/config.toml; put provider, notification, and telemetry keys in user-level config instead. Config profile files live next to config.toml as $CODEX_HOME/profile-name.config.toml; select one with --profile profile-name.

For sandbox and approval keys (approval_policy, sandbox_mode, and sandbox_workspace_write.*), pair this reference with Sandbox and approvals, Protected paths in writable roots, and Network access. For beta permission profiles, see Permissions.

Codex and ChatGPT Work no longer support approval_policy = "untrusted". Remove the setting or choose a supported policy. Project entries with trust_level = "untrusted" in user-level ~/.codex/config.toml remain supported. See Migrate from the retired untrusted approval policy for examples and approval tradeoffs.

Key	Type / Values	Details
`agents`	`table`	Multi-agent settings and custom role declarations. Scalar setting names are reserved and can't be used as custom role names.
`agents.<name>.config_file`	`string (path)`	Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.
`agents.<name>.description`	`string`	Role guidance shown to Codex when choosing and spawning that agent type.
`agents.default_subagent_model`	`string`	Default model for spawned agents. An explicit spawn model takes precedence.
`agents.default_subagent_reasoning_effort`	`string`	Default reasoning effort for spawned agents. An explicit spawn effort takes precedence.
`agents.enabled`	`boolean`	Enable or disable multi-agent tools (default: true).
`agents.interrupt_message`	`boolean`	Record a model-visible message when an agent turn is interrupted (default: true).
`agents.max_concurrent_threads_per_session`	`number`	Maximum number of spawned-agent threads that can be open concurrently, excluding the primary thread. When unset, Codex chooses the default.
`agents.max_threads`	`number`	Legacy alias for `agents.max_concurrent_threads_per_session`.
`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.
`analytics.enabled`	`boolean`	Enable or disable analytics for this machine/profile. When unset, the client default applies.
`approval_policy`	`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. `untrusted` is unsupported, and `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.
`approval_policy.granular.mcp_elicitations`	`boolean`	When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.
`approval_policy.granular.request_permissions`	`boolean`	When `true`, prompts from the `request_permissions` tool are allowed to surface.
`approval_policy.granular.rules`	`boolean`	When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.
`approval_policy.granular.sandbox_approval`	`boolean`	When `true`, sandbox escalation approval prompts are allowed to surface.
`approval_policy.granular.skill_approval`	`boolean`	When `true`, skill-script approval prompts are allowed to surface.
`approvals_reviewer`	`user \| auto_review`	Who reviews eligible approval prompts under `on-request` or granular approval policies. Defaults to `user`; `auto_review` uses the reviewer subagent. This setting doesn't change sandboxing or review actions already allowed inside the sandbox.
`apps._default.approvals_reviewer`	`user \| auto_review`	Default reviewer for app tool approval prompts unless overridden per app. When omitted, apps inherit the top-level `approvals_reviewer` value.
`apps._default.default_tools_approval_mode`	`auto \| prompt \| writes \| approve`	Default approval behavior for app tools without per-app or per-tool overrides.
`apps._default.destructive_enabled`	`boolean`	Default allow/deny for app tools with `destructive_hint = true`.
`apps._default.enabled`	`boolean`	Default app enabled state for all apps unless overridden per app.
`apps._default.open_world_enabled`	`boolean`	Default allow/deny for app tools with `open_world_hint = true`.
`apps.<id>.approvals_reviewer`	`user \| auto_review`	Reviewer for this app's tool approval prompts. Overrides `apps._default.approvals_reviewer`.
`apps.<id>.default_tools_approval_mode`	`auto \| prompt \| writes \| approve`	Default approval behavior for tools in this app unless a per-tool override exists.
`apps.<id>.default_tools_enabled`	`boolean`	Default enabled state for tools in this app unless a per-tool override exists.
`apps.<id>.destructive_enabled`	`boolean`	Allow or block tools in this app that advertise `destructive_hint = true`.
`apps.<id>.enabled`	`boolean`	Enable or disable a specific app/connector by id (default: true).
`apps.<id>.open_world_enabled`	`boolean`	Allow or block tools in this app that advertise `open_world_hint = true`.
`apps.<id>.tools.<tool>.approval_mode`	`auto \| prompt \| writes \| approve`	Per-tool approval behavior override for a single app tool.
`apps.<id>.tools.<tool>.enabled`	`boolean`	Per-tool enabled override for an app tool (for example `repos/list`).
`auto_review.policy`	`string`	Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored.
`background_terminal_max_timeout`	`number`	Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.
`browser_use.allow_history_access`	`boolean`	Set to `false` to restrict browser-history access. Managed requirements can enforce this restriction.
`browser_use.default_origin_policy`	`table`	Fallback browser-origin restrictions. Supports `access`, `uploads`, `downloads`, and `full_cdp_access`, each set to `allow` or `deny`.
`browser_use.origins.<origin>`	`table`	Per-origin browser restrictions with the same fields as `browser_use.default_origin_policy`. Include an HTTP or HTTPS scheme and optional port; omit paths, queries, and fragments. Local values cannot relax managed denies.
`chatgpt_base_url`	`string`	Override the base URL used during the ChatGPT login flow.
`check_for_update_on_startup`	`boolean`	Check for Codex updates on startup (set to false only when updates are centrally managed).
`cli_auth_credentials_store`	`file \| keyring \| auto \| ephemeral`	Control where the CLI stores cached credentials.
`compact_prompt`	`string`	Inline override for the history compaction prompt.
`computer_use.default_app_access`	`allow \| deny`	Fallback native-app access policy for Computer Use. App-specific entries can supply a policy; local configuration cannot relax managed restrictions.
`computer_use.macos.bundle_ids`	`map<string, allow \| deny>`	Native macOS app access keyed by bundle identifier.
`computer_use.windows.always_allowed_app_ids`	`array<string>`	Windows app identifiers that Computer Use can open without prompting. Apps not in the list require approval; remove saved entries from the ChatGPT desktop app's Computer Use settings.
`computer_use.windows.aumids`	`map<string, allow \| deny>`	Packaged Windows app access keyed by Application User Model ID (AUMID).
`computer_use.windows.exes`	`array<table>`	Windows executable access rules. Each rule requires `publisher_name`, `product_name`, and `access` (`allow` or `deny`); `binary_name` is optional.
`default_permissions`	`string`	Name of the default permissions profile to apply to sandboxed tool calls. Built-ins are `:read-only`, `:workspace`, and `:danger-full-access`; custom profile names require matching `[permissions.<name>]` tables. Don't combine with `sandbox_mode` or `[sandbox_workspace_write]`.
`desktop.custom_file_handlers.<id>`	`table`	User-level only. Defines an additional Open in target for the ChatGPT desktop app. See Add custom file handlers for examples and handler ID constraints.
`desktop.custom_file_handlers.<id>.args`	`array<string>`	Arguments inserted between the command and file input (default: `[]`).
`desktop.custom_file_handlers.<id>.command`	`string`	Executable path or command name to detect and launch. Required.
`desktop.custom_file_handlers.<id>.icon`	`string`	Bundled asset path, Base64-encoded `data:image/...` URL, file URI, or absolute local path for the handler icon. Required; unsupported sources use the default VS Code icon.
`desktop.custom_file_handlers.<id>.input`	`path \| json_argument \| json_stdin`	How the app sends file input to the handler (default: `path`).
`desktop.custom_file_handlers.<id>.label`	`string`	Display name shown in Open in menus. Required.
`desktop.custom_file_handlers.<id>.supports_ssh`	`boolean`	Offer the handler for files in SSH workspaces (default: `false`).
`developer_instructions`	`string`	Additional developer instructions injected into the session (optional).
`disable_paste_burst`	`boolean`	Disable burst-paste detection in the TUI.
`experimental_compact_prompt_file`	`string (path)`	Load the compaction prompt override from a file (experimental).
`experimental_use_unified_exec_tool`	`boolean`	Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.
`features.apps`	`boolean`	Enable app (connector) integrations (stable; on by default). App and connector traffic is not controlled by the sandboxed-command network proxy or its domain allowlist.
`features.code_mode.direct_only_tool_namespaces`	`array<string>`	Tool namespaces code mode can use only through direct tool calls.
`features.code_mode.enabled`	`boolean`	Enable code mode feature configuration. This feature is under development and off by default.
`features.code_mode.excluded_tool_namespaces`	`array<string>`	Tool namespaces code mode excludes from nested code-mode tool guidance and executor exposure.
`features.context_management.experimental_mode`	`boolean`	Enable experimental context management (off by default). Rather than repeatedly compressing context into a single summary, it uses notes and searchable history to preserve accumulated details. Requires ChatGPT sign-in on Plus, Pro, or Pro Lite.
`features.enable_request_compression`	`boolean`	Compress streaming request bodies with zstd when supported (stable; on by default).
`features.fast_mode`	`boolean`	Enable model-catalog service tier selection in the TUI, including Fast-tier commands when the active model advertises them (stable; on by default).
`features.goals`	`boolean`	Enable persisted goals and automatic continuation (stable; on by default).
`features.hooks`	`boolean`	Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. `features.codex_hooks` is a deprecated alias.
`features.memories`	`boolean`	Enable Memories (off by default).
`features.multi_agent`	`boolean`	Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).
`features.network_proxy`	`boolean \| table`	Start the network proxy for sandboxed commands (experimental; off by default). Required to enforce permission-profile domain rules unless enabled administrator-managed `experimental_network` requirements start the proxy. Use a table when setting feature-level policy options such as `domains`. Does not filter web search, apps, MCP, or other hosted tools.
`features.network_proxy.allow_local_binding`	`boolean`	Allow broader local/private-network access. Defaults to `false`; exact local IP literal or `localhost` allow rules can still permit specific local targets.
`features.network_proxy.allow_upstream_proxy`	`boolean`	Allow chaining through an upstream proxy from the environment. Defaults to `true`.
`features.network_proxy.dangerously_allow_all_unix_sockets`	`boolean`	Permit arbitrary Unix socket destinations instead of allowlist-only access. Defaults to `false`; use only in tightly controlled environments.
`features.network_proxy.dangerously_allow_non_loopback_proxy`	`boolean`	Permit non-loopback listener addresses. Defaults to `false`; enabling it can expose proxy listeners beyond localhost.
`features.network_proxy.domains`	`map<string, allow \| deny>`	Domain policy for sandboxed networking. Unset by default, which means no external destinations are allowed until you add `allow` rules. Supports exact hosts, `.example.com` for subdomains only, `.example.com` for apex plus subdomains, and global `` allow rules; prefer scoped rules because `*` broadly opens public outbound access. Add `deny` rules for blocked destinations; `deny` wins on conflicts.
`features.network_proxy.enable_socks5`	`boolean`	Expose SOCKS5 support. Defaults to `true`.
`features.network_proxy.enable_socks5_udp`	`boolean`	Allow UDP over SOCKS5. Defaults to `true`.
`features.network_proxy.enabled`	`boolean`	Start the sandboxed-command network proxy when command network access is enabled. Defaults to `false`; permission-profile domain rules are not enforced while the proxy is off.
`features.network_proxy.proxy_url`	`string`	HTTP listener URL for sandboxed networking. Defaults to `"http://127.0.0.1:3128"`.
`features.network_proxy.socks_url`	`string`	SOCKS5 listener URL. Defaults to `"http://127.0.0.1:8081"`.
`features.network_proxy.unix_sockets`	`map<string, allow \| deny>`	Unix socket policy for sandboxed networking. Unset by default; add `allow` entries for permitted sockets.
`features.personality`	`boolean`	Enable personality selection controls (stable; on by default).
`features.prevent_idle_sleep`	`boolean`	Prevent the machine from sleeping while a turn is actively running (experimental; off by default).
`features.remote_plugin`	`boolean`	Enable the remote plugin catalog (stable; on by default).
`features.rollout_budget.enabled`	`boolean`	Enable rollout budget tracking. This feature is under development and off by default. When enabled, `features.rollout_budget.limit_tokens` is required.
`features.rollout_budget.limit_tokens`	`integer`	Positive token limit for rollout budget tracking. Required when rollout budget is enabled.
`features.rollout_budget.prefill_token_weight`	`number`	Finite non-negative multiplier for prefill tokens in rollout budget accounting. Defaults to `1.0`.
`features.rollout_budget.reminder_interval_tokens`	`integer`	Positive token interval between rollout budget reminders. Defaults to 10% of `limit_tokens`, with a minimum of 1 token.
`features.rollout_budget.sampling_token_weight`	`number`	Finite non-negative multiplier for sampled tokens in rollout budget accounting. Defaults to `1.0`.
`features.shell_snapshot`	`boolean`	Snapshot shell environment to speed up repeated commands (stable; on by default).
`features.shell_tool`	`boolean`	Enable the default `shell` tool for running commands (stable; on by default).
`features.skill_mcp_dependency_install`	`boolean`	Allow prompting and installing missing MCP dependencies for skills (stable; on by default).
`features.unified_exec`	`boolean`	Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).
`features.web_search`	`boolean`	Deprecated legacy toggle; prefer the top-level `web_search` setting.
`features.web_search_cached`	`boolean`	Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.
`features.web_search_request`	`boolean`	Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.
`feedback.enabled`	`boolean`	Enable feedback submission via `/feedback` across local clients (default: true).
`file_opener`	`vscode \| vscode-insiders \| windsurf \| cursor \| none`	URI scheme used to open citations from Codex output (default: `vscode`).
`forced_chatgpt_workspace_id`	`string (uuid)`	Limit ChatGPT logins to a specific workspace identifier.
`forced_login_method`	`chatgpt \| api`	Restrict Codex to a specific authentication method.
`hide_agent_reasoning`	`boolean`	Suppress reasoning events in both the TUI and `codex exec` output.
`history.max_bytes`	`number`	If set, caps the history file size in bytes by dropping oldest entries.
`history.persistence`	`save-all \| none`	Control whether Codex saves session transcripts to history.jsonl.
`hooks`	`table`	Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.
`hooks.<Event>`	`array<table>`	Matcher groups for hook events such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `SessionEnd`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`, `Stop`, or `Interrupt`.
`hooks.<Event>[].hooks`	`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.
`hooks.<Event>[].hooks[].additionalContextLimit`	`integer`	Approximate per-handler token threshold for saving oversized `additionalContext` to disk and showing the model a shorter preview. Defaults to `2500`; `0` passes the full context directly to the model. See Large hook output.
`hooks.<Event>[].hooks[].async`	`boolean`	Run a command hook in the background without delaying the triggering operation. Defaults to `false`; `SessionEnd` always runs synchronously. See Run hooks in the background.
`hooks.<Event>[].hooks[].commandWindows`	`string`	Windows-only command override for command hooks. The TOML alias `command_windows` is also accepted.
`instructions`	`string`	Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.
`log_dir`	`string (path)`	Directory where Codex writes log files; defaults to `$CODEX_HOME/log`. Setting this explicitly also enables the opt-in plaintext TUI log, `codex-tui.log`, in that directory.
`marketplaces.<name>.ref`	`string`	Optional Git branch, tag, or commit for the marketplace.
`marketplaces.<name>.source`	`string`	Git repository location or local marketplace root directory. Use an absolute path for a local source; the directory contains .agents/plugins/marketplace.json.
`marketplaces.<name>.source_type`	`git \| local`	Source kind for a configured plugin marketplace. Marketplaces can be defined in system, cloud-managed, user, or trusted-project config.toml.
`marketplaces.<name>.sparse_paths`	`array<string>`	Optional sparse checkout paths for a Git marketplace. Include the marketplace catalog and any local plugin directories it references.
`mcp_oauth_callback_port`	`integer`	Optional global fixed port for the local HTTP callback server used during MCP OAuth login. A server-specific `oauth.callback_port` takes precedence. When neither is set, Codex binds to an ephemeral port chosen by the OS.
`mcp_oauth_callback_url`	`string`	Optional base callback URL for MCP OAuth login, such as a devbox ingress URL. Newly added pre-registered clients use this URL unchanged when the authorization server supports issuer identification; existing clients without a saved callback append a server-specific callback ID. Without issuer support, any pre-registered MCP server whose configured callback lacks the required ID falls back to this URL with the ID appended. Callback URL ports don't select the listener port.
`mcp_oauth_credentials_store`	`auto \| file \| keyring`	Preferred store for MCP OAuth credentials.
`mcp_optional_startup_grace_ms`	`integer (milliseconds)`	Shared wait for optional MCP servers when building the initial tool catalog. Defaults to `1000`. Set to `0` to wait for each server's `startup_timeout_sec` instead.
`mcp_servers.<id>.args`	`array<string>`	Arguments passed to the MCP stdio server command.
`mcp_servers.<id>.auth`	`oauth \| chatgpt`	Authentication fallback for an MCP HTTP server after configured bearer tokens and authorization headers. `oauth` (default) uses stored MCP OAuth credentials when available. `chatgpt` uses the current ChatGPT session for the trusted first-party ChatGPT origin, then falls back to stored OAuth. Both modes can connect without authentication if no credential source resolves.
`mcp_servers.<id>.bearer_token_env_var`	`string`	Environment variable sourcing the bearer token for an MCP HTTP server.
`mcp_servers.<id>.command`	`string`	Launcher command for an MCP stdio server.
`mcp_servers.<id>.cwd`	`string`	Working directory for the MCP stdio server process.
`mcp_servers.<id>.default_tools_approval_mode`	`auto \| prompt \| writes \| approve`	Default approval behavior for MCP tools on this server unless a per-tool override exists.
`mcp_servers.<id>.disabled_tools`	`array<string>`	Deny list applied after `enabled_tools` for the MCP server.
`mcp_servers.<id>.enabled`	`boolean`	Disable an MCP server without removing its configuration.
`mcp_servers.<id>.enabled_tools`	`array<string>`	Allow list of tool names exposed by the MCP server.
`mcp_servers.<id>.env`	`map<string,string>`	Environment variables forwarded to the MCP stdio server.
`mcp_servers.<id>.env_http_headers`	`map<string,string>`	HTTP headers populated from environment variables for an MCP HTTP server.
`mcp_servers.<id>.env_vars`	`array<string \| { name = string, source = "local" \| "remote" }>`	Additional environment variables to whitelist for an MCP stdio server. String entries default to `source = "local"`; use `source = "remote"` only with executor-backed remote stdio.
`mcp_servers.<id>.experimental_environment`	`local \| remote`	Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.
`mcp_servers.<id>.http_headers`	`map<string,string>`	Static HTTP headers included with each MCP HTTP request.
`mcp_servers.<id>.http_headers_helper`	`string (command)`	Local command that prints a JSON object of HTTP header names and values. Supported only for locally connected HTTP MCP servers. Explicit bearer tokens and OAuth credentials take precedence over helper-provided Authorization headers.
`mcp_servers.<id>.oauth_resource`	`string`	Optional RFC 8707 OAuth resource parameter to include during MCP login.
`mcp_servers.<id>.oauth.callback_port`	`integer`	Fixed OAuth callback listener port for this MCP server. Overrides `mcp_oauth_callback_port`. For a direct loopback callback with an explicit URL port, configure the same listener port.
`mcp_servers.<id>.oauth.callback_url`	`string`	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. Otherwise, Codex uses the global or default callback with that ID appended. Clients without a pre-registered ID use this callback during client registration.
`mcp_servers.<id>.oauth.client_id`	`string`	Pre-registered OAuth client ID used for authorization and token exchange with this MCP server.
`mcp_servers.<id>.required`	`boolean`	When true, fail startup/resume if this enabled MCP server cannot initialize.
`mcp_servers.<id>.scopes`	`array<string>`	OAuth scopes to request when authenticating to that MCP server.
`mcp_servers.<id>.startup_timeout_ms`	`number`	Alias for `startup_timeout_sec` in milliseconds.
`mcp_servers.<id>.startup_timeout_sec`	`number`	Override the default 10s startup timeout for an MCP server.
`mcp_servers.<id>.tool_timeout_sec`	`number`	Override the default 60s per-tool timeout for an MCP server.
`mcp_servers.<id>.tools.<tool>.approval_mode`	`auto \| prompt \| writes \| approve`	Per-tool approval behavior override for one MCP tool on this server.
`mcp_servers.<id>.tools.<tool>.output_token_limit`	`integer (positive)`	Token budget for one MCP tool's output, before the standard 20% serialization allowance. Overrides the model's default output truncation budget for that tool.
`mcp_servers.<id>.url`	`string`	Endpoint for an MCP streamable HTTP server.
`memories.consolidation_model`	`string`	Optional model override for global memory consolidation.
`memories.disable_on_external_context`	`boolean`	When `true`, threads that use external context such as MCP tool calls, web search, or tool search are kept out of memory generation. Defaults to `false`. Legacy alias: `memories.no_memories_if_mcp_or_web_search`.
`memories.extract_model`	`string`	Optional model override for per-thread memory extraction.
`memories.generate_memories`	`boolean`	When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.
`memories.max_raw_memories_for_consolidation`	`number`	Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.
`memories.max_rollout_age_days`	`number`	Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.
`memories.max_rollouts_per_startup`	`number`	Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.
`memories.max_unused_days`	`number`	Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.
`memories.min_rate_limit_remaining_percent`	`number`	Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`.
`memories.min_rollout_idle_hours`	`number`	Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.
`memories.use_memories`	`boolean`	When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.
`model`	`string`	Model to use (e.g., `gpt-5.6-sol`).
`model_auto_compact_token_limit`	`number`	Token threshold that triggers automatic history compaction (unset uses model defaults).
`model_auto_compact_token_limit_scope`	`total \| body_after_prefix`	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`).
`model_catalog_json`	`string (path)`	Optional path to a JSON model catalog loaded on startup. A selected `$CODEX_HOME/profile-name.config.toml` profile file can override this per profile.
`model_context_window`	`number`	Context window tokens available to the active model.
`model_instructions_file`	`string (path)`	Replacement for built-in instructions instead of `AGENTS.md`.
`model_provider`	`string`	Provider id from `model_providers` (default: `openai`).
`model_providers.<id>`	`table`	Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.
`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`.
`model_providers.<id>.auth.args`	`array<string>`	Arguments passed to the token command.
`model_providers.<id>.auth.command`	`string`	Command to run when Codex needs a bearer token. The command must print the token to stdout.
`model_providers.<id>.auth.cwd`	`string (path)`	Working directory for the token command.
`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.
`model_providers.<id>.auth.timeout_ms`	`number`	Maximum token command runtime in milliseconds (default: 5000).
`model_providers.<id>.base_url`	`string`	API base URL for the model provider.
`model_providers.<id>.env_http_headers`	`map<string,string>`	HTTP headers populated from environment variables when present.
`model_providers.<id>.env_key`	`string`	Environment variable supplying the provider API key.
`model_providers.<id>.env_key_instructions`	`string`	Optional setup guidance for the provider API key.
`model_providers.<id>.experimental_bearer_token`	`string`	Direct bearer token for the provider (discouraged; use `env_key`).
`model_providers.<id>.http_headers`	`map<string,string>`	Static HTTP headers added to provider requests.
`model_providers.<id>.name`	`string`	Display name for a custom model provider.
`model_providers.<id>.query_params`	`map<string,string>`	Extra query parameters appended to provider requests.
`model_providers.<id>.request_max_retries`	`number`	Retry count for HTTP requests to the provider (default: 4).
`model_providers.<id>.requires_openai_auth`	`boolean`	The provider uses OpenAI authentication (defaults to false).
`model_providers.<id>.stream_idle_timeout_ms`	`number`	Idle timeout for SSE streams in milliseconds (default: 300000).
`model_providers.<id>.stream_max_retries`	`number`	Retry count for SSE streaming interruptions (default: 5).
`model_providers.<id>.supports_standalone_web_search`	`boolean`	Advertise support for a compatible standalone web search endpoint (default: false). Standalone search remains under development and off by default; provider compatibility alone doesn't enable it.
`model_providers.<id>.supports_websockets`	`boolean`	Whether that provider supports the Responses API WebSocket transport.
`model_providers.<id>.wire_api`	`responses`	Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.
`model_providers.amazon-bedrock.aws.profile`	`string`	AWS profile name used by the built-in `amazon-bedrock` provider.
`model_providers.amazon-bedrock.aws.region`	`string`	AWS region used by the built-in `amazon-bedrock` provider.
`model_reasoning_effort`	`minimal \| low \| medium \| high \| xhigh`	Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).
`model_reasoning_summary`	`auto \| concise \| detailed \| none`	Select reasoning summary detail or disable summaries entirely.
`model_supports_reasoning_summaries`	`boolean`	Force Codex to send or not send reasoning metadata.
`model_verbosity`	`low \| medium \| high`	Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.
`notice.hide_full_access_warning`	`boolean`	Track acknowledgement of the full access warning prompt.
`notice.hide_gpt-5.1-codex-max_migration_prompt`	`boolean`	Track acknowledgement of the gpt-5.1-codex-max migration prompt.
`notice.hide_gpt5_1_migration_prompt`	`boolean`	Track acknowledgement of the GPT-5.1 migration prompt.
`notice.hide_rate_limit_model_nudge`	`boolean`	Track opt-out of the rate limit model switch reminder.
`notice.hide_world_writable_warning`	`boolean`	Track acknowledgement of the Windows world-writable directories warning.
`notice.model_migrations`	`map<string,string>`	Track acknowledged model migrations as old->new mappings.
`notify`	`array<string>`	Command invoked for notifications; receives a JSON payload from Codex.
`openai_base_url`	`string`	Base URL override for the built-in `openai` model provider.
`oss_provider`	`lmstudio \| ollama`	Default local provider used when running with `--oss` (defaults to prompting if unset).
`otel.environment`	`string`	Environment tag applied to emitted OpenTelemetry events (default: `dev`).
`otel.exporter`	`none \| otlp-http \| otlp-grpc`	Select the OpenTelemetry exporter and provide any endpoint metadata.
`otel.exporter.<id>.endpoint`	`string`	Exporter endpoint for OTEL logs.
`otel.exporter.<id>.headers`	`map<string,string>`	Static headers included with OTEL exporter requests.
`otel.exporter.<id>.protocol`	`binary \| json`	Protocol used by the OTLP/HTTP exporter.
`otel.exporter.<id>.tls.ca-certificate`	`string`	CA certificate path for OTEL exporter TLS.
`otel.exporter.<id>.tls.client-certificate`	`string`	Client certificate path for OTEL exporter TLS.
`otel.exporter.<id>.tls.client-private-key`	`string`	Client private key path for OTEL exporter TLS.
`otel.log_user_prompt`	`boolean`	Opt in to exporting raw user prompts with OpenTelemetry logs.
`otel.metrics_exporter`	`none \| statsig \| otlp-http \| otlp-grpc`	Select the OpenTelemetry metrics exporter (defaults to `statsig`).
`otel.trace_exporter`	`none \| otlp-http \| otlp-grpc`	Select the OpenTelemetry trace exporter and provide any endpoint metadata.
`otel.trace_exporter.<id>.endpoint`	`string`	Trace exporter endpoint for OTEL logs.
`otel.trace_exporter.<id>.headers`	`map<string,string>`	Static headers included with OTEL trace exporter requests.
`otel.trace_exporter.<id>.protocol`	`binary \| json`	Protocol used by the OTLP/HTTP trace exporter.
`otel.trace_exporter.<id>.tls.ca-certificate`	`string`	CA certificate path for OTEL trace exporter TLS.
`otel.trace_exporter.<id>.tls.client-certificate`	`string`	Client certificate path for OTEL trace exporter TLS.
`otel.trace_exporter.<id>.tls.client-private-key`	`string`	Client private key path for OTEL trace exporter TLS.
`permissions.<name>.description`	`string`	Human-readable description for this named profile. A profile does not inherit its parent's description through `extends`.
`permissions.<name>.extends`	`string`	Optional parent profile applied before this named profile. Set it to another named profile, `:read-only`, or `:workspace`; `:danger-full-access`, undefined parents, and cycles are rejected.
`permissions.<name>.filesystem`	`table`	Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:workspace_roots`.
`permissions.<name>.filesystem.":workspace_roots".<subpath-or-glob>`	`"read" \| "write" \| "deny"`	Scoped filesystem access relative to each effective workspace root. Use `"."` for the root itself; glob subpaths such as `"*/.env"` can deny reads with `"deny"`.
`permissions.<name>.filesystem.<path-or-glob>`	`"read" \| "write" \| "deny" \| table`	Grant direct access for a path, glob pattern, or special token, or scope nested entries under that root. Use `"deny"` to deny reads for matching paths.
`permissions.<name>.filesystem.glob_scan_max_depth`	`number`	Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set.
`permissions.<name>.network.allow_local_binding`	`boolean`	Permit broader local/private-network access through sandboxed networking. Exact local IP literal or `localhost` allow rules can still permit specific local targets when this stays `false`.
`permissions.<name>.network.allow_upstream_proxy`	`boolean`	Allow sandboxed networking to chain through another upstream proxy.
`permissions.<name>.network.dangerously_allow_all_unix_sockets`	`boolean`	Allow arbitrary Unix socket destinations instead of the default restricted set. Use only in tightly controlled environments.
`permissions.<name>.network.dangerously_allow_non_loopback_proxy`	`boolean`	Permit non-loopback bind addresses for sandboxed networking listeners. Enabling it can expose listeners beyond localhost.
`permissions.<name>.network.domains`	`table`	Domain rules for sandboxed commands. Enforced only when `features.network_proxy` or enabled administrator-managed networking requirements activate the proxy. Supports exact hosts, `.example.com`, `.example.com`, and global `` allow rules; `deny` wins. Does not restrict web search, apps, or MCP servers.
`permissions.<name>.network.domains.<pattern>`	`allow \| deny`	Allow or deny an exact host or scoped wildcard pattern such as `.example.com` or `*.example.com`.
`permissions.<name>.network.enable_socks5`	`boolean`	Expose SOCKS5 support when this permissions profile enables sandboxed networking.
`permissions.<name>.network.enable_socks5_udp`	`boolean`	Allow UDP over the SOCKS5 listener when enabled.
`permissions.<name>.network.enabled`	`boolean`	Enable network access for commands in this permission profile. This does not start the network proxy. Without `features.network_proxy` or enabled administrator-managed networking requirements, command network access is direct and profile domain rules are not enforced.
`permissions.<name>.network.mode`	`limited \| full`	Network proxy mode used for subprocess traffic.
`permissions.<name>.network.proxy_url`	`string`	HTTP listener URL used when this permissions profile enables sandboxed networking.
`permissions.<name>.network.socks_url`	`string`	SOCKS5 proxy endpoint used by this permissions profile.
`permissions.<name>.network.unix_sockets`	`table`	Unix socket allowlist overrides for sandboxed networking. Use socket paths as keys; `allow` adds a path, and `deny` rejects it.
`permissions.<name>.network.unix_sockets.<path>`	`allow \| deny`	Add an absolute Unix socket path to the effective allowlist with `allow`, or reject it with `deny`. Denied entries are omitted from the effective allowlist.
`permissions.<name>.workspace_roots`	`table`	Profile-defined workspace roots that receive `:workspace_roots` filesystem rules alongside the session's runtime workspace roots.
`permissions.<name>.workspace_roots.<path>`	`boolean`	Opt a path into the profile's workspace root set when `true`. Disabled entries remain inactive.
`personality`	`none \| friendly \| pragmatic`	Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.
`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.
`plugins.<plugin>.enabled`	`boolean`	Enable or disable a local-marketplace plugin using a `plugin-name@marketplace-name` key. Read from the effective merged config; trusted-project settings can override user, cloud-managed, and system defaults. Marketplace refresh can install or refresh configured plugins even when disabled. This does not override workspace-managed enabled states.
`plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode`	`auto \| prompt \| writes \| approve`	Default approval behavior for tools on a plugin-provided MCP server.
`plugins.<plugin>.mcp_servers.<server>.disabled_tools`	`array<string>`	Deny list applied after `enabled_tools` for a plugin-provided MCP server.
`plugins.<plugin>.mcp_servers.<server>.enabled`	`boolean`	Enable or disable an MCP server bundled by an installed plugin without changing the plugin manifest.
`plugins.<plugin>.mcp_servers.<server>.enabled_tools`	`array<string>`	Allow list of tools exposed from a plugin-provided MCP server.
`plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode`	`auto \| prompt \| writes \| approve`	Per-tool approval behavior override for a plugin-provided MCP tool.
`project_doc_fallback_filenames`	`array<string>`	Additional filenames to try when `AGENTS.md` is missing.
`project_doc_max_bytes`	`number`	Maximum bytes read from `AGENTS.md` when building project instructions.
`project_root_markers`	`array<string>`	List of project root marker filenames; used when searching parent directories for the project root.
`projects.<path>.trust_level`	`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.
`review_model`	`string`	Optional model override used by `/review` (defaults to the current session model).
`sandbox_mode`	`read-only \| workspace-write \| danger-full-access`	Sandbox policy for filesystem and network access during command execution.
`sandbox_workspace_write.exclude_slash_tmp`	`boolean`	Exclude `/tmp` from writable roots in workspace-write mode.
`sandbox_workspace_write.exclude_tmpdir_env_var`	`boolean`	Exclude `$TMPDIR` from writable roots in workspace-write mode.
`sandbox_workspace_write.network_access`	`boolean`	Allow outbound network access inside the workspace-write sandbox.
`sandbox_workspace_write.writable_roots`	`array<string>`	Additional writable roots when `sandbox_mode = "workspace-write"`.
`service_tier`	`string`	Preferred service tier for new turns. Use `fast` or another tier advertised by the active model; `fast` maps to the request value `priority`.
`shell_environment_policy.exclude`	`array<string>`	Legacy environment-variable exclusion patterns. Use `shell_environment_policy.filters` for new configuration; don't combine both forms in the same layer.
`shell_environment_policy.experimental_use_profile`	`boolean`	Use the user shell profile when spawning subprocesses.
`shell_environment_policy.filters`	`map<string, include \| exclude>`	Canonical case-insensitive environment-variable pattern filters. Include entries create an allowlist and can't restore excluded values. Explicit `set` values apply after exclusions. Don't combine filters with legacy `exclude` or `include_only` arrays in the same layer.
`shell_environment_policy.ignore_default_excludes`	`boolean`	Keep variables containing KEY, SECRET, or TOKEN before other filters run (default: true). Set to false to apply automatic secret-name exclusions.
`shell_environment_policy.include_only`	`array<string>`	Legacy allowlist of environment-variable patterns. Use `shell_environment_policy.filters` for new configuration; don't combine both forms in the same layer.
`shell_environment_policy.inherit`	`all \| core \| none`	Baseline environment inheritance when spawning subprocesses.
`shell_environment_policy.set`	`map<string,string>`	Explicit environment values injected after exclusions; include filters can still remove them.
`show_raw_agent_reasoning`	`boolean`	Surface raw reasoning content when the active model emits it.
`skills.config`	`array<object>`	Per-skill enablement overrides stored in config.toml.
`skills.config.<index>.enabled`	`boolean`	Enable or disable the referenced skill.
`skills.config.<index>.path`	`string (path)`	Path to a skill folder containing `SKILL.md`.
`skills.max_context_tokens`	`integer (positive)`	Token budget for the available-skills catalog. Defaults to 2% of the model's context window. Explicit values are capped at `10000` tokens.
`sqlite_home`	`string (path)`	Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.
`suppress_unstable_features_warning`	`boolean`	Suppress the warning that appears when under-development feature flags are enabled.
`tool_output_token_limit`	`number`	Token budget for storing individual tool/function outputs in history.
`tool_suggest.disabled_tools`	`array<table>`	Disable suggestions for specific discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.
`tool_suggest.discoverables`	`array<table>`	Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.
`tools.view_image`	`boolean`	Enable the local-image attachment tool `view_image`.
`tools.web_search`	`boolean \| { context_size = "low\|medium\|high", allowed_domains = [string], location = { country, region, city, timezone } }`	Optional web search tool configuration. The object form can set search context size, allowed search domains, and approximate user location. These search-domain filters are separate from sandboxed-command network domain rules and do not restrict connectors or MCP servers.
`tui`	`table`	TUI-specific options such as enabling inline desktop notifications.
`tui.alternate_screen`	`auto \| always \| never`	Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).
`tui.animations`	`boolean`	Enable terminal animations (welcome screen, shimmer, spinner) (default: true).
`tui.keymap.<context>.<action>`	`string \| array<string>`	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`. Selected composer actions fall back to matching `tui.keymap.global` bindings; context-specific bindings take precedence when supported.
`tui.keymap.<context>.<action> = []`	`empty array`	Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, `page-down`, or `minus`.
`tui.model_availability_nux.<model>`	`integer`	Internal startup-tooltip state keyed by model slug.
`tui.notification_condition`	`unfocused \| always`	Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`.
`tui.notification_method`	`auto \| osc9 \| bel`	Notification method for terminal notifications (default: auto).
`tui.notifications`	`boolean \| array<string>`	Enable TUI notifications; optionally restrict to specific event types.
`tui.raw_output_mode`	`boolean`	Start the TUI in raw scrollback mode for copy-friendly terminal selection (default: false). You can toggle it with `/raw` or the default `alt-r` key binding.
`tui.resume_cwd`	`current \| session`	Working directory to use when resuming or forking a session. When unset, Codex asks you to choose if your current directory differs from the session's saved directory.
`tui.show_tooltips`	`boolean`	Show onboarding tooltips in the TUI welcome screen (default: true).
`tui.status_line`	`array<string> \| null`	Ordered list of TUI footer status-line item identifiers. `null` disables the status line.
`tui.terminal_title`	`array<string> \| null`	Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates.
`tui.theme`	`string`	Syntax-highlighting theme override (kebab-case theme name).
`tui.vim_mode_default`	`boolean`	Start the composer in Vim normal mode instead of insert mode (default: false). You can still toggle it per session with `/vim`.
`web_search`	`disabled \| cached \| indexed \| live`	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"`). Use `"live"` for unrestricted live retrieval, or `"disabled"` to remove the tool.
`windows_wsl_setup_acknowledged`	`boolean`	Track Windows onboarding acknowledgement (Windows only).
`windows.sandbox`	`unelevated \| elevated`	Windows-only native sandbox mode when running Codex natively on Windows.
`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.

You can find the latest JSON schema for config.toml here.

To get autocompletion and diagnostics when editing config.toml in VS Code or Cursor, you can install the Even Better TOML extension and add this line to the top of your config.toml:

#:schema https://developers.openai.com/codex/config-schema.json

Note: Rename experimental_instructions_file to model_instructions_file. Codex deprecates the old key; update existing configs to the new name.

`requirements.toml`

requirements.toml is an admin-enforced configuration file that constrains security-sensitive settings users can't override. For details, locations, and examples, see Admin-enforced requirements.

For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched requirements. See the security page for precedence details.

Use [features] in requirements.toml to pin runtime feature flags by the same canonical keys that config.toml uses. Requirements can also include documented app-only keys that don't belong in config.toml. Omitted keys remain unconstrained.

Some managed requirements enforce an exact configuration value instead of an allowlist. Users can't override an enforced path, update preference, login-shell policy, feedback setting, or Windows private-desktop setting.

Managed permission-profile allowlists require Codex 0.138.0 or later. Codex 0.137.0 and earlier ignore allowed_permission_profiles and managed default_permissions.

Use allowed_sandbox_modes with sandbox_mode. For permission-profile deployments, use allowed_permission_profiles with managed default_permissions.

An untrusted entry in allowed_approval_policies is still valid for the stricter approval behavior Codex derives when a project uses trust_level = "untrusted". It does not permit explicitly setting approval_policy = "untrusted".

The [models.new_thread] table supplies managed defaults, not enforcement. If you explicitly override the model or reasoning effort with --model, --config, or --profile, Codex ignores both model and model_reasoning_effort in [models.new_thread]. service_tier is independent.

The browser requirements cover three separate surfaces. in_app_browser controls the browser pane that a person opens and uses directly. browser_use controls agent-driven work in a browser. computer_use controls agent-driven work in native desktop apps.

The nested Browser Use and Computer Use policy values do not grant access by themselves. An origin- or app-specific allow can override the fallback for the same policy source, but normal feature, approval, and other policy checks still apply. Where managed requirements and config.toml both apply, a deny from either one wins.

Key	Type / Values	Details
`allow_appshots`	`boolean`	Set to `false` to disable Appshots for managed users. If omitted, Appshots remain unconstrained by requirements and follow normal product availability.
`allow_browser_and_computer_use`	`boolean`	Set to `false` to block both agent-driven Browser Use and native-app Computer Use. Setting it to `true` or omitting it does not enable either feature; the remaining feature, policy, and approval checks still apply.
`allow_login_shell`	`boolean`	Enforce whether shell tools can start a login shell.
`allow_managed_hooks_only`	`boolean`	When `true`, Codex skips user, project, session, and plugin hooks while still allowing managed hooks from `requirements.toml` and other managed config layers.
`allow_remote_control`	`boolean`	Set to `false` to disable device remote control for managed users. If omitted, device remote control remains unconstrained by requirements and follows normal product availability.
`allowed_approval_policies`	`array<string>`	Allowed approval policies, such as `on-request`, `never`, and `granular`. Include `untrusted` to permit the stricter policy derived from an untrusted project; it cannot be selected directly with `approval_policy`.
`allowed_approvals_reviewers`	`array<string>`	Allowed values for `approvals_reviewer`, such as `user` and `auto_review`.
`allowed_chatgpt_workspaces`	`array<string>`	Restrict ChatGPT login, including Codex access tokens, to the listed workspace IDs. An empty list disables ChatGPT login; API authentication remains available when permitted. Set through the local system requirements file or macOS MDM; cloud-managed values are ignored.
`allowed_login_methods`	`array<string>`	Allow `chatgpt`, `api`, or both. If omitted, this setting doesn't restrict login methods. If set, the list must contain at least one method. `api` permits API authentication, including Amazon Bedrock. Set through the local system requirements file or macOS MDM. Cloud-managed values are ignored.
`allowed_permission_profiles`	`table<boolean>`	Complete list of allowed permission profiles. Profiles set to `true` are allowed. Profiles that are omitted or set to `false` are denied, including profiles added in future versions. When requirements sources are combined, entries are matched by profile name.
`allowed_permission_profiles.<name>`	`boolean`	Allow or deny a built-in or custom permission profile defined in a loaded config or requirements source. A later, higher-precedence requirements source can use `false` to turn off a profile allowed by an earlier, lower-precedence source.
`allowed_sandbox_modes`	`array<string>`	Allowed values for `sandbox_mode`.
`allowed_web_search_modes`	`array<string>`	Allowed values for `web_search` (`disabled`, `cached`, `indexed`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`.
`apps`	`table`	Managed app requirements keyed by app identifier. Requirements can disable an app or constrain approval behavior for individual tools.
`apps.<id>.enabled`	`boolean`	Set to `false` to disable an app. A disabled requirement remains restrictive when multiple requirements sources are merged.
`apps.<id>.tools.<tool>.approval_mode`	`auto \| prompt \| writes \| approve`	Set the managed approval mode for one app tool.
`browser_use`	`table`	Managed requirements for agent-driven Browser Use.
`browser_use.allow_global_persistent_approval`	`boolean`	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. Existing saved approvals are ignored, not deleted. Setting it to `true` or omitting it does not create an approval.
`browser_use.allow_history_access`	`boolean`	Set to `false` to prevent Browser Use from reading browser history. Setting it to `true` or omitting it leaves normal history settings and availability checks in place.
`browser_use.default_origin_policy`	`table`	Fallback for each Browser Use setting when no matching entry under `browser_use.origins` defines it. A matching origin rule replaces the fallback for that source. Codex then applies the stricter result from managed requirements and user configuration.
`browser_use.default_origin_policy.access`	`allow \| deny`	Use `deny` to block Browser Use on origins that use the fallback. A denied origin also blocks uploads, downloads, full browser debugging access, and automatic review there. `allow` only lets normal approval and policy checks continue.
`browser_use.default_origin_policy.access_approval_lifetime`	`turn \| thread`	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. `persistent_approval` separately controls whether `Always allow` is available. The product default is `thread`.
`browser_use.default_origin_policy.auto_review`	`allow \| deny`	Use `deny` to skip automatic review on origins that use the fallback and ask the user for approval instead. `allow` leaves automatic review available when other settings allow it.
`browser_use.default_origin_policy.downloads`	`allow \| deny`	Use `deny` to block Browser Use downloads on origins that use the fallback. `allow` only lets normal approval and policy checks continue.
`browser_use.default_origin_policy.full_cdp_access`	`allow \| deny`	Use `deny` to block full Chrome DevTools Protocol (CDP) access on origins that use the fallback. `allow` only lets normal opt-in and approval checks continue.
`browser_use.default_origin_policy.persistent_approval`	`boolean`	Set to `false` to prevent Browser Use from saving or honoring an `Always allow` approval on origins that use the fallback. Approvals for the current turn or thread can still apply. `true` makes `Always allow` available when otherwise permitted but does not create an approval.
`browser_use.default_origin_policy.uploads`	`allow \| deny`	Use `deny` to block Browser Use uploads on origins that use the fallback. `allow` only lets normal approval and policy checks continue.
`browser_use.disable_auto_review`	`boolean`	Set to `true` to skip automatic review for Browser Use and ask the user for approval instead. Setting it to `false` or omitting it leaves automatic review available when other settings allow it.
`browser_use.origins`	`map<string, table>`	Origin-specific Browser Use policies. Keys use `<scheme>://<host-pattern>[:<port>]` with `http` or `https`. Use an exact host, `.example.com` for subdomains only, or `.example.com` for the base domain and its subdomains. Other `` wildcards can span dots, so `region.example.com` also matches `region.api.example.com`; a host of `` matches every host for that scheme. Schemes and nondefault ports are significant; explicit default ports are normalized away. Paths, queries, embedded usernames or passwords, and wildcard schemes or ports are invalid. Quote the pattern in TOML, for example `[browser_use.origins."https://**.example.com"]`.
`browser_use.origins.<pattern>`	`table`	Policy for origins matching this pattern. If several patterns match, Codex uses the most restrictive value for each capability: `deny` over `allow`, `false` over `true`, and `turn` over `thread`.
`browser_use.origins.<pattern>.access`	`allow \| deny`	Use `deny` to block Browser Use on matching origins. Denial also blocks uploads, downloads, full browser debugging access, and automatic review there. `allow` only lets normal approval and policy checks continue.
`browser_use.origins.<pattern>.access_approval_lifetime`	`turn \| thread`	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. `persistent_approval` separately controls whether `Always allow` is available.
`browser_use.origins.<pattern>.auto_review`	`allow \| deny`	Use `deny` to skip automatic review on matching origins and ask the user for approval instead. `allow` leaves automatic review available when other settings allow it.
`browser_use.origins.<pattern>.downloads`	`allow \| deny`	Use `deny` to block Browser Use downloads on matching origins. `allow` only lets normal approval and policy checks continue.
`browser_use.origins.<pattern>.full_cdp_access`	`allow \| deny`	Use `deny` to block full Chrome DevTools Protocol (CDP) access on matching origins. `allow` only lets normal opt-in and approval checks continue.
`browser_use.origins.<pattern>.persistent_approval`	`boolean`	Set to `false` to prevent Browser Use from saving or honoring an `Always allow` approval on matching origins. Approvals for the current turn or thread can still apply. `true` makes `Always allow` available when otherwise permitted but does not create an approval.
`browser_use.origins.<pattern>.uploads`	`allow \| deny`	Use `deny` to block Browser Use uploads on matching origins. `allow` only lets normal approval and policy checks continue.
`chatgpt_base_url`	`string`	Enforce the ChatGPT service base URL before authentication and cloud-policy retrieval. This doesn't configure every Codex network destination. Set through the local system requirements file or macOS MDM; cloud-managed values are ignored.
`check_for_update_on_startup`	`boolean`	Enforce whether Codex checks for updates when it starts.
`cli_auth_credentials_store`	`file \| keyring \| auto \| ephemeral`	Enforce the CLI credential store before authentication loads. `file` uses `CODEX_HOME/auth.json`; `keyring` requires the OS credential store; `auto` falls back to a file if the credential store is unavailable; `ephemeral` keeps credentials in memory for the current process. Set through the local system requirements file or macOS MDM; cloud-managed values are ignored.
`computer_use`	`table`	Managed requirements for agent-driven work in native desktop apps. Managed app rules and `config.toml` app rules are both enforced; an app must be allowed by each policy source.
`computer_use.allow_locked_computer_use`	`boolean`	Set to `false` to prevent users from enabling Locked Use on a managed macOS device. This requirement removes the enablement controls; it does not turn off Locked Use if it is already enabled. If omitted, normal product availability applies.
`computer_use.allow_persistent_approval`	`boolean`	Set to `false` to remove the option to save app approvals across sessions. Approvals for the current session remain available. Setting it to `true` or omitting it does not approve an app.
`computer_use.default_app_access`	`allow \| deny`	Fallback access for native apps that do not match a platform-specific rule. `deny` blocks access. `allow` only lets normal approval and policy checks continue. The product default is `allow`.
`computer_use.macos`	`table`	Computer Use app rules for macOS.
`computer_use.macos.bundle_ids`	`map<string, allow \| deny>`	Map exact macOS bundle identifiers to `allow` or `deny`. A matching rule replaces `computer_use.default_app_access` within the same policy source. A deny from either managed requirements or user configuration still blocks access.
`computer_use.macos.bundle_ids.<bundle-id>`	`allow \| deny`	Use `deny` to block the exact bundle identifier. `allow` overrides only this policy source's default and still requires any other policy source and the normal approval flow to allow the app.
`computer_use.windows`	`table`	Computer Use app rules for packaged and unpackaged Windows apps.
`computer_use.windows.aumids`	`map<string, allow \| deny>`	Map exact, registered Application User Model IDs (AUMIDs) for signed packaged apps to `allow` or `deny`. A matching rule replaces `computer_use.default_app_access` within the same policy source.
`computer_use.windows.aumids.<aumid>`	`allow \| deny`	Use `deny` to block the exact packaged-app identity. `allow` overrides only this policy source's default and still requires any other policy source and the normal approval flow to allow the app.
`computer_use.windows.exes`	`array<table>`	Rules for signed, unpackaged Windows executables. Rules match the executable's verified publisher and signed version information, not its path or current file name. A matching deny takes precedence over matching allows. Unsigned executables use `computer_use.default_app_access`; executables whose signed identity cannot be verified unambiguously are blocked.
`computer_use.windows.exes[].access`	`allow \| deny`	Required access decision for matching executables. `deny` blocks access. `allow` overrides only this policy source's default and still requires any other policy source and the normal approval flow to allow the app.
`computer_use.windows.exes[].binary_name`	`string`	Optional `OriginalFilename` from the executable's signed version information. Matching is case-insensitive. If a matching publisher and product rule requires this value but the executable does not provide it, Computer Use blocks the executable.
`computer_use.windows.exes[].product_name`	`string`	Required exact `ProductName` from the executable's signed version information.
`computer_use.windows.exes[].publisher_name`	`string`	Required exact publisher name from the executable's trusted signing certificate, formatted as a Windows X.500 distinguished name.
`default_permissions`	`string`	Managed default permission profile. The profile must be allowed by `allowed_permission_profiles`. Set this explicitly for predictable behavior; if omitted, Codex defaults to `:workspace` only when both `:workspace` and `:read-only` are explicitly allowed.
`enforce_residency`	`string`	Require Codex service traffic to use a supported data residency. Currently accepts `us`.
`experimental_network`	`table`	Administrator-managed network requirements for sandboxed local commands, enforced from `requirements.toml`. When enabled, these requirements can start the command network proxy without `features.network_proxy`. Browser tools separately check managed network denies and exclusive allowlists. These requirements do not route browser traffic through the proxy or control web search, apps, MCP servers, native-app traffic, or Codex cloud networking.
`experimental_network.allow_local_binding`	`boolean`	Permit broader local/private-network access for sandboxed networking. Exact local IP literal or `localhost` allow rules can still permit specific local targets when this stays `false`.
`experimental_network.allow_upstream_proxy`	`boolean`	Allow sandboxed networking to chain through an upstream proxy from the environment.
`experimental_network.allowed_domains`	`array<string>`	Administrator allow rules for sandboxed-command networking while the managed network proxy is enabled. These rules do not apply to web search, apps, or MCP servers. Do not combine this with `experimental_network.domains`.
`experimental_network.dangerously_allow_all_unix_sockets`	`boolean`	Permit arbitrary Unix socket destinations instead of allowlist-only access. Use only in tightly controlled environments.
`experimental_network.dangerously_allow_non_loopback_proxy`	`boolean`	Permit non-loopback listener addresses for `[experimental_network]` requirements. Enabling it can expose listeners beyond localhost.
`experimental_network.denied_domains`	`array<string>`	List-shaped administrator deny rules for sandboxed networking. Do not combine this with `experimental_network.domains`.
`experimental_network.domains`	`map<string, allow \| deny>`	Map-shaped administrator domain policy for sandboxed networking. Supports exact hosts, `.example.com` for subdomains only, `.example.com` for apex plus subdomains, and global `` allow rules; prefer scoped rules because `*` broadly opens public outbound access. `deny` wins on conflicts. Do not combine this with `experimental_network.allowed_domains` or `experimental_network.denied_domains`.
`experimental_network.enabled`	`boolean`	Enable sandboxed networking requirements. This does not grant network access when the active sandbox keeps command networking off.
`experimental_network.http_port`	`integer`	Loopback HTTP listener port to use for `[experimental_network]` requirements.
`experimental_network.managed_allowed_domains_only`	`boolean`	When `true`, only administrator-managed allow rules remain effective while sandboxed networking requirements are active; user allowlist additions are ignored. Without managed allow rules, user-added domain allow rules do not remain effective.
`experimental_network.socks_port`	`integer`	Loopback SOCKS5 listener port to use for `[experimental_network]` requirements.
`experimental_network.unix_sockets`	`map<string, allow \| deny>`	Administrator-managed Unix socket policy for sandboxed networking.
`features`	`table`	Pinned feature values. Use canonical names from `config.toml` for runtime features; documented app-only requirement keys are also supported here.
`features.<name>`	`boolean`	Require a documented runtime or app feature to stay enabled or disabled.
`features.apps`	`boolean`	Pin Apps integration availability on or off for managed users.
`features.browser_use`	`boolean`	Set to `false` in `requirements.toml` to disable agent-driven Browser Use.
`features.browser_use_external`	`boolean`	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.
`features.browser_use_full_cdp_access`	`boolean`	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. If omitted, normal product availability applies.
`features.computer_use`	`boolean`	Set to `false` in `requirements.toml` to disable Computer Use, Record & Replay, and related install or enablement flows.
`features.fast_mode`	`boolean`	Pin the canonical `fast_mode` feature on or off for managed users.
`features.guardian_approval`	`boolean`	Pin Guardian approval availability on or off for managed users.
`features.in_app_browser`	`boolean`	Set to `false` in `requirements.toml` to disable the built-in browser pane that users open and control directly.
`features.in_app_updates`	`boolean`	Set to `false` in `requirements.toml` to disable in-app updates. Updates remain enabled by default when this requirement is omitted.
`features.memories`	`boolean`	Pin Memories availability on or off for managed users.
`features.multi_agent`	`boolean`	Pin multi-agent availability on or off for managed users.
`features.plugin_sharing`	`boolean`	Set to `false` in cloud-managed `requirements.toml` to disable workspace sharing for locally built plugins.
`features.plugins`	`boolean`	Pin plugin availability on or off for managed users.
`features.remote_plugin`	`boolean`	Pin remote plugin catalog availability on or off for managed users.
`features.workspace_dependencies`	`boolean`	Pin bundled workspace-dependency runtime availability on or off for managed users.
`feedback`	`table`	Managed feedback settings.
`feedback.enabled`	`boolean`	Enforce whether users can submit feedback across Codex clients.
`guardian_policy_config`	`string`	Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored.
`hooks`	`table`	Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`.
`hooks.<Event>`	`array<table>`	Matcher groups for a hook event such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `SessionEnd`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`, or `Stop`.
`hooks.<Event>[].hooks`	`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.
`hooks.<Event>[].hooks[].additionalContextLimit`	`integer`	Approximate per-handler token threshold for saving oversized `additionalContext` to disk and showing the model a shorter preview. Defaults to `2500`; `0` passes the full context directly to the model. See Large hook output.
`hooks.<Event>[].hooks[].async`	`boolean`	Run a command hook in the background without delaying the triggering operation. Defaults to `false`; `SessionEnd` always runs synchronously. See Run hooks in the background.
`hooks.<Event>[].hooks[].commandWindows`	`string`	Windows-only command override for command hooks. The TOML alias `command_windows` is also accepted.
`hooks.managed_dir`	`string (absolute path)`	Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks.
`hooks.windows_managed_dir`	`string (absolute path)`	Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks.
`in_app_browser`	`table`	Requirements for the built-in browser pane. These settings do not control agent-driven Browser Use.
`in_app_browser.allow_external_browser_settings_import`	`boolean`	Set to `false` to prevent users from importing settings or browsing data from an external browser into the built-in browser. Setting it to `true` or omitting it leaves the import available when other product checks allow it. This is a managed-only setting with no `config.toml` override.
`log_dir`	`string (path)`	Enforce the directory where Codex writes local log files.
`marketplaces`	`table`	Admin requirements for plugin marketplace sources. Rules take effect when `restrict_to_allowed_sources` is `true`.
`marketplaces.allowed_sources`	`table`	Allowed marketplace sources keyed by administrator-chosen rule name. Distinct names accumulate across requirements layers; fields under the same name use normal layer precedence.
`marketplaces.allowed_sources.<name>`	`table`	One allowed source rule. The final `source` value after requirements merge determines which sibling fields Codex interprets.
`marketplaces.allowed_sources.<name>.host_pattern`	`string`	Regular expression required when `source = "host_pattern"`. Codex matches it against the lowercase hostname parsed from an HTTPS, SSH, or SCP-style Git source. Use `^` and `$` to require a whole-host match.
`marketplaces.allowed_sources.<name>.path`	`string (absolute path)`	Local marketplace directory required when `source = "local"`. Codex requires an absolute path and compares paths after normalization.
`marketplaces.allowed_sources.<name>.ref`	`string`	Optional exact Git ref for a `git` rule. When omitted, the rule allows any ref for the matching repository.
`marketplaces.allowed_sources.<name>.source`	`git \| host_pattern \| local`	Marketplace source matcher type. Use `git` for one repository, `host_pattern` for Git hosts matched by regular expression, or `local` for one directory.
`marketplaces.allowed_sources.<name>.url`	`string`	Git repository URL required when `source = "git"`. Codex normalizes the configured and allowed URLs before requiring an exact repository match.
`marketplaces.restrict_to_allowed_sources`	`boolean`	When `true`, require configured marketplace sources to match `allowed_sources` for marketplace add, plugin install, refresh, and runtime loading. OpenAI-curated Git catalogs, including the API-key catalog, must also match the allowlist. Bundled and remotely installed workspace plugins are separate from this curated Git source policy.
`mcp_servers`	`table`	Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled.
`mcp_servers.<id>.identity`	`table`	Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP).
`mcp_servers.<id>.identity.command`	`string \| table`	Allow an MCP stdio server by exact command string, or use a matcher table to require an exact executable and ordered argument matchers. The string form doesn't inspect arguments, `cwd`, `env`, or `env_vars`.
`mcp_servers.<id>.identity.command.args`	`array<table>`	Ordered argument matchers for a stdio server. The configured argument list must have the same length, and every position must match. Command matchers don't inspect `cwd`, `env`, or `env_vars`.
`mcp_servers.<id>.identity.command.args[].expression`	`string`	Regular expression used by a `regex` argument matcher. The expression must be valid and match the complete argument value.
`mcp_servers.<id>.identity.command.args[].match`	`exact \| prefix \| regex`	Match operation for this argument position.
`mcp_servers.<id>.identity.command.args[].value`	`string`	Value used by an `exact` or `prefix` argument matcher.
`mcp_servers.<id>.identity.command.executable`	`string`	Executable that the stdio server's configured `command` must match exactly.
`mcp_servers.<id>.identity.url`	`string \| table`	Allow an MCP streamable HTTP server by exact URL string, or use an `exact`, `prefix`, or `regex` value matcher table.
`mcp_servers.<id>.identity.url.expression`	`string`	Regular expression used by a `regex` URL matcher. The expression must be valid and match the complete URL value.
`mcp_servers.<id>.identity.url.match`	`exact \| prefix \| regex`	Match operation for the configured MCP server URL.
`mcp_servers.<id>.identity.url.value`	`string`	Value used by an `exact` or `prefix` URL matcher.
`model_catalog_json`	`string (path)`	Enforce the JSON model catalog Codex uses at startup.
`models`	`table`	Managed model defaults for new threads. These values take priority over user and project defaults, but an explicit selection for the new thread can override them.
`models.new_thread`	`table`	Defaults to apply when a new local thread starts. Each model setting is optional.
`models.new_thread.model`	`string`	Default model for new threads. An explicit `--model` or model/reasoning `--config` override takes precedence.
`models.new_thread.model_reasoning_effort`	`string`	Default reasoning effort for new threads. An explicit model or reasoning-effort override skips both managed model fields.
`models.new_thread.service_tier`	`string`	Default service tier for new threads. An explicit service-tier override takes precedence independently of the model fields.
`permissions`	`table`	Admin-defined permission profiles keyed by profile name. Uses the same profile fields as `config.toml`.
`permissions.<name>`	`table`	Admin-defined permission profile. The name can't start with `:`, use the reserved name `filesystem`, or duplicate a profile from a loaded config. Uses the same profile fields as `config.toml`; see the Permissions guide for the complete profile schema.
`permissions.filesystem.deny_read`	`array<string>`	Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config.
`plugins`	`table`	Plugin-specific MCP server allowlists keyed by plugin identifier. When this table is present, plugin-bundled servers without a matching plugin and server entry are disabled.
`plugins.<plugin>.mcp_servers`	`table`	Allowlist for MCP servers bundled with one plugin. Plugin server requirements use the same exact identity and matcher forms as top-level `mcp_servers` requirements.
`plugins.<plugin>.mcp_servers.<server>.identity`	`table`	Identity rule for one plugin-bundled MCP server. Set either `command` (stdio) or `url` (streamable HTTP).
`plugins.<plugin>.mcp_servers.<server>.identity.command`	`string \| table`	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.
`plugins.<plugin>.mcp_servers.<server>.identity.command.args`	`array<table>`	Ordered argument matchers for a plugin-bundled stdio server. The configured argument list must have the same length, and every position must match.
`plugins.<plugin>.mcp_servers.<server>.identity.command.args[].expression`	`string`	Regular expression used by a `regex` argument matcher. The expression must match the complete argument value.
`plugins.<plugin>.mcp_servers.<server>.identity.command.args[].match`	`exact \| prefix \| regex`	Match operation for this argument position.
`plugins.<plugin>.mcp_servers.<server>.identity.command.args[].value`	`string`	Value used by an `exact` or `prefix` argument matcher.
`plugins.<plugin>.mcp_servers.<server>.identity.command.executable`	`string`	Executable that the plugin-bundled stdio server's configured command must match exactly.
`plugins.<plugin>.mcp_servers.<server>.identity.url`	`string \| table`	Allow a plugin's streamable HTTP MCP server by exact URL string, or use an `exact`, `prefix`, or `regex` value matcher table.
`plugins.<plugin>.mcp_servers.<server>.identity.url.expression`	`string`	Regular expression used by a `regex` URL matcher. The expression must match the complete URL value.
`plugins.<plugin>.mcp_servers.<server>.identity.url.match`	`exact \| prefix \| regex`	Match operation for the plugin-bundled MCP server URL.
`plugins.<plugin>.mcp_servers.<server>.identity.url.value`	`string`	Value used by an `exact` or `prefix` URL matcher.
`remote_sandbox_config`	`array<table>`	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. Host-specific entries currently override sandbox modes only.
`remote_sandbox_config[].allowed_sandbox_modes`	`array<string>`	Allowed sandbox modes to apply when this host-specific entry matches.
`remote_sandbox_config[].hostname_patterns`	`array<string>`	Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character.
`rules`	`table`	Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive.
`rules.prefix_rules`	`array<table>`	List of enforced prefix rules. Each rule must include `pattern` and `decision`.
`rules.prefix_rules[].decision`	`prompt \| forbidden`	Required. Requirements rules can only prompt or forbid (not allow).
`rules.prefix_rules[].justification`	`string`	Optional non-empty rationale surfaced in approval prompts or rejection messages.
`rules.prefix_rules[].pattern`	`array<table>`	Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`.
`rules.prefix_rules[].pattern[].any_of`	`array<string>`	A list of allowed alternative tokens at this position.
`rules.prefix_rules[].pattern[].token`	`string`	A single literal token at this position.
`sqlite_home`	`string (path)`	Enforce the directory where Codex stores SQLite-backed runtime state.
`windows`	`table`	Native Windows sandbox requirements.
`windows.allowed_sandbox_implementations`	`array<string>`	Allowed native Windows sandbox implementations for `windows.sandbox` (`elevated` and `unelevated`). The list must not be empty. When both are allowed and no mode is selected, Codex prefers `elevated`.
`windows.sandbox_private_desktop`	`boolean`	Enforce whether the native Windows sandbox starts its child process on a private desktop.

Recent searches

Suggested searches

Documentation navigation

`config.toml`

`requirements.toml`