8 8
9For 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).9For 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).
10 10
11| Key | Type / Values | Details |11<ConfigTable
12| --- | --- | --- |12 options={[
13| `agents.<name>.config_file` | `string (path)` | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |13 {
14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |14 key: "model",
15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |15 type: "string",
16| `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. |16 description: "Model to use (e.g., `gpt-5.5`).",
17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |17 },
18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |18 {
19| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |19 key: "review_model",
20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |20 type: "string",
21| `approval_policy` | `untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |21 description:
22| `approval_policy.granular.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected. |22 "Optional model override used by `/review` (defaults to the current session model).",
23| `approval_policy.granular.request_permissions` | `boolean` | When `true`, prompts from the `request_permissions` tool are allowed to surface. |23 },
24| `approval_policy.granular.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface. |24 {
25| `approval_policy.granular.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are allowed to surface. |25 key: "model_provider",
26| `approval_policy.granular.skill_approval` | `boolean` | When `true`, skill-script approval prompts are allowed to surface. |26 type: "string",
27| `approvals_reviewer` | `user | guardian_subagent` | Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent. |27 description: "Provider id from `model_providers` (default: `openai`).",
28| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |28 },
29| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |29 {
30| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |30 key: "openai_base_url",
31| `apps.<id>.default_tools_approval_mode` | `auto | prompt | approve` | Default approval behavior for tools in this app unless a per-tool override exists. |31 type: "string",
32| `apps.<id>.default_tools_enabled` | `boolean` | Default enabled state for tools in this app unless a per-tool override exists. |32 description:
33| `apps.<id>.destructive_enabled` | `boolean` | Allow or block tools in this app that advertise `destructive_hint = true`. |33 "Base URL override for the built-in `openai` model provider.",
34| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |34 },
35| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |35 {
36| `apps.<id>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. |36 key: "model_context_window",
37| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |37 type: "number",
38| `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. |38 description: "Context window tokens available to the active model.",
39| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |39 },
40| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |40 {
41| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |41 key: "model_auto_compact_token_limit",
42| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |42 type: "number",
43| `compact_prompt` | `string` | Inline override for the history compaction prompt. |43 description:
44| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. |44 "Token threshold that triggers automatic history compaction (unset uses model defaults).",
45| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |45 },
46| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |46 {
47| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |47 key: "model_catalog_json",
48| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |48 type: "string (path)",
49| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |49 description:
50| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |50 "Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.",
51| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |51 },
52| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |52 {
53| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |53 key: "oss_provider",
54| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |54 type: "lmstudio | ollama",
55| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |55 description:
56| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |56 "Default local provider used when running with `--oss` (defaults to prompting if unset).",
57| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |57 },
58| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |58 {
59| `features.smart_approvals` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). |59 key: "approval_policy",
60| `features.undo` | `boolean` | Enable undo support (stable; off by default). |60 type: "untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }",
61| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (stable; enabled by default except on Windows). |61 description:
62| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |62 "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.",
63| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |63 },
64| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |64 {
65| `feedback.enabled` | `boolean` | Enable feedback submission via `/feedback` across Codex surfaces (default: true). |65 key: "approval_policy.granular.sandbox_approval",
66| `file_opener` | `vscode | vscode-insiders | windsurf | cursor | none` | URI scheme used to open citations from Codex output (default: `vscode`). |66 type: "boolean",
67| `forced_chatgpt_workspace_id` | `string (uuid)` | Limit ChatGPT logins to a specific workspace identifier. |67 description:
68| `forced_login_method` | `chatgpt | api` | Restrict Codex to a specific authentication method. |68 "When `true`, sandbox escalation approval prompts are allowed to surface.",
69| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |69 },
70| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |70 {
71| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |71 key: "approval_policy.granular.rules",
72| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |72 type: "boolean",
73| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |73 description:
74| `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. |74 "When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.",
75| `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. |75 },
76| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |76 {
77| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |77 key: "approval_policy.granular.mcp_elicitations",
78| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |78 type: "boolean",
79| `mcp_servers.<id>.command` | `string` | Launcher command for an MCP stdio server. |79 description:
80| `mcp_servers.<id>.cwd` | `string` | Working directory for the MCP stdio server process. |80 "When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.",
81| `mcp_servers.<id>.disabled_tools` | `array<string>` | Deny list applied after `enabled_tools` for the MCP server. |81 },
82| `mcp_servers.<id>.enabled` | `boolean` | Disable an MCP server without removing its configuration. |82 {
83| `mcp_servers.<id>.enabled_tools` | `array<string>` | Allow list of tool names exposed by the MCP server. |83 key: "approval_policy.granular.request_permissions",
84| `mcp_servers.<id>.env` | `map<string,string>` | Environment variables forwarded to the MCP stdio server. |84 type: "boolean",
85| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |85 description:
86| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |86 "When `true`, prompts from the `request_permissions` tool are allowed to surface.",
87| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |87 },
88| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |88 {
89| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |89 key: "approval_policy.granular.skill_approval",
90| `mcp_servers.<id>.scopes` | `array<string>` | OAuth scopes to request when authenticating to that MCP server. |90 type: "boolean",
91| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |91 description:
92| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |92 "When `true`, skill-script approval prompts are allowed to surface.",
93| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |93 },
94| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |94 {
95| `model` | `string` | Model to use (e.g., `gpt-5.4`). |95 key: "approvals_reviewer",
96| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |96 type: "user | auto_review",
97| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |97 description:
98| `model_context_window` | `number` | Context window tokens available to the active model. |98 "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.",
99| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |99 },
100| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |100 {
101| `model_providers.<id>` | `table` | Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden. |101 key: "auto_review.policy",
102| `model_providers.<id>.auth` | `table` | Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`. |102 type: "string",
103| `model_providers.<id>.auth.args` | `array<string>` | Arguments passed to the token command. |103 description:
104| `model_providers.<id>.auth.command` | `string` | Command to run when Codex needs a bearer token. The command must print the token to stdout. |104 "Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored.",
105| `model_providers.<id>.auth.cwd` | `string (path)` | Working directory for the token command. |105 },
106| `model_providers.<id>.auth.refresh_interval_ms` | `number` | How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry. |106 {
107| `model_providers.<id>.auth.timeout_ms` | `number` | Maximum token command runtime in milliseconds (default: 5000). |107 key: "allow_login_shell",
108| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |108 type: "boolean",
109| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |109 description:
110| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |110 "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.",
111| `model_providers.<id>.env_key_instructions` | `string` | Optional setup guidance for the provider API key. |111 },
112| `model_providers.<id>.experimental_bearer_token` | `string` | Direct bearer token for the provider (discouraged; use `env_key`). |112 {
113| `model_providers.<id>.http_headers` | `map<string,string>` | Static HTTP headers added to provider requests. |113 key: "sandbox_mode",
114| `model_providers.<id>.name` | `string` | Display name for a custom model provider. |114 type: "read-only | workspace-write | danger-full-access",
115| `model_providers.<id>.query_params` | `map<string,string>` | Extra query parameters appended to provider requests. |115 description:
116| `model_providers.<id>.request_max_retries` | `number` | Retry count for HTTP requests to the provider (default: 4). |116 "Sandbox policy for filesystem and network access during command execution.",
117| `model_providers.<id>.requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). |117 },
118| `model_providers.<id>.stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). |118 {
119| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |119 key: "sandbox_workspace_write.writable_roots",
120| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |120 type: "array<string>",
121| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |121 description:
122| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |122 'Additional writable roots when `sandbox_mode = "workspace-write"`.',
123| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |123 },
124| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |124 {
125| `model_verbosity` | `low | medium | high` | Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used. |125 key: "sandbox_workspace_write.network_access",
126| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |126 type: "boolean",
127| `notice.hide_gpt-5.1-codex-max_migration_prompt` | `boolean` | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |127 description:
128| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |128 "Allow outbound network access inside the workspace-write sandbox.",
129| `notice.hide_rate_limit_model_nudge` | `boolean` | Track opt-out of the rate limit model switch reminder. |129 },
130| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |130 {
131| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |131 key: "sandbox_workspace_write.exclude_tmpdir_env_var",
132| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |132 type: "boolean",
133| `openai_base_url` | `string` | Base URL override for the built-in `openai` model provider. |133 description:
134| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |134 "Exclude `$TMPDIR` from writable roots in workspace-write mode.",
135| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |135 },
136| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |136 {
137| `otel.exporter.<id>.endpoint` | `string` | Exporter endpoint for OTEL logs. |137 key: "sandbox_workspace_write.exclude_slash_tmp",
138| `otel.exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL exporter requests. |138 type: "boolean",
139| `otel.exporter.<id>.protocol` | `binary | json` | Protocol used by the OTLP/HTTP exporter. |139 description:
140| `otel.exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL exporter TLS. |140 "Exclude `/tmp` from writable roots in workspace-write mode.",
141| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |141 },
142| `otel.exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL exporter TLS. |142 {
143| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |143 key: "windows.sandbox",
144| `otel.metrics_exporter` | `none | statsig | otlp-http | otlp-grpc` | Select the OpenTelemetry metrics exporter (defaults to `statsig`). |144 type: "unelevated | elevated",
145| `otel.trace_exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |145 description:
146| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |146 "Windows-only native sandbox mode when running Codex natively on Windows.",
147| `otel.trace_exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL trace exporter requests. |147 },
148| `otel.trace_exporter.<id>.protocol` | `binary | json` | Protocol used by the OTLP/HTTP trace exporter. |148 {
149| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |149 key: "windows.sandbox_private_desktop",
150| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |150 type: "boolean",
151| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |151 description:
152| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |152 "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.",
153| `permissions.<name>.filesystem.":project_roots".<subpath>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself. |153 },
154| `permissions.<name>.filesystem.<path>` | `"read" | "write" | "none" | table` | Grant direct access for a path or special token, or scope nested entries under that root. |154 {
155| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |155 key: "notify",
156| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |156 type: "array<string>",
157| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |157 description:
158| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |158 "Command invoked for notifications; receives a JSON payload from Codex.",
159| `permissions.<name>.network.domains` | `map<string, allow | deny>` | Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values. |159 },
160| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |160 {
161| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |161 key: "check_for_update_on_startup",
162| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |162 type: "boolean",
163| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |163 description:
164| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |164 "Check for Codex updates on startup (set to false only when updates are centrally managed).",
165| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |165 },
166| `permissions.<name>.network.unix_sockets` | `map<string, allow | none>` | Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values. |166 {
167| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |167 key: "feedback.enabled",
168| `plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default. |168 type: "boolean",
169| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |169 description:
170| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |170 "Enable feedback submission via `/feedback` across Codex surfaces (default: true).",
171| `profiles.<name>.analytics.enabled` | `boolean` | Profile-scoped analytics enablement override. |171 },
172| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |172 {
173| `profiles.<name>.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). |173 key: "analytics.enabled",
174| `profiles.<name>.model_instructions_file` | `string (path)` | Profile-scoped replacement for the built-in instruction file. |174 type: "boolean",
175| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |175 description:
176| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |176 "Enable or disable analytics for this machine/profile. When unset, the client default applies.",
177| `profiles.<name>.plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Profile-scoped Plan-mode reasoning override. |177 },
178| `profiles.<name>.service_tier` | `flex | fast` | Profile-scoped service tier preference for new turns. |178 {
179| `profiles.<name>.tools_view_image` | `boolean` | Enable or disable the `view_image` tool in that profile. |179 key: "instructions",
180| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |180 type: "string",
181| `profiles.<name>.windows.sandbox` | `unelevated | elevated` | Profile-scoped Windows sandbox mode override. |181 description:
182| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |182 "Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.",
183| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |183 },
184| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |184 {
185| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers. |185 key: "developer_instructions",
186| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |186 type: "string",
187| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |187 description:
188| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |188 "Additional developer instructions injected into the session (optional).",
189| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |189 },
190| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |190 {
191| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |191 key: "log_dir",
192| `service_tier` | `flex | fast` | Preferred service tier for new turns. |192 type: "string (path)",
193| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |193 description:
194| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |194 "Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.",
195| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |195 },
196| `shell_environment_policy.include_only` | `array<string>` | Whitelist of patterns; when set only matching variables are kept. |196 {
197| `shell_environment_policy.inherit` | `all | core | none` | Baseline environment inheritance when spawning subprocesses. |197 key: "sqlite_home",
198| `shell_environment_policy.set` | `map<string,string>` | Explicit environment overrides injected into every subprocess. |198 type: "string (path)",
199| `show_raw_agent_reasoning` | `boolean` | Surface raw reasoning content when the active model emits it. |199 description:
200| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |200 "Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.",
201| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |201 },
202| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |202 {
203| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |203 key: "compact_prompt",
204| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |204 type: "string",
205| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |205 description: "Inline override for the history compaction prompt.",
206| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |206 },
207| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |207 {
208| `tools.web_search` | `boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }` | Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location. |208 key: "commit_attribution",
209| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |209 type: "string",
210| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |210 description:
211| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |211 "Override the commit co-author trailer text. Set an empty string to disable automatic attribution.",
212| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |212 },
213| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |213 {
214| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |214 key: "model_instructions_file",
215| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |215 type: "string (path)",
216| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |216 description:
217| `tui.terminal_title` | `array<string> | null` | Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates. |217 "Replacement for built-in instructions instead of `AGENTS.md`.",
218| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |218 },
219| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |219 {
220| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |220 key: "personality",
221| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |221 type: "none | friendly | pragmatic",
222| `windows.sandbox_private_desktop` | `boolean` | Run the final sandboxed child process on a private desktop by default on native Windows. Set `false` only for compatibility with the older `Winsta0\\Default` behavior. |222 description:
223 223 "Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.",
224Key224 },
225 225 {
226`agents.<name>.config_file`226 key: "service_tier",
227 227 type: "flex | fast",
228Type / Values228 description: "Preferred service tier for new turns.",
229 229 },
230`string (path)`230 {
231 231 key: "experimental_compact_prompt_file",
232Details232 type: "string (path)",
233 233 description:
234Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.234 "Load the compaction prompt override from a file (experimental).",
235 235 },
236Key236 {
237 237 key: "skills.config",
238`agents.<name>.description`238 type: "array<object>",
239 239 description: "Per-skill enablement overrides stored in config.toml.",
240Type / Values240 },
241 241 {
242`string`242 key: "skills.config.<index>.path",
243 243 type: "string (path)",
244Details244 description: "Path to a skill folder containing `SKILL.md`.",
245 245 },
246Role guidance shown to Codex when choosing and spawning that agent type.246 {
247 247 key: "skills.config.<index>.enabled",
248Key248 type: "boolean",
249 249 description: "Enable or disable the referenced skill.",
250`agents.<name>.nickname_candidates`250 },
251 251 {
252Type / Values252 key: "apps.<id>.enabled",
253 253 type: "boolean",
254`array<string>`254 description:
255 255 "Enable or disable a specific app/connector by id (default: true).",
256Details256 },
257 257 {
258Optional pool of display nicknames for spawned agents in that role.258 key: "apps._default.enabled",
259 259 type: "boolean",
260Key260 description:
261 261 "Default app enabled state for all apps unless overridden per app.",
262`agents.job_max_runtime_seconds`262 },
263 263 {
264Type / Values264 key: "apps._default.destructive_enabled",
265 265 type: "boolean",
266`number`266 description:
267 267 "Default allow/deny for app tools with `destructive_hint = true`.",
268Details268 },
269 269 {
270Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.270 key: "apps._default.open_world_enabled",
271 271 type: "boolean",
272Key272 description:
273 273 "Default allow/deny for app tools with `open_world_hint = true`.",
274`agents.max_depth`274 },
275 275 {
276Type / Values276 key: "apps.<id>.destructive_enabled",
277 277 type: "boolean",
278`number`278 description:
279 279 "Allow or block tools in this app that advertise `destructive_hint = true`.",
280Details280 },
281 281 {
282Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).282 key: "apps.<id>.open_world_enabled",
283 283 type: "boolean",
284Key284 description:
285 285 "Allow or block tools in this app that advertise `open_world_hint = true`.",
286`agents.max_threads`286 },
287 287 {
288Type / Values288 key: "apps.<id>.default_tools_enabled",
289 289 type: "boolean",
290`number`290 description:
291 291 "Default enabled state for tools in this app unless a per-tool override exists.",
292Details292 },
293 293 {
294Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.294 key: "apps.<id>.default_tools_approval_mode",
295 295 type: "auto | prompt | approve",
296Key296 description:
297 297 "Default approval behavior for tools in this app unless a per-tool override exists.",
298`allow_login_shell`298 },
299 299 {
300Type / Values300 key: "apps.<id>.tools.<tool>.enabled",
301 301 type: "boolean",
302`boolean`302 description:
303 303 "Per-tool enabled override for an app tool (for example `repos/list`).",
304Details304 },
305 305 {
306Allow 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.306 key: "apps.<id>.tools.<tool>.approval_mode",
307 307 type: "auto | prompt | approve",
308Key308 description: "Per-tool approval behavior override for a single app tool.",
309 309 },
310`analytics.enabled`310 {
311 311 key: "tool_suggest.discoverables",
312Type / Values312 type: "array<table>",
313 313 description:
314`boolean`314 'Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.',
315 315 },
316Details316 {
317 317 key: "tool_suggest.disabled_tools",
318Enable or disable analytics for this machine/profile. When unset, the client default applies.318 type: "array<table>",
319 319 description:
320Key320 'Disable suggestions for specific discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.',
321 321 },
322`approval_policy`322 {
323 323 key: "features.apps",
324Type / Values324 type: "boolean",
325 325 description: "Enable ChatGPT Apps/connectors support (experimental).",
326`untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }`326 },
327 327 {
328Details328 key: "features.codex_hooks",
329 329 type: "boolean",
330Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.330 description:
331 331 "Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.",
332Key332 },
333 333 {
334`approval_policy.granular.mcp_elicitations`334 key: "hooks",
335 335 type: "table",
336Type / Values336 description:
337 337 "Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.",
338`boolean`338 },
339 339 {
340Details340 key: "features.memories",
341 341 type: "boolean",
342When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.342 description: "Enable [Memories](https://developers.openai.com/codex/memories) (off by default).",
343 343 },
344Key344 {
345 345 key: "mcp_servers.<id>.command",
346`approval_policy.granular.request_permissions`346 type: "string",
347 347 description: "Launcher command for an MCP stdio server.",
348Type / Values348 },
349 349 {
350`boolean`350 key: "mcp_servers.<id>.args",
351 351 type: "array<string>",
352Details352 description: "Arguments passed to the MCP stdio server command.",
353 353 },
354When `true`, prompts from the `request_permissions` tool are allowed to surface.354 {
355 355 key: "mcp_servers.<id>.env",
356Key356 type: "map<string,string>",
357 357 description: "Environment variables forwarded to the MCP stdio server.",
358`approval_policy.granular.rules`358 },
359 359 {
360Type / Values360 key: "mcp_servers.<id>.env_vars",
361 361 type: 'array<string | { name = string, source = "local" | "remote" }>',
362`boolean`362 description:
363 363 '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.',
364Details364 },
365 365 {
366When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.366 key: "mcp_servers.<id>.cwd",
367 367 type: "string",
368Key368 description: "Working directory for the MCP stdio server process.",
369 369 },
370`approval_policy.granular.sandbox_approval`370 {
371 371 key: "mcp_servers.<id>.url",
372Type / Values372 type: "string",
373 373 description: "Endpoint for an MCP streamable HTTP server.",
374`boolean`374 },
375 375 {
376Details376 key: "mcp_servers.<id>.bearer_token_env_var",
377 377 type: "string",
378When `true`, sandbox escalation approval prompts are allowed to surface.378 description:
379 379 "Environment variable sourcing the bearer token for an MCP HTTP server.",
380Key380 },
381 381 {
382`approval_policy.granular.skill_approval`382 key: "mcp_servers.<id>.http_headers",
383 383 type: "map<string,string>",
384Type / Values384 description: "Static HTTP headers included with each MCP HTTP request.",
385 385 },
386`boolean`386 {
387 387 key: "mcp_servers.<id>.env_http_headers",
388Details388 type: "map<string,string>",
389 389 description:
390When `true`, skill-script approval prompts are allowed to surface.390 "HTTP headers populated from environment variables for an MCP HTTP server.",
391 391 },
392Key392 {
393 393 key: "mcp_servers.<id>.enabled",
394`approvals_reviewer`394 type: "boolean",
395 395 description: "Disable an MCP server without removing its configuration.",
396Type / Values396 },
397 397 {
398`user | guardian_subagent`398 key: "mcp_servers.<id>.required",
399 399 type: "boolean",
400Details400 description:
401 401 "When true, fail startup/resume if this enabled MCP server cannot initialize.",
402Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent.402 },
403 403 {
404Key404 key: "mcp_servers.<id>.startup_timeout_sec",
405 405 type: "number",
406`apps._default.destructive_enabled`406 description:
407 407 "Override the default 10s startup timeout for an MCP server.",
408Type / Values408 },
409 409 {
410`boolean`410 key: "mcp_servers.<id>.startup_timeout_ms",
411 411 type: "number",
412Details412 description: "Alias for `startup_timeout_sec` in milliseconds.",
413 413 },
414Default allow/deny for app tools with `destructive_hint = true`.414 {
415 415 key: "mcp_servers.<id>.tool_timeout_sec",
416Key416 type: "number",
417 417 description:
418`apps._default.enabled`418 "Override the default 60s per-tool timeout for an MCP server.",
419 419 },
420Type / Values420 {
421 421 key: "mcp_servers.<id>.enabled_tools",
422`boolean`422 type: "array<string>",
423 423 description: "Allow list of tool names exposed by the MCP server.",
424Details424 },
425 425 {
426Default app enabled state for all apps unless overridden per app.426 key: "mcp_servers.<id>.disabled_tools",
427 427 type: "array<string>",
428Key428 description:
429 429 "Deny list applied after `enabled_tools` for the MCP server.",
430`apps._default.open_world_enabled`430 },
431 431 {
432Type / Values432 key: "mcp_servers.<id>.scopes",
433 433 type: "array<string>",
434`boolean`434 description:
435 435 "OAuth scopes to request when authenticating to that MCP server.",
436Details436 },
437 437 {
438Default allow/deny for app tools with `open_world_hint = true`.438 key: "mcp_servers.<id>.oauth_resource",
439 439 type: "string",
440Key440 description:
441 441 "Optional RFC 8707 OAuth resource parameter to include during MCP login.",
442`apps.<id>.default_tools_approval_mode`442 },
443 443 {
444Type / Values444 key: "mcp_servers.<id>.experimental_environment",
445 445 type: "local | remote",
446`auto | prompt | approve`446 description:
447 447 "Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.",
448Details448 },
449 449 {
450Default approval behavior for tools in this app unless a per-tool override exists.450 key: "agents.max_threads",
451 451 type: "number",
452Key452 description:
453 453 "Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.",
454`apps.<id>.default_tools_enabled`454 },
455 455 {
456Type / Values456 key: "agents.max_depth",
457 457 type: "number",
458`boolean`458 description:
459 459 "Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).",
460Details460 },
461 461 {
462Default enabled state for tools in this app unless a per-tool override exists.462 key: "agents.job_max_runtime_seconds",
463 463 type: "number",
464Key464 description:
465 465 "Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.",
466`apps.<id>.destructive_enabled`466 },
467 467 {
468Type / Values468 key: "agents.<name>.description",
469 469 type: "string",
470`boolean`470 description:
471 471 "Role guidance shown to Codex when choosing and spawning that agent type.",
472Details472 },
473 473 {
474Allow or block tools in this app that advertise `destructive_hint = true`.474 key: "agents.<name>.config_file",
475 475 type: "string (path)",
476Key476 description:
477 477 "Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.",
478`apps.<id>.enabled`478 },
479 479 {
480Type / Values480 key: "agents.<name>.nickname_candidates",
481 481 type: "array<string>",
482`boolean`482 description:
483 483 "Optional pool of display nicknames for spawned agents in that role.",
484Details484 },
485 485 {
486Enable or disable a specific app/connector by id (default: true).486 key: "memories.generate_memories",
487 487 type: "boolean",
488Key488 description:
489 489 "When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.",
490`apps.<id>.open_world_enabled`490 },
491 491 {
492Type / Values492 key: "memories.use_memories",
493 493 type: "boolean",
494`boolean`494 description:
495 495 "When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.",
496Details496 },
497 497 {
498Allow or block tools in this app that advertise `open_world_hint = true`.498 key: "memories.disable_on_external_context",
499 499 type: "boolean",
500Key500 description:
501 501 "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`.",
502`apps.<id>.tools.<tool>.approval_mode`502 },
503 503 {
504Type / Values504 key: "memories.max_raw_memories_for_consolidation",
505 505 type: "number",
506`auto | prompt | approve`506 description:
507 507 "Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.",
508Details508 },
509 509 {
510Per-tool approval behavior override for a single app tool.510 key: "memories.max_unused_days",
511 511 type: "number",
512Key512 description:
513 513 "Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.",
514`apps.<id>.tools.<tool>.enabled`514 },
515 515 {
516Type / Values516 key: "memories.max_rollout_age_days",
517 517 type: "number",
518`boolean`518 description:
519 519 "Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.",
520Details520 },
521 521 {
522Per-tool enabled override for an app tool (for example `repos/list`).522 key: "memories.max_rollouts_per_startup",
523 523 type: "number",
524Key524 description:
525 525 "Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.",
526`background_terminal_max_timeout`526 },
527 527 {
528Type / Values528 key: "memories.min_rollout_idle_hours",
529 529 type: "number",
530`number`530 description:
531 531 "Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.",
532Details532 },
533 533 {
534Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.534 key: "memories.min_rate_limit_remaining_percent",
535 535 type: "number",
536Key536 description:
537 537 "Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`.",
538`chatgpt_base_url`538 },
539 539 {
540Type / Values540 key: "memories.extract_model",
541 541 type: "string",
542`string`542 description: "Optional model override for per-thread memory extraction.",
543 543 },
544Details544 {
545 545 key: "memories.consolidation_model",
546Override the base URL used during the ChatGPT login flow.546 type: "string",
547 547 description: "Optional model override for global memory consolidation.",
548Key548 },
549 549 {
550`check_for_update_on_startup`550 key: "features.unified_exec",
551 551 type: "boolean",
552Type / Values552 description:
553 553 "Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).",
554`boolean`554 },
555 555 {
556Details556 key: "features.shell_snapshot",
557 557 type: "boolean",
558Check for Codex updates on startup (set to false only when updates are centrally managed).558 description:
559 559 "Snapshot shell environment to speed up repeated commands (stable; on by default).",
560Key560 },
561 561 {
562`cli_auth_credentials_store`562 key: "features.undo",
563 563 type: "boolean",
564Type / Values564 description: "Enable undo support (stable; off by default).",
565 565 },
566`file | keyring | auto`566 {
567 567 key: "features.multi_agent",
568Details568 type: "boolean",
569 569 description:
570Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).570 "Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).",
571 571 },
572Key572 {
573 573 key: "features.personality",
574`commit_attribution`574 type: "boolean",
575 575 description:
576Type / Values576 "Enable personality selection controls (stable; on by default).",
577 577 },
578`string`578 {
579 579 key: "features.web_search",
580Details580 type: "boolean",
581 581 description:
582Override the commit co-author trailer text. Set an empty string to disable automatic attribution.582 "Deprecated legacy toggle; prefer the top-level `web_search` setting.",
583 583 },
584Key584 {
585 585 key: "features.web_search_cached",
586`compact_prompt`586 type: "boolean",
587 587 description:
588Type / Values588 'Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.',
589 589 },
590`string`590 {
591 591 key: "features.web_search_request",
592Details592 type: "boolean",
593 593 description:
594Inline override for the history compaction prompt.594 'Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.',
595 595 },
596Key596 {
597 597 key: "features.shell_tool",
598`default_permissions`598 type: "boolean",
599 599 description:
600Type / Values600 "Enable the default `shell` tool for running commands (stable; on by default).",
601 601 },
602`string`602 {
603 603 key: "features.enable_request_compression",
604Details604 type: "boolean",
605 605 description:
606Name of the default permissions profile to apply to sandboxed tool calls.606 "Compress streaming request bodies with zstd when supported (stable; on by default).",
607 607 },
608Key608 {
609 609 key: "features.skill_mcp_dependency_install",
610`developer_instructions`610 type: "boolean",
611 611 description:
612Type / Values612 "Allow prompting and installing missing MCP dependencies for skills (stable; on by default).",
613 613 },
614`string`614 {
615 615 key: "features.fast_mode",
616Details616 type: "boolean",
617 617 description:
618Additional developer instructions injected into the session (optional).618 'Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).',
619 619 },
620Key620 {
621 621 key: "features.prevent_idle_sleep",
622`disable_paste_burst`622 type: "boolean",
623 623 description:
624Type / Values624 "Prevent the machine from sleeping while a turn is actively running (experimental; off by default).",
625 625 },
626`boolean`626 {
627 627 key: "suppress_unstable_features_warning",
628Details628 type: "boolean",
629 629 description:
630Disable burst-paste detection in the TUI.630 "Suppress the warning that appears when under-development feature flags are enabled.",
631 631 },
632Key632 {
633 633 key: "model_providers.<id>",
634`experimental_compact_prompt_file`634 type: "table",
635 635 description:
636Type / Values636 "Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.",
637 637 },
638`string (path)`638 {
639 639 key: "model_providers.<id>.name",
640Details640 type: "string",
641 641 description: "Display name for a custom model provider.",
642Load the compaction prompt override from a file (experimental).642 },
643 643 {
644Key644 key: "model_providers.<id>.base_url",
645 645 type: "string",
646`experimental_use_unified_exec_tool`646 description: "API base URL for the model provider.",
647 647 },
648Type / Values648 {
649 649 key: "model_providers.<id>.env_key",
650`boolean`650 type: "string",
651 651 description: "Environment variable supplying the provider API key.",
652Details652 },
653 653 {
654Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.654 key: "model_providers.<id>.env_key_instructions",
655 655 type: "string",
656Key656 description: "Optional setup guidance for the provider API key.",
657 657 },
658`features.apps`658 {
659 659 key: "model_providers.<id>.experimental_bearer_token",
660Type / Values660 type: "string",
661 661 description:
662`boolean`662 "Direct bearer token for the provider (discouraged; use `env_key`).",
663 663 },
664Details664 {
665 665 key: "model_providers.<id>.requires_openai_auth",
666Enable ChatGPT Apps/connectors support (experimental).666 type: "boolean",
667 667 description:
668Key668 "The provider uses OpenAI authentication (defaults to false).",
669 669 },
670`features.codex_hooks`670 {
671 671 key: "model_providers.<id>.wire_api",
672Type / Values672 type: "responses",
673 673 description:
674`boolean`674 "Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.",
675 675 },
676Details676 {
677 677 key: "model_providers.<id>.query_params",
678Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).678 type: "map<string,string>",
679 679 description: "Extra query parameters appended to provider requests.",
680Key680 },
681 681 {
682`features.enable_request_compression`682 key: "model_providers.<id>.http_headers",
683 683 type: "map<string,string>",
684Type / Values684 description: "Static HTTP headers added to provider requests.",
685 685 },
686`boolean`686 {
687 687 key: "model_providers.<id>.env_http_headers",
688Details688 type: "map<string,string>",
689 689 description:
690Compress streaming request bodies with zstd when supported (stable; on by default).690 "HTTP headers populated from environment variables when present.",
691 691 },
692Key692 {
693 693 key: "model_providers.<id>.request_max_retries",
694`features.fast_mode`694 type: "number",
695 695 description:
696Type / Values696 "Retry count for HTTP requests to the provider (default: 4).",
697 697 },
698`boolean`698 {
699 699 key: "model_providers.<id>.stream_max_retries",
700Details700 type: "number",
701 701 description: "Retry count for SSE streaming interruptions (default: 5).",
702Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).702 },
703 703 {
704Key704 key: "model_providers.<id>.stream_idle_timeout_ms",
705 705 type: "number",
706`features.multi_agent`706 description:
707 707 "Idle timeout for SSE streams in milliseconds (default: 300000).",
708Type / Values708 },
709 709 {
710`boolean`710 key: "model_providers.<id>.supports_websockets",
711 711 type: "boolean",
712Details712 description:
713 713 "Whether that provider supports the Responses API WebSocket transport.",
714Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).714 },
715 715 {
716Key716 key: "model_providers.<id>.auth",
717 717 type: "table",
718`features.personality`718 description:
719 719 "Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.",
720Type / Values720 },
721 721 {
722`boolean`722 key: "model_providers.<id>.auth.command",
723 723 type: "string",
724Details724 description:
725 725 "Command to run when Codex needs a bearer token. The command must print the token to stdout.",
726Enable personality selection controls (stable; on by default).726 },
727 727 {
728Key728 key: "model_providers.<id>.auth.args",
729 729 type: "array<string>",
730`features.prevent_idle_sleep`730 description: "Arguments passed to the token command.",
731 731 },
732Type / Values732 {
733 733 key: "model_providers.<id>.auth.timeout_ms",
734`boolean`734 type: "number",
735 735 description:
736Details736 "Maximum token command runtime in milliseconds (default: 5000).",
737 737 },
738Prevent the machine from sleeping while a turn is actively running (experimental; off by default).738 {
739 739 key: "model_providers.<id>.auth.refresh_interval_ms",
740Key740 type: "number",
741 741 description:
742`features.shell_snapshot`742 "How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.",
743 743 },
744Type / Values744 {
745 745 key: "model_providers.<id>.auth.cwd",
746`boolean`746 type: "string (path)",
747 747 description: "Working directory for the token command.",
748Details748 },
749 749 {
750Snapshot shell environment to speed up repeated commands (stable; on by default).750 key: "model_providers.amazon-bedrock.aws.profile",
751 751 type: "string",
752Key752 description:
753 753 "AWS profile name used by the built-in `amazon-bedrock` provider.",
754`features.shell_tool`754 },
755 755 {
756Type / Values756 key: "model_providers.amazon-bedrock.aws.region",
757 757 type: "string",
758`boolean`758 description: "AWS region used by the built-in `amazon-bedrock` provider.",
759 759 },
760Details760 {
761 761 key: "model_reasoning_effort",
762Enable the default `shell` tool for running commands (stable; on by default).762 type: "minimal | low | medium | high | xhigh",
763 763 description:
764Key764 "Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).",
765 765 },
766`features.skill_mcp_dependency_install`766 {
767 767 key: "plan_mode_reasoning_effort",
768Type / Values768 type: "none | minimal | low | medium | high | xhigh",
769 769 description:
770`boolean`770 "Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default.",
771 771 },
772Details772 {
773 773 key: "model_reasoning_summary",
774Allow prompting and installing missing MCP dependencies for skills (stable; on by default).774 type: "auto | concise | detailed | none",
775 775 description:
776Key776 "Select reasoning summary detail or disable summaries entirely.",
777 777 },
778`features.smart_approvals`778 {
779 779 key: "model_verbosity",
780Type / Values780 type: "low | medium | high",
781 781 description:
782`boolean`782 "Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.",
783 783 },
784Details784 {
785 785 key: "model_supports_reasoning_summaries",
786Route eligible approval requests through the guardian reviewer subagent (experimental; off by default).786 type: "boolean",
787 787 description: "Force Codex to send or not send reasoning metadata.",
788Key788 },
789 789 {
790`features.undo`790 key: "shell_environment_policy.inherit",
791 791 type: "all | core | none",
792Type / Values792 description:
793 793 "Baseline environment inheritance when spawning subprocesses.",
794`boolean`794 },
795 795 {
796Details796 key: "shell_environment_policy.ignore_default_excludes",
797 797 type: "boolean",
798Enable undo support (stable; off by default).798 description:
799 799 "Keep variables containing KEY/SECRET/TOKEN before other filters run.",
800Key800 },
801 801 {
802`features.unified_exec`802 key: "shell_environment_policy.exclude",
803 803 type: "array<string>",
804Type / Values804 description:
805 805 "Glob patterns for removing environment variables after the defaults.",
806`boolean`806 },
807 807 {
808Details808 key: "shell_environment_policy.include_only",
809 809 type: "array<string>",
810Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).810 description:
811 811 "Whitelist of patterns; when set only matching variables are kept.",
812Key812 },
813 813 {
814`features.web_search`814 key: "shell_environment_policy.set",
815 815 type: "map<string,string>",
816Type / Values816 description:
817 817 "Explicit environment overrides injected into every subprocess.",
818`boolean`818 },
819 819 {
820Details820 key: "shell_environment_policy.experimental_use_profile",
821 821 type: "boolean",
822Deprecated legacy toggle; prefer the top-level `web_search` setting.822 description: "Use the user shell profile when spawning subprocesses.",
823 823 },
824Key824 {
825 825 key: "project_root_markers",
826`features.web_search_cached`826 type: "array<string>",
827 827 description:
828Type / Values828 "List of project root marker filenames; used when searching parent directories for the project root.",
829 829 },
830`boolean`830 {
831 831 key: "project_doc_max_bytes",
832Details832 type: "number",
833 833 description:
834Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.834 "Maximum bytes read from `AGENTS.md` when building project instructions.",
835 835 },
836Key836 {
837 837 key: "project_doc_fallback_filenames",
838`features.web_search_request`838 type: "array<string>",
839 839 description: "Additional filenames to try when `AGENTS.md` is missing.",
840Type / Values840 },
841 841 {
842`boolean`842 key: "profile",
843 843 type: "string",
844Details844 description:
845 845 "Default profile applied at startup (equivalent to `--profile`).",
846Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.846 },
847 847 {
848Key848 key: "profiles.<name>.*",
849 849 type: "various",
850`feedback.enabled`850 description:
851 851 "Profile-scoped overrides for any of the supported configuration keys.",
852Type / Values852 },
853 853 {
854`boolean`854 key: "profiles.<name>.service_tier",
855 855 type: "flex | fast",
856Details856 description: "Profile-scoped service tier preference for new turns.",
857 857 },
858Enable feedback submission via `/feedback` across Codex surfaces (default: true).858 {
859 859 key: "profiles.<name>.plan_mode_reasoning_effort",
860Key860 type: "none | minimal | low | medium | high | xhigh",
861 861 description: "Profile-scoped Plan-mode reasoning override.",
862`file_opener`862 },
863 863 {
864Type / Values864 key: "profiles.<name>.web_search",
865 865 type: "disabled | cached | live",
866`vscode | vscode-insiders | windsurf | cursor | none`866 description:
867 867 'Profile-scoped web search mode override (default: `"cached"`).',
868Details868 },
869 869 {
870URI scheme used to open citations from Codex output (default: `vscode`).870 key: "profiles.<name>.personality",
871 871 type: "none | friendly | pragmatic",
872Key872 description:
873 873 "Profile-scoped communication style override for supported models.",
874`forced_chatgpt_workspace_id`874 },
875 875 {
876Type / Values876 key: "profiles.<name>.model_catalog_json",
877 877 type: "string (path)",
878`string (uuid)`878 description:
879 879 "Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).",
880Details880 },
881 881 {
882Limit ChatGPT logins to a specific workspace identifier.882 key: "profiles.<name>.model_instructions_file",
883 883 type: "string (path)",
884Key884 description:
885 885 "Profile-scoped replacement for the built-in instruction file.",
886`forced_login_method`886 },
887 887 {
888Type / Values888 key: "profiles.<name>.experimental_use_unified_exec_tool",
889 889 type: "boolean",
890`chatgpt | api`890 description:
891 891 "Legacy name for enabling unified exec; prefer `[features].unified_exec`.",
892Details892 },
893 893 {
894Restrict Codex to a specific authentication method.894 key: "profiles.<name>.oss_provider",
895 895 type: "lmstudio | ollama",
896Key896 description: "Profile-scoped OSS provider for `--oss` sessions.",
897 897 },
898`hide_agent_reasoning`898 {
899 899 key: "profiles.<name>.tools_view_image",
900Type / Values900 type: "boolean",
901 901 description: "Enable or disable the `view_image` tool in that profile.",
902`boolean`902 },
903 903 {
904Details904 key: "profiles.<name>.analytics.enabled",
905 905 type: "boolean",
906Suppress reasoning events in both the TUI and `codex exec` output.906 description: "Profile-scoped analytics enablement override.",
907 907 },
908Key908 {
909 909 key: "profiles.<name>.windows.sandbox",
910`history.max_bytes`910 type: "unelevated | elevated",
911 911 description: "Profile-scoped Windows sandbox mode override.",
912Type / Values912 },
913 913 {
914`number`914 key: "history.persistence",
915 915 type: "save-all | none",
916Details916 description:
917 917 "Control whether Codex saves session transcripts to history.jsonl.",
918If set, caps the history file size in bytes by dropping oldest entries.918 },
919 919 {
920Key920 key: "tool_output_token_limit",
921 921 type: "number",
922`history.persistence`922 description:
923 923 "Token budget for storing individual tool/function outputs in history.",
924Type / Values924 },
925 925 {
926`save-all | none`926 key: "background_terminal_max_timeout",
927 927 type: "number",
928Details928 description:
929 929 "Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.",
930Control whether Codex saves session transcripts to history.jsonl.930 },
931 931 {
932Key932 key: "history.max_bytes",
933 933 type: "number",
934`instructions`934 description:
935 935 "If set, caps the history file size in bytes by dropping oldest entries.",
936Type / Values936 },
937 937 {
938`string`938 key: "file_opener",
939 939 type: "vscode | vscode-insiders | windsurf | cursor | none",
940Details940 description:
941 941 "URI scheme used to open citations from Codex output (default: `vscode`).",
942Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.942 },
943 943 {
944Key944 key: "otel.environment",
945 945 type: "string",
946`log_dir`946 description:
947 947 "Environment tag applied to emitted OpenTelemetry events (default: `dev`).",
948Type / Values948 },
949 949 {
950`string (path)`950 key: "otel.exporter",
951 951 type: "none | otlp-http | otlp-grpc",
952Details952 description:
953 953 "Select the OpenTelemetry exporter and provide any endpoint metadata.",
954Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.954 },
955 955 {
956Key956 key: "otel.trace_exporter",
957 957 type: "none | otlp-http | otlp-grpc",
958`mcp_oauth_callback_port`958 description:
959 959 "Select the OpenTelemetry trace exporter and provide any endpoint metadata.",
960Type / Values960 },
961 961 {
962`integer`962 key: "otel.metrics_exporter",
963 963 type: "none | statsig | otlp-http | otlp-grpc",
964Details964 description:
965 965 "Select the OpenTelemetry metrics exporter (defaults to `statsig`).",
966Optional 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.966 },
967 967 {
968Key968 key: "otel.log_user_prompt",
969 969 type: "boolean",
970`mcp_oauth_callback_url`970 description:
971 971 "Opt in to exporting raw user prompts with OpenTelemetry logs.",
972Type / Values972 },
973 973 {
974`string`974 key: "otel.exporter.<id>.endpoint",
975 975 type: "string",
976Details976 description: "Exporter endpoint for OTEL logs.",
977 977 },
978Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.978 {
979 979 key: "otel.exporter.<id>.protocol",
980Key980 type: "binary | json",
981 981 description: "Protocol used by the OTLP/HTTP exporter.",
982`mcp_oauth_credentials_store`982 },
983 983 {
984Type / Values984 key: "otel.exporter.<id>.headers",
985 985 type: "map<string,string>",
986`auto | file | keyring`986 description: "Static headers included with OTEL exporter requests.",
987 987 },
988Details988 {
989 989 key: "otel.trace_exporter.<id>.endpoint",
990Preferred store for MCP OAuth credentials.990 type: "string",
991 991 description: "Trace exporter endpoint for OTEL logs.",
992Key992 },
993 993 {
994`mcp_servers.<id>.args`994 key: "otel.trace_exporter.<id>.protocol",
995 995 type: "binary | json",
996Type / Values996 description: "Protocol used by the OTLP/HTTP trace exporter.",
997 997 },
998`array<string>`998 {
999 999 key: "otel.trace_exporter.<id>.headers",
1000Details1000 type: "map<string,string>",
1001 1001 description: "Static headers included with OTEL trace exporter requests.",
1002Arguments passed to the MCP stdio server command.1002 },
1003 1003 {
1004Key1004 key: "otel.exporter.<id>.tls.ca-certificate",
1005 1005 type: "string",
1006`mcp_servers.<id>.bearer_token_env_var`1006 description: "CA certificate path for OTEL exporter TLS.",
1007 1007 },
1008Type / Values1008 {
1009 1009 key: "otel.exporter.<id>.tls.client-certificate",
1010`string`1010 type: "string",
1011 1011 description: "Client certificate path for OTEL exporter TLS.",
1012Details1012 },
1013 1013 {
1014Environment variable sourcing the bearer token for an MCP HTTP server.1014 key: "otel.exporter.<id>.tls.client-private-key",
1015 1015 type: "string",
1016Key1016 description: "Client private key path for OTEL exporter TLS.",
1017 1017 },
1018`mcp_servers.<id>.command`1018 {
1019 1019 key: "otel.trace_exporter.<id>.tls.ca-certificate",
1020Type / Values1020 type: "string",
1021 1021 description: "CA certificate path for OTEL trace exporter TLS.",
1022`string`1022 },
1023 1023 {
1024Details1024 key: "otel.trace_exporter.<id>.tls.client-certificate",
1025 1025 type: "string",
1026Launcher command for an MCP stdio server.1026 description: "Client certificate path for OTEL trace exporter TLS.",
1027 1027 },
1028Key1028 {
1029 1029 key: "otel.trace_exporter.<id>.tls.client-private-key",
1030`mcp_servers.<id>.cwd`1030 type: "string",
1031 1031 description: "Client private key path for OTEL trace exporter TLS.",
1032Type / Values1032 },
1033 1033 {
1034`string`1034 key: "tui",
1035 1035 type: "table",
1036Details1036 description:
1037 1037 "TUI-specific options such as enabling inline desktop notifications.",
1038Working directory for the MCP stdio server process.1038 },
1039 1039 {
1040Key1040 key: "tui.notifications",
1041 1041 type: "boolean | array<string>",
1042`mcp_servers.<id>.disabled_tools`1042 description:
1043 1043 "Enable TUI notifications; optionally restrict to specific event types.",
1044Type / Values1044 },
1045 1045 {
1046`array<string>`1046 key: "tui.notification_method",
1047 1047 type: "auto | osc9 | bel",
1048Details1048 description:
1049 1049 "Notification method for terminal notifications (default: auto).",
1050Deny list applied after `enabled_tools` for the MCP server.1050 },
1051 1051 {
1052Key1052 key: "tui.notification_condition",
1053 1053 type: "unfocused | always",
1054`mcp_servers.<id>.enabled`1054 description:
1055 1055 "Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`.",
1056Type / Values1056 },
1057 1057 {
1058`boolean`1058 key: "tui.animations",
1059 1059 type: "boolean",
1060Details1060 description:
1061 1061 "Enable terminal animations (welcome screen, shimmer, spinner) (default: true).",
1062Disable an MCP server without removing its configuration.1062 },
1063 1063 {
1064Key1064 key: "tui.alternate_screen",
1065 1065 type: "auto | always | never",
1066`mcp_servers.<id>.enabled_tools`1066 description:
1067 1067 "Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).",
1068Type / Values1068 },
1069 1069 {
1070`array<string>`1070 key: "tui.show_tooltips",
1071 1071 type: "boolean",
1072Details1072 description:
1073 1073 "Show onboarding tooltips in the TUI welcome screen (default: true).",
1074Allow list of tool names exposed by the MCP server.1074 },
1075 1075 {
1076Key1076 key: "tui.status_line",
1077 1077 type: "array<string> | null",
1078`mcp_servers.<id>.env`1078 description:
1079 1079 "Ordered list of TUI footer status-line item identifiers. `null` disables the status line.",
1080Type / Values1080 },
1081 1081 {
1082`map<string,string>`1082 key: "tui.terminal_title",
1083 1083 type: "array<string> | null",
1084Details1084 description:
1085 1085 'Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates.',
1086Environment variables forwarded to the MCP stdio server.1086 },
1087 1087 {
1088Key1088 key: "tui.theme",
1089 1089 type: "string",
1090`mcp_servers.<id>.env_http_headers`1090 description:
1091 1091 "Syntax-highlighting theme override (kebab-case theme name).",
1092Type / Values1092 },
1093 1093 {
1094`map<string,string>`1094 key: "tui.keymap.<context>.<action>",
1095 1095 type: "string | array<string>",
1096Details1096 description:
1097 1097 "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`.",
1098HTTP headers populated from environment variables for an MCP HTTP server.1098 },
1099 1099 {
1100Key1100 key: "tui.keymap.<context>.<action> = []",
1101 1101 type: "empty array",
1102`mcp_servers.<id>.env_vars`1102 description:
1103 1103 "Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, or `page-down`.",
1104Type / Values1104 },
1105 1105 {
1106`array<string>`1106 key: "tui.model_availability_nux.<model>",
1107 1107 type: "integer",
1108Details1108 description: "Internal startup-tooltip state keyed by model slug.",
1109 1109 },
1110Additional environment variables to whitelist for an MCP stdio server.1110 {
1111 1111 key: "hide_agent_reasoning",
1112Key1112 type: "boolean",
1113 1113 description:
1114`mcp_servers.<id>.http_headers`1114 "Suppress reasoning events in both the TUI and `codex exec` output.",
1115 1115 },
1116Type / Values1116 {
1117 1117 key: "show_raw_agent_reasoning",
1118`map<string,string>`1118 type: "boolean",
1119 1119 description:
1120Details1120 "Surface raw reasoning content when the active model emits it.",
1121 1121 },
1122Static HTTP headers included with each MCP HTTP request.1122 {
1123 1123 key: "disable_paste_burst",
1124Key1124 type: "boolean",
1125 1125 description: "Disable burst-paste detection in the TUI.",
1126`mcp_servers.<id>.oauth_resource`1126 },
1127 1127 {
1128Type / Values1128 key: "windows_wsl_setup_acknowledged",
1129 1129 type: "boolean",
1130`string`1130 description: "Track Windows onboarding acknowledgement (Windows only).",
1131 1131 },
1132Details1132 {
1133 1133 key: "chatgpt_base_url",
1134Optional RFC 8707 OAuth resource parameter to include during MCP login.1134 type: "string",
1135 1135 description: "Override the base URL used during the ChatGPT login flow.",
1136Key1136 },
1137 1137 {
1138`mcp_servers.<id>.required`1138 key: "cli_auth_credentials_store",
1139 1139 type: "file | keyring | auto",
1140Type / Values1140 description:
1141 1141 "Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).",
1142`boolean`1142 },
1143 1143 {
1144Details1144 key: "mcp_oauth_credentials_store",
1145 1145 type: "auto | file | keyring",
1146When true, fail startup/resume if this enabled MCP server cannot initialize.1146 description: "Preferred store for MCP OAuth credentials.",
1147 1147 },
1148Key1148 {
1149 1149 key: "mcp_oauth_callback_port",
1150`mcp_servers.<id>.scopes`1150 type: "integer",
1151 1151 description:
1152Type / Values1152 "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.",
1153 1153 },
1154`array<string>`1154 {
1155 1155 key: "mcp_oauth_callback_url",
1156Details1156 type: "string",
1157 1157 description:
1158OAuth scopes to request when authenticating to that MCP server.1158 "Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.",
1159 1159 },
1160Key1160 {
1161 1161 key: "experimental_use_unified_exec_tool",
1162`mcp_servers.<id>.startup_timeout_ms`1162 type: "boolean",
1163 1163 description:
1164Type / Values1164 "Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.",
1165 1165 },
1166`number`1166 {
1167 1167 key: "tools.web_search",
1168Details1168 type: 'boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }',
1169 1169 description:
1170Alias for `startup_timeout_sec` in milliseconds.1170 "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.",
1171 1171 },
1172Key1172 {
1173 1173 key: "tools.view_image",
1174`mcp_servers.<id>.startup_timeout_sec`1174 type: "boolean",
1175 1175 description: "Enable the local-image attachment tool `view_image`.",
1176Type / Values1176 },
1177 1177 {
1178`number`1178 key: "web_search",
1179 1179 type: "disabled | cached | live",
1180Details1180 description:
1181 1181 '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.',
1182Override the default 10s startup timeout for an MCP server.1182 },
1183 1183 {
1184Key1184 key: "default_permissions",
1185 1185 type: "string",
1186`mcp_servers.<id>.tool_timeout_sec`1186 description:
1187 1187 "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.<name>]` tables.",
1188Type / Values1188 },
1189 1189 {
1190`number`1190 key: "permissions.<name>.filesystem",
1191 1191 type: "table",
1192Details1192 description:
1193 1193 "Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.",
1194Override the default 60s per-tool timeout for an MCP server.1194 },
1195 1195 {
1196Key1196 key: "permissions.<name>.filesystem.glob_scan_max_depth",
1197 1197 type: "number",
1198`mcp_servers.<id>.url`1198 description:
1199 1199 "Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set.",
1200Type / Values1200 },
1201 1201 {
1202`string`1202 key: "permissions.<name>.filesystem.<path-or-glob>",
1203 1203 type: '"read" | "write" | "none" | table',
1204Details1204 description:
1205 1205 '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.',
1206Endpoint for an MCP streamable HTTP server.1206 },
1207 1207 {
1208Key1208 key: 'permissions.<name>.filesystem.":project_roots".<subpath-or-glob>',
1209 1209 type: '"read" | "write" | "none"',
1210`model`1210 description:
1211 1211 'Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`.',
1212Type / Values1212 },
1213 1213 {
1214`string`1214 key: "permissions.<name>.network.enabled",
1215 1215 type: "boolean",
1216Details1216 description: "Enable network access for this named permissions profile.",
1217 1217 },
1218Model to use (e.g., `gpt-5.4`).1218 {
1219 1219 key: "permissions.<name>.network.proxy_url",
1220Key1220 type: "string",
1221 1221 description:
1222`model_auto_compact_token_limit`1222 "HTTP proxy endpoint used when this permissions profile enables the managed network proxy.",
1223 1223 },
1224Type / Values1224 {
1225 1225 key: "permissions.<name>.network.enable_socks5",
1226`number`1226 type: "boolean",
1227 1227 description:
1228Details1228 "Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.",
1229 1229 },
1230Token threshold that triggers automatic history compaction (unset uses model defaults).1230 {
1231 1231 key: "permissions.<name>.network.socks_url",
1232Key1232 type: "string",
1233 1233 description: "SOCKS5 proxy endpoint used by this permissions profile.",
1234`model_catalog_json`1234 },
1235 1235 {
1236Type / Values1236 key: "permissions.<name>.network.enable_socks5_udp",
1237 1237 type: "boolean",
1238`string (path)`1238 description: "Allow UDP over the SOCKS5 listener when enabled.",
1239 1239 },
1240Details1240 {
1241 1241 key: "permissions.<name>.network.allow_upstream_proxy",
1242Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.1242 type: "boolean",
1243 1243 description:
1244Key1244 "Allow the managed proxy to chain to another upstream proxy.",
1245 1245 },
1246`model_context_window`1246 {
1247 1247 key: "permissions.<name>.network.dangerously_allow_non_loopback_proxy",
1248Type / Values1248 type: "boolean",
1249 1249 description:
1250`number`1250 "Permit non-loopback bind addresses for the managed proxy listener.",
1251 1251 },
1252Details1252 {
1253 1253 key: "permissions.<name>.network.dangerously_allow_all_unix_sockets",
1254Context window tokens available to the active model.1254 type: "boolean",
1255 1255 description:
1256Key1256 "Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.",
1257 1257 },
1258`model_instructions_file`1258 {
1259 1259 key: "permissions.<name>.network.mode",
1260Type / Values1260 type: "limited | full",
1261 1261 description: "Network proxy mode used for subprocess traffic.",
1262`string (path)`1262 },
1263 1263 {
1264Details1264 key: "permissions.<name>.network.domains",
1265 1265 type: "map<string, allow | deny>",
1266Replacement for built-in instructions instead of `AGENTS.md`.1266 description:
1267 1267 "Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values.",
1268Key1268 },
1269 1269 {
1270`model_provider`1270 key: "permissions.<name>.network.unix_sockets",
1271 1271 type: "map<string, allow | none>",
1272Type / Values1272 description:
1273 1273 "Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values.",
1274`string`1274 },
1275 1275 {
1276Details1276 key: "permissions.<name>.network.allow_local_binding",
1277 1277 type: "boolean",
1278Provider id from `model_providers` (default: `openai`).1278 description:
1279 1279 "Permit local bind/listen operations through the managed proxy.",
1280Key1280 },
1281 1281 {
1282`model_providers.<id>`1282 key: "projects.<path>.trust_level",
1283 1283 type: "string",
1284Type / Values1284 description:
1285 1285 '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.',
1286`table`1286 },
1287 1287 {
1288Details1288 key: "notice.hide_full_access_warning",
1289 1289 type: "boolean",
1290Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.1290 description: "Track acknowledgement of the full access warning prompt.",
1291 1291 },
1292Key1292 {
1293 1293 key: "notice.hide_world_writable_warning",
1294`model_providers.<id>.auth`1294 type: "boolean",
1295 1295 description:
1296Type / Values1296 "Track acknowledgement of the Windows world-writable directories warning.",
1297 1297 },
1298`table`1298 {
1299 1299 key: "notice.hide_rate_limit_model_nudge",
1300Details1300 type: "boolean",
1301 1301 description: "Track opt-out of the rate limit model switch reminder.",
1302Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.1302 },
1303 1303 {
1304Key1304 key: "notice.hide_gpt5_1_migration_prompt",
1305 1305 type: "boolean",
1306`model_providers.<id>.auth.args`1306 description: "Track acknowledgement of the GPT-5.1 migration prompt.",
1307 1307 },
1308Type / Values1308 {
1309 1309 key: "notice.hide_gpt-5.1-codex-max_migration_prompt",
1310`array<string>`1310 type: "boolean",
1311 1311 description:
1312Details1312 "Track acknowledgement of the gpt-5.1-codex-max migration prompt.",
1313 1313 },
1314Arguments passed to the token command.1314 {
1315 1315 key: "notice.model_migrations",
1316Key1316 type: "map<string,string>",
1317 1317 description: "Track acknowledged model migrations as old->new mappings.",
1318`model_providers.<id>.auth.command`1318 },
1319 1319 {
1320Type / Values1320 key: "forced_login_method",
1321 1321 type: "chatgpt | api",
1322`string`1322 description: "Restrict Codex to a specific authentication method.",
1323 1323 },
1324Details1324 {
1325 1325 key: "forced_chatgpt_workspace_id",
1326Command to run when Codex needs a bearer token. The command must print the token to stdout.1326 type: "string (uuid)",
1327 1327 description: "Limit ChatGPT logins to a specific workspace identifier.",
1328Key1328 },
1329 1329 ]}
1330`model_providers.<id>.auth.cwd`1330 client:load
1331 1331/>
1332Type / Values
1333
1334`string (path)`
1335
1336Details
1337
1338Working directory for the token command.
1339
1340Key
1341
1342`model_providers.<id>.auth.refresh_interval_ms`
1343
1344Type / Values
1345
1346`number`
1347
1348Details
1349
1350How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.
1351
1352Key
1353
1354`model_providers.<id>.auth.timeout_ms`
1355
1356Type / Values
1357
1358`number`
1359
1360Details
1361
1362Maximum token command runtime in milliseconds (default: 5000).
1363
1364Key
1365
1366`model_providers.<id>.base_url`
1367
1368Type / Values
1369
1370`string`
1371
1372Details
1373
1374API base URL for the model provider.
1375
1376Key
1377
1378`model_providers.<id>.env_http_headers`
1379
1380Type / Values
1381
1382`map<string,string>`
1383
1384Details
1385
1386HTTP headers populated from environment variables when present.
1387
1388Key
1389
1390`model_providers.<id>.env_key`
1391
1392Type / Values
1393
1394`string`
1395
1396Details
1397
1398Environment variable supplying the provider API key.
1399
1400Key
1401
1402`model_providers.<id>.env_key_instructions`
1403
1404Type / Values
1405
1406`string`
1407
1408Details
1409
1410Optional setup guidance for the provider API key.
1411
1412Key
1413
1414`model_providers.<id>.experimental_bearer_token`
1415
1416Type / Values
1417
1418`string`
1419
1420Details
1421
1422Direct bearer token for the provider (discouraged; use `env_key`).
1423
1424Key
1425
1426`model_providers.<id>.http_headers`
1427
1428Type / Values
1429
1430`map<string,string>`
1431
1432Details
1433
1434Static HTTP headers added to provider requests.
1435
1436Key
1437
1438`model_providers.<id>.name`
1439
1440Type / Values
1441
1442`string`
1443
1444Details
1445
1446Display name for a custom model provider.
1447
1448Key
1449
1450`model_providers.<id>.query_params`
1451
1452Type / Values
1453
1454`map<string,string>`
1455
1456Details
1457
1458Extra query parameters appended to provider requests.
1459
1460Key
1461
1462`model_providers.<id>.request_max_retries`
1463
1464Type / Values
1465
1466`number`
1467
1468Details
1469
1470Retry count for HTTP requests to the provider (default: 4).
1471
1472Key
1473
1474`model_providers.<id>.requires_openai_auth`
1475
1476Type / Values
1477
1478`boolean`
1479
1480Details
1481
1482The provider uses OpenAI authentication (defaults to false).
1483
1484Key
1485
1486`model_providers.<id>.stream_idle_timeout_ms`
1487
1488Type / Values
1489
1490`number`
1491
1492Details
1493
1494Idle timeout for SSE streams in milliseconds (default: 300000).
1495
1496Key
1497
1498`model_providers.<id>.stream_max_retries`
1499
1500Type / Values
1501
1502`number`
1503
1504Details
1505
1506Retry count for SSE streaming interruptions (default: 5).
1507
1508Key
1509
1510`model_providers.<id>.supports_websockets`
1511
1512Type / Values
1513
1514`boolean`
1515
1516Details
1517
1518Whether that provider supports the Responses API WebSocket transport.
1519
1520Key
1521
1522`model_providers.<id>.wire_api`
1523
1524Type / Values
1525
1526`responses`
1527
1528Details
1529
1530Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.
1531
1532Key
1533
1534`model_reasoning_effort`
1535
1536Type / Values
1537
1538`minimal | low | medium | high | xhigh`
1539
1540Details
1541
1542Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).
1543
1544Key
1545
1546`model_reasoning_summary`
1547
1548Type / Values
1549
1550`auto | concise | detailed | none`
1551
1552Details
1553
1554Select reasoning summary detail or disable summaries entirely.
1555
1556Key
1557
1558`model_supports_reasoning_summaries`
1559
1560Type / Values
1561
1562`boolean`
1563
1564Details
1565
1566Force Codex to send or not send reasoning metadata.
1567
1568Key
1569
1570`model_verbosity`
1571
1572Type / Values
1573
1574`low | medium | high`
1575
1576Details
1577
1578Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.
1579
1580Key
1581
1582`notice.hide_full_access_warning`
1583
1584Type / Values
1585
1586`boolean`
1587
1588Details
1589
1590Track acknowledgement of the full access warning prompt.
1591
1592Key
1593
1594`notice.hide_gpt-5.1-codex-max_migration_prompt`
1595
1596Type / Values
1597
1598`boolean`
1599
1600Details
1601
1602Track acknowledgement of the gpt-5.1-codex-max migration prompt.
1603
1604Key
1605
1606`notice.hide_gpt5_1_migration_prompt`
1607
1608Type / Values
1609
1610`boolean`
1611
1612Details
1613
1614Track acknowledgement of the GPT-5.1 migration prompt.
1615
1616Key
1617
1618`notice.hide_rate_limit_model_nudge`
1619
1620Type / Values
1621
1622`boolean`
1623
1624Details
1625
1626Track opt-out of the rate limit model switch reminder.
1627
1628Key
1629
1630`notice.hide_world_writable_warning`
1631
1632Type / Values
1633
1634`boolean`
1635
1636Details
1637
1638Track acknowledgement of the Windows world-writable directories warning.
1639
1640Key
1641
1642`notice.model_migrations`
1643
1644Type / Values
1645
1646`map<string,string>`
1647
1648Details
1649
1650Track acknowledged model migrations as old->new mappings.
1651
1652Key
1653
1654`notify`
1655
1656Type / Values
1657
1658`array<string>`
1659
1660Details
1661
1662Command invoked for notifications; receives a JSON payload from Codex.
1663
1664Key
1665
1666`openai_base_url`
1667
1668Type / Values
1669
1670`string`
1671
1672Details
1673
1674Base URL override for the built-in `openai` model provider.
1675
1676Key
1677
1678`oss_provider`
1679
1680Type / Values
1681
1682`lmstudio | ollama`
1683
1684Details
1685
1686Default local provider used when running with `--oss` (defaults to prompting if unset).
1687
1688Key
1689
1690`otel.environment`
1691
1692Type / Values
1693
1694`string`
1695
1696Details
1697
1698Environment tag applied to emitted OpenTelemetry events (default: `dev`).
1699
1700Key
1701
1702`otel.exporter`
1703
1704Type / Values
1705
1706`none | otlp-http | otlp-grpc`
1707
1708Details
1709
1710Select the OpenTelemetry exporter and provide any endpoint metadata.
1711
1712Key
1713
1714`otel.exporter.<id>.endpoint`
1715
1716Type / Values
1717
1718`string`
1719
1720Details
1721
1722Exporter endpoint for OTEL logs.
1723
1724Key
1725
1726`otel.exporter.<id>.headers`
1727
1728Type / Values
1729
1730`map<string,string>`
1731
1732Details
1733
1734Static headers included with OTEL exporter requests.
1735
1736Key
1737
1738`otel.exporter.<id>.protocol`
1739
1740Type / Values
1741
1742`binary | json`
1743
1744Details
1745
1746Protocol used by the OTLP/HTTP exporter.
1747
1748Key
1749
1750`otel.exporter.<id>.tls.ca-certificate`
1751
1752Type / Values
1753
1754`string`
1755
1756Details
1757
1758CA certificate path for OTEL exporter TLS.
1759
1760Key
1761
1762`otel.exporter.<id>.tls.client-certificate`
1763
1764Type / Values
1765
1766`string`
1767
1768Details
1769
1770Client certificate path for OTEL exporter TLS.
1771
1772Key
1773
1774`otel.exporter.<id>.tls.client-private-key`
1775
1776Type / Values
1777
1778`string`
1779
1780Details
1781
1782Client private key path for OTEL exporter TLS.
1783
1784Key
1785
1786`otel.log_user_prompt`
1787
1788Type / Values
1789
1790`boolean`
1791
1792Details
1793
1794Opt in to exporting raw user prompts with OpenTelemetry logs.
1795
1796Key
1797
1798`otel.metrics_exporter`
1799
1800Type / Values
1801
1802`none | statsig | otlp-http | otlp-grpc`
1803
1804Details
1805
1806Select the OpenTelemetry metrics exporter (defaults to `statsig`).
1807
1808Key
1809
1810`otel.trace_exporter`
1811
1812Type / Values
1813
1814`none | otlp-http | otlp-grpc`
1815
1816Details
1817
1818Select the OpenTelemetry trace exporter and provide any endpoint metadata.
1819
1820Key
1821
1822`otel.trace_exporter.<id>.endpoint`
1823
1824Type / Values
1825
1826`string`
1827
1828Details
1829
1830Trace exporter endpoint for OTEL logs.
1831
1832Key
1833
1834`otel.trace_exporter.<id>.headers`
1835
1836Type / Values
1837
1838`map<string,string>`
1839
1840Details
1841
1842Static headers included with OTEL trace exporter requests.
1843
1844Key
1845
1846`otel.trace_exporter.<id>.protocol`
1847
1848Type / Values
1849
1850`binary | json`
1851
1852Details
1853
1854Protocol used by the OTLP/HTTP trace exporter.
1855
1856Key
1857
1858`otel.trace_exporter.<id>.tls.ca-certificate`
1859
1860Type / Values
1861
1862`string`
1863
1864Details
1865
1866CA certificate path for OTEL trace exporter TLS.
1867
1868Key
1869
1870`otel.trace_exporter.<id>.tls.client-certificate`
1871
1872Type / Values
1873
1874`string`
1875
1876Details
1877
1878Client certificate path for OTEL trace exporter TLS.
1879
1880Key
1881
1882`otel.trace_exporter.<id>.tls.client-private-key`
1883
1884Type / Values
1885
1886`string`
1887
1888Details
1889
1890Client private key path for OTEL trace exporter TLS.
1891
1892Key
1893
1894`permissions.<name>.filesystem`
1895
1896Type / Values
1897
1898`table`
1899
1900Details
1901
1902Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.
1903
1904Key
1905
1906`permissions.<name>.filesystem.":project_roots".<subpath>`
1907
1908Type / Values
1909
1910`"read" | "write" | "none"`
1911
1912Details
1913
1914Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself.
1915
1916Key
1917
1918`permissions.<name>.filesystem.<path>`
1919
1920Type / Values
1921
1922`"read" | "write" | "none" | table`
1923
1924Details
1925
1926Grant direct access for a path or special token, or scope nested entries under that root.
1927
1928Key
1929
1930`permissions.<name>.network.allow_local_binding`
1931
1932Type / Values
1933
1934`boolean`
1935
1936Details
1937
1938Permit local bind/listen operations through the managed proxy.
1939
1940Key
1941
1942`permissions.<name>.network.allow_upstream_proxy`
1943
1944Type / Values
1945
1946`boolean`
1947
1948Details
1949
1950Allow the managed proxy to chain to another upstream proxy.
1951
1952Key
1953
1954`permissions.<name>.network.dangerously_allow_all_unix_sockets`
1955
1956Type / Values
1957
1958`boolean`
1959
1960Details
1961
1962Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.
1963
1964Key
1965
1966`permissions.<name>.network.dangerously_allow_non_loopback_proxy`
1967
1968Type / Values
1969
1970`boolean`
1971
1972Details
1973
1974Permit non-loopback bind addresses for the managed proxy listener.
1975
1976Key
1977
1978`permissions.<name>.network.domains`
1979
1980Type / Values
1981
1982`map<string, allow | deny>`
1983
1984Details
1985
1986Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values.
1987
1988Key
1989
1990`permissions.<name>.network.enable_socks5`
1991
1992Type / Values
1993
1994`boolean`
1995
1996Details
1997
1998Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.
1999
2000Key
2001
2002`permissions.<name>.network.enable_socks5_udp`
2003
2004Type / Values
2005
2006`boolean`
2007
2008Details
2009
2010Allow UDP over the SOCKS5 listener when enabled.
2011
2012Key
2013
2014`permissions.<name>.network.enabled`
2015
2016Type / Values
2017
2018`boolean`
2019
2020Details
2021
2022Enable network access for this named permissions profile.
2023
2024Key
2025
2026`permissions.<name>.network.mode`
2027
2028Type / Values
2029
2030`limited | full`
2031
2032Details
2033
2034Network proxy mode used for subprocess traffic.
2035
2036Key
2037
2038`permissions.<name>.network.proxy_url`
2039
2040Type / Values
2041
2042`string`
2043
2044Details
2045
2046HTTP proxy endpoint used when this permissions profile enables the managed network proxy.
2047
2048Key
2049
2050`permissions.<name>.network.socks_url`
2051
2052Type / Values
2053
2054`string`
2055
2056Details
2057
2058SOCKS5 proxy endpoint used by this permissions profile.
2059
2060Key
2061
2062`permissions.<name>.network.unix_sockets`
2063
2064Type / Values
2065
2066`map<string, allow | none>`
2067
2068Details
2069
2070Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values.
2071
2072Key
2073
2074`personality`
2075
2076Type / Values
2077
2078`none | friendly | pragmatic`
2079
2080Details
2081
2082Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.
2083
2084Key
2085
2086`plan_mode_reasoning_effort`
2087
2088Type / Values
2089
2090`none | minimal | low | medium | high | xhigh`
2091
2092Details
2093
2094Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default.
2095
2096Key
2097
2098`profile`
2099
2100Type / Values
2101
2102`string`
2103
2104Details
2105
2106Default profile applied at startup (equivalent to `--profile`).
2107
2108Key
2109
2110`profiles.<name>.*`
2111
2112Type / Values
2113
2114`various`
2115
2116Details
2117
2118Profile-scoped overrides for any of the supported configuration keys.
2119
2120Key
2121
2122`profiles.<name>.analytics.enabled`
2123
2124Type / Values
2125
2126`boolean`
2127
2128Details
2129
2130Profile-scoped analytics enablement override.
2131
2132Key
2133
2134`profiles.<name>.experimental_use_unified_exec_tool`
2135
2136Type / Values
2137
2138`boolean`
2139
2140Details
2141
2142Legacy name for enabling unified exec; prefer `[features].unified_exec`.
2143
2144Key
2145
2146`profiles.<name>.model_catalog_json`
2147
2148Type / Values
2149
2150`string (path)`
2151
2152Details
2153
2154Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).
2155
2156Key
2157
2158`profiles.<name>.model_instructions_file`
2159
2160Type / Values
2161
2162`string (path)`
2163
2164Details
2165
2166Profile-scoped replacement for the built-in instruction file.
2167
2168Key
2169
2170`profiles.<name>.oss_provider`
2171
2172Type / Values
2173
2174`lmstudio | ollama`
2175
2176Details
2177
2178Profile-scoped OSS provider for `--oss` sessions.
2179
2180Key
2181
2182`profiles.<name>.personality`
2183
2184Type / Values
2185
2186`none | friendly | pragmatic`
2187
2188Details
2189
2190Profile-scoped communication style override for supported models.
2191
2192Key
2193
2194`profiles.<name>.plan_mode_reasoning_effort`
2195
2196Type / Values
2197
2198`none | minimal | low | medium | high | xhigh`
2199
2200Details
2201
2202Profile-scoped Plan-mode reasoning override.
2203
2204Key
2205
2206`profiles.<name>.service_tier`
2207
2208Type / Values
2209
2210`flex | fast`
2211
2212Details
2213
2214Profile-scoped service tier preference for new turns.
2215
2216Key
2217
2218`profiles.<name>.tools_view_image`
2219
2220Type / Values
2221
2222`boolean`
2223
2224Details
2225
2226Enable or disable the `view_image` tool in that profile.
2227
2228Key
2229
2230`profiles.<name>.web_search`
2231
2232Type / Values
2233
2234`disabled | cached | live`
2235
2236Details
2237
2238Profile-scoped web search mode override (default: `"cached"`).
2239
2240Key
2241
2242`profiles.<name>.windows.sandbox`
2243
2244Type / Values
2245
2246`unelevated | elevated`
2247
2248Details
2249
2250Profile-scoped Windows sandbox mode override.
2251
2252Key
2253
2254`project_doc_fallback_filenames`
2255
2256Type / Values
2257
2258`array<string>`
2259
2260Details
2261
2262Additional filenames to try when `AGENTS.md` is missing.
2263
2264Key
2265
2266`project_doc_max_bytes`
2267
2268Type / Values
2269
2270`number`
2271
2272Details
2273
2274Maximum bytes read from `AGENTS.md` when building project instructions.
2275
2276Key
2277
2278`project_root_markers`
2279
2280Type / Values
2281
2282`array<string>`
2283
2284Details
2285
2286List of project root marker filenames; used when searching parent directories for the project root.
2287
2288Key
2289
2290`projects.<path>.trust_level`
2291
2292Type / Values
2293
2294`string`
2295
2296Details
2297
2298Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers.
2299
2300Key
2301
2302`review_model`
2303
2304Type / Values
2305
2306`string`
2307
2308Details
2309
2310Optional model override used by `/review` (defaults to the current session model).
2311
2312Key
2313
2314`sandbox_mode`
2315
2316Type / Values
2317
2318`read-only | workspace-write | danger-full-access`
2319
2320Details
2321
2322Sandbox policy for filesystem and network access during command execution.
2323
2324Key
2325
2326`sandbox_workspace_write.exclude_slash_tmp`
2327
2328Type / Values
2329
2330`boolean`
2331
2332Details
2333
2334Exclude `/tmp` from writable roots in workspace-write mode.
2335
2336Key
2337
2338`sandbox_workspace_write.exclude_tmpdir_env_var`
2339
2340Type / Values
2341
2342`boolean`
2343
2344Details
2345
2346Exclude `$TMPDIR` from writable roots in workspace-write mode.
2347
2348Key
2349
2350`sandbox_workspace_write.network_access`
2351
2352Type / Values
2353
2354`boolean`
2355
2356Details
2357
2358Allow outbound network access inside the workspace-write sandbox.
2359
2360Key
2361
2362`sandbox_workspace_write.writable_roots`
2363
2364Type / Values
2365
2366`array<string>`
2367
2368Details
2369
2370Additional writable roots when `sandbox_mode = "workspace-write"`.
2371
2372Key
2373
2374`service_tier`
2375
2376Type / Values
2377
2378`flex | fast`
2379
2380Details
2381
2382Preferred service tier for new turns.
2383
2384Key
2385
2386`shell_environment_policy.exclude`
2387
2388Type / Values
2389
2390`array<string>`
2391
2392Details
2393
2394Glob patterns for removing environment variables after the defaults.
2395
2396Key
2397
2398`shell_environment_policy.experimental_use_profile`
2399
2400Type / Values
2401
2402`boolean`
2403
2404Details
2405
2406Use the user shell profile when spawning subprocesses.
2407
2408Key
2409
2410`shell_environment_policy.ignore_default_excludes`
2411
2412Type / Values
2413
2414`boolean`
2415
2416Details
2417
2418Keep variables containing KEY/SECRET/TOKEN before other filters run.
2419
2420Key
2421
2422`shell_environment_policy.include_only`
2423
2424Type / Values
2425
2426`array<string>`
2427
2428Details
2429
2430Whitelist of patterns; when set only matching variables are kept.
2431
2432Key
2433
2434`shell_environment_policy.inherit`
2435
2436Type / Values
2437
2438`all | core | none`
2439
2440Details
2441
2442Baseline environment inheritance when spawning subprocesses.
2443
2444Key
2445
2446`shell_environment_policy.set`
2447
2448Type / Values
2449
2450`map<string,string>`
2451
2452Details
2453
2454Explicit environment overrides injected into every subprocess.
2455
2456Key
2457
2458`show_raw_agent_reasoning`
2459
2460Type / Values
2461
2462`boolean`
2463
2464Details
2465
2466Surface raw reasoning content when the active model emits it.
2467
2468Key
2469
2470`skills.config`
2471
2472Type / Values
2473
2474`array<object>`
2475
2476Details
2477
2478Per-skill enablement overrides stored in config.toml.
2479
2480Key
2481
2482`skills.config.<index>.enabled`
2483
2484Type / Values
2485
2486`boolean`
2487
2488Details
2489
2490Enable or disable the referenced skill.
2491
2492Key
2493
2494`skills.config.<index>.path`
2495
2496Type / Values
2497
2498`string (path)`
2499
2500Details
2501
2502Path to a skill folder containing `SKILL.md`.
2503
2504Key
2505
2506`sqlite_home`
2507
2508Type / Values
2509
2510`string (path)`
2511
2512Details
2513
2514Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.
2515
2516Key
2517
2518`suppress_unstable_features_warning`
2519
2520Type / Values
2521
2522`boolean`
2523
2524Details
2525
2526Suppress the warning that appears when under-development feature flags are enabled.
2527
2528Key
2529
2530`tool_output_token_limit`
2531
2532Type / Values
2533
2534`number`
2535
2536Details
2537
2538Token budget for storing individual tool/function outputs in history.
2539
2540Key
2541
2542`tool_suggest.discoverables`
2543
2544Type / Values
2545
2546`array<table>`
2547
2548Details
2549
2550Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.
2551
2552Key
2553
2554`tools.view_image`
2555
2556Type / Values
2557
2558`boolean`
2559
2560Details
2561
2562Enable the local-image attachment tool `view_image`.
2563
2564Key
2565
2566`tools.web_search`
2567
2568Type / Values
2569
2570`boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }`
2571
2572Details
2573
2574Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location.
2575
2576Key
2577
2578`tui`
2579
2580Type / Values
2581
2582`table`
2583
2584Details
2585
2586TUI-specific options such as enabling inline desktop notifications.
2587
2588Key
2589
2590`tui.alternate_screen`
2591
2592Type / Values
2593
2594`auto | always | never`
2595
2596Details
2597
2598Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).
2599
2600Key
2601
2602`tui.animations`
2603
2604Type / Values
2605
2606`boolean`
2607
2608Details
2609
2610Enable terminal animations (welcome screen, shimmer, spinner) (default: true).
2611
2612Key
2613
2614`tui.model_availability_nux.<model>`
2615
2616Type / Values
2617
2618`integer`
2619
2620Details
2621
2622Internal startup-tooltip state keyed by model slug.
2623
2624Key
2625
2626`tui.notification_method`
2627
2628Type / Values
2629
2630`auto | osc9 | bel`
2631
2632Details
2633
2634Notification method for unfocused terminal notifications (default: auto).
2635
2636Key
2637
2638`tui.notifications`
2639
2640Type / Values
2641
2642`boolean | array<string>`
2643
2644Details
2645
2646Enable TUI notifications; optionally restrict to specific event types.
2647
2648Key
2649
2650`tui.show_tooltips`
2651
2652Type / Values
2653
2654`boolean`
2655
2656Details
2657
2658Show onboarding tooltips in the TUI welcome screen (default: true).
2659
2660Key
2661
2662`tui.status_line`
2663
2664Type / Values
2665
2666`array<string> | null`
2667
2668Details
2669
2670Ordered list of TUI footer status-line item identifiers. `null` disables the status line.
2671
2672Key
2673
2674`tui.terminal_title`
2675
2676Type / Values
2677
2678`array<string> | null`
2679
2680Details
2681
2682Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates.
2683
2684Key
2685
2686`tui.theme`
2687
2688Type / Values
2689
2690`string`
2691
2692Details
2693
2694Syntax-highlighting theme override (kebab-case theme name).
2695
2696Key
2697
2698`web_search`
2699
2700Type / Values
2701
2702`disabled | cached | live`
2703
2704Details
2705
2706Web 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.
2707
2708Key
2709
2710`windows_wsl_setup_acknowledged`
2711
2712Type / Values
2713
2714`boolean`
2715
2716Details
2717
2718Track Windows onboarding acknowledgement (Windows only).
2719
2720Key
2721
2722`windows.sandbox`
2723
2724Type / Values
2725
2726`unelevated | elevated`
2727
2728Details
2729
2730Windows-only native sandbox mode when running Codex natively on Windows.
2731
2732Key
2733
2734`windows.sandbox_private_desktop`
2735
2736Type / Values
2737
2738`boolean`
2739
2740Details
2741
2742Run the final sandboxed child process on a private desktop by default on native Windows. Set `false` only for compatibility with the older `Winsta0\\Default` behavior.
2743
2744Expand to view all
2745 1332
2746You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).1333You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).
2747 1334
2763Use `[features]` in `requirements.toml` to pin feature flags by the same1350Use `[features]` in `requirements.toml` to pin feature flags by the same
2764canonical keys that `config.toml` uses. Omitted keys remain unconstrained.1351canonical keys that `config.toml` uses. Omitted keys remain unconstrained.
2765 1352
2766| Key | Type / Values | Details |1353<ConfigTable
2767| --- | --- | --- |1354 options={[
2768| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). |1355 {
2769| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer` (for example `user` and `guardian_subagent`). |1356 key: "allowed_approval_policies",
2770| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |1357 type: "array<string>",
2771| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |1358 description:
2772| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |1359 "Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`).",
2773| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |1360 },
2774| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |1361 {
2775| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |1362 key: "allowed_approvals_reviewers",
2776| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |1363 type: "array<string>",
2777| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |1364 description:
2778| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |1365 "Allowed values for `approvals_reviewer`, such as `user` and `auto_review`.",
2779| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |1366 },
2780| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |1367 {
2781| `rules.prefix_rules[].justification` | `string` | Optional non-empty rationale surfaced in approval prompts or rejection messages. |1368 key: "guardian_policy_config",
2782| `rules.prefix_rules[].pattern` | `array<table>` | Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`. |1369 type: "string",
2783| `rules.prefix_rules[].pattern[].any_of` | `array<string>` | A list of allowed alternative tokens at this position. |1370 description:
2784| `rules.prefix_rules[].pattern[].token` | `string` | A single literal token at this position. |1371 "Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored.",
2785 1372 },
2786Key1373 {
2787 1374 key: "allowed_sandbox_modes",
2788`allowed_approval_policies`1375 type: "array<string>",
2789 1376 description: "Allowed values for `sandbox_mode`.",
2790Type / Values1377 },
2791 1378 {
2792`array<string>`1379 key: "remote_sandbox_config",
2793 1380 type: "array<table>",
2794Details1381 description:
2795 1382 "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.",
2796Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`).1383 },
2797 1384 {
2798Key1385 key: "remote_sandbox_config[].hostname_patterns",
2799 1386 type: "array<string>",
2800`allowed_approvals_reviewers`1387 description:
2801 1388 "Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character.",
2802Type / Values1389 },
2803 1390 {
2804`array<string>`1391 key: "remote_sandbox_config[].allowed_sandbox_modes",
2805 1392 type: "array<string>",
2806Details1393 description:
2807 1394 "Allowed sandbox modes to apply when this host-specific entry matches.",
2808Allowed values for `approvals_reviewer` (for example `user` and `guardian_subagent`).1395 },
2809 1396 {
2810Key1397 key: "allowed_web_search_modes",
2811 1398 type: "array<string>",
2812`allowed_sandbox_modes`1399 description:
2813 1400 "Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`.",
2814Type / Values1401 },
2815 1402 {
2816`array<string>`1403 key: "features",
2817 1404 type: "table",
2818Details1405 description:
2819 1406 "Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.",
2820Allowed values for `sandbox_mode`.1407 },
2821 1408 {
2822Key1409 key: "features.<name>",
2823 1410 type: "boolean",
2824`allowed_web_search_modes`1411 description:
2825 1412 "Require a specific canonical feature key to stay enabled or disabled.",
2826Type / Values1413 },
2827 1414 {
2828`array<string>`1415 key: "features.in_app_browser",
2829 1416 type: "boolean",
2830Details1417 description:
2831 1418 "Set to `false` in `requirements.toml` to disable the in-app browser pane.",
2832Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`.1419 },
2833 1420 {
2834Key1421 key: "features.browser_use",
2835 1422 type: "boolean",
2836`features`1423 description:
2837 1424 "Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability.",
2838Type / Values1425 },
2839 1426 {
2840`table`1427 key: "features.computer_use",
2841 1428 type: "boolean",
2842Details1429 description:
2843 1430 "Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.",
2844Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.1431 },
2845 1432 {
2846Key1433 key: "hooks",
2847 1434 type: "table",
2848`features.<name>`1435 description:
2849 1436 "Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`.",
2850Type / Values1437 },
2851 1438 {
2852`boolean`1439 key: "hooks.managed_dir",
2853 1440 type: "string (absolute path)",
2854Details1441 description:
2855 1442 "Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks.",
2856Require a specific canonical feature key to stay enabled or disabled.1443 },
2857 1444 {
2858Key1445 key: "hooks.windows_managed_dir",
2859 1446 type: "string (absolute path)",
2860`mcp_servers`1447 description:
2861 1448 "Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks.",
2862Type / Values1449 },
2863 1450 {
2864`table`1451 key: "hooks.<Event>",
2865 1452 type: "array<table>",
2866Details1453 description:
2867 1454 "Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`.",
2868Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled.1455 },
2869 1456 {
2870Key1457 key: "hooks.<Event>[].hooks",
2871 1458 type: "array<table>",
2872`mcp_servers.<id>.identity`1459 description:
2873 1460 "Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped.",
2874Type / Values1461 },
2875 1462 {
2876`table`1463 key: "permissions.filesystem.deny_read",
2877 1464 type: "array<string>",
2878Details1465 description:
2879 1466 "Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config.",
2880Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP).1467 },
2881 1468 {
2882Key1469 key: "mcp_servers",
2883 1470 type: "table",
2884`mcp_servers.<id>.identity.command`1471 description:
2885 1472 "Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled.",
2886Type / Values1473 },
2887 1474 {
2888`string`1475 key: "mcp_servers.<id>.identity",
2889 1476 type: "table",
2890Details1477 description:
2891 1478 "Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP).",
2892Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command.1479 },
2893 1480 {
2894Key1481 key: "mcp_servers.<id>.identity.command",
2895 1482 type: "string",
2896`mcp_servers.<id>.identity.url`1483 description:
2897 1484 "Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command.",
2898Type / Values1485 },
2899 1486 {
2900`string`1487 key: "mcp_servers.<id>.identity.url",
2901 1488 type: "string",
2902Details1489 description:
2903 1490 "Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL.",
2904Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL.1491 },
2905 1492 {
2906Key1493 key: "rules",
2907 1494 type: "table",
2908`rules`1495 description:
2909 1496 "Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive.",
2910Type / Values1497 },
2911 1498 {
2912`table`1499 key: "rules.prefix_rules",
2913 1500 type: "array<table>",
2914Details1501 description:
2915 1502 "List of enforced prefix rules. Each rule must include `pattern` and `decision`.",
2916Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive.1503 },
2917 1504 {
2918Key1505 key: "rules.prefix_rules[].pattern",
2919 1506 type: "array<table>",
2920`rules.prefix_rules`1507 description:
2921 1508 "Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`.",
2922Type / Values1509 },
2923 1510 {
2924`array<table>`1511 key: "rules.prefix_rules[].pattern[].token",
2925 1512 type: "string",
2926Details1513 description: "A single literal token at this position.",
2927 1514 },
2928List of enforced prefix rules. Each rule must include `pattern` and `decision`.1515 {
2929 1516 key: "rules.prefix_rules[].pattern[].any_of",
2930Key1517 type: "array<string>",
2931 1518 description: "A list of allowed alternative tokens at this position.",
2932`rules.prefix_rules[].decision`1519 },
2933 1520 {
2934Type / Values1521 key: "rules.prefix_rules[].decision",
2935 1522 type: "prompt | forbidden",
2936`prompt | forbidden`1523 description:
2937 1524 "Required. Requirements rules can only prompt or forbid (not allow).",
2938Details1525 },
2939 1526 {
2940Required. Requirements rules can only prompt or forbid (not allow).1527 key: "rules.prefix_rules[].justification",
2941 1528 type: "string",
2942Key1529 description:
2943 1530 "Optional non-empty rationale surfaced in approval prompts or rejection messages.",
2944`rules.prefix_rules[].justification`1531 },
2945 1532 ]}
2946Type / Values1533 client:load
2947 1534/>
2948`string`
2949
2950Details
2951
2952Optional non-empty rationale surfaced in approval prompts or rejection messages.
2953
2954Key
2955
2956`rules.prefix_rules[].pattern`
2957
2958Type / Values
2959
2960`array<table>`
2961
2962Details
2963
2964Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`.
2965
2966Key
2967
2968`rules.prefix_rules[].pattern[].any_of`
2969
2970Type / Values
2971
2972`array<string>`
2973
2974Details
2975
2976A list of allowed alternative tokens at this position.
2977
2978Key
2979
2980`rules.prefix_rules[].pattern[].token`
2981
2982Type / Values
2983
2984`string`
2985
2986Details
2987
2988A single literal token at this position.
2989
2990Expand to view all
