diff --git a/en/config-reference.md b/en/config-reference.md index 502947b..20d6093 100644 --- a/en/config-reference.md +++ b/en/config-reference.md @@ -1,4 +1,4 @@ -# Configuration Reference +# Configuration Reference – Codex Use this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with [Config basics](https://developers.openai.com/codex/config-basic) and [Advanced Config](https://developers.openai.com/codex/config-advanced). @@ -6,7 +6,7 @@ Use this page as a searchable reference for Codex configuration files. For conce 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, +Project-scoped config can’t override machine-local provider, auth, notification, profile, or telemetry routing keys. Codex ignores `openai_base_url`, `chatgpt_base_url`, `model_provider`, `model_providers`, `notify`, `profile`, `profiles`, `experimental_realtime_ws_base_url`, and @@ -15,1736 +15,3881 @@ user-level config instead. For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access). -.model_catalog_json` can override this per profile.", - }, - { - key: "oss_provider", - type: "lmstudio | ollama", - description: - "Default local provider used when running with `--oss` (defaults to prompting if unset).", - }, - { - key: "approval_policy", - type: "untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }", - description: - "Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.", - }, - { - key: "approval_policy.granular.sandbox_approval", - type: "boolean", - description: - "When `true`, sandbox escalation approval prompts are allowed to surface.", - }, - { - key: "approval_policy.granular.rules", - type: "boolean", - description: - "When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.", - }, - { - key: "approval_policy.granular.mcp_elicitations", - type: "boolean", - description: - "When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.", - }, - { - key: "approval_policy.granular.request_permissions", - type: "boolean", - description: - "When `true`, prompts from the `request_permissions` tool are allowed to surface.", - }, - { - key: "approval_policy.granular.skill_approval", - type: "boolean", - description: - "When `true`, skill-script approval prompts are allowed to surface.", - }, - { - key: "approvals_reviewer", - type: "user | auto_review", - description: - "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.", - }, - { - key: "auto_review.policy", - type: "string", - description: - "Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored.", - }, - { - key: "allow_login_shell", - type: "boolean", - description: - "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.", - }, - { - key: "sandbox_mode", - type: "read-only | workspace-write | danger-full-access", - description: - "Sandbox policy for filesystem and network access during command execution.", - }, - { - key: "sandbox_workspace_write.writable_roots", - type: "array", - description: - 'Additional writable roots when `sandbox_mode = "workspace-write"`.', - }, - { - key: "sandbox_workspace_write.network_access", - type: "boolean", - description: - "Allow outbound network access inside the workspace-write sandbox.", - }, - { - key: "sandbox_workspace_write.exclude_tmpdir_env_var", - type: "boolean", - description: - "Exclude `$TMPDIR` from writable roots in workspace-write mode.", - }, - { - key: "sandbox_workspace_write.exclude_slash_tmp", - type: "boolean", - description: - "Exclude `/tmp` from writable roots in workspace-write mode.", - }, - { - key: "windows.sandbox", - type: "unelevated | elevated", - description: - "Windows-only native sandbox mode when running Codex natively on Windows.", - }, - { - key: "windows.sandbox_private_desktop", - type: "boolean", - description: - "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.", - }, - { - key: "notify", - type: "array", - description: - "Command invoked for notifications; receives a JSON payload from Codex.", - }, - { - key: "check_for_update_on_startup", - type: "boolean", - description: - "Check for Codex updates on startup (set to false only when updates are centrally managed).", - }, - { - key: "feedback.enabled", - type: "boolean", - description: - "Enable feedback submission via `/feedback` across Codex surfaces (default: true).", - }, - { - key: "analytics.enabled", - type: "boolean", - description: - "Enable or disable analytics for this machine/profile. When unset, the client default applies.", - }, - { - key: "instructions", - type: "string", - description: - "Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.", - }, - { - key: "developer_instructions", - type: "string", - description: - "Additional developer instructions injected into the session (optional).", - }, - { - key: "log_dir", - type: "string (path)", - description: - "Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.", - }, - { - key: "sqlite_home", - type: "string (path)", - description: - "Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.", - }, - { - key: "compact_prompt", - type: "string", - description: "Inline override for the history compaction prompt.", - }, - { - key: "commit_attribution", - type: "string", - description: - 'Commit co-author trailer used when `[features].codex_git_commit` is enabled. Defaults to `Codex `; set `""` to disable.', - }, - { - key: "model_instructions_file", - type: "string (path)", - description: - "Replacement for built-in instructions instead of `AGENTS.md`.", - }, - { - key: "personality", - type: "none | friendly | pragmatic", - description: - "Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.", - }, - { - key: "service_tier", - type: "string", - description: - "Preferred service tier for new turns. Built-in values include `flex` and `fast`; legacy `fast` config maps to the request value `priority`, and catalog-provided tier IDs can also be stored.", - }, - { - key: "experimental_compact_prompt_file", - type: "string (path)", - description: - "Load the compaction prompt override from a file (experimental).", - }, - { - key: "skills.config", - type: "array", - description: "Per-skill enablement overrides stored in config.toml.", - }, - { - key: "skills.config..path", - type: "string (path)", - description: "Path to a skill folder containing `SKILL.md`.", - }, - { - key: "skills.config..enabled", - type: "boolean", - description: "Enable or disable the referenced skill.", - }, - { - key: "apps..enabled", - type: "boolean", - description: - "Enable or disable a specific app/connector by id (default: true).", - }, - { - key: "apps._default.enabled", - type: "boolean", - description: - "Default app enabled state for all apps unless overridden per app.", - }, - { - key: "apps._default.destructive_enabled", - type: "boolean", - description: - "Default allow/deny for app tools with `destructive_hint = true`.", - }, - { - key: "apps._default.open_world_enabled", - type: "boolean", - description: - "Default allow/deny for app tools with `open_world_hint = true`.", - }, - { - key: "apps..destructive_enabled", - type: "boolean", - description: - "Allow or block tools in this app that advertise `destructive_hint = true`.", - }, - { - key: "apps..open_world_enabled", - type: "boolean", - description: - "Allow or block tools in this app that advertise `open_world_hint = true`.", - }, - { - key: "apps..default_tools_enabled", - type: "boolean", - description: - "Default enabled state for tools in this app unless a per-tool override exists.", - }, - { - key: "apps..default_tools_approval_mode", - type: "auto | prompt | approve", - description: - "Default approval behavior for tools in this app unless a per-tool override exists.", - }, - { - key: "apps..tools..enabled", - type: "boolean", - description: - "Per-tool enabled override for an app tool (for example `repos/list`).", - }, - { - key: "apps..tools..approval_mode", - type: "auto | prompt | approve", - description: "Per-tool approval behavior override for a single app tool.", - }, - { - key: "tool_suggest.discoverables", - type: "array", - description: - 'Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.', - }, - { - key: "tool_suggest.disabled_tools", - type: "array
", - description: - 'Disable suggestions for specific discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.', - }, - { - key: "features.apps", - type: "boolean", - description: "Enable ChatGPT Apps/connectors support (experimental).", - }, - { - key: "features.hooks", - type: "boolean", - description: - "Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. `features.codex_hooks` is a deprecated alias.", - }, - { - key: "features.codex_git_commit", - type: "boolean", - description: - "Enable Codex-generated git commits. When enabled, Codex uses `commit_attribution` to append a `Co-authored-by:` trailer to generated commit messages.", - }, - { - key: "hooks", - type: "table", - description: - "Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.", - }, - { - key: "features.plugin_hooks", - type: "boolean", - description: - "Opt into lifecycle hooks bundled with enabled plugins. Off by default in this release; set to `true` to opt in.", - }, - { - key: "features.memories", - type: "boolean", - description: "Enable [Memories](https://developers.openai.com/codex/memories) (off by default).", - }, - { - key: "mcp_servers..command", - type: "string", - description: "Launcher command for an MCP stdio server.", - }, - { - key: "mcp_servers..args", - type: "array", - description: "Arguments passed to the MCP stdio server command.", - }, - { - key: "mcp_servers..env", - type: "map", - description: "Environment variables forwarded to the MCP stdio server.", - }, - { - key: "mcp_servers..env_vars", - type: 'array', - description: - '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.', - }, - { - key: "mcp_servers..cwd", - type: "string", - description: "Working directory for the MCP stdio server process.", - }, - { - key: "mcp_servers..url", - type: "string", - description: "Endpoint for an MCP streamable HTTP server.", - }, - { - key: "mcp_servers..bearer_token_env_var", - type: "string", - description: - "Environment variable sourcing the bearer token for an MCP HTTP server.", - }, - { - key: "mcp_servers..http_headers", - type: "map", - description: "Static HTTP headers included with each MCP HTTP request.", - }, - { - key: "mcp_servers..env_http_headers", - type: "map", - description: - "HTTP headers populated from environment variables for an MCP HTTP server.", - }, - { - key: "mcp_servers..enabled", - type: "boolean", - description: "Disable an MCP server without removing its configuration.", - }, - { - key: "mcp_servers..required", - type: "boolean", - description: - "When true, fail startup/resume if this enabled MCP server cannot initialize.", - }, - { - key: "mcp_servers..startup_timeout_sec", - type: "number", - description: - "Override the default 10s startup timeout for an MCP server.", - }, - { - key: "mcp_servers..startup_timeout_ms", - type: "number", - description: "Alias for `startup_timeout_sec` in milliseconds.", - }, - { - key: "mcp_servers..tool_timeout_sec", - type: "number", - description: - "Override the default 60s per-tool timeout for an MCP server.", - }, - { - key: "mcp_servers..enabled_tools", - type: "array", - description: "Allow list of tool names exposed by the MCP server.", - }, - { - key: "mcp_servers..disabled_tools", - type: "array", - description: - "Deny list applied after `enabled_tools` for the MCP server.", - }, - { - key: "mcp_servers..default_tools_approval_mode", - type: "auto | prompt | approve", - description: - "Default approval behavior for MCP tools on this server unless a per-tool override exists.", - }, - { - key: "mcp_servers..tools..approval_mode", - type: "auto | prompt | approve", - description: - "Per-tool approval behavior override for one MCP tool on this server.", - }, - { - key: "mcp_servers..scopes", - type: "array", - description: - "OAuth scopes to request when authenticating to that MCP server.", - }, - { - key: "mcp_servers..oauth_resource", - type: "string", - description: - "Optional RFC 8707 OAuth resource parameter to include during MCP login.", - }, - { - key: "mcp_servers..experimental_environment", - type: "local | remote", - description: - "Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.", - }, - { - key: "agents.max_threads", - type: "number", - description: - "Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.", - }, - { - key: "agents.max_depth", - type: "number", - description: - "Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).", - }, - { - key: "agents.job_max_runtime_seconds", - type: "number", - description: - "Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.", - }, - { - key: "agents..description", - type: "string", - description: - "Role guidance shown to Codex when choosing and spawning that agent type.", - }, - { - key: "agents..config_file", - type: "string (path)", - description: - "Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.", - }, - { - key: "agents..nickname_candidates", - type: "array", - description: - "Optional pool of display nicknames for spawned agents in that role.", - }, - { - key: "memories.generate_memories", - type: "boolean", - description: - "When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.", - }, - { - key: "memories.use_memories", - type: "boolean", - description: - "When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.", - }, - { - key: "memories.disable_on_external_context", - type: "boolean", - description: - "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`.", - }, - { - key: "memories.max_raw_memories_for_consolidation", - type: "number", - description: - "Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.", - }, - { - key: "memories.max_unused_days", - type: "number", - description: - "Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.", - }, - { - key: "memories.max_rollout_age_days", - type: "number", - description: - "Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.", - }, - { - key: "memories.max_rollouts_per_startup", - type: "number", - description: - "Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.", - }, - { - key: "memories.min_rollout_idle_hours", - type: "number", - description: - "Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.", - }, - { - key: "memories.min_rate_limit_remaining_percent", - type: "number", - description: - "Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`.", - }, - { - key: "memories.extract_model", - type: "string", - description: "Optional model override for per-thread memory extraction.", - }, - { - key: "memories.consolidation_model", - type: "string", - description: "Optional model override for global memory consolidation.", - }, - { - key: "features.unified_exec", - type: "boolean", - description: - "Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).", - }, - { - key: "features.shell_snapshot", - type: "boolean", - description: - "Snapshot shell environment to speed up repeated commands (stable; on by default).", - }, - { - key: "features.undo", - type: "boolean", - description: "Enable undo support (stable; off by default).", - }, - { - key: "features.multi_agent", - type: "boolean", - description: - "Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).", - }, - { - key: "features.personality", - type: "boolean", - description: - "Enable personality selection controls (stable; on by default).", - }, - { - key: "features.network_proxy", - type: "boolean | table", - description: - "Enable sandboxed networking. Use a table form when setting network policy options such as `domains` (experimental; off by default).", - }, - { - key: "features.network_proxy.enabled", - type: "boolean", - description: "Enable sandboxed networking. Defaults to `false`.", - }, - { - key: "features.network_proxy.domains", - type: "map", - description: - "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.", - }, - { - key: "features.network_proxy.unix_sockets", - type: "map", - description: - "Unix socket policy for sandboxed networking. Unset by default; add `allow` entries for permitted sockets.", - }, - { - key: "features.network_proxy.allow_local_binding", - type: "boolean", - description: - "Allow broader local/private-network access. Defaults to `false`; exact local IP literal or `localhost` allow rules can still permit specific local targets.", - }, - { - key: "features.network_proxy.enable_socks5", - type: "boolean", - description: "Expose SOCKS5 support. Defaults to `true`.", - }, - { - key: "features.network_proxy.enable_socks5_udp", - type: "boolean", - description: "Allow UDP over SOCKS5. Defaults to `true`.", - }, - { - key: "features.network_proxy.allow_upstream_proxy", - type: "boolean", - description: - "Allow chaining through an upstream proxy from the environment. Defaults to `true`.", - }, - { - key: "features.network_proxy.dangerously_allow_non_loopback_proxy", - type: "boolean", - description: - "Permit non-loopback listener addresses. Defaults to `false`; enabling it can expose proxy listeners beyond localhost.", - }, - { - key: "features.network_proxy.dangerously_allow_all_unix_sockets", - type: "boolean", - description: - "Permit arbitrary Unix socket destinations instead of allowlist-only access. Defaults to `false`; use only in tightly controlled environments.", - }, - { - key: "features.network_proxy.proxy_url", - type: "string", - description: - 'HTTP listener URL for sandboxed networking. Defaults to `"http://127.0.0.1:3128"`.', - }, - { - key: "features.network_proxy.socks_url", - type: "string", - description: - 'SOCKS5 listener URL. Defaults to `"http://127.0.0.1:8081"`.', - }, - { - key: "features.web_search", - type: "boolean", - description: - "Deprecated legacy toggle; prefer the top-level `web_search` setting.", - }, - { - key: "features.web_search_cached", - type: "boolean", - description: - 'Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.', - }, - { - key: "features.web_search_request", - type: "boolean", - description: - 'Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.', - }, - { - key: "features.shell_tool", - type: "boolean", - description: - "Enable the default `shell` tool for running commands (stable; on by default).", - }, - { - key: "features.enable_request_compression", - type: "boolean", - description: - "Compress streaming request bodies with zstd when supported (stable; on by default).", - }, - { - key: "features.skill_mcp_dependency_install", - type: "boolean", - description: - "Allow prompting and installing missing MCP dependencies for skills (stable; on by default).", - }, - { - key: "features.fast_mode", - type: "boolean", - description: - "Enable model-catalog service tier selection in the TUI, including Fast-tier commands when the active model advertises them (stable; on by default).", - }, - { - key: "features.prevent_idle_sleep", - type: "boolean", - description: - "Prevent the machine from sleeping while a turn is actively running (experimental; off by default).", - }, - { - key: "suppress_unstable_features_warning", - type: "boolean", - description: - "Suppress the warning that appears when under-development feature flags are enabled.", - }, - { - key: "model_providers.", - type: "table", - description: - "Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.", - }, - { - key: "model_providers..name", - type: "string", - description: "Display name for a custom model provider.", - }, - { - key: "model_providers..base_url", - type: "string", - description: "API base URL for the model provider.", - }, - { - key: "model_providers..env_key", - type: "string", - description: "Environment variable supplying the provider API key.", - }, - { - key: "model_providers..env_key_instructions", - type: "string", - description: "Optional setup guidance for the provider API key.", - }, - { - key: "model_providers..experimental_bearer_token", - type: "string", - description: - "Direct bearer token for the provider (discouraged; use `env_key`).", - }, - { - key: "model_providers..requires_openai_auth", - type: "boolean", - description: - "The provider uses OpenAI authentication (defaults to false).", - }, - { - key: "model_providers..wire_api", - type: "responses", - description: - "Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.", - }, - { - key: "model_providers..query_params", - type: "map", - description: "Extra query parameters appended to provider requests.", - }, - { - key: "model_providers..http_headers", - type: "map", - description: "Static HTTP headers added to provider requests.", - }, - { - key: "model_providers..env_http_headers", - type: "map", - description: - "HTTP headers populated from environment variables when present.", - }, - { - key: "model_providers..request_max_retries", - type: "number", - description: - "Retry count for HTTP requests to the provider (default: 4).", - }, - { - key: "model_providers..stream_max_retries", - type: "number", - description: "Retry count for SSE streaming interruptions (default: 5).", - }, - { - key: "model_providers..stream_idle_timeout_ms", - type: "number", - description: - "Idle timeout for SSE streams in milliseconds (default: 300000).", - }, - { - key: "model_providers..supports_websockets", - type: "boolean", - description: - "Whether that provider supports the Responses API WebSocket transport.", - }, - { - key: "model_providers..auth", - type: "table", - description: - "Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.", - }, - { - key: "model_providers..auth.command", - type: "string", - description: - "Command to run when Codex needs a bearer token. The command must print the token to stdout.", - }, - { - key: "model_providers..auth.args", - type: "array", - description: "Arguments passed to the token command.", - }, - { - key: "model_providers..auth.timeout_ms", - type: "number", - description: - "Maximum token command runtime in milliseconds (default: 5000).", - }, - { - key: "model_providers..auth.refresh_interval_ms", - type: "number", - description: - "How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.", - }, - { - key: "model_providers..auth.cwd", - type: "string (path)", - description: "Working directory for the token command.", - }, - { - key: "model_providers.amazon-bedrock.aws.profile", - type: "string", - description: - "AWS profile name used by the built-in `amazon-bedrock` provider.", - }, - { - key: "model_providers.amazon-bedrock.aws.region", - type: "string", - description: "AWS region used by the built-in `amazon-bedrock` provider.", - }, - { - key: "model_reasoning_effort", - type: "minimal | low | medium | high | xhigh", - description: - "Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).", - }, - { - key: "plan_mode_reasoning_effort", - type: "none | minimal | low | medium | high | xhigh", - description: - "Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default.", - }, - { - key: "model_reasoning_summary", - type: "auto | concise | detailed | none", - description: - "Select reasoning summary detail or disable summaries entirely.", - }, - { - key: "model_verbosity", - type: "low | medium | high", - description: - "Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.", - }, - { - key: "model_supports_reasoning_summaries", - type: "boolean", - description: "Force Codex to send or not send reasoning metadata.", - }, - { - key: "shell_environment_policy.inherit", - type: "all | core | none", - description: - "Baseline environment inheritance when spawning subprocesses.", - }, - { - key: "shell_environment_policy.ignore_default_excludes", - type: "boolean", - description: - "Keep variables containing KEY/SECRET/TOKEN before other filters run.", - }, - { - key: "shell_environment_policy.exclude", - type: "array", - description: - "Glob patterns for removing environment variables after the defaults.", - }, - { - key: "shell_environment_policy.include_only", - type: "array", - description: - "Whitelist of patterns; when set only matching variables are kept.", - }, - { - key: "shell_environment_policy.set", - type: "map", - description: - "Explicit environment overrides injected into every subprocess.", - }, - { - key: "shell_environment_policy.experimental_use_profile", - type: "boolean", - description: "Use the user shell profile when spawning subprocesses.", - }, - { - key: "project_root_markers", - type: "array", - description: - "List of project root marker filenames; used when searching parent directories for the project root.", - }, - { - key: "project_doc_max_bytes", - type: "number", - description: - "Maximum bytes read from `AGENTS.md` when building project instructions.", - }, - { - key: "project_doc_fallback_filenames", - type: "array", - description: "Additional filenames to try when `AGENTS.md` is missing.", - }, - { - key: "profile", - type: "string", - description: - "Default profile applied at startup (equivalent to `--profile`).", - }, - { - key: "profiles..*", - type: "various", - description: - "Profile-scoped overrides for any of the supported configuration keys.", - }, - { - key: "profiles..service_tier", - type: "string", - description: "Profile-scoped service tier preference for new turns.", - }, - { - key: "profiles..plan_mode_reasoning_effort", - type: "none | minimal | low | medium | high | xhigh", - description: "Profile-scoped Plan-mode reasoning override.", - }, - { - key: "profiles..web_search", - type: "disabled | cached | live", - description: - 'Profile-scoped web search mode override (default: `"cached"`).', - }, - { - key: "profiles..personality", - type: "none | friendly | pragmatic", - description: - "Profile-scoped communication style override for supported models.", - }, - { - key: "profiles..model_catalog_json", - type: "string (path)", - description: - "Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).", - }, - { - key: "profiles..model_instructions_file", - type: "string (path)", - description: - "Profile-scoped replacement for the built-in instruction file.", - }, - { - key: "profiles..experimental_use_unified_exec_tool", - type: "boolean", - description: - "Legacy name for enabling unified exec; prefer `[features].unified_exec`.", - }, - { - key: "profiles..oss_provider", - type: "lmstudio | ollama", - description: "Profile-scoped OSS provider for `--oss` sessions.", - }, - { - key: "profiles..tools_view_image", - type: "boolean", - description: "Enable or disable the `view_image` tool in that profile.", - }, - { - key: "profiles..analytics.enabled", - type: "boolean", - description: "Profile-scoped analytics enablement override.", - }, - { - key: "profiles..windows.sandbox", - type: "unelevated | elevated", - description: "Profile-scoped Windows sandbox mode override.", - }, - { - key: "history.persistence", - type: "save-all | none", - description: - "Control whether Codex saves session transcripts to history.jsonl.", - }, - { - key: "tool_output_token_limit", - type: "number", - description: - "Token budget for storing individual tool/function outputs in history.", - }, - { - key: "background_terminal_max_timeout", - type: "number", - description: - "Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.", - }, - { - key: "history.max_bytes", - type: "number", - description: - "If set, caps the history file size in bytes by dropping oldest entries.", - }, - { - key: "file_opener", - type: "vscode | vscode-insiders | windsurf | cursor | none", - description: - "URI scheme used to open citations from Codex output (default: `vscode`).", - }, - { - key: "otel.environment", - type: "string", - description: - "Environment tag applied to emitted OpenTelemetry events (default: `dev`).", - }, - { - key: "otel.exporter", - type: "none | otlp-http | otlp-grpc", - description: - "Select the OpenTelemetry exporter and provide any endpoint metadata.", - }, - { - key: "otel.trace_exporter", - type: "none | otlp-http | otlp-grpc", - description: - "Select the OpenTelemetry trace exporter and provide any endpoint metadata.", - }, - { - key: "otel.metrics_exporter", - type: "none | statsig | otlp-http | otlp-grpc", - description: - "Select the OpenTelemetry metrics exporter (defaults to `statsig`).", - }, - { - key: "otel.log_user_prompt", - type: "boolean", - description: - "Opt in to exporting raw user prompts with OpenTelemetry logs.", - }, - { - key: "otel.exporter..endpoint", - type: "string", - description: "Exporter endpoint for OTEL logs.", - }, - { - key: "otel.exporter..protocol", - type: "binary | json", - description: "Protocol used by the OTLP/HTTP exporter.", - }, - { - key: "otel.exporter..headers", - type: "map", - description: "Static headers included with OTEL exporter requests.", - }, - { - key: "otel.trace_exporter..endpoint", - type: "string", - description: "Trace exporter endpoint for OTEL logs.", - }, - { - key: "otel.trace_exporter..protocol", - type: "binary | json", - description: "Protocol used by the OTLP/HTTP trace exporter.", - }, - { - key: "otel.trace_exporter..headers", - type: "map", - description: "Static headers included with OTEL trace exporter requests.", - }, - { - key: "otel.exporter..tls.ca-certificate", - type: "string", - description: "CA certificate path for OTEL exporter TLS.", - }, - { - key: "otel.exporter..tls.client-certificate", - type: "string", - description: "Client certificate path for OTEL exporter TLS.", - }, - { - key: "otel.exporter..tls.client-private-key", - type: "string", - description: "Client private key path for OTEL exporter TLS.", - }, - { - key: "otel.trace_exporter..tls.ca-certificate", - type: "string", - description: "CA certificate path for OTEL trace exporter TLS.", - }, - { - key: "otel.trace_exporter..tls.client-certificate", - type: "string", - description: "Client certificate path for OTEL trace exporter TLS.", - }, - { - key: "otel.trace_exporter..tls.client-private-key", - type: "string", - description: "Client private key path for OTEL trace exporter TLS.", - }, - { - key: "tui", - type: "table", - description: - "TUI-specific options such as enabling inline desktop notifications.", - }, - { - key: "tui.notifications", - type: "boolean | array", - description: - "Enable TUI notifications; optionally restrict to specific event types.", - }, - { - key: "tui.notification_method", - type: "auto | osc9 | bel", - description: - "Notification method for terminal notifications (default: auto).", - }, - { - key: "tui.notification_condition", - type: "unfocused | always", - description: - "Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`.", - }, - { - key: "tui.animations", - type: "boolean", - description: - "Enable terminal animations (welcome screen, shimmer, spinner) (default: true).", - }, - { - key: "tui.alternate_screen", - type: "auto | always | never", - description: - "Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).", - }, - { - key: "tui.vim_mode_default", - type: "boolean", - description: - "Start the composer in Vim normal mode instead of insert mode (default: false). You can still toggle it per session with `/vim`.", - }, - { - key: "tui.raw_output_mode", - type: "boolean", - description: - "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.", - }, - { - key: "tui.show_tooltips", - type: "boolean", - description: - "Show onboarding tooltips in the TUI welcome screen (default: true).", - }, - { - key: "tui.status_line", - type: "array | null", - description: - "Ordered list of TUI footer status-line item identifiers. `null` disables the status line.", - }, - { - key: "tui.terminal_title", - type: "array | null", - description: - 'Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates.', - }, - { - key: "tui.theme", - type: "string", - description: - "Syntax-highlighting theme override (kebab-case theme name).", - }, - { - key: "tui.keymap..", - type: "string | array", - description: - "Keyboard shortcut binding for a TUI action. Supported contexts include `global`, `chat`, `composer`, `editor`, `pager`, `list`, and `approval`; context-specific bindings override `tui.keymap.global`.", - }, - { - key: "tui.keymap.. = []", - type: "empty array", - description: - "Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, `page-down`, or `minus`.", - }, - { - key: "plugins..mcp_servers..enabled", - type: "boolean", - description: - "Enable or disable an MCP server bundled by an installed plugin without changing the plugin manifest.", - }, - { - key: "plugins..mcp_servers..default_tools_approval_mode", - type: "auto | prompt | approve", - description: - "Default approval behavior for tools on a plugin-provided MCP server.", - }, - { - key: "plugins..mcp_servers..enabled_tools", - type: "array", - description: - "Allow list of tools exposed from a plugin-provided MCP server.", - }, - { - key: "plugins..mcp_servers..disabled_tools", - type: "array", - description: - "Deny list applied after `enabled_tools` for a plugin-provided MCP server.", - }, - { - key: "plugins..mcp_servers..tools..approval_mode", - type: "auto | prompt | approve", - description: - "Per-tool approval behavior override for a plugin-provided MCP tool.", - }, - { - key: "tui.model_availability_nux.", - type: "integer", - description: "Internal startup-tooltip state keyed by model slug.", - }, - { - key: "hide_agent_reasoning", - type: "boolean", - description: - "Suppress reasoning events in both the TUI and `codex exec` output.", - }, - { - key: "show_raw_agent_reasoning", - type: "boolean", - description: - "Surface raw reasoning content when the active model emits it.", - }, - { - key: "disable_paste_burst", - type: "boolean", - description: "Disable burst-paste detection in the TUI.", - }, - { - key: "windows_wsl_setup_acknowledged", - type: "boolean", - description: "Track Windows onboarding acknowledgement (Windows only).", - }, - { - key: "chatgpt_base_url", - type: "string", - description: "Override the base URL used during the ChatGPT login flow.", - }, - { - key: "cli_auth_credentials_store", - type: "file | keyring | auto", - description: - "Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).", - }, - { - key: "mcp_oauth_credentials_store", - type: "auto | file | keyring", - description: "Preferred store for MCP OAuth credentials.", - }, - { - key: "mcp_oauth_callback_port", - type: "integer", - description: - "Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS.", - }, - { - key: "mcp_oauth_callback_url", - type: "string", - description: - "Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.", - }, - { - key: "experimental_use_unified_exec_tool", - type: "boolean", - description: - "Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.", - }, - { - key: "tools.web_search", - type: 'boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }', - description: - "Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location.", - }, - { - key: "tools.view_image", - type: "boolean", - description: "Enable the local-image attachment tool `view_image`.", - }, - { - key: "web_search", - type: "disabled | cached | live", - description: - 'Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool.', - }, - { - key: "default_permissions", - type: "string", - description: - "Name of the default permissions profile to apply to sandboxed tool calls. Built-ins are `:read-only`, `:workspace`, and `:danger-no-sandbox`; custom profile names require matching `[permissions.]` tables.", - }, - { - key: "permissions..filesystem", - type: "table", - description: - "Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.", - }, - { - key: "permissions..filesystem.glob_scan_max_depth", - type: "number", - description: - "Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set.", - }, - { - key: "permissions..filesystem.", - type: '"read" | "write" | "none" | table', - description: - 'Grant direct access for a path, glob pattern, or special token, or scope nested entries under that root. Use `"none"` to deny reads for matching paths.', - }, - { - key: 'permissions..filesystem.":project_roots".', - type: '"read" | "write" | "none"', - description: - 'Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`.', - }, - { - key: "permissions..network.enabled", - type: "boolean", - description: "Enable network access for this named permissions profile.", - }, - { - key: "permissions..network.proxy_url", - type: "string", - description: - "HTTP listener URL used when this permissions profile enables sandboxed networking.", - }, - { - key: "permissions..network.enable_socks5", - type: "boolean", - description: - "Expose SOCKS5 support when this permissions profile enables sandboxed networking.", - }, - { - key: "permissions..network.socks_url", - type: "string", - description: "SOCKS5 proxy endpoint used by this permissions profile.", - }, - { - key: "permissions..network.enable_socks5_udp", - type: "boolean", - description: "Allow UDP over the SOCKS5 listener when enabled.", - }, - { - key: "permissions..network.allow_upstream_proxy", - type: "boolean", - description: - "Allow sandboxed networking to chain through another upstream proxy.", - }, - { - key: "permissions..network.dangerously_allow_non_loopback_proxy", - type: "boolean", - description: - "Permit non-loopback bind addresses for sandboxed networking listeners. Enabling it can expose listeners beyond localhost.", - }, - { - key: "permissions..network.dangerously_allow_all_unix_sockets", - type: "boolean", - description: - "Allow arbitrary Unix socket destinations instead of the default restricted set. Use only in tightly controlled environments.", - }, - { - key: "permissions..network.domains", - type: "map", - description: - "Domain rules for sandboxed networking. Supports exact hosts, `*.example.com` for subdomains only, `**.example.com` for apex plus subdomains, and global `*` allow rules. `deny` wins on conflicts.", - }, - { - key: "permissions..network.unix_sockets", - type: "map", - description: - "Unix socket rules for sandboxed networking. Use socket paths as keys, with `allow` or `none` values.", - }, - { - key: "permissions..network.allow_local_binding", - type: "boolean", - description: - "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`.", - }, - { - key: "projects..trust_level", - type: "string", - description: - '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.', - }, - { - key: "notice.hide_full_access_warning", - type: "boolean", - description: "Track acknowledgement of the full access warning prompt.", - }, - { - key: "notice.hide_world_writable_warning", - type: "boolean", - description: - "Track acknowledgement of the Windows world-writable directories warning.", - }, - { - key: "notice.hide_rate_limit_model_nudge", - type: "boolean", - description: "Track opt-out of the rate limit model switch reminder.", - }, - { - key: "notice.hide_gpt5_1_migration_prompt", - type: "boolean", - description: "Track acknowledgement of the GPT-5.1 migration prompt.", - }, - { - key: "notice.hide_gpt-5.1-codex-max_migration_prompt", - type: "boolean", - description: - "Track acknowledgement of the gpt-5.1-codex-max migration prompt.", - }, - { - key: "notice.model_migrations", - type: "map", - description: "Track acknowledged model migrations as old->new mappings.", - }, - { - key: "forced_login_method", - type: "chatgpt | api", - description: "Restrict Codex to a specific authentication method.", - }, - { - key: "forced_chatgpt_workspace_id", - type: "string (uuid)", - description: "Limit ChatGPT logins to a specific workspace identifier.", - }, - ]} - client:load -/> +| Key | Type / Values | Details | +| --- | --- | --- | +| `agents..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..description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. | +| `agents..nickname_candidates` | `array` | Optional pool of display nicknames for spawned agents in that role. | +| `agents.job_max_runtime_seconds` | `number` | Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker. | +| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). | +| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. | +| `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` | `untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. | +| `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.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..default_tools_approval_mode` | `auto | prompt | approve` | Default approval behavior for tools in this app unless a per-tool override exists. | +| `apps..default_tools_enabled` | `boolean` | Default enabled state for tools in this app unless a per-tool override exists. | +| `apps..destructive_enabled` | `boolean` | Allow or block tools in this app that advertise `destructive_hint = true`. | +| `apps..enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). | +| `apps..open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. | +| `apps..tools..approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. | +| `apps..tools..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. | +| `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` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). | +| `commit_attribution` | `string` | Commit co-author trailer used when `[features].codex_git_commit` is enabled. Defaults to `Codex `; set `""` to disable. | +| `compact_prompt` | `string` | Inline override for the history compaction prompt. | +| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. Built-ins are `:read-only`, `:workspace`, and `:danger-no-sandbox`; custom profile names require matching `[permissions.]` tables. | +| `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 ChatGPT Apps/connectors support (experimental). | +| `features.codex_git_commit` | `boolean` | Enable Codex-generated git commits. When enabled, Codex uses `commit_attribution` to append a `Co-authored-by:` trailer to generated commit messages. | +| `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.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](https://developers.openai.com/codex/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` | Enable sandboxed networking. Use a table form when setting network policy options such as `domains` (experimental; off by default). | +| `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` | 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` | Enable sandboxed networking. Defaults to `false`. | +| `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` | 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.plugin_hooks` | `boolean` | Opt into lifecycle hooks bundled with enabled plugins. Off by default in this release; set to `true` to opt in. | +| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). | +| `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.undo` | `boolean` | Enable undo support (stable; off 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 Codex surfaces (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. | +| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. | +| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. | +| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. | +| `mcp_oauth_callback_url` | `string` | Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port. | +| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. | +| `mcp_servers..args` | `array` | Arguments passed to the MCP stdio server command. | +| `mcp_servers..bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. | +| `mcp_servers..command` | `string` | Launcher command for an MCP stdio server. | +| `mcp_servers..cwd` | `string` | Working directory for the MCP stdio server process. | +| `mcp_servers..default_tools_approval_mode` | `auto | prompt | approve` | Default approval behavior for MCP tools on this server unless a per-tool override exists. | +| `mcp_servers..disabled_tools` | `array` | Deny list applied after `enabled_tools` for the MCP server. | +| `mcp_servers..enabled` | `boolean` | Disable an MCP server without removing its configuration. | +| `mcp_servers..enabled_tools` | `array` | Allow list of tool names exposed by the MCP server. | +| `mcp_servers..env` | `map` | Environment variables forwarded to the MCP stdio server. | +| `mcp_servers..env_http_headers` | `map` | HTTP headers populated from environment variables for an MCP HTTP server. | +| `mcp_servers..env_vars` | `array` | 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..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..http_headers` | `map` | Static HTTP headers included with each MCP HTTP request. | +| `mcp_servers..oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. | +| `mcp_servers..required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. | +| `mcp_servers..scopes` | `array` | OAuth scopes to request when authenticating to that MCP server. | +| `mcp_servers..startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. | +| `mcp_servers..startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. | +| `mcp_servers..tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. | +| `mcp_servers..tools..approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for one MCP tool on this server. | +| `mcp_servers..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.5`). | +| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). | +| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles..model_catalog_json` 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.` | `table` | Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden. | +| `model_providers..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..auth.args` | `array` | Arguments passed to the token command. | +| `model_providers..auth.command` | `string` | Command to run when Codex needs a bearer token. The command must print the token to stdout. | +| `model_providers..auth.cwd` | `string (path)` | Working directory for the token command. | +| `model_providers..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..auth.timeout_ms` | `number` | Maximum token command runtime in milliseconds (default: 5000). | +| `model_providers..base_url` | `string` | API base URL for the model provider. | +| `model_providers..env_http_headers` | `map` | HTTP headers populated from environment variables when present. | +| `model_providers..env_key` | `string` | Environment variable supplying the provider API key. | +| `model_providers..env_key_instructions` | `string` | Optional setup guidance for the provider API key. | +| `model_providers..experimental_bearer_token` | `string` | Direct bearer token for the provider (discouraged; use `env_key`). | +| `model_providers..http_headers` | `map` | Static HTTP headers added to provider requests. | +| `model_providers..name` | `string` | Display name for a custom model provider. | +| `model_providers..query_params` | `map` | Extra query parameters appended to provider requests. | +| `model_providers..request_max_retries` | `number` | Retry count for HTTP requests to the provider (default: 4). | +| `model_providers..requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). | +| `model_providers..stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). | +| `model_providers..stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). | +| `model_providers..supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. | +| `model_providers..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` | Track acknowledged model migrations as old->new mappings. | +| `notify` | `array` | 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..endpoint` | `string` | Exporter endpoint for OTEL logs. | +| `otel.exporter..headers` | `map` | Static headers included with OTEL exporter requests. | +| `otel.exporter..protocol` | `binary | json` | Protocol used by the OTLP/HTTP exporter. | +| `otel.exporter..tls.ca-certificate` | `string` | CA certificate path for OTEL exporter TLS. | +| `otel.exporter..tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. | +| `otel.exporter..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..endpoint` | `string` | Trace exporter endpoint for OTEL logs. | +| `otel.trace_exporter..headers` | `map` | Static headers included with OTEL trace exporter requests. | +| `otel.trace_exporter..protocol` | `binary | json` | Protocol used by the OTLP/HTTP trace exporter. | +| `otel.trace_exporter..tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. | +| `otel.trace_exporter..tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. | +| `otel.trace_exporter..tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. | +| `permissions..filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. | +| `permissions..filesystem.":project_roots".` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`. | +| `permissions..filesystem.` | `"read" | "write" | "none" | table` | Grant direct access for a path, glob pattern, or special token, or scope nested entries under that root. Use `"none"` to deny reads for matching paths. | +| `permissions..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..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..network.allow_upstream_proxy` | `boolean` | Allow sandboxed networking to chain through another upstream proxy. | +| `permissions..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..network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for sandboxed networking listeners. Enabling it can expose listeners beyond localhost. | +| `permissions..network.domains` | `map` | Domain rules for sandboxed networking. Supports exact hosts, `*.example.com` for subdomains only, `**.example.com` for apex plus subdomains, and global `*` allow rules. `deny` wins on conflicts. | +| `permissions..network.enable_socks5` | `boolean` | Expose SOCKS5 support when this permissions profile enables sandboxed networking. | +| `permissions..network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. | +| `permissions..network.enabled` | `boolean` | Enable network access for this named permissions profile. | +| `permissions..network.proxy_url` | `string` | HTTP listener URL used when this permissions profile enables sandboxed networking. | +| `permissions..network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. | +| `permissions..network.unix_sockets` | `map` | Unix socket rules for sandboxed networking. Use socket paths as keys, with `allow` or `none` values. | +| `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..mcp_servers..default_tools_approval_mode` | `auto | prompt | approve` | Default approval behavior for tools on a plugin-provided MCP server. | +| `plugins..mcp_servers..disabled_tools` | `array` | Deny list applied after `enabled_tools` for a plugin-provided MCP server. | +| `plugins..mcp_servers..enabled` | `boolean` | Enable or disable an MCP server bundled by an installed plugin without changing the plugin manifest. | +| `plugins..mcp_servers..enabled_tools` | `array` | Allow list of tools exposed from a plugin-provided MCP server. | +| `plugins..mcp_servers..tools..approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a plugin-provided MCP tool. | +| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). | +| `profiles..*` | `various` | Profile-scoped overrides for any of the supported configuration keys. | +| `profiles..analytics.enabled` | `boolean` | Profile-scoped analytics enablement override. | +| `profiles..experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. | +| `profiles..model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). | +| `profiles..model_instructions_file` | `string (path)` | Profile-scoped replacement for the built-in instruction file. | +| `profiles..oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. | +| `profiles..personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. | +| `profiles..plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Profile-scoped Plan-mode reasoning override. | +| `profiles..service_tier` | `string` | Profile-scoped service tier preference for new turns. | +| `profiles..tools_view_image` | `boolean` | Enable or disable the `view_image` tool in that profile. | +| `profiles..web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). | +| `profiles..windows.sandbox` | `unelevated | elevated` | Profile-scoped Windows sandbox mode override. | +| `project_doc_fallback_filenames` | `array` | 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` | List of project root marker filenames; used when searching parent directories for the project root. | +| `projects..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` | Additional writable roots when `sandbox_mode = "workspace-write"`. | +| `service_tier` | `string` | Preferred service tier for new turns. Built-in values include `flex` and `fast`; legacy `fast` config maps to the request value `priority`, and catalog-provided tier IDs can also be stored. | +| `shell_environment_policy.exclude` | `array` | Glob patterns for removing environment variables after the defaults. | +| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. | +| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. | +| `shell_environment_policy.include_only` | `array` | Whitelist of patterns; when set only matching variables are kept. | +| `shell_environment_policy.inherit` | `all | core | none` | Baseline environment inheritance when spawning subprocesses. | +| `shell_environment_policy.set` | `map` | Explicit environment overrides injected into every subprocess. | +| `show_raw_agent_reasoning` | `boolean` | Surface raw reasoning content when the active model emits it. | +| `skills.config` | `array` | Per-skill enablement overrides stored in config.toml. | +| `skills.config..enabled` | `boolean` | Enable or disable the referenced skill. | +| `skills.config..path` | `string (path)` | Path to a skill folder containing `SKILL.md`. | +| `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
` | Disable suggestions for specific discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. | +| `tool_suggest.discoverables` | `array
` | 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 legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location. | +| `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..` | `string | array` | Keyboard shortcut binding for a TUI action. Supported contexts include `global`, `chat`, `composer`, `editor`, `pager`, `list`, and `approval`; context-specific bindings override `tui.keymap.global`. | +| `tui.keymap.. = []` | `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.` | `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` | 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.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). | +| `tui.status_line` | `array | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. | +| `tui.terminal_title` | `array | 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 | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. | +| `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. | + +Key + +`agents..config_file` + +Type / Values + +`string (path)` + +Details + +Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. + +Key + +`agents..description` + +Type / Values + +`string` + +Details + +Role guidance shown to Codex when choosing and spawning that agent type. + +Key + +`agents..nickname_candidates` + +Type / Values + +`array` + +Details + +Optional pool of display nicknames for spawned agents in that role. + +Key + +`agents.job_max_runtime_seconds` + +Type / Values + +`number` + +Details + +Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker. + +Key + +`agents.max_depth` + +Type / Values + +`number` + +Details + +Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). + +Key + +`agents.max_threads` + +Type / Values + +`number` + +Details + +Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. + +Key + +`allow_login_shell` + +Type / Values + +`boolean` + +Details + +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. + +Key + +`analytics.enabled` + +Type / Values + +`boolean` + +Details + +Enable or disable analytics for this machine/profile. When unset, the client default applies. + +Key + +`approval_policy` + +Type / Values + +`untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }` + +Details + +Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. + +Key + +`approval_policy.granular.mcp_elicitations` + +Type / Values + +`boolean` + +Details + +When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected. + +Key + +`approval_policy.granular.request_permissions` + +Type / Values + +`boolean` + +Details + +When `true`, prompts from the `request_permissions` tool are allowed to surface. + +Key + +`approval_policy.granular.rules` + +Type / Values + +`boolean` + +Details + +When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface. + +Key + +`approval_policy.granular.sandbox_approval` + +Type / Values + +`boolean` + +Details + +When `true`, sandbox escalation approval prompts are allowed to surface. + +Key + +`approval_policy.granular.skill_approval` + +Type / Values + +`boolean` + +Details + +When `true`, skill-script approval prompts are allowed to surface. + +Key + +`approvals_reviewer` + +Type / Values + +`user | auto_review` + +Details + +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. + +Key + +`apps._default.destructive_enabled` + +Type / Values + +`boolean` + +Details + +Default allow/deny for app tools with `destructive_hint = true`. + +Key + +`apps._default.enabled` + +Type / Values + +`boolean` + +Details + +Default app enabled state for all apps unless overridden per app. + +Key + +`apps._default.open_world_enabled` + +Type / Values + +`boolean` + +Details + +Default allow/deny for app tools with `open_world_hint = true`. + +Key + +`apps..default_tools_approval_mode` + +Type / Values + +`auto | prompt | approve` + +Details + +Default approval behavior for tools in this app unless a per-tool override exists. + +Key + +`apps..default_tools_enabled` + +Type / Values + +`boolean` + +Details + +Default enabled state for tools in this app unless a per-tool override exists. + +Key + +`apps..destructive_enabled` + +Type / Values + +`boolean` + +Details + +Allow or block tools in this app that advertise `destructive_hint = true`. + +Key + +`apps..enabled` + +Type / Values + +`boolean` + +Details + +Enable or disable a specific app/connector by id (default: true). + +Key + +`apps..open_world_enabled` + +Type / Values + +`boolean` + +Details + +Allow or block tools in this app that advertise `open_world_hint = true`. + +Key + +`apps..tools..approval_mode` + +Type / Values + +`auto | prompt | approve` + +Details + +Per-tool approval behavior override for a single app tool. + +Key + +`apps..tools..enabled` + +Type / Values + +`boolean` + +Details + +Per-tool enabled override for an app tool (for example `repos/list`). + +Key + +`auto_review.policy` + +Type / Values + +`string` + +Details + +Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored. + +Key + +`background_terminal_max_timeout` + +Type / Values + +`number` + +Details + +Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key. + +Key + +`chatgpt_base_url` + +Type / Values + +`string` + +Details + +Override the base URL used during the ChatGPT login flow. + +Key + +`check_for_update_on_startup` + +Type / Values + +`boolean` + +Details + +Check for Codex updates on startup (set to false only when updates are centrally managed). + +Key + +`cli_auth_credentials_store` + +Type / Values + +`file | keyring | auto` + +Details + +Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). + +Key + +`commit_attribution` + +Type / Values + +`string` + +Details + +Commit co-author trailer used when `[features].codex_git_commit` is enabled. Defaults to `Codex `; set `""` to disable. + +Key + +`compact_prompt` + +Type / Values + +`string` + +Details + +Inline override for the history compaction prompt. + +Key + +`default_permissions` + +Type / Values + +`string` + +Details + +Name of the default permissions profile to apply to sandboxed tool calls. Built-ins are `:read-only`, `:workspace`, and `:danger-no-sandbox`; custom profile names require matching `[permissions.]` tables. + +Key + +`developer_instructions` + +Type / Values + +`string` + +Details + +Additional developer instructions injected into the session (optional). + +Key + +`disable_paste_burst` + +Type / Values + +`boolean` + +Details + +Disable burst-paste detection in the TUI. + +Key + +`experimental_compact_prompt_file` + +Type / Values + +`string (path)` + +Details + +Load the compaction prompt override from a file (experimental). + +Key + +`experimental_use_unified_exec_tool` + +Type / Values + +`boolean` + +Details + +Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. + +Key + +`features.apps` + +Type / Values + +`boolean` + +Details + +Enable ChatGPT Apps/connectors support (experimental). + +Key + +`features.codex_git_commit` + +Type / Values + +`boolean` + +Details + +Enable Codex-generated git commits. When enabled, Codex uses `commit_attribution` to append a `Co-authored-by:` trailer to generated commit messages. + +Key + +`features.enable_request_compression` + +Type / Values + +`boolean` + +Details + +Compress streaming request bodies with zstd when supported (stable; on by default). + +Key + +`features.fast_mode` + +Type / Values + +`boolean` + +Details + +Enable model-catalog service tier selection in the TUI, including Fast-tier commands when the active model advertises them (stable; on by default). + +Key + +`features.hooks` + +Type / Values + +`boolean` + +Details + +Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. `features.codex_hooks` is a deprecated alias. + +Key + +`features.memories` + +Type / Values + +`boolean` + +Details + +Enable [Memories](https://developers.openai.com/codex/memories) (off by default). + +Key + +`features.multi_agent` + +Type / Values + +`boolean` + +Details + +Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). + +Key + +`features.network_proxy` + +Type / Values + +`boolean | table` + +Details + +Enable sandboxed networking. Use a table form when setting network policy options such as `domains` (experimental; off by default). + +Key + +`features.network_proxy.allow_local_binding` + +Type / Values + +`boolean` + +Details + +Allow broader local/private-network access. Defaults to `false`; exact local IP literal or `localhost` allow rules can still permit specific local targets. + +Key + +`features.network_proxy.allow_upstream_proxy` + +Type / Values + +`boolean` + +Details + +Allow chaining through an upstream proxy from the environment. Defaults to `true`. + +Key + +`features.network_proxy.dangerously_allow_all_unix_sockets` + +Type / Values + +`boolean` + +Details + +Permit arbitrary Unix socket destinations instead of allowlist-only access. Defaults to `false`; use only in tightly controlled environments. + +Key + +`features.network_proxy.dangerously_allow_non_loopback_proxy` + +Type / Values + +`boolean` + +Details + +Permit non-loopback listener addresses. Defaults to `false`; enabling it can expose proxy listeners beyond localhost. + +Key + +`features.network_proxy.domains` + +Type / Values + +`map` + +Details + +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. + +Key + +`features.network_proxy.enable_socks5` + +Type / Values + +`boolean` + +Details + +Expose SOCKS5 support. Defaults to `true`. + +Key + +`features.network_proxy.enable_socks5_udp` + +Type / Values + +`boolean` + +Details + +Allow UDP over SOCKS5. Defaults to `true`. + +Key + +`features.network_proxy.enabled` + +Type / Values + +`boolean` + +Details + +Enable sandboxed networking. Defaults to `false`. + +Key + +`features.network_proxy.proxy_url` + +Type / Values + +`string` + +Details + +HTTP listener URL for sandboxed networking. Defaults to `"http://127.0.0.1:3128"`. + +Key + +`features.network_proxy.socks_url` + +Type / Values + +`string` + +Details + +SOCKS5 listener URL. Defaults to `"http://127.0.0.1:8081"`. + +Key + +`features.network_proxy.unix_sockets` + +Type / Values + +`map` + +Details + +Unix socket policy for sandboxed networking. Unset by default; add `allow` entries for permitted sockets. + +Key + +`features.personality` + +Type / Values + +`boolean` + +Details + +Enable personality selection controls (stable; on by default). + +Key + +`features.plugin_hooks` + +Type / Values + +`boolean` + +Details + +Opt into lifecycle hooks bundled with enabled plugins. Off by default in this release; set to `true` to opt in. + +Key + +`features.prevent_idle_sleep` + +Type / Values + +`boolean` + +Details + +Prevent the machine from sleeping while a turn is actively running (experimental; off by default). + +Key + +`features.shell_snapshot` + +Type / Values + +`boolean` + +Details + +Snapshot shell environment to speed up repeated commands (stable; on by default). + +Key + +`features.shell_tool` + +Type / Values + +`boolean` + +Details + +Enable the default `shell` tool for running commands (stable; on by default). + +Key + +`features.skill_mcp_dependency_install` + +Type / Values + +`boolean` + +Details + +Allow prompting and installing missing MCP dependencies for skills (stable; on by default). + +Key + +`features.undo` + +Type / Values + +`boolean` + +Details + +Enable undo support (stable; off by default). + +Key + +`features.unified_exec` + +Type / Values + +`boolean` + +Details + +Use the unified PTY-backed exec tool (stable; enabled by default except on Windows). + +Key + +`features.web_search` + +Type / Values + +`boolean` + +Details + +Deprecated legacy toggle; prefer the top-level `web_search` setting. + +Key + +`features.web_search_cached` + +Type / Values + +`boolean` + +Details + +Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. + +Key + +`features.web_search_request` + +Type / Values + +`boolean` + +Details + +Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. + +Key + +`feedback.enabled` + +Type / Values + +`boolean` + +Details + +Enable feedback submission via `/feedback` across Codex surfaces (default: true). + +Key + +`file_opener` + +Type / Values + +`vscode | vscode-insiders | windsurf | cursor | none` + +Details + +URI scheme used to open citations from Codex output (default: `vscode`). + +Key + +`forced_chatgpt_workspace_id` + +Type / Values + +`string (uuid)` + +Details + +Limit ChatGPT logins to a specific workspace identifier. + +Key + +`forced_login_method` + +Type / Values + +`chatgpt | api` + +Details + +Restrict Codex to a specific authentication method. + +Key + +`hide_agent_reasoning` + +Type / Values + +`boolean` + +Details + +Suppress reasoning events in both the TUI and `codex exec` output. + +Key + +`history.max_bytes` + +Type / Values + +`number` + +Details + +If set, caps the history file size in bytes by dropping oldest entries. + +Key + +`history.persistence` + +Type / Values + +`save-all | none` + +Details + +Control whether Codex saves session transcripts to history.jsonl. + +Key + +`hooks` + +Type / Values + +`table` + +Details + +Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events. + +Key + +`instructions` + +Type / Values + +`string` + +Details + +Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. + +Key + +`log_dir` + +Type / Values + +`string (path)` + +Details + +Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. + +Key + +`mcp_oauth_callback_port` + +Type / Values + +`integer` + +Details + +Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. + +Key + +`mcp_oauth_callback_url` + +Type / Values + +`string` + +Details + +Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port. + +Key + +`mcp_oauth_credentials_store` + +Type / Values + +`auto | file | keyring` + +Details + +Preferred store for MCP OAuth credentials. + +Key + +`mcp_servers..args` + +Type / Values + +`array` + +Details + +Arguments passed to the MCP stdio server command. + +Key + +`mcp_servers..bearer_token_env_var` + +Type / Values + +`string` + +Details + +Environment variable sourcing the bearer token for an MCP HTTP server. + +Key + +`mcp_servers..command` + +Type / Values + +`string` + +Details + +Launcher command for an MCP stdio server. + +Key + +`mcp_servers..cwd` + +Type / Values + +`string` + +Details + +Working directory for the MCP stdio server process. + +Key + +`mcp_servers..default_tools_approval_mode` + +Type / Values + +`auto | prompt | approve` + +Details + +Default approval behavior for MCP tools on this server unless a per-tool override exists. + +Key + +`mcp_servers..disabled_tools` + +Type / Values + +`array` + +Details + +Deny list applied after `enabled_tools` for the MCP server. + +Key + +`mcp_servers..enabled` + +Type / Values + +`boolean` + +Details + +Disable an MCP server without removing its configuration. + +Key + +`mcp_servers..enabled_tools` + +Type / Values + +`array` + +Details + +Allow list of tool names exposed by the MCP server. + +Key + +`mcp_servers..env` + +Type / Values + +`map` + +Details + +Environment variables forwarded to the MCP stdio server. + +Key + +`mcp_servers..env_http_headers` + +Type / Values + +`map` + +Details + +HTTP headers populated from environment variables for an MCP HTTP server. + +Key + +`mcp_servers..env_vars` + +Type / Values + +`array` + +Details + +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. + +Key + +`mcp_servers..experimental_environment` + +Type / Values + +`local | remote` + +Details + +Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented. + +Key + +`mcp_servers..http_headers` + +Type / Values + +`map` + +Details + +Static HTTP headers included with each MCP HTTP request. + +Key + +`mcp_servers..oauth_resource` + +Type / Values + +`string` + +Details + +Optional RFC 8707 OAuth resource parameter to include during MCP login. + +Key + +`mcp_servers..required` + +Type / Values + +`boolean` + +Details + +When true, fail startup/resume if this enabled MCP server cannot initialize. + +Key + +`mcp_servers..scopes` + +Type / Values + +`array` + +Details + +OAuth scopes to request when authenticating to that MCP server. + +Key + +`mcp_servers..startup_timeout_ms` + +Type / Values + +`number` + +Details + +Alias for `startup_timeout_sec` in milliseconds. + +Key + +`mcp_servers..startup_timeout_sec` + +Type / Values + +`number` + +Details + +Override the default 10s startup timeout for an MCP server. + +Key + +`mcp_servers..tool_timeout_sec` + +Type / Values + +`number` + +Details + +Override the default 60s per-tool timeout for an MCP server. + +Key + +`mcp_servers..tools..approval_mode` + +Type / Values + +`auto | prompt | approve` + +Details + +Per-tool approval behavior override for one MCP tool on this server. + +Key + +`mcp_servers..url` + +Type / Values + +`string` + +Details + +Endpoint for an MCP streamable HTTP server. + +Key + +`memories.consolidation_model` + +Type / Values + +`string` + +Details + +Optional model override for global memory consolidation. + +Key + +`memories.disable_on_external_context` + +Type / Values + +`boolean` + +Details + +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`. + +Key + +`memories.extract_model` + +Type / Values + +`string` + +Details + +Optional model override for per-thread memory extraction. + +Key + +`memories.generate_memories` + +Type / Values + +`boolean` + +Details + +When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`. + +Key + +`memories.max_raw_memories_for_consolidation` + +Type / Values + +`number` + +Details + +Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`. + +Key + +`memories.max_rollout_age_days` + +Type / Values + +`number` + +Details + +Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`. + +Key + +`memories.max_rollouts_per_startup` + +Type / Values + +`number` + +Details + +Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`. + +Key + +`memories.max_unused_days` + +Type / Values + +`number` + +Details + +Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`. + +Key + +`memories.min_rate_limit_remaining_percent` + +Type / Values + +`number` + +Details + +Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`. + +Key + +`memories.min_rollout_idle_hours` + +Type / Values + +`number` + +Details + +Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`. + +Key + +`memories.use_memories` + +Type / Values + +`boolean` + +Details + +When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`. + +Key + +`model` + +Type / Values + +`string` + +Details + +Model to use (e.g., `gpt-5.5`). + +Key + +`model_auto_compact_token_limit` + +Type / Values + +`number` + +Details + +Token threshold that triggers automatic history compaction (unset uses model defaults). + +Key + +`model_catalog_json` + +Type / Values + +`string (path)` + +Details + +Optional path to a JSON model catalog loaded on startup. Profile-level `profiles..model_catalog_json` can override this per profile. + +Key + +`model_context_window` + +Type / Values + +`number` + +Details + +Context window tokens available to the active model. + +Key + +`model_instructions_file` + +Type / Values + +`string (path)` + +Details + +Replacement for built-in instructions instead of `AGENTS.md`. + +Key + +`model_provider` + +Type / Values + +`string` + +Details + +Provider id from `model_providers` (default: `openai`). + +Key + +`model_providers.` + +Type / Values + +`table` + +Details + +Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden. + +Key + +`model_providers..auth` + +Type / Values + +`table` + +Details + +Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`. + +Key + +`model_providers..auth.args` + +Type / Values + +`array` + +Details + +Arguments passed to the token command. + +Key + +`model_providers..auth.command` + +Type / Values + +`string` + +Details + +Command to run when Codex needs a bearer token. The command must print the token to stdout. + +Key + +`model_providers..auth.cwd` + +Type / Values + +`string (path)` + +Details + +Working directory for the token command. + +Key + +`model_providers..auth.refresh_interval_ms` + +Type / Values + +`number` + +Details + +How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry. + +Key + +`model_providers..auth.timeout_ms` + +Type / Values + +`number` + +Details + +Maximum token command runtime in milliseconds (default: 5000). + +Key + +`model_providers..base_url` + +Type / Values + +`string` + +Details + +API base URL for the model provider. + +Key + +`model_providers..env_http_headers` + +Type / Values + +`map` + +Details + +HTTP headers populated from environment variables when present. + +Key + +`model_providers..env_key` + +Type / Values + +`string` + +Details + +Environment variable supplying the provider API key. + +Key + +`model_providers..env_key_instructions` + +Type / Values + +`string` + +Details + +Optional setup guidance for the provider API key. + +Key + +`model_providers..experimental_bearer_token` + +Type / Values + +`string` + +Details + +Direct bearer token for the provider (discouraged; use `env_key`). + +Key + +`model_providers..http_headers` + +Type / Values + +`map` + +Details + +Static HTTP headers added to provider requests. + +Key + +`model_providers..name` + +Type / Values + +`string` + +Details + +Display name for a custom model provider. + +Key + +`model_providers..query_params` + +Type / Values + +`map` + +Details + +Extra query parameters appended to provider requests. + +Key + +`model_providers..request_max_retries` + +Type / Values + +`number` + +Details + +Retry count for HTTP requests to the provider (default: 4). + +Key + +`model_providers..requires_openai_auth` + +Type / Values + +`boolean` + +Details + +The provider uses OpenAI authentication (defaults to false). + +Key + +`model_providers..stream_idle_timeout_ms` + +Type / Values + +`number` + +Details + +Idle timeout for SSE streams in milliseconds (default: 300000). + +Key + +`model_providers..stream_max_retries` + +Type / Values + +`number` + +Details + +Retry count for SSE streaming interruptions (default: 5). + +Key + +`model_providers..supports_websockets` + +Type / Values + +`boolean` + +Details + +Whether that provider supports the Responses API WebSocket transport. + +Key + +`model_providers..wire_api` + +Type / Values + +`responses` + +Details + +Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. + +Key + +`model_providers.amazon-bedrock.aws.profile` + +Type / Values + +`string` + +Details + +AWS profile name used by the built-in `amazon-bedrock` provider. + +Key + +`model_providers.amazon-bedrock.aws.region` + +Type / Values + +`string` + +Details + +AWS region used by the built-in `amazon-bedrock` provider. + +Key + +`model_reasoning_effort` + +Type / Values + +`minimal | low | medium | high | xhigh` + +Details + +Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). + +Key + +`model_reasoning_summary` + +Type / Values + +`auto | concise | detailed | none` + +Details + +Select reasoning summary detail or disable summaries entirely. + +Key + +`model_supports_reasoning_summaries` + +Type / Values + +`boolean` + +Details + +Force Codex to send or not send reasoning metadata. + +Key + +`model_verbosity` + +Type / Values + +`low | medium | high` + +Details + +Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used. + +Key + +`notice.hide_full_access_warning` + +Type / Values + +`boolean` + +Details + +Track acknowledgement of the full access warning prompt. + +Key + +`notice.hide_gpt-5.1-codex-max_migration_prompt` + +Type / Values + +`boolean` + +Details + +Track acknowledgement of the gpt-5.1-codex-max migration prompt. + +Key + +`notice.hide_gpt5_1_migration_prompt` + +Type / Values + +`boolean` + +Details + +Track acknowledgement of the GPT-5.1 migration prompt. + +Key + +`notice.hide_rate_limit_model_nudge` + +Type / Values + +`boolean` + +Details + +Track opt-out of the rate limit model switch reminder. + +Key + +`notice.hide_world_writable_warning` + +Type / Values + +`boolean` + +Details + +Track acknowledgement of the Windows world-writable directories warning. + +Key + +`notice.model_migrations` + +Type / Values + +`map` + +Details + +Track acknowledged model migrations as old->new mappings. + +Key + +`notify` + +Type / Values + +`array` + +Details + +Command invoked for notifications; receives a JSON payload from Codex. + +Key + +`openai_base_url` + +Type / Values + +`string` + +Details + +Base URL override for the built-in `openai` model provider. + +Key + +`oss_provider` + +Type / Values + +`lmstudio | ollama` + +Details + +Default local provider used when running with `--oss` (defaults to prompting if unset). + +Key + +`otel.environment` + +Type / Values + +`string` + +Details + +Environment tag applied to emitted OpenTelemetry events (default: `dev`). + +Key + +`otel.exporter` + +Type / Values + +`none | otlp-http | otlp-grpc` + +Details + +Select the OpenTelemetry exporter and provide any endpoint metadata. + +Key + +`otel.exporter..endpoint` + +Type / Values + +`string` + +Details + +Exporter endpoint for OTEL logs. + +Key + +`otel.exporter..headers` + +Type / Values + +`map` + +Details + +Static headers included with OTEL exporter requests. + +Key + +`otel.exporter..protocol` + +Type / Values + +`binary | json` + +Details + +Protocol used by the OTLP/HTTP exporter. + +Key + +`otel.exporter..tls.ca-certificate` + +Type / Values + +`string` + +Details + +CA certificate path for OTEL exporter TLS. + +Key + +`otel.exporter..tls.client-certificate` + +Type / Values + +`string` + +Details + +Client certificate path for OTEL exporter TLS. + +Key + +`otel.exporter..tls.client-private-key` + +Type / Values + +`string` + +Details + +Client private key path for OTEL exporter TLS. + +Key + +`otel.log_user_prompt` + +Type / Values + +`boolean` + +Details + +Opt in to exporting raw user prompts with OpenTelemetry logs. + +Key + +`otel.metrics_exporter` + +Type / Values + +`none | statsig | otlp-http | otlp-grpc` + +Details + +Select the OpenTelemetry metrics exporter (defaults to `statsig`). + +Key + +`otel.trace_exporter` + +Type / Values + +`none | otlp-http | otlp-grpc` + +Details + +Select the OpenTelemetry trace exporter and provide any endpoint metadata. + +Key + +`otel.trace_exporter..endpoint` + +Type / Values + +`string` + +Details + +Trace exporter endpoint for OTEL logs. + +Key + +`otel.trace_exporter..headers` + +Type / Values + +`map` + +Details + +Static headers included with OTEL trace exporter requests. + +Key + +`otel.trace_exporter..protocol` + +Type / Values + +`binary | json` + +Details + +Protocol used by the OTLP/HTTP trace exporter. + +Key + +`otel.trace_exporter..tls.ca-certificate` + +Type / Values + +`string` + +Details + +CA certificate path for OTEL trace exporter TLS. + +Key + +`otel.trace_exporter..tls.client-certificate` + +Type / Values + +`string` + +Details + +Client certificate path for OTEL trace exporter TLS. + +Key + +`otel.trace_exporter..tls.client-private-key` + +Type / Values + +`string` + +Details + +Client private key path for OTEL trace exporter TLS. + +Key + +`permissions..filesystem` + +Type / Values + +`table` + +Details + +Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. + +Key + +`permissions..filesystem.":project_roots".` + +Type / Values + +`"read" | "write" | "none"` + +Details + +Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`. + +Key + +`permissions..filesystem.` + +Type / Values + +`"read" | "write" | "none" | table` + +Details + +Grant direct access for a path, glob pattern, or special token, or scope nested entries under that root. Use `"none"` to deny reads for matching paths. + +Key + +`permissions..filesystem.glob_scan_max_depth` + +Type / Values + +`number` + +Details + +Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set. + +Key + +`permissions..network.allow_local_binding` + +Type / Values + +`boolean` + +Details + +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`. + +Key + +`permissions..network.allow_upstream_proxy` + +Type / Values + +`boolean` + +Details + +Allow sandboxed networking to chain through another upstream proxy. + +Key + +`permissions..network.dangerously_allow_all_unix_sockets` + +Type / Values + +`boolean` + +Details + +Allow arbitrary Unix socket destinations instead of the default restricted set. Use only in tightly controlled environments. + +Key + +`permissions..network.dangerously_allow_non_loopback_proxy` + +Type / Values + +`boolean` + +Details + +Permit non-loopback bind addresses for sandboxed networking listeners. Enabling it can expose listeners beyond localhost. + +Key + +`permissions..network.domains` + +Type / Values + +`map` + +Details + +Domain rules for sandboxed networking. Supports exact hosts, `*.example.com` for subdomains only, `**.example.com` for apex plus subdomains, and global `*` allow rules. `deny` wins on conflicts. + +Key + +`permissions..network.enable_socks5` + +Type / Values + +`boolean` + +Details + +Expose SOCKS5 support when this permissions profile enables sandboxed networking. + +Key + +`permissions..network.enable_socks5_udp` + +Type / Values + +`boolean` + +Details + +Allow UDP over the SOCKS5 listener when enabled. + +Key + +`permissions..network.enabled` + +Type / Values + +`boolean` + +Details + +Enable network access for this named permissions profile. + +Key + +`permissions..network.proxy_url` + +Type / Values + +`string` + +Details + +HTTP listener URL used when this permissions profile enables sandboxed networking. + +Key + +`permissions..network.socks_url` + +Type / Values + +`string` + +Details + +SOCKS5 proxy endpoint used by this permissions profile. + +Key + +`permissions..network.unix_sockets` + +Type / Values + +`map` + +Details + +Unix socket rules for sandboxed networking. Use socket paths as keys, with `allow` or `none` values. + +Key + +`personality` + +Type / Values + +`none | friendly | pragmatic` + +Details + +Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. + +Key + +`plan_mode_reasoning_effort` + +Type / Values + +`none | minimal | low | medium | high | xhigh` + +Details + +Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default. + +Key + +`plugins..mcp_servers..default_tools_approval_mode` + +Type / Values + +`auto | prompt | approve` + +Details + +Default approval behavior for tools on a plugin-provided MCP server. + +Key + +`plugins..mcp_servers..disabled_tools` + +Type / Values + +`array` + +Details + +Deny list applied after `enabled_tools` for a plugin-provided MCP server. + +Key + +`plugins..mcp_servers..enabled` + +Type / Values + +`boolean` + +Details + +Enable or disable an MCP server bundled by an installed plugin without changing the plugin manifest. + +Key + +`plugins..mcp_servers..enabled_tools` + +Type / Values + +`array` + +Details + +Allow list of tools exposed from a plugin-provided MCP server. + +Key + +`plugins..mcp_servers..tools..approval_mode` + +Type / Values + +`auto | prompt | approve` + +Details + +Per-tool approval behavior override for a plugin-provided MCP tool. + +Key + +`profile` + +Type / Values + +`string` + +Details + +Default profile applied at startup (equivalent to `--profile`). + +Key + +`profiles..*` + +Type / Values + +`various` + +Details + +Profile-scoped overrides for any of the supported configuration keys. + +Key + +`profiles..analytics.enabled` + +Type / Values + +`boolean` + +Details + +Profile-scoped analytics enablement override. + +Key + +`profiles..experimental_use_unified_exec_tool` + +Type / Values + +`boolean` + +Details + +Legacy name for enabling unified exec; prefer `[features].unified_exec`. + +Key + +`profiles..model_catalog_json` + +Type / Values + +`string (path)` + +Details + +Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). + +Key + +`profiles..model_instructions_file` + +Type / Values + +`string (path)` + +Details + +Profile-scoped replacement for the built-in instruction file. + +Key + +`profiles..oss_provider` + +Type / Values + +`lmstudio | ollama` + +Details + +Profile-scoped OSS provider for `--oss` sessions. + +Key + +`profiles..personality` + +Type / Values + +`none | friendly | pragmatic` + +Details + +Profile-scoped communication style override for supported models. + +Key + +`profiles..plan_mode_reasoning_effort` + +Type / Values + +`none | minimal | low | medium | high | xhigh` + +Details + +Profile-scoped Plan-mode reasoning override. + +Key + +`profiles..service_tier` + +Type / Values + +`string` + +Details + +Profile-scoped service tier preference for new turns. + +Key + +`profiles..tools_view_image` + +Type / Values + +`boolean` + +Details + +Enable or disable the `view_image` tool in that profile. + +Key + +`profiles..web_search` + +Type / Values + +`disabled | cached | live` + +Details + +Profile-scoped web search mode override (default: `"cached"`). + +Key + +`profiles..windows.sandbox` + +Type / Values + +`unelevated | elevated` + +Details + +Profile-scoped Windows sandbox mode override. + +Key + +`project_doc_fallback_filenames` + +Type / Values + +`array` + +Details + +Additional filenames to try when `AGENTS.md` is missing. + +Key + +`project_doc_max_bytes` + +Type / Values + +`number` + +Details + +Maximum bytes read from `AGENTS.md` when building project instructions. + +Key + +`project_root_markers` + +Type / Values + +`array` + +Details + +List of project root marker filenames; used when searching parent directories for the project root. + +Key + +`projects..trust_level` + +Type / Values + +`string` + +Details + +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. + +Key + +`review_model` + +Type / Values + +`string` + +Details + +Optional model override used by `/review` (defaults to the current session model). + +Key + +`sandbox_mode` + +Type / Values + +`read-only | workspace-write | danger-full-access` + +Details + +Sandbox policy for filesystem and network access during command execution. + +Key + +`sandbox_workspace_write.exclude_slash_tmp` + +Type / Values + +`boolean` + +Details + +Exclude `/tmp` from writable roots in workspace-write mode. + +Key + +`sandbox_workspace_write.exclude_tmpdir_env_var` + +Type / Values + +`boolean` + +Details + +Exclude `$TMPDIR` from writable roots in workspace-write mode. + +Key + +`sandbox_workspace_write.network_access` + +Type / Values + +`boolean` + +Details + +Allow outbound network access inside the workspace-write sandbox. + +Key + +`sandbox_workspace_write.writable_roots` + +Type / Values + +`array` + +Details + +Additional writable roots when `sandbox_mode = "workspace-write"`. + +Key + +`service_tier` + +Type / Values + +`string` + +Details + +Preferred service tier for new turns. Built-in values include `flex` and `fast`; legacy `fast` config maps to the request value `priority`, and catalog-provided tier IDs can also be stored. + +Key + +`shell_environment_policy.exclude` + +Type / Values + +`array` + +Details + +Glob patterns for removing environment variables after the defaults. + +Key + +`shell_environment_policy.experimental_use_profile` + +Type / Values + +`boolean` + +Details + +Use the user shell profile when spawning subprocesses. + +Key + +`shell_environment_policy.ignore_default_excludes` + +Type / Values + +`boolean` + +Details + +Keep variables containing KEY/SECRET/TOKEN before other filters run. + +Key + +`shell_environment_policy.include_only` + +Type / Values + +`array` + +Details + +Whitelist of patterns; when set only matching variables are kept. + +Key + +`shell_environment_policy.inherit` + +Type / Values + +`all | core | none` + +Details + +Baseline environment inheritance when spawning subprocesses. + +Key + +`shell_environment_policy.set` + +Type / Values + +`map` + +Details + +Explicit environment overrides injected into every subprocess. + +Key + +`show_raw_agent_reasoning` + +Type / Values + +`boolean` + +Details + +Surface raw reasoning content when the active model emits it. + +Key + +`skills.config` + +Type / Values + +`array` + +Details + +Per-skill enablement overrides stored in config.toml. + +Key + +`skills.config..enabled` + +Type / Values + +`boolean` + +Details + +Enable or disable the referenced skill. + +Key + +`skills.config..path` + +Type / Values + +`string (path)` + +Details + +Path to a skill folder containing `SKILL.md`. + +Key + +`sqlite_home` + +Type / Values + +`string (path)` + +Details + +Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. + +Key + +`suppress_unstable_features_warning` + +Type / Values + +`boolean` + +Details + +Suppress the warning that appears when under-development feature flags are enabled. + +Key + +`tool_output_token_limit` + +Type / Values + +`number` + +Details + +Token budget for storing individual tool/function outputs in history. + +Key + +`tool_suggest.disabled_tools` + +Type / Values + +`array
` + +Details + +Disable suggestions for specific discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. + +Key + +`tool_suggest.discoverables` + +Type / Values + +`array
` + +Details + +Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. + +Key + +`tools.view_image` + +Type / Values + +`boolean` + +Details + +Enable the local-image attachment tool `view_image`. + +Key + +`tools.web_search` + +Type / Values + +`boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }` + +Details + +Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location. + +Key + +`tui` + +Type / Values + +`table` + +Details + +TUI-specific options such as enabling inline desktop notifications. + +Key + +`tui.alternate_screen` + +Type / Values + +`auto | always | never` + +Details + +Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). + +Key + +`tui.animations` + +Type / Values + +`boolean` + +Details + +Enable terminal animations (welcome screen, shimmer, spinner) (default: true). + +Key + +`tui.keymap..` + +Type / Values + +`string | array` + +Details + +Keyboard shortcut binding for a TUI action. Supported contexts include `global`, `chat`, `composer`, `editor`, `pager`, `list`, and `approval`; context-specific bindings override `tui.keymap.global`. + +Key + +`tui.keymap.. = []` + +Type / Values + +`empty array` + +Details + +Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, `page-down`, or `minus`. + +Key + +`tui.model_availability_nux.` + +Type / Values + +`integer` + +Details + +Internal startup-tooltip state keyed by model slug. + +Key + +`tui.notification_condition` + +Type / Values + +`unfocused | always` + +Details + +Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`. + +Key + +`tui.notification_method` + +Type / Values + +`auto | osc9 | bel` + +Details + +Notification method for terminal notifications (default: auto). + +Key + +`tui.notifications` + +Type / Values + +`boolean | array` + +Details + +Enable TUI notifications; optionally restrict to specific event types. + +Key + +`tui.raw_output_mode` + +Type / Values + +`boolean` + +Details + +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. + +Key + +`tui.show_tooltips` + +Type / Values + +`boolean` + +Details + +Show onboarding tooltips in the TUI welcome screen (default: true). + +Key + +`tui.status_line` + +Type / Values + +`array | null` + +Details + +Ordered list of TUI footer status-line item identifiers. `null` disables the status line. + +Key + +`tui.terminal_title` + +Type / Values + +`array | null` + +Details + +Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates. + +Key + +`tui.theme` + +Type / Values + +`string` + +Details + +Syntax-highlighting theme override (kebab-case theme name). + +Key + +`tui.vim_mode_default` + +Type / Values + +`boolean` + +Details + +Start the composer in Vim normal mode instead of insert mode (default: false). You can still toggle it per session with `/vim`. + +Key + +`web_search` + +Type / Values + +`disabled | cached | live` + +Details + +Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. + +Key + +`windows_wsl_setup_acknowledged` + +Type / Values + +`boolean` + +Details + +Track Windows onboarding acknowledgement (Windows only). + +Key + +`windows.sandbox` + +Type / Values + +`unelevated | elevated` + +Details + +Windows-only native sandbox mode when running Codex natively on Windows. + +Key + +`windows.sandbox_private_desktop` + +Type / Values + +`boolean` + +Details + +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. + +Expand to view all You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json). -To get autocompletion and diagnostics when editing `config.toml` in VS Code or Cursor, you can install the [Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml) extension and add this line to the top of your `config.toml`: +To get autocompletion and diagnostics when editing `config.toml` in VS Code or Cursor, you can install the [Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.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](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml). + +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 feature flags by the same +canonical keys that `config.toml` uses. Omitted keys remain unconstrained. + +| Key | Type / Values | Details | +| --- | --- | --- | +| `allowed_approval_policies` | `array` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). | +| `allowed_approvals_reviewers` | `array` | Allowed values for `approvals_reviewer`, such as `user` and `auto_review`. | +| `allowed_sandbox_modes` | `array` | Allowed values for `sandbox_mode`. | +| `allowed_web_search_modes` | `array` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. | +| `experimental_network` | `table` | Network access requirements enforced from `requirements.toml`. These constraints are separate from `features.network_proxy` and can configure sandboxed networking without the user feature flag. | +| `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` | List-shaped administrator allow rules for sandboxed networking. 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` | List-shaped administrator deny rules for sandboxed networking. Do not combine this with `experimental_network.domains`. | +| `experimental_network.domains` | `map` | 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` | Administrator-managed Unix socket policy for sandboxed networking. | +| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. | +| `features.` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. | +| `features.browser_use` | `boolean` | Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability. | +| `features.computer_use` | `boolean` | Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows. | +| `features.in_app_browser` | `boolean` | Set to `false` in `requirements.toml` to disable the in-app browser pane. | +| `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.` | `array
` | Matcher groups for a hook event such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, or `Stop`. | +| `hooks.[].hooks` | `array
` | Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped. | +| `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. | +| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (``) 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..identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). | +| `mcp_servers..identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers..command` matches this command. | +| `mcp_servers..identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers..url` matches this URL. | +| `permissions.filesystem.deny_read` | `array` | Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config. | +| `remote_sandbox_config` | `array
` | 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` | Allowed sandbox modes to apply when this host-specific entry matches. | +| `remote_sandbox_config[].hostname_patterns` | `array` | 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
` | 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
` | Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`. | +| `rules.prefix_rules[].pattern[].any_of` | `array` | A list of allowed alternative tokens at this position. | +| `rules.prefix_rules[].pattern[].token` | `string` | A single literal token at this position. | + +Key + +`allowed_approval_policies` + +Type / Values + +`array` + +Details + +Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). -```toml -#:schema https://developers.openai.com/codex/config-schema.json -``` +Key -Note: Rename `experimental_instructions_file` to `model_instructions_file`. Codex deprecates the old key; update existing configs to the new name. +`allowed_approvals_reviewers` -## `requirements.toml` +Type / Values -`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](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml). +`array` -For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched -requirements. See the security page for precedence details. +Details -Use `[features]` in `requirements.toml` to pin feature flags by the same -canonical keys that `config.toml` uses. Omitted keys remain unconstrained. +Allowed values for `approvals_reviewer`, such as `user` and `auto_review`. + +Key + +`allowed_sandbox_modes` + +Type / Values + +`array` + +Details + +Allowed values for `sandbox_mode`. + +Key + +`allowed_web_search_modes` + +Type / Values + +`array` + +Details + +Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. + +Key + +`experimental_network` + +Type / Values + +`table` + +Details + +Network access requirements enforced from `requirements.toml`. These constraints are separate from `features.network_proxy` and can configure sandboxed networking without the user feature flag. + +Key + +`experimental_network.allow_local_binding` + +Type / Values + +`boolean` + +Details + +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`. + +Key + +`experimental_network.allow_upstream_proxy` + +Type / Values + +`boolean` + +Details + +Allow sandboxed networking to chain through an upstream proxy from the environment. + +Key + +`experimental_network.allowed_domains` + +Type / Values + +`array` + +Details + +List-shaped administrator allow rules for sandboxed networking. Do not combine this with `experimental_network.domains`. + +Key + +`experimental_network.dangerously_allow_all_unix_sockets` + +Type / Values + +`boolean` + +Details + +Permit arbitrary Unix socket destinations instead of allowlist-only access. Use only in tightly controlled environments. + +Key + +`experimental_network.dangerously_allow_non_loopback_proxy` + +Type / Values + +`boolean` + +Details + +Permit non-loopback listener addresses for `[experimental_network]` requirements. Enabling it can expose listeners beyond localhost. + +Key + +`experimental_network.denied_domains` + +Type / Values + +`array` + +Details + +List-shaped administrator deny rules for sandboxed networking. Do not combine this with `experimental_network.domains`. + +Key + +`experimental_network.domains` + +Type / Values + +`map` + +Details + +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`. + +Key + +`experimental_network.enabled` + +Type / Values + +`boolean` + +Details + +Enable sandboxed networking requirements. This does not grant network access when the active sandbox keeps command networking off. + +Key + +`experimental_network.http_port` + +Type / Values + +`integer` + +Details + +Loopback HTTP listener port to use for `[experimental_network]` requirements. + +Key + +`experimental_network.managed_allowed_domains_only` + +Type / Values + +`boolean` + +Details + +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. + +Key + +`experimental_network.socks_port` + +Type / Values + +`integer` + +Details + +Loopback SOCKS5 listener port to use for `[experimental_network]` requirements. + +Key + +`experimental_network.unix_sockets` + +Type / Values + +`map` + +Details + +Administrator-managed Unix socket policy for sandboxed networking. + +Key + +`features` + +Type / Values + +`table` + +Details + +Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. + +Key + +`features.` + +Type / Values + +`boolean` + +Details + +Require a specific canonical feature key to stay enabled or disabled. + +Key + +`features.browser_use` + +Type / Values + +`boolean` + +Details + +Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability. + +Key + +`features.computer_use` + +Type / Values + +`boolean` + +Details + +Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows. + +Key + +`features.in_app_browser` + +Type / Values + +`boolean` + +Details + +Set to `false` in `requirements.toml` to disable the in-app browser pane. + +Key + +`guardian_policy_config` + +Type / Values + +`string` + +Details + +Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored. + +Key + +`hooks` + +Type / Values + +`table` + +Details + +Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`. + +Key + +`hooks.` + +Type / Values + +`array
` + +Details + +Matcher groups for a hook event such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, or `Stop`. + +Key + +`hooks.[].hooks` + +Type / Values + +`array
` + +Details + +Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped. + +Key + +`hooks.managed_dir` + +Type / Values + +`string (absolute path)` + +Details + +Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks. + +Key + +`hooks.windows_managed_dir` + +Type / Values + +`string (absolute path)` + +Details + +Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks. + +Key + +`mcp_servers` + +Type / Values + +`table` + +Details + +Allowlist of MCP servers that may be enabled. Both the server name (``) 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. + +Key + +`mcp_servers..identity` + +Type / Values + +`table` + +Details + +Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). + +Key + +`mcp_servers..identity.command` + +Type / Values + +`string` + +Details + +Allow an MCP stdio server when its `mcp_servers..command` matches this command. + +Key + +`mcp_servers..identity.url` + +Type / Values + +`string` + +Details + +Allow an MCP streamable HTTP server when its `mcp_servers..url` matches this URL. + +Key + +`permissions.filesystem.deny_read` + +Type / Values + +`array` + +Details + +Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config. + +Key + +`remote_sandbox_config` + +Type / Values + +`array
` + +Details + +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. + +Key + +`remote_sandbox_config[].allowed_sandbox_modes` + +Type / Values + +`array` + +Details + +Allowed sandbox modes to apply when this host-specific entry matches. + +Key + +`remote_sandbox_config[].hostname_patterns` + +Type / Values + +`array` + +Details + +Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character. + +Key + +`rules` + +Type / Values + +`table` + +Details + +Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. + +Key + +`rules.prefix_rules` + +Type / Values + +`array
` + +Details + +List of enforced prefix rules. Each rule must include `pattern` and `decision`. + +Key + +`rules.prefix_rules[].decision` + +Type / Values + +`prompt | forbidden` + +Details + +Required. Requirements rules can only prompt or forbid (not allow). + +Key + +`rules.prefix_rules[].justification` + +Type / Values + +`string` + +Details + +Optional non-empty rationale surfaced in approval prompts or rejection messages. + +Key + +`rules.prefix_rules[].pattern` + +Type / Values + +`array
` + +Details + +Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`. + +Key + +`rules.prefix_rules[].pattern[].any_of` + +Type / Values + +`array` + +Details + +A list of allowed alternative tokens at this position. + +Key + +`rules.prefix_rules[].pattern[].token` + +Type / Values + +`string` + +Details + +A single literal token at this position. + +Expand to view all -", - description: - "Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`).", - }, - { - key: "allowed_approvals_reviewers", - type: "array", - description: - "Allowed values for `approvals_reviewer`, such as `user` and `auto_review`.", - }, - { - key: "guardian_policy_config", - type: "string", - description: - "Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored.", - }, - { - key: "allowed_sandbox_modes", - type: "array", - description: "Allowed values for `sandbox_mode`.", - }, - { - key: "remote_sandbox_config", - type: "array
", - description: - "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.", - }, - { - key: "remote_sandbox_config[].hostname_patterns", - type: "array", - description: - "Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character.", - }, - { - key: "remote_sandbox_config[].allowed_sandbox_modes", - type: "array", - description: - "Allowed sandbox modes to apply when this host-specific entry matches.", - }, - { - key: "allowed_web_search_modes", - type: "array", - description: - "Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`.", - }, - { - key: "features", - type: "table", - description: - "Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.", - }, - { - key: "features.", - type: "boolean", - description: - "Require a specific canonical feature key to stay enabled or disabled.", - }, - { - key: "features.in_app_browser", - type: "boolean", - description: - "Set to `false` in `requirements.toml` to disable the in-app browser pane.", - }, - { - key: "features.browser_use", - type: "boolean", - description: - "Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability.", - }, - { - key: "features.computer_use", - type: "boolean", - description: - "Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.", - }, - { - key: "experimental_network", - type: "table", - description: - "Network access requirements enforced from `requirements.toml`. These constraints are separate from `features.network_proxy` and can configure sandboxed networking without the user feature flag.", - }, - { - key: "experimental_network.enabled", - type: "boolean", - description: - "Enable sandboxed networking requirements. This does not grant network access when the active sandbox keeps command networking off.", - }, - { - key: "experimental_network.http_port", - type: "integer", - description: - "Loopback HTTP listener port to use for `[experimental_network]` requirements.", - }, - { - key: "experimental_network.socks_port", - type: "integer", - description: - "Loopback SOCKS5 listener port to use for `[experimental_network]` requirements.", - }, - { - key: "experimental_network.allow_upstream_proxy", - type: "boolean", - description: - "Allow sandboxed networking to chain through an upstream proxy from the environment.", - }, - { - key: "experimental_network.dangerously_allow_non_loopback_proxy", - type: "boolean", - description: - "Permit non-loopback listener addresses for `[experimental_network]` requirements. Enabling it can expose listeners beyond localhost.", - }, - { - key: "experimental_network.dangerously_allow_all_unix_sockets", - type: "boolean", - description: - "Permit arbitrary Unix socket destinations instead of allowlist-only access. Use only in tightly controlled environments.", - }, - { - key: "experimental_network.domains", - type: "map", - description: - "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`.", - }, - { - key: "experimental_network.allowed_domains", - type: "array", - description: - "List-shaped administrator allow rules for sandboxed networking. Do not combine this with `experimental_network.domains`.", - }, - { - key: "experimental_network.denied_domains", - type: "array", - description: - "List-shaped administrator deny rules for sandboxed networking. Do not combine this with `experimental_network.domains`.", - }, - { - key: "experimental_network.managed_allowed_domains_only", - type: "boolean", - description: - "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.", - }, - { - key: "experimental_network.unix_sockets", - type: "map", - description: - "Administrator-managed Unix socket policy for sandboxed networking.", - }, - { - key: "experimental_network.allow_local_binding", - type: "boolean", - description: - "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`.", - }, - { - key: "hooks", - type: "table", - description: - "Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`.", - }, - { - key: "hooks.managed_dir", - type: "string (absolute path)", - description: - "Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks.", - }, - { - key: "hooks.windows_managed_dir", - type: "string (absolute path)", - description: - "Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks.", - }, - { - key: "hooks.", - type: "array
", - description: - "Matcher groups for a hook event such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, or `Stop`.", - }, - { - key: "hooks.[].hooks", - type: "array
", - description: - "Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped.", - }, - { - key: "permissions.filesystem.deny_read", - type: "array", - description: - "Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config.", - }, - { - key: "mcp_servers", - type: "table", - description: - "Allowlist of MCP servers that may be enabled. Both the server name (``) 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.", - }, - { - key: "mcp_servers..identity", - type: "table", - description: - "Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP).", - }, - { - key: "mcp_servers..identity.command", - type: "string", - description: - "Allow an MCP stdio server when its `mcp_servers..command` matches this command.", - }, - { - key: "mcp_servers..identity.url", - type: "string", - description: - "Allow an MCP streamable HTTP server when its `mcp_servers..url` matches this URL.", - }, - { - key: "rules", - type: "table", - description: - "Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive.", - }, - { - key: "rules.prefix_rules", - type: "array
", - description: - "List of enforced prefix rules. Each rule must include `pattern` and `decision`.", - }, - { - key: "rules.prefix_rules[].pattern", - type: "array
", - description: - "Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`.", - }, - { - key: "rules.prefix_rules[].pattern[].token", - type: "string", - description: "A single literal token at this position.", - }, - { - key: "rules.prefix_rules[].pattern[].any_of", - type: "array", - description: "A list of allowed alternative tokens at this position.", - }, - { - key: "rules.prefix_rules[].decision", - type: "prompt | forbidden", - description: - "Required. Requirements rules can only prompt or forbid (not allow).", - }, - { - key: "rules.prefix_rules[].justification", - type: "string", - description: - "Optional non-empty rationale surfaced in approval prompts or rejection messages.", - }, - ]} - client:load -/>