config-reference.md +1518 −2159
1# Configuration Reference1# Configuration Reference
2 2
33Complete reference for Codex config.toml and requirements.tomlUse this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with [Config basics](https://developers.openai.com/codex/config-basic) and [Advanced Config](https://developers.openai.com/codex/config-advanced).
4
5Use this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with [Config basics](https://developers.openai.com/codex/config-basic) and [Advanced Config](https://developers.openai.com/codex/config-advanced).
6
7## `config.toml`
8
9User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.
10
11| Key | Type / Values | Details |
12| --- | --- | --- |
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. |
14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |
15| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |
16| `approval_policy` | `untrusted | on-request | never` | Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |
17| `apps.<id>.disabled_reason` | `unknown | user` | Optional reason attached when an app/connector is disabled. |
18| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |
19| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |
20| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |
21| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |
22| `compact_prompt` | `string` | Inline override for the history compaction prompt. |
23| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |
24| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |
25| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |
26| `experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`. |
27| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |
28| `features.apply_patch_freeform` | `boolean` | Expose the freeform `apply_patch` tool (experimental). |
29| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |
30| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |
31| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |
32| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |
33| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |
34| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |
35| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |
36| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |
37| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |
38| `features.remote_models` | `boolean` | Refresh remote model list before showing readiness (experimental). |
39| `features.request_rule` | `boolean` | Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default). |
40| `features.runtime_metrics` | `boolean` | Show runtime metrics summary in TUI turn separators (experimental). |
41| `features.search_tool` | `boolean` | Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental). |
42| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (beta). |
43| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |
44| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (beta). |
45| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |
46| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |
47| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |
48| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |
49| `feedback.enabled` | `boolean` | Enable feedback submission via `/feedback` across Codex surfaces (default: true). |
50| `file_opener` | `vscode | vscode-insiders | windsurf | cursor | none` | URI scheme used to open citations from Codex output (default: `vscode`). |
51| `forced_chatgpt_workspace_id` | `string (uuid)` | Limit ChatGPT logins to a specific workspace identifier. |
52| `forced_login_method` | `chatgpt | api` | Restrict Codex to a specific authentication method. |
53| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |
54| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |
55| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |
56| `include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |
57| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |
58| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |
59| `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. |
60| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |
61| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |
62| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |
63| `mcp_servers.<id>.command` | `string` | Launcher command for an MCP stdio server. |
64| `mcp_servers.<id>.cwd` | `string` | Working directory for the MCP stdio server process. |
65| `mcp_servers.<id>.disabled_tools` | `array<string>` | Deny list applied after `enabled_tools` for the MCP server. |
66| `mcp_servers.<id>.enabled` | `boolean` | Disable an MCP server without removing its configuration. |
67| `mcp_servers.<id>.enabled_tools` | `array<string>` | Allow list of tool names exposed by the MCP server. |
68| `mcp_servers.<id>.env` | `map<string,string>` | Environment variables forwarded to the MCP stdio server. |
69| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |
70| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |
71| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |
72| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |
73| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |
74| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |
75| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |
76| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |
77| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |
78| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |
79| `model_context_window` | `number` | Context window tokens available to the active model. |
80| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |
81| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |
82| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |
83| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |
84| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |
85| `model_providers.<id>.env_key_instructions` | `string` | Optional setup guidance for the provider API key. |
86| `model_providers.<id>.experimental_bearer_token` | `string` | Direct bearer token for the provider (discouraged; use `env_key`). |
87| `model_providers.<id>.http_headers` | `map<string,string>` | Static HTTP headers added to provider requests. |
88| `model_providers.<id>.name` | `string` | Display name for a custom model provider. |
89| `model_providers.<id>.query_params` | `map<string,string>` | Extra query parameters appended to provider requests. |
90| `model_providers.<id>.request_max_retries` | `number` | Retry count for HTTP requests to the provider (default: 4). |
91| `model_providers.<id>.requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). |
92| `model_providers.<id>.stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). |
93| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |
94| `model_providers.<id>.wire_api` | `chat | responses` | Protocol used by the provider (defaults to `chat` if omitted). |
95| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |
96| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |
97| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |
98| `model_verbosity` | `low | medium | high` | Control GPT-5 Responses API verbosity (defaults to `medium`). |
99| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |
100| `notice.hide_gpt-5.1-codex-max_migration_prompt` | `boolean` | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |
101| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |
102| `notice.hide_rate_limit_model_nudge` | `boolean` | Track opt-out of the rate limit model switch reminder. |
103| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |
104| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |
105| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |
106| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |
107| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |
108| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |
109| `otel.exporter.<id>.endpoint` | `string` | Exporter endpoint for OTEL logs. |
110| `otel.exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL exporter requests. |
111| `otel.exporter.<id>.protocol` | `binary | json` | Protocol used by the OTLP/HTTP exporter. |
112| `otel.exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL exporter TLS. |
113| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |
114| `otel.exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL exporter TLS. |
115| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |
116| `otel.trace_exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |
117| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |
118| `otel.trace_exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL trace exporter requests. |
119| `otel.trace_exporter.<id>.protocol` | `binary | json` | Protocol used by the OTLP/HTTP trace exporter. |
120| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |
121| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |
122| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |
123| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |
124| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |
125| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |
126| `profiles.<name>.experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |
127| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |
128| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |
129| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |
130| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |
131| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |
132| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |
133| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |
134| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |
135| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers. |
136| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |
137| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |
138| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |
139| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |
140| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |
141| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |
142| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |
143| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |
144| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |
145| `shell_environment_policy.include_only` | `array<string>` | Whitelist of patterns; when set only matching variables are kept. |
146| `shell_environment_policy.inherit` | `all | core | none` | Baseline environment inheritance when spawning subprocesses. |
147| `shell_environment_policy.set` | `map<string,string>` | Explicit environment overrides injected into every subprocess. |
148| `show_raw_agent_reasoning` | `boolean` | Surface raw reasoning content when the active model emits it. |
149| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |
150| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |
151| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |
152| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |
153| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |
154| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |
155| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |
156| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |
157| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |
158| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |
159| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |
160| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |
161| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |
162| `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. |
163| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |
164
165Key
166
167`agents.<name>.config_file`
168
169Type / Values
170
171`string (path)`
172
173Details
174
175Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.
176
177Key
178
179`agents.<name>.description`
180
181Type / Values
182
183`string`
184
185Details
186
187Role guidance shown to Codex when choosing and spawning that agent type.
188
189Key
190
191`agents.max_threads`
192
193Type / Values
194
195`number`
196
197Details
198
199Maximum number of agent threads that can be open concurrently.
200
201Key
202
203`approval_policy`
204
205Type / Values
206
207`untrusted | on-request | never`
208
209Details
210
211Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.
212
213Key
214
215`apps.<id>.disabled_reason`
216
217Type / Values
218
219`unknown | user`
220
221Details
222
223Optional reason attached when an app/connector is disabled.
224
225Key
226
227`apps.<id>.enabled`
228
229Type / Values
230
231`boolean`
232
233Details
234
235Enable or disable a specific app/connector by id (default: true).
236
237Key
238
239`chatgpt_base_url`
240
241Type / Values
242
243`string`
244
245Details
246
247Override the base URL used during the ChatGPT login flow.
248
249Key
250
251`check_for_update_on_startup`
252
253Type / Values
254
255`boolean`
256
257Details
258
259Check for Codex updates on startup (set to false only when updates are centrally managed).
260
261Key
262
263`cli_auth_credentials_store`
264
265Type / Values
266
267`file | keyring | auto`
268
269Details
270
271Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).
272
273Key
274
275`compact_prompt`
276
277Type / Values
278
279`string`
280
281Details
282
283Inline override for the history compaction prompt.
284
285Key
286
287`developer_instructions`
288
289Type / Values
290
291`string`
292
293Details
294
295Additional developer instructions injected into the session (optional).
296
297Key
298
299`disable_paste_burst`
300
301Type / Values
302
303`boolean`
304
305Details
306
307Disable burst-paste detection in the TUI.
308
309Key
310
311`experimental_compact_prompt_file`
312
313Type / Values
314
315`string (path)`
316
317Details
318
319Load the compaction prompt override from a file (experimental).
320
321Key
322
323`experimental_use_freeform_apply_patch`
324
325Type / Values
326
327`boolean`
328
329Details
330
331Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.
332
333Key
334
335`experimental_use_unified_exec_tool`
336
337Type / Values
338
339`boolean`
340
341Details
342
343Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.
344
345Key
346
347`features.apply_patch_freeform`
348
349Type / Values
350
351`boolean`
352
353Details
354
355Expose the freeform `apply_patch` tool (experimental).
356
357Key
358
359`features.apps`
360
361Type / Values
362
363`boolean`
364
365Details
366
367Enable ChatGPT Apps/connectors support (experimental).
368
369Key
370
371`features.apps_mcp_gateway`
372
373Type / Values
374
375`boolean`
376
377Details
378
379Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).
380
381Key
382
383`features.child_agents_md`
384
385Type / Values
386
387`boolean`
388
389Details
390
391Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).
392
393Key
394
395`features.collaboration_modes`
396
397Type / Values
398
399`boolean`
400
401Details
402
403Enable collaboration modes such as plan mode (stable; on by default).
404
405Key
406
407`features.elevated_windows_sandbox`
408
409Type / Values
410
411`boolean`
412
413Details
414
415Enable the elevated Windows sandbox pipeline (experimental).
416
417Key
418
419`features.experimental_windows_sandbox`
420
421Type / Values
422
423`boolean`
424
425Details
426
427Run the Windows restricted-token sandbox (experimental).
428
429Key
430
431`features.multi_agent`
432
433Type / Values
434
435`boolean`
436
437Details
438
439Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).
440
441Key
442
443`features.personality`
444
445Type / Values
446
447`boolean`
448
449Details
450
451Enable personality selection controls (stable; on by default).
452
453Key
454
455`features.powershell_utf8`
456
457Type / Values
458
459`boolean`
460
461Details
462
463Force PowerShell UTF-8 output (defaults to true).
464
465Key
466
467`features.remote_models`
468
469Type / Values
470
471`boolean`
472
473Details
474
475Refresh remote model list before showing readiness (experimental).
476
477Key
478
479`features.request_rule`
480
481Type / Values
482
483`boolean`
484
485Details
486
487Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).
488
489Key
490
491`features.runtime_metrics`
492
493Type / Values
494
495`boolean`
496
497Details
498
499Show runtime metrics summary in TUI turn separators (experimental).
500
501Key
502
503`features.search_tool`
504
505Type / Values
506
507`boolean`
508
509Details
510
511Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).
512
513Key
514
515`features.shell_snapshot`
516
517Type / Values
518
519`boolean`
520
521Details
522
523Snapshot shell environment to speed up repeated commands (beta).
524
525Key
526
527`features.shell_tool`
528
529Type / Values
530
531`boolean`
532
533Details
534
535Enable the default `shell` tool for running commands (stable; on by default).
536
537Key
538
539`features.unified_exec`
540
541Type / Values
542
543`boolean`
544
545Details
546
547Use the unified PTY-backed exec tool (beta).
548
549Key
550
551`features.use_linux_sandbox_bwrap`
552
553Type / Values
554
555`boolean`
556
557Details
558
559Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).
560
561Key
562
563`features.web_search`
564
565Type / Values
566
567`boolean`
568
569Details
570
571Deprecated legacy toggle; prefer the top-level `web_search` setting.
572
573Key
574
575`features.web_search_cached`
576
577Type / Values
578
579`boolean`
580
581Details
582
583Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.
584
585Key
586
587`features.web_search_request`
588
589Type / Values
590
591`boolean`
592
593Details
594
595Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.
596
597Key
598
599`feedback.enabled`
600
601Type / Values
602
603`boolean`
604
605Details
606
607Enable feedback submission via `/feedback` across Codex surfaces (default: true).
608
609Key
610
611`file_opener`
612
613Type / Values
614
615`vscode | vscode-insiders | windsurf | cursor | none`
616
617Details
618
619URI scheme used to open citations from Codex output (default: `vscode`).
620
621Key
622
623`forced_chatgpt_workspace_id`
624
625Type / Values
626
627`string (uuid)`
628
629Details
630
631Limit ChatGPT logins to a specific workspace identifier.
632
633Key
634
635`forced_login_method`
636
637Type / Values
638
639`chatgpt | api`
640
641Details
642
643Restrict Codex to a specific authentication method.
644
645Key
646
647`hide_agent_reasoning`
648
649Type / Values
650
651`boolean`
652
653Details
654
655Suppress reasoning events in both the TUI and `codex exec` output.
656
657Key
658
659`history.max_bytes`
660
661Type / Values
662
663`number`
664
665Details
666
667If set, caps the history file size in bytes by dropping oldest entries.
668
669Key
670
671`history.persistence`
672
673Type / Values
674
675`save-all | none`
676
677Details
678
679Control whether Codex saves session transcripts to history.jsonl.
680
681Key
682
683`include_apply_patch_tool`
684
685Type / Values
686
687`boolean`
688
689Details
690
691Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.
692
693Key
694
695`instructions`
696
697Type / Values
698
699`string`
700
701Details
702
703Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.
704
705Key
706
707`log_dir`
708
709Type / Values
710
711`string (path)`
712
713Details
714
715Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.
716
717Key
718
719`mcp_oauth_callback_port`
720
721Type / Values
722
723`integer`
724
725Details
726
727Optional 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.
728
729Key
730
731`mcp_oauth_credentials_store`
732
733Type / Values
734
735`auto | file | keyring`
736
737Details
738
739Preferred store for MCP OAuth credentials.
740
741Key
742
743`mcp_servers.<id>.args`
744
745Type / Values
746
747`array<string>`
748
749Details
750
751Arguments passed to the MCP stdio server command.
752
753Key
754
755`mcp_servers.<id>.bearer_token_env_var`
756
757Type / Values
758
759`string`
760
761Details
762
763Environment variable sourcing the bearer token for an MCP HTTP server.
764
765Key
766
767`mcp_servers.<id>.command`
768
769Type / Values
770
771`string`
772
773Details
774
775Launcher command for an MCP stdio server.
776
777Key
778
779`mcp_servers.<id>.cwd`
780
781Type / Values
782
783`string`
784
785Details
786
787Working directory for the MCP stdio server process.
788
789Key
790
791`mcp_servers.<id>.disabled_tools`
792
793Type / Values
794
795`array<string>`
796
797Details
798
799Deny list applied after `enabled_tools` for the MCP server.
800
801Key
802
803`mcp_servers.<id>.enabled`
804
805Type / Values
806
807`boolean`
808
809Details
810
811Disable an MCP server without removing its configuration.
812
813Key
814
815`mcp_servers.<id>.enabled_tools`
816
817Type / Values
818
819`array<string>`
820
821Details
822
823Allow list of tool names exposed by the MCP server.
824
825Key
826
827`mcp_servers.<id>.env`
828
829Type / Values
830
831`map<string,string>`
832
833Details
834
835Environment variables forwarded to the MCP stdio server.
836
837Key
838
839`mcp_servers.<id>.env_http_headers`
840
841Type / Values
842
843`map<string,string>`
844
845Details
846
847HTTP headers populated from environment variables for an MCP HTTP server.
848
849Key
850
851`mcp_servers.<id>.env_vars`
852
853Type / Values
854
855`array<string>`
856
857Details
858
859Additional environment variables to whitelist for an MCP stdio server.
860
861Key
862
863`mcp_servers.<id>.http_headers`
864
865Type / Values
866
867`map<string,string>`
868
869Details
870
871Static HTTP headers included with each MCP HTTP request.
872
873Key
874
875`mcp_servers.<id>.required`
876
877Type / Values
878
879`boolean`
880
881Details
882
883When true, fail startup/resume if this enabled MCP server cannot initialize.
884
885Key
886
887`mcp_servers.<id>.startup_timeout_ms`
888
889Type / Values
890
891`number`
892
893Details
894
895Alias for `startup_timeout_sec` in milliseconds.
896
897Key
898
899`mcp_servers.<id>.startup_timeout_sec`
900
901Type / Values
902
903`number`
904
905Details
906
907Override the default 10s startup timeout for an MCP server.
908
909Key
910
911`mcp_servers.<id>.tool_timeout_sec`
912
913Type / Values
914
915`number`
916
917Details
918
919Override the default 60s per-tool timeout for an MCP server.
920
921Key
922
923`mcp_servers.<id>.url`
924
925Type / Values
926
927`string`
928
929Details
930
931Endpoint for an MCP streamable HTTP server.
932
933Key
934
935`model`
936
937Type / Values
938
939`string`
940
941Details
942
943Model to use (e.g., `gpt-5-codex`).
944
945Key
946
947`model_auto_compact_token_limit`
948
949Type / Values
950
951`number`
952
953Details
954
955Token threshold that triggers automatic history compaction (unset uses model defaults).
956
957Key
958
959`model_context_window`
960
961Type / Values
962
963`number`
964
965Details
966
967Context window tokens available to the active model.
968
969Key
970
971`model_instructions_file`
972
973Type / Values
974
975`string (path)`
976
977Details
978
979Replacement for built-in instructions instead of `AGENTS.md`.
980
981Key
982
983`model_provider`
984
985Type / Values
986
987`string`
988
989Details
990
991Provider id from `model_providers` (default: `openai`).
992
993Key
994
995`model_providers.<id>.base_url`
996
997Type / Values
998
999`string`
1000
1001Details
1002
1003API base URL for the model provider.
1004
1005Key
1006
1007`model_providers.<id>.env_http_headers`
1008
1009Type / Values
1010
1011`map<string,string>`
1012
1013Details
1014
1015HTTP headers populated from environment variables when present.
1016
1017Key
1018
1019`model_providers.<id>.env_key`
1020
1021Type / Values
1022
1023`string`
1024
1025Details
1026
1027Environment variable supplying the provider API key.
1028
1029Key
1030
1031`model_providers.<id>.env_key_instructions`
1032
1033Type / Values
1034
1035`string`
1036
1037Details
1038
1039Optional setup guidance for the provider API key.
1040
1041Key
1042
1043`model_providers.<id>.experimental_bearer_token`
1044
1045Type / Values
1046
1047`string`
1048
1049Details
1050
1051Direct bearer token for the provider (discouraged; use `env_key`).
1052
1053Key
1054
1055`model_providers.<id>.http_headers`
1056
1057Type / Values
1058
1059`map<string,string>`
1060
1061Details
1062
1063Static HTTP headers added to provider requests.
1064
1065Key
1066
1067`model_providers.<id>.name`
1068
1069Type / Values
1070
1071`string`
1072
1073Details
1074
1075Display name for a custom model provider.
1076
1077Key
1078
1079`model_providers.<id>.query_params`
1080
1081Type / Values
1082
1083`map<string,string>`
1084
1085Details
1086
1087Extra query parameters appended to provider requests.
1088
1089Key
1090
1091`model_providers.<id>.request_max_retries`
1092
1093Type / Values
1094
1095`number`
1096
1097Details
1098
1099Retry count for HTTP requests to the provider (default: 4).
1100
1101Key
1102
1103`model_providers.<id>.requires_openai_auth`
1104
1105Type / Values
1106
1107`boolean`
1108
1109Details
1110
1111The provider uses OpenAI authentication (defaults to false).
1112
1113Key
1114
1115`model_providers.<id>.stream_idle_timeout_ms`
1116
1117Type / Values
1118
1119`number`
1120
1121Details
1122
1123Idle timeout for SSE streams in milliseconds (default: 300000).
1124
1125Key
1126
1127`model_providers.<id>.stream_max_retries`
1128
1129Type / Values
1130
1131`number`
1132
1133Details
1134
1135Retry count for SSE streaming interruptions (default: 5).
1136
1137Key
1138
1139`model_providers.<id>.wire_api`
1140
1141Type / Values
1142
1143`chat | responses`
1144
1145Details
1146
1147Protocol used by the provider (defaults to `chat` if omitted).
1148
1149Key
1150
1151`model_reasoning_effort`
1152
1153Type / Values
1154
1155`minimal | low | medium | high | xhigh`
1156
1157Details
1158
1159Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).
1160
1161Key
1162
1163`model_reasoning_summary`
1164
1165Type / Values
1166
1167`auto | concise | detailed | none`
1168
1169Details
1170
1171Select reasoning summary detail or disable summaries entirely.
1172
1173Key
1174
1175`model_supports_reasoning_summaries`
1176
1177Type / Values
1178
1179`boolean`
1180
1181Details
1182
1183Force Codex to send or not send reasoning metadata.
1184
1185Key
1186
1187`model_verbosity`
1188
1189Type / Values
1190
1191`low | medium | high`
1192
1193Details
1194
1195Control GPT-5 Responses API verbosity (defaults to `medium`).
1196
1197Key
1198
1199`notice.hide_full_access_warning`
1200
1201Type / Values
1202
1203`boolean`
1204
1205Details
1206
1207Track acknowledgement of the full access warning prompt.
1208
1209Key
1210
1211`notice.hide_gpt-5.1-codex-max_migration_prompt`
1212
1213Type / Values
1214
1215`boolean`
1216
1217Details
1218
1219Track acknowledgement of the gpt-5.1-codex-max migration prompt.
1220
1221Key
1222
1223`notice.hide_gpt5_1_migration_prompt`
1224
1225Type / Values
1226
1227`boolean`
1228
1229Details
1230
1231Track acknowledgement of the GPT-5.1 migration prompt.
1232
1233Key
1234
1235`notice.hide_rate_limit_model_nudge`
1236
1237Type / Values
1238
1239`boolean`
1240
1241Details
1242
1243Track opt-out of the rate limit model switch reminder.
1244
1245Key
1246
1247`notice.hide_world_writable_warning`
1248
1249Type / Values
1250
1251`boolean`
1252
1253Details
1254
1255Track acknowledgement of the Windows world-writable directories warning.
1256
1257Key
1258
1259`notice.model_migrations`
1260
1261Type / Values
1262
1263`map<string,string>`
1264
1265Details
1266
1267Track acknowledged model migrations as old->new mappings.
1268
1269Key
1270
1271`notify`
1272
1273Type / Values
1274
1275`array<string>`
1276
1277Details
1278
1279Command invoked for notifications; receives a JSON payload from Codex.
1280
1281Key
1282
1283`oss_provider`
1284
1285Type / Values
1286
1287`lmstudio | ollama`
1288
1289Details
1290
1291Default local provider used when running with `--oss` (defaults to prompting if unset).
1292
1293Key
1294
1295`otel.environment`
1296
1297Type / Values
1298
1299`string`
1300
1301Details
1302
1303Environment tag applied to emitted OpenTelemetry events (default: `dev`).
1304
1305Key
1306
1307`otel.exporter`
1308
1309Type / Values
1310
1311`none | otlp-http | otlp-grpc`
1312
1313Details
1314
1315Select the OpenTelemetry exporter and provide any endpoint metadata.
1316
1317Key
1318
1319`otel.exporter.<id>.endpoint`
1320
1321Type / Values
1322
1323`string`
1324
1325Details
1326
1327Exporter endpoint for OTEL logs.
1328
1329Key
1330
1331`otel.exporter.<id>.headers`
1332
1333Type / Values
1334
1335`map<string,string>`
1336
1337Details
1338
1339Static headers included with OTEL exporter requests.
1340
1341Key
1342
1343`otel.exporter.<id>.protocol`
1344
1345Type / Values
1346
1347`binary | json`
1348
1349Details
1350
1351Protocol used by the OTLP/HTTP exporter.
1352
1353Key
1354
1355`otel.exporter.<id>.tls.ca-certificate`
1356
1357Type / Values
1358
1359`string`
1360
1361Details
1362
1363CA certificate path for OTEL exporter TLS.
1364
1365Key
1366
1367`otel.exporter.<id>.tls.client-certificate`
1368
1369Type / Values
1370
1371`string`
1372
1373Details
1374
1375Client certificate path for OTEL exporter TLS.
1376
1377Key
1378
1379`otel.exporter.<id>.tls.client-private-key`
1380
1381Type / Values
1382
1383`string`
1384
1385Details
1386
1387Client private key path for OTEL exporter TLS.
1388
1389Key
1390
1391`otel.log_user_prompt`
1392
1393Type / Values
1394
1395`boolean`
1396
1397Details
1398
1399Opt in to exporting raw user prompts with OpenTelemetry logs.
1400
1401Key
1402
1403`otel.trace_exporter`
1404
1405Type / Values
1406
1407`none | otlp-http | otlp-grpc`
1408
1409Details
1410
1411Select the OpenTelemetry trace exporter and provide any endpoint metadata.
1412
1413Key
1414
1415`otel.trace_exporter.<id>.endpoint`
1416
1417Type / Values
1418
1419`string`
1420
1421Details
1422
1423Trace exporter endpoint for OTEL logs.
1424
1425Key
1426
1427`otel.trace_exporter.<id>.headers`
1428
1429Type / Values
1430
1431`map<string,string>`
1432
1433Details
1434
1435Static headers included with OTEL trace exporter requests.
1436
1437Key
1438
1439`otel.trace_exporter.<id>.protocol`
1440
1441Type / Values
1442
1443`binary | json`
1444
1445Details
1446
1447Protocol used by the OTLP/HTTP trace exporter.
1448
1449Key
1450
1451`otel.trace_exporter.<id>.tls.ca-certificate`
1452
1453Type / Values
1454
1455`string`
1456
1457Details
1458
1459CA certificate path for OTEL trace exporter TLS.
1460
1461Key
1462
1463`otel.trace_exporter.<id>.tls.client-certificate`
1464
1465Type / Values
1466
1467`string`
1468
1469Details
1470
1471Client certificate path for OTEL trace exporter TLS.
1472
1473Key
1474
1475`otel.trace_exporter.<id>.tls.client-private-key`
1476
1477Type / Values
1478
1479`string`
1480
1481Details
1482
1483Client private key path for OTEL trace exporter TLS.
1484
1485Key
1486
1487`personality`
1488
1489Type / Values
1490
1491`none | friendly | pragmatic`
1492
1493Details
1494
1495Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.
1496
1497Key
1498
1499`profile`
1500
1501Type / Values
1502
1503`string`
1504
1505Details
1506
1507Default profile applied at startup (equivalent to `--profile`).
1508
1509Key
1510
1511`profiles.<name>.*`
1512
1513Type / Values
1514
1515`various`
1516
1517Details
1518
1519Profile-scoped overrides for any of the supported configuration keys.
1520
1521Key
1522
1523`profiles.<name>.experimental_use_freeform_apply_patch`
1524
1525Type / Values
1526
1527`boolean`
1528
1529Details
1530
1531Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.
1532
1533Key
1534
1535`profiles.<name>.experimental_use_unified_exec_tool`
1536
1537Type / Values
1538
1539`boolean`
1540
1541Details
1542
1543Legacy name for enabling unified exec; prefer `[features].unified_exec`.
1544
1545Key
1546
1547`profiles.<name>.include_apply_patch_tool`
1548
1549Type / Values
1550
1551`boolean`
1552
1553Details
1554
1555Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.
1556
1557Key
1558
1559`profiles.<name>.oss_provider`
1560
1561Type / Values
1562
1563`lmstudio | ollama`
1564
1565Details
1566
1567Profile-scoped OSS provider for `--oss` sessions.
1568
1569Key
1570
1571`profiles.<name>.personality`
1572
1573Type / Values
1574
1575`none | friendly | pragmatic`
1576
1577Details
1578
1579Profile-scoped communication style override for supported models.
1580
1581Key
1582
1583`profiles.<name>.web_search`
1584
1585Type / Values
1586
1587`disabled | cached | live`
1588
1589Details
1590
1591Profile-scoped web search mode override (default: `"cached"`).
1592
1593Key
1594
1595`project_doc_fallback_filenames`
1596
1597Type / Values
1598
1599`array<string>`
1600
1601Details
1602
1603Additional filenames to try when `AGENTS.md` is missing.
1604
1605Key
1606
1607`project_doc_max_bytes`
1608
1609Type / Values
1610
1611`number`
1612
1613Details
1614
1615Maximum bytes read from `AGENTS.md` when building project instructions.
1616
1617Key
1618
1619`project_root_markers`
1620
1621Type / Values
1622
1623`array<string>`
1624
1625Details
1626
1627List of project root marker filenames; used when searching parent directories for the project root.
1628
1629Key
1630
1631`projects.<path>.trust_level`
1632
1633Type / Values
1634
1635`string`
1636
1637Details
1638
1639Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers.
1640
1641Key
1642
1643`review_model`
1644
1645Type / Values
1646
1647`string`
1648
1649Details
1650
1651Optional model override used by `/review` (defaults to the current session model).
1652
1653Key
1654
1655`sandbox_mode`
1656
1657Type / Values
1658
1659`read-only | workspace-write | danger-full-access`
1660
1661Details
1662
1663Sandbox policy for filesystem and network access during command execution.
1664
1665Key
1666
1667`sandbox_workspace_write.exclude_slash_tmp`
1668
1669Type / Values
1670
1671`boolean`
1672
1673Details
1674
1675Exclude `/tmp` from writable roots in workspace-write mode.
1676
1677Key
1678
1679`sandbox_workspace_write.exclude_tmpdir_env_var`
1680
1681Type / Values
1682
1683`boolean`
1684
1685Details
1686
1687Exclude `$TMPDIR` from writable roots in workspace-write mode.
1688
1689Key
1690
1691`sandbox_workspace_write.network_access`
1692
1693Type / Values
1694
1695`boolean`
1696
1697Details
1698
1699Allow outbound network access inside the workspace-write sandbox.
1700
1701Key
1702
1703`sandbox_workspace_write.writable_roots`
1704
1705Type / Values
1706
1707`array<string>`
1708
1709Details
1710
1711Additional writable roots when `sandbox_mode = "workspace-write"`.
1712
1713Key
1714
1715`shell_environment_policy.exclude`
1716
1717Type / Values
1718
1719`array<string>`
1720
1721Details
1722
1723Glob patterns for removing environment variables after the defaults.
1724
1725Key
1726
1727`shell_environment_policy.experimental_use_profile`
1728
1729Type / Values
1730
1731`boolean`
1732
1733Details
1734
1735Use the user shell profile when spawning subprocesses.
1736
1737Key
1738
1739`shell_environment_policy.ignore_default_excludes`
1740
1741Type / Values
1742
1743`boolean`
1744
1745Details
1746
1747Keep variables containing KEY/SECRET/TOKEN before other filters run.
1748
1749Key
1750
1751`shell_environment_policy.include_only`
1752
1753Type / Values
1754
1755`array<string>`
1756
1757Details
1758
1759Whitelist of patterns; when set only matching variables are kept.
1760
1761Key
1762
1763`shell_environment_policy.inherit`
1764
1765Type / Values
1766
1767`all | core | none`
1768
1769Details
1770
1771Baseline environment inheritance when spawning subprocesses.
1772
1773Key
1774
1775`shell_environment_policy.set`
1776
1777Type / Values
1778
1779`map<string,string>`
1780
1781Details
1782
1783Explicit environment overrides injected into every subprocess.
1784
1785Key
1786
1787`show_raw_agent_reasoning`
1788
1789Type / Values
1790
1791`boolean`
1792
1793Details
1794
1795Surface raw reasoning content when the active model emits it.
1796
1797Key
1798
1799`skills.config`
1800
1801Type / Values
1802
1803`array<object>`
1804
1805Details
1806
1807Per-skill enablement overrides stored in config.toml.
1808
1809Key
1810
1811`skills.config.<index>.enabled`
1812
1813Type / Values
1814
1815`boolean`
1816
1817Details
1818
1819Enable or disable the referenced skill.
1820
1821Key
1822
1823`skills.config.<index>.path`
1824
1825Type / Values
1826
1827`string (path)`
1828
1829Details
1830
1831Path to a skill folder containing `SKILL.md`.
1832
1833Key
1834
1835`suppress_unstable_features_warning`
1836
1837Type / Values
1838
1839`boolean`
1840
1841Details
1842
1843Suppress the warning that appears when under-development feature flags are enabled.
1844
1845Key
1846
1847`tool_output_token_limit`
1848
1849Type / Values
1850
1851`number`
1852
1853Details
1854
1855Token budget for storing individual tool/function outputs in history.
1856
1857Key
1858
1859`tools.web_search`
1860
1861Type / Values
1862
1863`boolean`
1864
1865Details
1866
1867Deprecated legacy toggle for web search; prefer the top-level `web_search` setting.
1868
1869Key
1870
1871`tui`
1872
1873Type / Values
1874
1875`table`
1876
1877Details
1878
1879TUI-specific options such as enabling inline desktop notifications.
1880
1881Key
1882
1883`tui.alternate_screen`
1884
1885Type / Values
1886
1887`auto | always | never`
1888
1889Details
1890
1891Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).
1892
1893Key
1894
1895`tui.animations`
1896
1897Type / Values
1898
1899`boolean`
1900
1901Details
1902
1903Enable terminal animations (welcome screen, shimmer, spinner) (default: true).
1904
1905Key
1906
1907`tui.notification_method`
1908
1909Type / Values
1910
1911`auto | osc9 | bel`
1912
1913Details
1914
1915Notification method for unfocused terminal notifications (default: auto).
1916
1917Key
1918
1919`tui.notifications`
1920
1921Type / Values
1922
1923`boolean | array<string>`
1924
1925Details
1926
1927Enable TUI notifications; optionally restrict to specific event types.
1928
1929Key
1930
1931`tui.show_tooltips`
1932
1933Type / Values
1934
1935`boolean`
1936
1937Details
1938
1939Show onboarding tooltips in the TUI welcome screen (default: true).
1940
1941Key
1942
1943`tui.status_line`
1944
1945Type / Values
1946
1947`array<string> | null`
1948
1949Details
1950
1951Ordered list of TUI footer status-line item identifiers. `null` disables the status line.
1952
1953Key
1954
1955`web_search`
1956
1957Type / Values
1958
1959`disabled | cached | live`
1960
1961Details
1962
1963Web 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.
1964
1965Key
1966
1967`windows_wsl_setup_acknowledged`
1968
1969Type / Values
1970
1971`boolean`
1972 4
19735Details## `config.toml`
1974 6
19757Track Windows onboarding acknowledgement (Windows only).User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.
1976 8
19779Expand to view allFor 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
11<ConfigTable
12 options={[
13 {
14 key: "model",
15 type: "string",
16 description: "Model to use (e.g., `gpt-5.5`).",
17 },
18 {
19 key: "review_model",
20 type: "string",
21 description:
22 "Optional model override used by `/review` (defaults to the current session model).",
23 },
24 {
25 key: "model_provider",
26 type: "string",
27 description: "Provider id from `model_providers` (default: `openai`).",
28 },
29 {
30 key: "openai_base_url",
31 type: "string",
32 description:
33 "Base URL override for the built-in `openai` model provider.",
34 },
35 {
36 key: "model_context_window",
37 type: "number",
38 description: "Context window tokens available to the active model.",
39 },
40 {
41 key: "model_auto_compact_token_limit",
42 type: "number",
43 description:
44 "Token threshold that triggers automatic history compaction (unset uses model defaults).",
45 },
46 {
47 key: "model_catalog_json",
48 type: "string (path)",
49 description:
50 "Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.",
51 },
52 {
53 key: "oss_provider",
54 type: "lmstudio | ollama",
55 description:
56 "Default local provider used when running with `--oss` (defaults to prompting if unset).",
57 },
58 {
59 key: "approval_policy",
60 type: "untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }",
61 description:
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 },
64 {
65 key: "approval_policy.granular.sandbox_approval",
66 type: "boolean",
67 description:
68 "When `true`, sandbox escalation approval prompts are allowed to surface.",
69 },
70 {
71 key: "approval_policy.granular.rules",
72 type: "boolean",
73 description:
74 "When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.",
75 },
76 {
77 key: "approval_policy.granular.mcp_elicitations",
78 type: "boolean",
79 description:
80 "When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.",
81 },
82 {
83 key: "approval_policy.granular.request_permissions",
84 type: "boolean",
85 description:
86 "When `true`, prompts from the `request_permissions` tool are allowed to surface.",
87 },
88 {
89 key: "approval_policy.granular.skill_approval",
90 type: "boolean",
91 description:
92 "When `true`, skill-script approval prompts are allowed to surface.",
93 },
94 {
95 key: "approvals_reviewer",
96 type: "user | auto_review",
97 description:
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 },
100 {
101 key: "auto_review.policy",
102 type: "string",
103 description:
104 "Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored.",
105 },
106 {
107 key: "allow_login_shell",
108 type: "boolean",
109 description:
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 },
112 {
113 key: "sandbox_mode",
114 type: "read-only | workspace-write | danger-full-access",
115 description:
116 "Sandbox policy for filesystem and network access during command execution.",
117 },
118 {
119 key: "sandbox_workspace_write.writable_roots",
120 type: "array<string>",
121 description:
122 'Additional writable roots when `sandbox_mode = "workspace-write"`.',
123 },
124 {
125 key: "sandbox_workspace_write.network_access",
126 type: "boolean",
127 description:
128 "Allow outbound network access inside the workspace-write sandbox.",
129 },
130 {
131 key: "sandbox_workspace_write.exclude_tmpdir_env_var",
132 type: "boolean",
133 description:
134 "Exclude `$TMPDIR` from writable roots in workspace-write mode.",
135 },
136 {
137 key: "sandbox_workspace_write.exclude_slash_tmp",
138 type: "boolean",
139 description:
140 "Exclude `/tmp` from writable roots in workspace-write mode.",
141 },
142 {
143 key: "windows.sandbox",
144 type: "unelevated | elevated",
145 description:
146 "Windows-only native sandbox mode when running Codex natively on Windows.",
147 },
148 {
149 key: "windows.sandbox_private_desktop",
150 type: "boolean",
151 description:
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 },
154 {
155 key: "notify",
156 type: "array<string>",
157 description:
158 "Command invoked for notifications; receives a JSON payload from Codex.",
159 },
160 {
161 key: "check_for_update_on_startup",
162 type: "boolean",
163 description:
164 "Check for Codex updates on startup (set to false only when updates are centrally managed).",
165 },
166 {
167 key: "feedback.enabled",
168 type: "boolean",
169 description:
170 "Enable feedback submission via `/feedback` across Codex surfaces (default: true).",
171 },
172 {
173 key: "analytics.enabled",
174 type: "boolean",
175 description:
176 "Enable or disable analytics for this machine/profile. When unset, the client default applies.",
177 },
178 {
179 key: "instructions",
180 type: "string",
181 description:
182 "Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.",
183 },
184 {
185 key: "developer_instructions",
186 type: "string",
187 description:
188 "Additional developer instructions injected into the session (optional).",
189 },
190 {
191 key: "log_dir",
192 type: "string (path)",
193 description:
194 "Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.",
195 },
196 {
197 key: "sqlite_home",
198 type: "string (path)",
199 description:
200 "Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.",
201 },
202 {
203 key: "compact_prompt",
204 type: "string",
205 description: "Inline override for the history compaction prompt.",
206 },
207 {
208 key: "commit_attribution",
209 type: "string",
210 description:
211 'Commit co-author trailer used when `[features].codex_git_commit` is enabled. Defaults to `Codex <noreply@openai.com>`; set `""` to disable.',
212 },
213 {
214 key: "model_instructions_file",
215 type: "string (path)",
216 description:
217 "Replacement for built-in instructions instead of `AGENTS.md`.",
218 },
219 {
220 key: "personality",
221 type: "none | friendly | pragmatic",
222 description:
223 "Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.",
224 },
225 {
226 key: "service_tier",
227 type: "flex | fast",
228 description: "Preferred service tier for new turns.",
229 },
230 {
231 key: "experimental_compact_prompt_file",
232 type: "string (path)",
233 description:
234 "Load the compaction prompt override from a file (experimental).",
235 },
236 {
237 key: "skills.config",
238 type: "array<object>",
239 description: "Per-skill enablement overrides stored in config.toml.",
240 },
241 {
242 key: "skills.config.<index>.path",
243 type: "string (path)",
244 description: "Path to a skill folder containing `SKILL.md`.",
245 },
246 {
247 key: "skills.config.<index>.enabled",
248 type: "boolean",
249 description: "Enable or disable the referenced skill.",
250 },
251 {
252 key: "apps.<id>.enabled",
253 type: "boolean",
254 description:
255 "Enable or disable a specific app/connector by id (default: true).",
256 },
257 {
258 key: "apps._default.enabled",
259 type: "boolean",
260 description:
261 "Default app enabled state for all apps unless overridden per app.",
262 },
263 {
264 key: "apps._default.destructive_enabled",
265 type: "boolean",
266 description:
267 "Default allow/deny for app tools with `destructive_hint = true`.",
268 },
269 {
270 key: "apps._default.open_world_enabled",
271 type: "boolean",
272 description:
273 "Default allow/deny for app tools with `open_world_hint = true`.",
274 },
275 {
276 key: "apps.<id>.destructive_enabled",
277 type: "boolean",
278 description:
279 "Allow or block tools in this app that advertise `destructive_hint = true`.",
280 },
281 {
282 key: "apps.<id>.open_world_enabled",
283 type: "boolean",
284 description:
285 "Allow or block tools in this app that advertise `open_world_hint = true`.",
286 },
287 {
288 key: "apps.<id>.default_tools_enabled",
289 type: "boolean",
290 description:
291 "Default enabled state for tools in this app unless a per-tool override exists.",
292 },
293 {
294 key: "apps.<id>.default_tools_approval_mode",
295 type: "auto | prompt | approve",
296 description:
297 "Default approval behavior for tools in this app unless a per-tool override exists.",
298 },
299 {
300 key: "apps.<id>.tools.<tool>.enabled",
301 type: "boolean",
302 description:
303 "Per-tool enabled override for an app tool (for example `repos/list`).",
304 },
305 {
306 key: "apps.<id>.tools.<tool>.approval_mode",
307 type: "auto | prompt | approve",
308 description: "Per-tool approval behavior override for a single app tool.",
309 },
310 {
311 key: "tool_suggest.discoverables",
312 type: "array<table>",
313 description:
314 'Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.',
315 },
316 {
317 key: "tool_suggest.disabled_tools",
318 type: "array<table>",
319 description:
320 'Disable suggestions for specific discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.',
321 },
322 {
323 key: "features.apps",
324 type: "boolean",
325 description: "Enable ChatGPT Apps/connectors support (experimental).",
326 },
327 {
328 key: "features.codex_hooks",
329 type: "boolean",
330 description:
331 "Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.",
332 },
333 {
334 key: "features.codex_git_commit",
335 type: "boolean",
336 description:
337 "Enable Codex-generated git commits. When enabled, Codex uses `commit_attribution` to append a `Co-authored-by:` trailer to generated commit messages.",
338 },
339 {
340 key: "hooks",
341 type: "table",
342 description:
343 "Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.",
344 },
345 {
346 key: "features.memories",
347 type: "boolean",
348 description: "Enable [Memories](https://developers.openai.com/codex/memories) (off by default).",
349 },
350 {
351 key: "mcp_servers.<id>.command",
352 type: "string",
353 description: "Launcher command for an MCP stdio server.",
354 },
355 {
356 key: "mcp_servers.<id>.args",
357 type: "array<string>",
358 description: "Arguments passed to the MCP stdio server command.",
359 },
360 {
361 key: "mcp_servers.<id>.env",
362 type: "map<string,string>",
363 description: "Environment variables forwarded to the MCP stdio server.",
364 },
365 {
366 key: "mcp_servers.<id>.env_vars",
367 type: 'array<string | { name = string, source = "local" | "remote" }>',
368 description:
369 '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.',
370 },
371 {
372 key: "mcp_servers.<id>.cwd",
373 type: "string",
374 description: "Working directory for the MCP stdio server process.",
375 },
376 {
377 key: "mcp_servers.<id>.url",
378 type: "string",
379 description: "Endpoint for an MCP streamable HTTP server.",
380 },
381 {
382 key: "mcp_servers.<id>.bearer_token_env_var",
383 type: "string",
384 description:
385 "Environment variable sourcing the bearer token for an MCP HTTP server.",
386 },
387 {
388 key: "mcp_servers.<id>.http_headers",
389 type: "map<string,string>",
390 description: "Static HTTP headers included with each MCP HTTP request.",
391 },
392 {
393 key: "mcp_servers.<id>.env_http_headers",
394 type: "map<string,string>",
395 description:
396 "HTTP headers populated from environment variables for an MCP HTTP server.",
397 },
398 {
399 key: "mcp_servers.<id>.enabled",
400 type: "boolean",
401 description: "Disable an MCP server without removing its configuration.",
402 },
403 {
404 key: "mcp_servers.<id>.required",
405 type: "boolean",
406 description:
407 "When true, fail startup/resume if this enabled MCP server cannot initialize.",
408 },
409 {
410 key: "mcp_servers.<id>.startup_timeout_sec",
411 type: "number",
412 description:
413 "Override the default 10s startup timeout for an MCP server.",
414 },
415 {
416 key: "mcp_servers.<id>.startup_timeout_ms",
417 type: "number",
418 description: "Alias for `startup_timeout_sec` in milliseconds.",
419 },
420 {
421 key: "mcp_servers.<id>.tool_timeout_sec",
422 type: "number",
423 description:
424 "Override the default 60s per-tool timeout for an MCP server.",
425 },
426 {
427 key: "mcp_servers.<id>.enabled_tools",
428 type: "array<string>",
429 description: "Allow list of tool names exposed by the MCP server.",
430 },
431 {
432 key: "mcp_servers.<id>.disabled_tools",
433 type: "array<string>",
434 description:
435 "Deny list applied after `enabled_tools` for the MCP server.",
436 },
437 {
438 key: "mcp_servers.<id>.scopes",
439 type: "array<string>",
440 description:
441 "OAuth scopes to request when authenticating to that MCP server.",
442 },
443 {
444 key: "mcp_servers.<id>.oauth_resource",
445 type: "string",
446 description:
447 "Optional RFC 8707 OAuth resource parameter to include during MCP login.",
448 },
449 {
450 key: "mcp_servers.<id>.experimental_environment",
451 type: "local | remote",
452 description:
453 "Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.",
454 },
455 {
456 key: "agents.max_threads",
457 type: "number",
458 description:
459 "Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.",
460 },
461 {
462 key: "agents.max_depth",
463 type: "number",
464 description:
465 "Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).",
466 },
467 {
468 key: "agents.job_max_runtime_seconds",
469 type: "number",
470 description:
471 "Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.",
472 },
473 {
474 key: "agents.<name>.description",
475 type: "string",
476 description:
477 "Role guidance shown to Codex when choosing and spawning that agent type.",
478 },
479 {
480 key: "agents.<name>.config_file",
481 type: "string (path)",
482 description:
483 "Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.",
484 },
485 {
486 key: "agents.<name>.nickname_candidates",
487 type: "array<string>",
488 description:
489 "Optional pool of display nicknames for spawned agents in that role.",
490 },
491 {
492 key: "memories.generate_memories",
493 type: "boolean",
494 description:
495 "When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.",
496 },
497 {
498 key: "memories.use_memories",
499 type: "boolean",
500 description:
501 "When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.",
502 },
503 {
504 key: "memories.disable_on_external_context",
505 type: "boolean",
506 description:
507 "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`.",
508 },
509 {
510 key: "memories.max_raw_memories_for_consolidation",
511 type: "number",
512 description:
513 "Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.",
514 },
515 {
516 key: "memories.max_unused_days",
517 type: "number",
518 description:
519 "Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.",
520 },
521 {
522 key: "memories.max_rollout_age_days",
523 type: "number",
524 description:
525 "Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.",
526 },
527 {
528 key: "memories.max_rollouts_per_startup",
529 type: "number",
530 description:
531 "Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.",
532 },
533 {
534 key: "memories.min_rollout_idle_hours",
535 type: "number",
536 description:
537 "Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.",
538 },
539 {
540 key: "memories.min_rate_limit_remaining_percent",
541 type: "number",
542 description:
543 "Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`.",
544 },
545 {
546 key: "memories.extract_model",
547 type: "string",
548 description: "Optional model override for per-thread memory extraction.",
549 },
550 {
551 key: "memories.consolidation_model",
552 type: "string",
553 description: "Optional model override for global memory consolidation.",
554 },
555 {
556 key: "features.unified_exec",
557 type: "boolean",
558 description:
559 "Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).",
560 },
561 {
562 key: "features.shell_snapshot",
563 type: "boolean",
564 description:
565 "Snapshot shell environment to speed up repeated commands (stable; on by default).",
566 },
567 {
568 key: "features.undo",
569 type: "boolean",
570 description: "Enable undo support (stable; off by default).",
571 },
572 {
573 key: "features.multi_agent",
574 type: "boolean",
575 description:
576 "Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).",
577 },
578 {
579 key: "features.personality",
580 type: "boolean",
581 description:
582 "Enable personality selection controls (stable; on by default).",
583 },
584 {
585 key: "features.web_search",
586 type: "boolean",
587 description:
588 "Deprecated legacy toggle; prefer the top-level `web_search` setting.",
589 },
590 {
591 key: "features.web_search_cached",
592 type: "boolean",
593 description:
594 'Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.',
595 },
596 {
597 key: "features.web_search_request",
598 type: "boolean",
599 description:
600 'Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.',
601 },
602 {
603 key: "features.shell_tool",
604 type: "boolean",
605 description:
606 "Enable the default `shell` tool for running commands (stable; on by default).",
607 },
608 {
609 key: "features.enable_request_compression",
610 type: "boolean",
611 description:
612 "Compress streaming request bodies with zstd when supported (stable; on by default).",
613 },
614 {
615 key: "features.skill_mcp_dependency_install",
616 type: "boolean",
617 description:
618 "Allow prompting and installing missing MCP dependencies for skills (stable; on by default).",
619 },
620 {
621 key: "features.fast_mode",
622 type: "boolean",
623 description:
624 'Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).',
625 },
626 {
627 key: "features.prevent_idle_sleep",
628 type: "boolean",
629 description:
630 "Prevent the machine from sleeping while a turn is actively running (experimental; off by default).",
631 },
632 {
633 key: "suppress_unstable_features_warning",
634 type: "boolean",
635 description:
636 "Suppress the warning that appears when under-development feature flags are enabled.",
637 },
638 {
639 key: "model_providers.<id>",
640 type: "table",
641 description:
642 "Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.",
643 },
644 {
645 key: "model_providers.<id>.name",
646 type: "string",
647 description: "Display name for a custom model provider.",
648 },
649 {
650 key: "model_providers.<id>.base_url",
651 type: "string",
652 description: "API base URL for the model provider.",
653 },
654 {
655 key: "model_providers.<id>.env_key",
656 type: "string",
657 description: "Environment variable supplying the provider API key.",
658 },
659 {
660 key: "model_providers.<id>.env_key_instructions",
661 type: "string",
662 description: "Optional setup guidance for the provider API key.",
663 },
664 {
665 key: "model_providers.<id>.experimental_bearer_token",
666 type: "string",
667 description:
668 "Direct bearer token for the provider (discouraged; use `env_key`).",
669 },
670 {
671 key: "model_providers.<id>.requires_openai_auth",
672 type: "boolean",
673 description:
674 "The provider uses OpenAI authentication (defaults to false).",
675 },
676 {
677 key: "model_providers.<id>.wire_api",
678 type: "responses",
679 description:
680 "Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.",
681 },
682 {
683 key: "model_providers.<id>.query_params",
684 type: "map<string,string>",
685 description: "Extra query parameters appended to provider requests.",
686 },
687 {
688 key: "model_providers.<id>.http_headers",
689 type: "map<string,string>",
690 description: "Static HTTP headers added to provider requests.",
691 },
692 {
693 key: "model_providers.<id>.env_http_headers",
694 type: "map<string,string>",
695 description:
696 "HTTP headers populated from environment variables when present.",
697 },
698 {
699 key: "model_providers.<id>.request_max_retries",
700 type: "number",
701 description:
702 "Retry count for HTTP requests to the provider (default: 4).",
703 },
704 {
705 key: "model_providers.<id>.stream_max_retries",
706 type: "number",
707 description: "Retry count for SSE streaming interruptions (default: 5).",
708 },
709 {
710 key: "model_providers.<id>.stream_idle_timeout_ms",
711 type: "number",
712 description:
713 "Idle timeout for SSE streams in milliseconds (default: 300000).",
714 },
715 {
716 key: "model_providers.<id>.supports_websockets",
717 type: "boolean",
718 description:
719 "Whether that provider supports the Responses API WebSocket transport.",
720 },
721 {
722 key: "model_providers.<id>.auth",
723 type: "table",
724 description:
725 "Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.",
726 },
727 {
728 key: "model_providers.<id>.auth.command",
729 type: "string",
730 description:
731 "Command to run when Codex needs a bearer token. The command must print the token to stdout.",
732 },
733 {
734 key: "model_providers.<id>.auth.args",
735 type: "array<string>",
736 description: "Arguments passed to the token command.",
737 },
738 {
739 key: "model_providers.<id>.auth.timeout_ms",
740 type: "number",
741 description:
742 "Maximum token command runtime in milliseconds (default: 5000).",
743 },
744 {
745 key: "model_providers.<id>.auth.refresh_interval_ms",
746 type: "number",
747 description:
748 "How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.",
749 },
750 {
751 key: "model_providers.<id>.auth.cwd",
752 type: "string (path)",
753 description: "Working directory for the token command.",
754 },
755 {
756 key: "model_providers.amazon-bedrock.aws.profile",
757 type: "string",
758 description:
759 "AWS profile name used by the built-in `amazon-bedrock` provider.",
760 },
761 {
762 key: "model_providers.amazon-bedrock.aws.region",
763 type: "string",
764 description: "AWS region used by the built-in `amazon-bedrock` provider.",
765 },
766 {
767 key: "model_reasoning_effort",
768 type: "minimal | low | medium | high | xhigh",
769 description:
770 "Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).",
771 },
772 {
773 key: "plan_mode_reasoning_effort",
774 type: "none | minimal | low | medium | high | xhigh",
775 description:
776 "Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default.",
777 },
778 {
779 key: "model_reasoning_summary",
780 type: "auto | concise | detailed | none",
781 description:
782 "Select reasoning summary detail or disable summaries entirely.",
783 },
784 {
785 key: "model_verbosity",
786 type: "low | medium | high",
787 description:
788 "Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.",
789 },
790 {
791 key: "model_supports_reasoning_summaries",
792 type: "boolean",
793 description: "Force Codex to send or not send reasoning metadata.",
794 },
795 {
796 key: "shell_environment_policy.inherit",
797 type: "all | core | none",
798 description:
799 "Baseline environment inheritance when spawning subprocesses.",
800 },
801 {
802 key: "shell_environment_policy.ignore_default_excludes",
803 type: "boolean",
804 description:
805 "Keep variables containing KEY/SECRET/TOKEN before other filters run.",
806 },
807 {
808 key: "shell_environment_policy.exclude",
809 type: "array<string>",
810 description:
811 "Glob patterns for removing environment variables after the defaults.",
812 },
813 {
814 key: "shell_environment_policy.include_only",
815 type: "array<string>",
816 description:
817 "Whitelist of patterns; when set only matching variables are kept.",
818 },
819 {
820 key: "shell_environment_policy.set",
821 type: "map<string,string>",
822 description:
823 "Explicit environment overrides injected into every subprocess.",
824 },
825 {
826 key: "shell_environment_policy.experimental_use_profile",
827 type: "boolean",
828 description: "Use the user shell profile when spawning subprocesses.",
829 },
830 {
831 key: "project_root_markers",
832 type: "array<string>",
833 description:
834 "List of project root marker filenames; used when searching parent directories for the project root.",
835 },
836 {
837 key: "project_doc_max_bytes",
838 type: "number",
839 description:
840 "Maximum bytes read from `AGENTS.md` when building project instructions.",
841 },
842 {
843 key: "project_doc_fallback_filenames",
844 type: "array<string>",
845 description: "Additional filenames to try when `AGENTS.md` is missing.",
846 },
847 {
848 key: "profile",
849 type: "string",
850 description:
851 "Default profile applied at startup (equivalent to `--profile`).",
852 },
853 {
854 key: "profiles.<name>.*",
855 type: "various",
856 description:
857 "Profile-scoped overrides for any of the supported configuration keys.",
858 },
859 {
860 key: "profiles.<name>.service_tier",
861 type: "flex | fast",
862 description: "Profile-scoped service tier preference for new turns.",
863 },
864 {
865 key: "profiles.<name>.plan_mode_reasoning_effort",
866 type: "none | minimal | low | medium | high | xhigh",
867 description: "Profile-scoped Plan-mode reasoning override.",
868 },
869 {
870 key: "profiles.<name>.web_search",
871 type: "disabled | cached | live",
872 description:
873 'Profile-scoped web search mode override (default: `"cached"`).',
874 },
875 {
876 key: "profiles.<name>.personality",
877 type: "none | friendly | pragmatic",
878 description:
879 "Profile-scoped communication style override for supported models.",
880 },
881 {
882 key: "profiles.<name>.model_catalog_json",
883 type: "string (path)",
884 description:
885 "Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).",
886 },
887 {
888 key: "profiles.<name>.model_instructions_file",
889 type: "string (path)",
890 description:
891 "Profile-scoped replacement for the built-in instruction file.",
892 },
893 {
894 key: "profiles.<name>.experimental_use_unified_exec_tool",
895 type: "boolean",
896 description:
897 "Legacy name for enabling unified exec; prefer `[features].unified_exec`.",
898 },
899 {
900 key: "profiles.<name>.oss_provider",
901 type: "lmstudio | ollama",
902 description: "Profile-scoped OSS provider for `--oss` sessions.",
903 },
904 {
905 key: "profiles.<name>.tools_view_image",
906 type: "boolean",
907 description: "Enable or disable the `view_image` tool in that profile.",
908 },
909 {
910 key: "profiles.<name>.analytics.enabled",
911 type: "boolean",
912 description: "Profile-scoped analytics enablement override.",
913 },
914 {
915 key: "profiles.<name>.windows.sandbox",
916 type: "unelevated | elevated",
917 description: "Profile-scoped Windows sandbox mode override.",
918 },
919 {
920 key: "history.persistence",
921 type: "save-all | none",
922 description:
923 "Control whether Codex saves session transcripts to history.jsonl.",
924 },
925 {
926 key: "tool_output_token_limit",
927 type: "number",
928 description:
929 "Token budget for storing individual tool/function outputs in history.",
930 },
931 {
932 key: "background_terminal_max_timeout",
933 type: "number",
934 description:
935 "Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.",
936 },
937 {
938 key: "history.max_bytes",
939 type: "number",
940 description:
941 "If set, caps the history file size in bytes by dropping oldest entries.",
942 },
943 {
944 key: "file_opener",
945 type: "vscode | vscode-insiders | windsurf | cursor | none",
946 description:
947 "URI scheme used to open citations from Codex output (default: `vscode`).",
948 },
949 {
950 key: "otel.environment",
951 type: "string",
952 description:
953 "Environment tag applied to emitted OpenTelemetry events (default: `dev`).",
954 },
955 {
956 key: "otel.exporter",
957 type: "none | otlp-http | otlp-grpc",
958 description:
959 "Select the OpenTelemetry exporter and provide any endpoint metadata.",
960 },
961 {
962 key: "otel.trace_exporter",
963 type: "none | otlp-http | otlp-grpc",
964 description:
965 "Select the OpenTelemetry trace exporter and provide any endpoint metadata.",
966 },
967 {
968 key: "otel.metrics_exporter",
969 type: "none | statsig | otlp-http | otlp-grpc",
970 description:
971 "Select the OpenTelemetry metrics exporter (defaults to `statsig`).",
972 },
973 {
974 key: "otel.log_user_prompt",
975 type: "boolean",
976 description:
977 "Opt in to exporting raw user prompts with OpenTelemetry logs.",
978 },
979 {
980 key: "otel.exporter.<id>.endpoint",
981 type: "string",
982 description: "Exporter endpoint for OTEL logs.",
983 },
984 {
985 key: "otel.exporter.<id>.protocol",
986 type: "binary | json",
987 description: "Protocol used by the OTLP/HTTP exporter.",
988 },
989 {
990 key: "otel.exporter.<id>.headers",
991 type: "map<string,string>",
992 description: "Static headers included with OTEL exporter requests.",
993 },
994 {
995 key: "otel.trace_exporter.<id>.endpoint",
996 type: "string",
997 description: "Trace exporter endpoint for OTEL logs.",
998 },
999 {
1000 key: "otel.trace_exporter.<id>.protocol",
1001 type: "binary | json",
1002 description: "Protocol used by the OTLP/HTTP trace exporter.",
1003 },
1004 {
1005 key: "otel.trace_exporter.<id>.headers",
1006 type: "map<string,string>",
1007 description: "Static headers included with OTEL trace exporter requests.",
1008 },
1009 {
1010 key: "otel.exporter.<id>.tls.ca-certificate",
1011 type: "string",
1012 description: "CA certificate path for OTEL exporter TLS.",
1013 },
1014 {
1015 key: "otel.exporter.<id>.tls.client-certificate",
1016 type: "string",
1017 description: "Client certificate path for OTEL exporter TLS.",
1018 },
1019 {
1020 key: "otel.exporter.<id>.tls.client-private-key",
1021 type: "string",
1022 description: "Client private key path for OTEL exporter TLS.",
1023 },
1024 {
1025 key: "otel.trace_exporter.<id>.tls.ca-certificate",
1026 type: "string",
1027 description: "CA certificate path for OTEL trace exporter TLS.",
1028 },
1029 {
1030 key: "otel.trace_exporter.<id>.tls.client-certificate",
1031 type: "string",
1032 description: "Client certificate path for OTEL trace exporter TLS.",
1033 },
1034 {
1035 key: "otel.trace_exporter.<id>.tls.client-private-key",
1036 type: "string",
1037 description: "Client private key path for OTEL trace exporter TLS.",
1038 },
1039 {
1040 key: "tui",
1041 type: "table",
1042 description:
1043 "TUI-specific options such as enabling inline desktop notifications.",
1044 },
1045 {
1046 key: "tui.notifications",
1047 type: "boolean | array<string>",
1048 description:
1049 "Enable TUI notifications; optionally restrict to specific event types.",
1050 },
1051 {
1052 key: "tui.notification_method",
1053 type: "auto | osc9 | bel",
1054 description:
1055 "Notification method for terminal notifications (default: auto).",
1056 },
1057 {
1058 key: "tui.notification_condition",
1059 type: "unfocused | always",
1060 description:
1061 "Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`.",
1062 },
1063 {
1064 key: "tui.animations",
1065 type: "boolean",
1066 description:
1067 "Enable terminal animations (welcome screen, shimmer, spinner) (default: true).",
1068 },
1069 {
1070 key: "tui.alternate_screen",
1071 type: "auto | always | never",
1072 description:
1073 "Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).",
1074 },
1075 {
1076 key: "tui.show_tooltips",
1077 type: "boolean",
1078 description:
1079 "Show onboarding tooltips in the TUI welcome screen (default: true).",
1080 },
1081 {
1082 key: "tui.status_line",
1083 type: "array<string> | null",
1084 description:
1085 "Ordered list of TUI footer status-line item identifiers. `null` disables the status line.",
1086 },
1087 {
1088 key: "tui.terminal_title",
1089 type: "array<string> | null",
1090 description:
1091 'Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates.',
1092 },
1093 {
1094 key: "tui.theme",
1095 type: "string",
1096 description:
1097 "Syntax-highlighting theme override (kebab-case theme name).",
1098 },
1099 {
1100 key: "tui.keymap.<context>.<action>",
1101 type: "string | array<string>",
1102 description:
1103 "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`.",
1104 },
1105 {
1106 key: "tui.keymap.<context>.<action> = []",
1107 type: "empty array",
1108 description:
1109 "Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, or `page-down`.",
1110 },
1111 {
1112 key: "tui.model_availability_nux.<model>",
1113 type: "integer",
1114 description: "Internal startup-tooltip state keyed by model slug.",
1115 },
1116 {
1117 key: "hide_agent_reasoning",
1118 type: "boolean",
1119 description:
1120 "Suppress reasoning events in both the TUI and `codex exec` output.",
1121 },
1122 {
1123 key: "show_raw_agent_reasoning",
1124 type: "boolean",
1125 description:
1126 "Surface raw reasoning content when the active model emits it.",
1127 },
1128 {
1129 key: "disable_paste_burst",
1130 type: "boolean",
1131 description: "Disable burst-paste detection in the TUI.",
1132 },
1133 {
1134 key: "windows_wsl_setup_acknowledged",
1135 type: "boolean",
1136 description: "Track Windows onboarding acknowledgement (Windows only).",
1137 },
1138 {
1139 key: "chatgpt_base_url",
1140 type: "string",
1141 description: "Override the base URL used during the ChatGPT login flow.",
1142 },
1143 {
1144 key: "cli_auth_credentials_store",
1145 type: "file | keyring | auto",
1146 description:
1147 "Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).",
1148 },
1149 {
1150 key: "mcp_oauth_credentials_store",
1151 type: "auto | file | keyring",
1152 description: "Preferred store for MCP OAuth credentials.",
1153 },
1154 {
1155 key: "mcp_oauth_callback_port",
1156 type: "integer",
1157 description:
1158 "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.",
1159 },
1160 {
1161 key: "mcp_oauth_callback_url",
1162 type: "string",
1163 description:
1164 "Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.",
1165 },
1166 {
1167 key: "experimental_use_unified_exec_tool",
1168 type: "boolean",
1169 description:
1170 "Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.",
1171 },
1172 {
1173 key: "tools.web_search",
1174 type: 'boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }',
1175 description:
1176 "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.",
1177 },
1178 {
1179 key: "tools.view_image",
1180 type: "boolean",
1181 description: "Enable the local-image attachment tool `view_image`.",
1182 },
1183 {
1184 key: "web_search",
1185 type: "disabled | cached | live",
1186 description:
1187 '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.',
1188 },
1189 {
1190 key: "default_permissions",
1191 type: "string",
1192 description:
1193 "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.",
1194 },
1195 {
1196 key: "permissions.<name>.filesystem",
1197 type: "table",
1198 description:
1199 "Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.",
1200 },
1201 {
1202 key: "permissions.<name>.filesystem.glob_scan_max_depth",
1203 type: "number",
1204 description:
1205 "Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set.",
1206 },
1207 {
1208 key: "permissions.<name>.filesystem.<path-or-glob>",
1209 type: '"read" | "write" | "none" | table',
1210 description:
1211 '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.',
1212 },
1213 {
1214 key: 'permissions.<name>.filesystem.":project_roots".<subpath-or-glob>',
1215 type: '"read" | "write" | "none"',
1216 description:
1217 'Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`.',
1218 },
1219 {
1220 key: "permissions.<name>.network.enabled",
1221 type: "boolean",
1222 description: "Enable network access for this named permissions profile.",
1223 },
1224 {
1225 key: "permissions.<name>.network.proxy_url",
1226 type: "string",
1227 description:
1228 "HTTP proxy endpoint used when this permissions profile enables the managed network proxy.",
1229 },
1230 {
1231 key: "permissions.<name>.network.enable_socks5",
1232 type: "boolean",
1233 description:
1234 "Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.",
1235 },
1236 {
1237 key: "permissions.<name>.network.socks_url",
1238 type: "string",
1239 description: "SOCKS5 proxy endpoint used by this permissions profile.",
1240 },
1241 {
1242 key: "permissions.<name>.network.enable_socks5_udp",
1243 type: "boolean",
1244 description: "Allow UDP over the SOCKS5 listener when enabled.",
1245 },
1246 {
1247 key: "permissions.<name>.network.allow_upstream_proxy",
1248 type: "boolean",
1249 description:
1250 "Allow the managed proxy to chain to another upstream proxy.",
1251 },
1252 {
1253 key: "permissions.<name>.network.dangerously_allow_non_loopback_proxy",
1254 type: "boolean",
1255 description:
1256 "Permit non-loopback bind addresses for the managed proxy listener.",
1257 },
1258 {
1259 key: "permissions.<name>.network.dangerously_allow_all_unix_sockets",
1260 type: "boolean",
1261 description:
1262 "Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.",
1263 },
1264 {
1265 key: "permissions.<name>.network.mode",
1266 type: "limited | full",
1267 description: "Network proxy mode used for subprocess traffic.",
1268 },
1269 {
1270 key: "permissions.<name>.network.domains",
1271 type: "map<string, allow | deny>",
1272 description:
1273 "Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values.",
1274 },
1275 {
1276 key: "permissions.<name>.network.unix_sockets",
1277 type: "map<string, allow | none>",
1278 description:
1279 "Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values.",
1280 },
1281 {
1282 key: "permissions.<name>.network.allow_local_binding",
1283 type: "boolean",
1284 description:
1285 "Permit local bind/listen operations through the managed proxy.",
1286 },
1287 {
1288 key: "projects.<path>.trust_level",
1289 type: "string",
1290 description:
1291 '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.',
1292 },
1293 {
1294 key: "notice.hide_full_access_warning",
1295 type: "boolean",
1296 description: "Track acknowledgement of the full access warning prompt.",
1297 },
1298 {
1299 key: "notice.hide_world_writable_warning",
1300 type: "boolean",
1301 description:
1302 "Track acknowledgement of the Windows world-writable directories warning.",
1303 },
1304 {
1305 key: "notice.hide_rate_limit_model_nudge",
1306 type: "boolean",
1307 description: "Track opt-out of the rate limit model switch reminder.",
1308 },
1309 {
1310 key: "notice.hide_gpt5_1_migration_prompt",
1311 type: "boolean",
1312 description: "Track acknowledgement of the GPT-5.1 migration prompt.",
1313 },
1314 {
1315 key: "notice.hide_gpt-5.1-codex-max_migration_prompt",
1316 type: "boolean",
1317 description:
1318 "Track acknowledgement of the gpt-5.1-codex-max migration prompt.",
1319 },
1320 {
1321 key: "notice.model_migrations",
1322 type: "map<string,string>",
1323 description: "Track acknowledged model migrations as old->new mappings.",
1324 },
1325 {
1326 key: "forced_login_method",
1327 type: "chatgpt | api",
1328 description: "Restrict Codex to a specific authentication method.",
1329 },
1330 {
1331 key: "forced_chatgpt_workspace_id",
1332 type: "string (uuid)",
1333 description: "Limit ChatGPT logins to a specific workspace identifier.",
1334 },
1335 ]}
1336 client:load
1337/>
1978 1338
1979You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).1339You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).
1980 1340
1988 1348
1989## `requirements.toml`1349## `requirements.toml`
1990 1350
19911351`requirements.toml` is an admin-enforced configuration file that constrains security-sensitive settings users can’t override. For details, locations, and examples, see [Admin-enforced requirements](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).`requirements.toml` is an admin-enforced configuration file that constrains security-sensitive settings users can't override. For details, locations, and examples, see [Admin-enforced requirements](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).
1992 1352
1993For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched1353For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched
1994requirements. See the security page for precedence details.1354requirements. See the security page for precedence details.
1995 1355
19961356| Key | Type / Values | Details |Use `[features]` in `requirements.toml` to pin feature flags by the same
19971357| --- | --- | --- |canonical keys that `config.toml` uses. Omitted keys remain unconstrained.
19981358| `allowed_approval_policies` | `array<string>` | Allowed values for `approval\_policy`. |
19991359| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |<ConfigTable
20001360| `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`. | options={[
20011361| `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. | {
20021362| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). | key: "allowed_approval_policies",
20031363| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. | type: "array<string>",
20041364| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. | description:
20051365| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. | "Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`).",
20061366| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. | },
20071367| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). | {
20081368| `rules.prefix_rules[].justification` | `string` | Optional non-empty rationale surfaced in approval prompts or rejection messages. | key: "allowed_approvals_reviewers",
20091369| `rules.prefix_rules[].pattern` | `array<table>` | Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`. | type: "array<string>",
20101370| `rules.prefix_rules[].pattern[].any_of` | `array<string>` | A list of allowed alternative tokens at this position. | description:
20111371| `rules.prefix_rules[].pattern[].token` | `string` | A single literal token at this position. | "Allowed values for `approvals_reviewer`, such as `user` and `auto_review`.",
20121372 },
20131373Key {
20141374 key: "guardian_policy_config",
20151375`allowed_approval_policies` type: "string",
20161376 description:
20171377Type / Values "Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored.",
20181378 },
20191379`array<string>` {
20201380 key: "allowed_sandbox_modes",
20211381Details type: "array<string>",
20221382 description: "Allowed values for `sandbox_mode`.",
20231383Allowed values for `approval\_policy`. },
20241384 {
20251385Key key: "remote_sandbox_config",
20261386 type: "array<table>",
20271387`allowed_sandbox_modes` description:
20281388 "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.",
20291389Type / Values },
20301390 {
20311391`array<string>` key: "remote_sandbox_config[].hostname_patterns",
20321392 type: "array<string>",
20331393Details description:
20341394 "Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character.",
20351395Allowed values for `sandbox_mode`. },
20361396 {
20371397Key key: "remote_sandbox_config[].allowed_sandbox_modes",
20381398 type: "array<string>",
20391399`allowed_web_search_modes` description:
20401400 "Allowed sandbox modes to apply when this host-specific entry matches.",
20411401Type / Values },
20421402 {
20431403`array<string>` key: "allowed_web_search_modes",
20441404 type: "array<string>",
20451405Details description:
20461406 "Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`.",
20471407Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. },
20481408 {
20491409Key key: "features",
20501410 type: "table",
20511411`mcp_servers` description:
20521412 "Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.",
20531413Type / Values },
20541414 {
20551415`table` key: "features.<name>",
20561416 type: "boolean",
20571417Details description:
20581418 "Require a specific canonical feature key to stay enabled or disabled.",
20591419Allowlist 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. },
20601420 {
20611421Key key: "features.in_app_browser",
20621422 type: "boolean",
20631423`mcp_servers.<id>.identity` description:
20641424 "Set to `false` in `requirements.toml` to disable the in-app browser pane.",
20651425Type / Values },
20661426 {
20671427`table` key: "features.browser_use",
20681428 type: "boolean",
20691429Details description:
20701430 "Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability.",
20711431Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). },
20721432 {
20731433Key key: "features.computer_use",
20741434 type: "boolean",
20751435`mcp_servers.<id>.identity.command` description:
20761436 "Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.",
20771437Type / Values },
20781438 {
20791439`string` key: "hooks",
20801440 type: "table",
20811441Details description:
20821442 "Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`.",
20831443Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. },
20841444 {
20851445Key key: "hooks.managed_dir",
20861446 type: "string (absolute path)",
20871447`mcp_servers.<id>.identity.url` description:
20881448 "Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks.",
20891449Type / Values },
20901450 {
20911451`string` key: "hooks.windows_managed_dir",
20921452 type: "string (absolute path)",
20931453Details description:
20941454 "Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks.",
20951455Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. },
20961456 {
20971457Key key: "hooks.<Event>",
20981458 type: "array<table>",
20991459`rules` description:
21001460 "Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`.",
21011461Type / Values },
21021462 {
21031463`table` key: "hooks.<Event>[].hooks",
21041464 type: "array<table>",
21051465Details description:
21061466 "Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped.",
21071467Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. },
21081468 {
21091469Key key: "permissions.filesystem.deny_read",
21101470 type: "array<string>",
21111471`rules.prefix_rules` description:
21121472 "Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config.",
21131473Type / Values },
21141474 {
21151475`array<table>` key: "mcp_servers",
21161476 type: "table",
21171477Details description:
21181478 "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.",
21191479List of enforced prefix rules. Each rule must include `pattern` and `decision`. },
21201480 {
21211481Key key: "mcp_servers.<id>.identity",
21221482 type: "table",
21231483`rules.prefix_rules[].decision` description:
21241484 "Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP).",
21251485Type / Values },
21261486 {
21271487`prompt | forbidden` key: "mcp_servers.<id>.identity.command",
21281488 type: "string",
21291489Details description:
21301490 "Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command.",
21311491Required. Requirements rules can only prompt or forbid (not allow). },
21321492 {
21331493Key key: "mcp_servers.<id>.identity.url",
21341494 type: "string",
21351495`rules.prefix_rules[].justification` description:
21361496 "Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL.",
21371497Type / Values },
21381498 {
21391499`string` key: "rules",
21401500 type: "table",
21411501Details description:
21421502 "Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive.",
21431503Optional non-empty rationale surfaced in approval prompts or rejection messages. },
21441504 {
21451505Key key: "rules.prefix_rules",
21461506 type: "array<table>",
21471507`rules.prefix_rules[].pattern` description:
21481508 "List of enforced prefix rules. Each rule must include `pattern` and `decision`.",
21491509Type / Values },
21501510 {
21511511`array<table>` key: "rules.prefix_rules[].pattern",
21521512 type: "array<table>",
21531513Details description:
21541514 "Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`.",
21551515Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`. },
21561516 {
21571517Key key: "rules.prefix_rules[].pattern[].token",
21581518 type: "string",
21591519`rules.prefix_rules[].pattern[].any_of` description: "A single literal token at this position.",
21601520 },
21611521Type / Values {
21621522 key: "rules.prefix_rules[].pattern[].any_of",
21631523`array<string>` type: "array<string>",
21641524 description: "A list of allowed alternative tokens at this position.",
21651525Details },
21661526 {
21671527A list of allowed alternative tokens at this position. key: "rules.prefix_rules[].decision",
21681528 type: "prompt | forbidden",
21691529Key description:
21701530 "Required. Requirements rules can only prompt or forbid (not allow).",
21711531`rules.prefix_rules[].pattern[].token` },
21721532 {
21731533Type / Values key: "rules.prefix_rules[].justification",
21741534 type: "string",
21751535`string` description:
21761536 "Optional non-empty rationale surfaced in approval prompts or rejection messages.",
21771537Details },
21781538 ]}
21791539A single literal token at this position. client:load
21801540 />
2181Expand to view all