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