diff --git a/tmp/spybara-diff-qxhmy9jh/old.md b/tmp/spybara-diff-qxhmy9jh/new.md index fe6f16c..502947b 100644 --- a/tmp/spybara-diff-qxhmy9jh/old.md +++ b/tmp/spybara-diff-qxhmy9jh/new.md @@ -6,3015 +6,1467 @@ 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. -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). - -| 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` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. | -| `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_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. | -| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). | -| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). | -| `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.personality` | `boolean` | Enable personality selection controls (stable; on by default). | -| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). | -| `features.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..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..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 local bind/listen operations through the managed proxy. | -| `permissions..network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. | -| `permissions..network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. | -| `permissions..network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. | -| `permissions..network.domains` | `map` | Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values. | -| `permissions..network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. | -| `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.mode` | `limited | full` | Network proxy mode used for subprocess traffic. | -| `permissions..network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. | -| `permissions..network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. | -| `permissions..network.unix_sockets` | `map` | Unix socket rules for the managed proxy. 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. | -| `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` | `flex | fast` | 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` | `flex | fast` | Preferred service tier for new turns. | -| `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`, or `page-down`. | -| `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.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). | -| `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 - -Override the commit co-author trailer text. Set an empty string to disable automatic attribution. - -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_hooks` - -Type / Values - -`boolean` - -Details - -Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. - -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 Fast mode selection and the `service_tier = "fast"` path (stable; on by default). - -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.personality` - -Type / Values - -`boolean` - -Details - -Enable personality selection controls (stable; on by default). - -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..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..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 local bind/listen operations through the managed proxy. - -Key - -`permissions..network.allow_upstream_proxy` - -Type / Values - -`boolean` - -Details - -Allow the managed proxy to chain to another upstream proxy. - -Key - -`permissions..network.dangerously_allow_all_unix_sockets` - -Type / Values - -`boolean` - -Details - -Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. - -Key - -`permissions..network.dangerously_allow_non_loopback_proxy` - -Type / Values - -`boolean` - -Details - -Permit non-loopback bind addresses for the managed proxy listener. - -Key - -`permissions..network.domains` - -Type / Values - -`map` - -Details - -Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values. - -Key - -`permissions..network.enable_socks5` - -Type / Values - -`boolean` - -Details - -Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. - -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.mode` - -Type / Values - -`limited | full` - -Details - -Network proxy mode used for subprocess traffic. - -Key - -`permissions..network.proxy_url` - -Type / Values - -`string` - -Details - -HTTP proxy endpoint used when this permissions profile enables the managed network proxy. - -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 the managed proxy. 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 - -`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 - -`flex | fast` - -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 - -`flex | fast` - -Details - -Preferred service tier for new turns. - -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 +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 +`otel` when they appear in a project-local `.codex/config.toml`; put those in +user-level config instead. -`empty array` - -Details - -Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, or `page-down`. - -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.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 - -`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. +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). -Expand to view all +.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 +/> You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json). @@ -3036,397 +1488,263 @@ 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`. | -| `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`, `PostToolUse`, `PermissionRequest`, `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`). - -Key - -`allowed_approvals_reviewers` - -Type / Values - -`array` - -Details - -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 - -`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`, `PostToolUse`, `PermissionRequest`, `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 +/>