config-reference.md +1728 −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 allProject-scoped config can't override machine-local provider, auth,
10notification, profile, or telemetry routing keys. Codex ignores
11`openai_base_url`, `chatgpt_base_url`, `model_provider`, `model_providers`,
12`notify`, `profile`, `profiles`, `experimental_realtime_ws_base_url`, and
13`otel` when they appear in a project-local `.codex/config.toml`; put those in
14user-level config instead.
15
16For 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).
17
18<ConfigTable
19 options={[
20 {
21 key: "model",
22 type: "string",
23 description: "Model to use (e.g., `gpt-5.5`).",
24 },
25 {
26 key: "review_model",
27 type: "string",
28 description:
29 "Optional model override used by `/review` (defaults to the current session model).",
30 },
31 {
32 key: "model_provider",
33 type: "string",
34 description: "Provider id from `model_providers` (default: `openai`).",
35 },
36 {
37 key: "openai_base_url",
38 type: "string",
39 description:
40 "Base URL override for the built-in `openai` model provider.",
41 },
42 {
43 key: "model_context_window",
44 type: "number",
45 description: "Context window tokens available to the active model.",
46 },
47 {
48 key: "model_auto_compact_token_limit",
49 type: "number",
50 description:
51 "Token threshold that triggers automatic history compaction (unset uses model defaults).",
52 },
53 {
54 key: "model_catalog_json",
55 type: "string (path)",
56 description:
57 "Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.",
58 },
59 {
60 key: "oss_provider",
61 type: "lmstudio | ollama",
62 description:
63 "Default local provider used when running with `--oss` (defaults to prompting if unset).",
64 },
65 {
66 key: "approval_policy",
67 type: "untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }",
68 description:
69 "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.",
70 },
71 {
72 key: "approval_policy.granular.sandbox_approval",
73 type: "boolean",
74 description:
75 "When `true`, sandbox escalation approval prompts are allowed to surface.",
76 },
77 {
78 key: "approval_policy.granular.rules",
79 type: "boolean",
80 description:
81 "When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.",
82 },
83 {
84 key: "approval_policy.granular.mcp_elicitations",
85 type: "boolean",
86 description:
87 "When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.",
88 },
89 {
90 key: "approval_policy.granular.request_permissions",
91 type: "boolean",
92 description:
93 "When `true`, prompts from the `request_permissions` tool are allowed to surface.",
94 },
95 {
96 key: "approval_policy.granular.skill_approval",
97 type: "boolean",
98 description:
99 "When `true`, skill-script approval prompts are allowed to surface.",
100 },
101 {
102 key: "approvals_reviewer",
103 type: "user | auto_review",
104 description:
105 "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.",
106 },
107 {
108 key: "auto_review.policy",
109 type: "string",
110 description:
111 "Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored.",
112 },
113 {
114 key: "allow_login_shell",
115 type: "boolean",
116 description:
117 "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.",
118 },
119 {
120 key: "sandbox_mode",
121 type: "read-only | workspace-write | danger-full-access",
122 description:
123 "Sandbox policy for filesystem and network access during command execution.",
124 },
125 {
126 key: "sandbox_workspace_write.writable_roots",
127 type: "array<string>",
128 description:
129 'Additional writable roots when `sandbox_mode = "workspace-write"`.',
130 },
131 {
132 key: "sandbox_workspace_write.network_access",
133 type: "boolean",
134 description:
135 "Allow outbound network access inside the workspace-write sandbox.",
136 },
137 {
138 key: "sandbox_workspace_write.exclude_tmpdir_env_var",
139 type: "boolean",
140 description:
141 "Exclude `$TMPDIR` from writable roots in workspace-write mode.",
142 },
143 {
144 key: "sandbox_workspace_write.exclude_slash_tmp",
145 type: "boolean",
146 description:
147 "Exclude `/tmp` from writable roots in workspace-write mode.",
148 },
149 {
150 key: "windows.sandbox",
151 type: "unelevated | elevated",
152 description:
153 "Windows-only native sandbox mode when running Codex natively on Windows.",
154 },
155 {
156 key: "windows.sandbox_private_desktop",
157 type: "boolean",
158 description:
159 "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.",
160 },
161 {
162 key: "notify",
163 type: "array<string>",
164 description:
165 "Command invoked for notifications; receives a JSON payload from Codex.",
166 },
167 {
168 key: "check_for_update_on_startup",
169 type: "boolean",
170 description:
171 "Check for Codex updates on startup (set to false only when updates are centrally managed).",
172 },
173 {
174 key: "feedback.enabled",
175 type: "boolean",
176 description:
177 "Enable feedback submission via `/feedback` across Codex surfaces (default: true).",
178 },
179 {
180 key: "analytics.enabled",
181 type: "boolean",
182 description:
183 "Enable or disable analytics for this machine/profile. When unset, the client default applies.",
184 },
185 {
186 key: "instructions",
187 type: "string",
188 description:
189 "Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.",
190 },
191 {
192 key: "developer_instructions",
193 type: "string",
194 description:
195 "Additional developer instructions injected into the session (optional).",
196 },
197 {
198 key: "log_dir",
199 type: "string (path)",
200 description:
201 "Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.",
202 },
203 {
204 key: "sqlite_home",
205 type: "string (path)",
206 description:
207 "Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.",
208 },
209 {
210 key: "compact_prompt",
211 type: "string",
212 description: "Inline override for the history compaction prompt.",
213 },
214 {
215 key: "commit_attribution",
216 type: "string",
217 description:
218 'Commit co-author trailer used when `[features].codex_git_commit` is enabled. Defaults to `Codex <noreply@openai.com>`; set `""` to disable.',
219 },
220 {
221 key: "model_instructions_file",
222 type: "string (path)",
223 description:
224 "Replacement for built-in instructions instead of `AGENTS.md`.",
225 },
226 {
227 key: "personality",
228 type: "none | friendly | pragmatic",
229 description:
230 "Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.",
231 },
232 {
233 key: "service_tier",
234 type: "string",
235 description:
236 "Preferred service tier for new turns. Built-in values include `flex` and `fast`; legacy `fast` config maps to the request value `priority`, and catalog-provided tier IDs can also be stored.",
237 },
238 {
239 key: "experimental_compact_prompt_file",
240 type: "string (path)",
241 description:
242 "Load the compaction prompt override from a file (experimental).",
243 },
244 {
245 key: "skills.config",
246 type: "array<object>",
247 description: "Per-skill enablement overrides stored in config.toml.",
248 },
249 {
250 key: "skills.config.<index>.path",
251 type: "string (path)",
252 description: "Path to a skill folder containing `SKILL.md`.",
253 },
254 {
255 key: "skills.config.<index>.enabled",
256 type: "boolean",
257 description: "Enable or disable the referenced skill.",
258 },
259 {
260 key: "apps.<id>.enabled",
261 type: "boolean",
262 description:
263 "Enable or disable a specific app/connector by id (default: true).",
264 },
265 {
266 key: "apps._default.enabled",
267 type: "boolean",
268 description:
269 "Default app enabled state for all apps unless overridden per app.",
270 },
271 {
272 key: "apps._default.destructive_enabled",
273 type: "boolean",
274 description:
275 "Default allow/deny for app tools with `destructive_hint = true`.",
276 },
277 {
278 key: "apps._default.open_world_enabled",
279 type: "boolean",
280 description:
281 "Default allow/deny for app tools with `open_world_hint = true`.",
282 },
283 {
284 key: "apps.<id>.destructive_enabled",
285 type: "boolean",
286 description:
287 "Allow or block tools in this app that advertise `destructive_hint = true`.",
288 },
289 {
290 key: "apps.<id>.open_world_enabled",
291 type: "boolean",
292 description:
293 "Allow or block tools in this app that advertise `open_world_hint = true`.",
294 },
295 {
296 key: "apps.<id>.default_tools_enabled",
297 type: "boolean",
298 description:
299 "Default enabled state for tools in this app unless a per-tool override exists.",
300 },
301 {
302 key: "apps.<id>.default_tools_approval_mode",
303 type: "auto | prompt | approve",
304 description:
305 "Default approval behavior for tools in this app unless a per-tool override exists.",
306 },
307 {
308 key: "apps.<id>.tools.<tool>.enabled",
309 type: "boolean",
310 description:
311 "Per-tool enabled override for an app tool (for example `repos/list`).",
312 },
313 {
314 key: "apps.<id>.tools.<tool>.approval_mode",
315 type: "auto | prompt | approve",
316 description: "Per-tool approval behavior override for a single app tool.",
317 },
318 {
319 key: "tool_suggest.discoverables",
320 type: "array<table>",
321 description:
322 'Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.',
323 },
324 {
325 key: "tool_suggest.disabled_tools",
326 type: "array<table>",
327 description:
328 'Disable suggestions for specific discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.',
329 },
330 {
331 key: "features.apps",
332 type: "boolean",
333 description: "Enable ChatGPT Apps/connectors support (experimental).",
334 },
335 {
336 key: "features.hooks",
337 type: "boolean",
338 description:
339 "Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. `features.codex_hooks` is a deprecated alias.",
340 },
341 {
342 key: "features.codex_git_commit",
343 type: "boolean",
344 description:
345 "Enable Codex-generated git commits. When enabled, Codex uses `commit_attribution` to append a `Co-authored-by:` trailer to generated commit messages.",
346 },
347 {
348 key: "hooks",
349 type: "table",
350 description:
351 "Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.",
352 },
353 {
354 key: "features.plugin_hooks",
355 type: "boolean",
356 description:
357 "Opt into lifecycle hooks bundled with enabled plugins. Off by default in this release; set to `true` to opt in.",
358 },
359 {
360 key: "features.memories",
361 type: "boolean",
362 description: "Enable [Memories](https://developers.openai.com/codex/memories) (off by default).",
363 },
364 {
365 key: "mcp_servers.<id>.command",
366 type: "string",
367 description: "Launcher command for an MCP stdio server.",
368 },
369 {
370 key: "mcp_servers.<id>.args",
371 type: "array<string>",
372 description: "Arguments passed to the MCP stdio server command.",
373 },
374 {
375 key: "mcp_servers.<id>.env",
376 type: "map<string,string>",
377 description: "Environment variables forwarded to the MCP stdio server.",
378 },
379 {
380 key: "mcp_servers.<id>.env_vars",
381 type: 'array<string | { name = string, source = "local" | "remote" }>',
382 description:
383 '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.',
384 },
385 {
386 key: "mcp_servers.<id>.cwd",
387 type: "string",
388 description: "Working directory for the MCP stdio server process.",
389 },
390 {
391 key: "mcp_servers.<id>.url",
392 type: "string",
393 description: "Endpoint for an MCP streamable HTTP server.",
394 },
395 {
396 key: "mcp_servers.<id>.bearer_token_env_var",
397 type: "string",
398 description:
399 "Environment variable sourcing the bearer token for an MCP HTTP server.",
400 },
401 {
402 key: "mcp_servers.<id>.http_headers",
403 type: "map<string,string>",
404 description: "Static HTTP headers included with each MCP HTTP request.",
405 },
406 {
407 key: "mcp_servers.<id>.env_http_headers",
408 type: "map<string,string>",
409 description:
410 "HTTP headers populated from environment variables for an MCP HTTP server.",
411 },
412 {
413 key: "mcp_servers.<id>.enabled",
414 type: "boolean",
415 description: "Disable an MCP server without removing its configuration.",
416 },
417 {
418 key: "mcp_servers.<id>.required",
419 type: "boolean",
420 description:
421 "When true, fail startup/resume if this enabled MCP server cannot initialize.",
422 },
423 {
424 key: "mcp_servers.<id>.startup_timeout_sec",
425 type: "number",
426 description:
427 "Override the default 10s startup timeout for an MCP server.",
428 },
429 {
430 key: "mcp_servers.<id>.startup_timeout_ms",
431 type: "number",
432 description: "Alias for `startup_timeout_sec` in milliseconds.",
433 },
434 {
435 key: "mcp_servers.<id>.tool_timeout_sec",
436 type: "number",
437 description:
438 "Override the default 60s per-tool timeout for an MCP server.",
439 },
440 {
441 key: "mcp_servers.<id>.enabled_tools",
442 type: "array<string>",
443 description: "Allow list of tool names exposed by the MCP server.",
444 },
445 {
446 key: "mcp_servers.<id>.disabled_tools",
447 type: "array<string>",
448 description:
449 "Deny list applied after `enabled_tools` for the MCP server.",
450 },
451 {
452 key: "mcp_servers.<id>.default_tools_approval_mode",
453 type: "auto | prompt | approve",
454 description:
455 "Default approval behavior for MCP tools on this server unless a per-tool override exists.",
456 },
457 {
458 key: "mcp_servers.<id>.tools.<tool>.approval_mode",
459 type: "auto | prompt | approve",
460 description:
461 "Per-tool approval behavior override for one MCP tool on this server.",
462 },
463 {
464 key: "mcp_servers.<id>.scopes",
465 type: "array<string>",
466 description:
467 "OAuth scopes to request when authenticating to that MCP server.",
468 },
469 {
470 key: "mcp_servers.<id>.oauth_resource",
471 type: "string",
472 description:
473 "Optional RFC 8707 OAuth resource parameter to include during MCP login.",
474 },
475 {
476 key: "mcp_servers.<id>.experimental_environment",
477 type: "local | remote",
478 description:
479 "Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.",
480 },
481 {
482 key: "agents.max_threads",
483 type: "number",
484 description:
485 "Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.",
486 },
487 {
488 key: "agents.max_depth",
489 type: "number",
490 description:
491 "Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).",
492 },
493 {
494 key: "agents.job_max_runtime_seconds",
495 type: "number",
496 description:
497 "Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.",
498 },
499 {
500 key: "agents.<name>.description",
501 type: "string",
502 description:
503 "Role guidance shown to Codex when choosing and spawning that agent type.",
504 },
505 {
506 key: "agents.<name>.config_file",
507 type: "string (path)",
508 description:
509 "Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.",
510 },
511 {
512 key: "agents.<name>.nickname_candidates",
513 type: "array<string>",
514 description:
515 "Optional pool of display nicknames for spawned agents in that role.",
516 },
517 {
518 key: "memories.generate_memories",
519 type: "boolean",
520 description:
521 "When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.",
522 },
523 {
524 key: "memories.use_memories",
525 type: "boolean",
526 description:
527 "When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.",
528 },
529 {
530 key: "memories.disable_on_external_context",
531 type: "boolean",
532 description:
533 "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`.",
534 },
535 {
536 key: "memories.max_raw_memories_for_consolidation",
537 type: "number",
538 description:
539 "Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.",
540 },
541 {
542 key: "memories.max_unused_days",
543 type: "number",
544 description:
545 "Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.",
546 },
547 {
548 key: "memories.max_rollout_age_days",
549 type: "number",
550 description:
551 "Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.",
552 },
553 {
554 key: "memories.max_rollouts_per_startup",
555 type: "number",
556 description:
557 "Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.",
558 },
559 {
560 key: "memories.min_rollout_idle_hours",
561 type: "number",
562 description:
563 "Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.",
564 },
565 {
566 key: "memories.min_rate_limit_remaining_percent",
567 type: "number",
568 description:
569 "Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`.",
570 },
571 {
572 key: "memories.extract_model",
573 type: "string",
574 description: "Optional model override for per-thread memory extraction.",
575 },
576 {
577 key: "memories.consolidation_model",
578 type: "string",
579 description: "Optional model override for global memory consolidation.",
580 },
581 {
582 key: "features.unified_exec",
583 type: "boolean",
584 description:
585 "Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).",
586 },
587 {
588 key: "features.shell_snapshot",
589 type: "boolean",
590 description:
591 "Snapshot shell environment to speed up repeated commands (stable; on by default).",
592 },
593 {
594 key: "features.undo",
595 type: "boolean",
596 description: "Enable undo support (stable; off by default).",
597 },
598 {
599 key: "features.multi_agent",
600 type: "boolean",
601 description:
602 "Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).",
603 },
604 {
605 key: "features.personality",
606 type: "boolean",
607 description:
608 "Enable personality selection controls (stable; on by default).",
609 },
610 {
611 key: "features.network_proxy",
612 type: "boolean | table",
613 description:
614 "Enable sandboxed networking. Use a table form when setting network policy options such as `domains` (experimental; off by default).",
615 },
616 {
617 key: "features.network_proxy.enabled",
618 type: "boolean",
619 description: "Enable sandboxed networking. Defaults to `false`.",
620 },
621 {
622 key: "features.network_proxy.domains",
623 type: "map<string, allow | deny>",
624 description:
625 "Domain policy for sandboxed networking. Unset by default, which means no external destinations are allowed until you add `allow` rules. Supports exact hosts, `*.example.com` for subdomains only, `**.example.com` for apex plus subdomains, and global `*` allow rules; prefer scoped rules because `*` broadly opens public outbound access. Add `deny` rules for blocked destinations; `deny` wins on conflicts.",
626 },
627 {
628 key: "features.network_proxy.unix_sockets",
629 type: "map<string, allow | none>",
630 description:
631 "Unix socket policy for sandboxed networking. Unset by default; add `allow` entries for permitted sockets.",
632 },
633 {
634 key: "features.network_proxy.allow_local_binding",
635 type: "boolean",
636 description:
637 "Allow broader local/private-network access. Defaults to `false`; exact local IP literal or `localhost` allow rules can still permit specific local targets.",
638 },
639 {
640 key: "features.network_proxy.enable_socks5",
641 type: "boolean",
642 description: "Expose SOCKS5 support. Defaults to `true`.",
643 },
644 {
645 key: "features.network_proxy.enable_socks5_udp",
646 type: "boolean",
647 description: "Allow UDP over SOCKS5. Defaults to `true`.",
648 },
649 {
650 key: "features.network_proxy.allow_upstream_proxy",
651 type: "boolean",
652 description:
653 "Allow chaining through an upstream proxy from the environment. Defaults to `true`.",
654 },
655 {
656 key: "features.network_proxy.dangerously_allow_non_loopback_proxy",
657 type: "boolean",
658 description:
659 "Permit non-loopback listener addresses. Defaults to `false`; enabling it can expose proxy listeners beyond localhost.",
660 },
661 {
662 key: "features.network_proxy.dangerously_allow_all_unix_sockets",
663 type: "boolean",
664 description:
665 "Permit arbitrary Unix socket destinations instead of allowlist-only access. Defaults to `false`; use only in tightly controlled environments.",
666 },
667 {
668 key: "features.network_proxy.proxy_url",
669 type: "string",
670 description:
671 'HTTP listener URL for sandboxed networking. Defaults to `"http://127.0.0.1:3128"`.',
672 },
673 {
674 key: "features.network_proxy.socks_url",
675 type: "string",
676 description:
677 'SOCKS5 listener URL. Defaults to `"http://127.0.0.1:8081"`.',
678 },
679 {
680 key: "features.web_search",
681 type: "boolean",
682 description:
683 "Deprecated legacy toggle; prefer the top-level `web_search` setting.",
684 },
685 {
686 key: "features.web_search_cached",
687 type: "boolean",
688 description:
689 'Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.',
690 },
691 {
692 key: "features.web_search_request",
693 type: "boolean",
694 description:
695 'Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.',
696 },
697 {
698 key: "features.shell_tool",
699 type: "boolean",
700 description:
701 "Enable the default `shell` tool for running commands (stable; on by default).",
702 },
703 {
704 key: "features.enable_request_compression",
705 type: "boolean",
706 description:
707 "Compress streaming request bodies with zstd when supported (stable; on by default).",
708 },
709 {
710 key: "features.skill_mcp_dependency_install",
711 type: "boolean",
712 description:
713 "Allow prompting and installing missing MCP dependencies for skills (stable; on by default).",
714 },
715 {
716 key: "features.fast_mode",
717 type: "boolean",
718 description:
719 "Enable model-catalog service tier selection in the TUI, including Fast-tier commands when the active model advertises them (stable; on by default).",
720 },
721 {
722 key: "features.prevent_idle_sleep",
723 type: "boolean",
724 description:
725 "Prevent the machine from sleeping while a turn is actively running (experimental; off by default).",
726 },
727 {
728 key: "suppress_unstable_features_warning",
729 type: "boolean",
730 description:
731 "Suppress the warning that appears when under-development feature flags are enabled.",
732 },
733 {
734 key: "model_providers.<id>",
735 type: "table",
736 description:
737 "Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.",
738 },
739 {
740 key: "model_providers.<id>.name",
741 type: "string",
742 description: "Display name for a custom model provider.",
743 },
744 {
745 key: "model_providers.<id>.base_url",
746 type: "string",
747 description: "API base URL for the model provider.",
748 },
749 {
750 key: "model_providers.<id>.env_key",
751 type: "string",
752 description: "Environment variable supplying the provider API key.",
753 },
754 {
755 key: "model_providers.<id>.env_key_instructions",
756 type: "string",
757 description: "Optional setup guidance for the provider API key.",
758 },
759 {
760 key: "model_providers.<id>.experimental_bearer_token",
761 type: "string",
762 description:
763 "Direct bearer token for the provider (discouraged; use `env_key`).",
764 },
765 {
766 key: "model_providers.<id>.requires_openai_auth",
767 type: "boolean",
768 description:
769 "The provider uses OpenAI authentication (defaults to false).",
770 },
771 {
772 key: "model_providers.<id>.wire_api",
773 type: "responses",
774 description:
775 "Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.",
776 },
777 {
778 key: "model_providers.<id>.query_params",
779 type: "map<string,string>",
780 description: "Extra query parameters appended to provider requests.",
781 },
782 {
783 key: "model_providers.<id>.http_headers",
784 type: "map<string,string>",
785 description: "Static HTTP headers added to provider requests.",
786 },
787 {
788 key: "model_providers.<id>.env_http_headers",
789 type: "map<string,string>",
790 description:
791 "HTTP headers populated from environment variables when present.",
792 },
793 {
794 key: "model_providers.<id>.request_max_retries",
795 type: "number",
796 description:
797 "Retry count for HTTP requests to the provider (default: 4).",
798 },
799 {
800 key: "model_providers.<id>.stream_max_retries",
801 type: "number",
802 description: "Retry count for SSE streaming interruptions (default: 5).",
803 },
804 {
805 key: "model_providers.<id>.stream_idle_timeout_ms",
806 type: "number",
807 description:
808 "Idle timeout for SSE streams in milliseconds (default: 300000).",
809 },
810 {
811 key: "model_providers.<id>.supports_websockets",
812 type: "boolean",
813 description:
814 "Whether that provider supports the Responses API WebSocket transport.",
815 },
816 {
817 key: "model_providers.<id>.auth",
818 type: "table",
819 description:
820 "Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.",
821 },
822 {
823 key: "model_providers.<id>.auth.command",
824 type: "string",
825 description:
826 "Command to run when Codex needs a bearer token. The command must print the token to stdout.",
827 },
828 {
829 key: "model_providers.<id>.auth.args",
830 type: "array<string>",
831 description: "Arguments passed to the token command.",
832 },
833 {
834 key: "model_providers.<id>.auth.timeout_ms",
835 type: "number",
836 description:
837 "Maximum token command runtime in milliseconds (default: 5000).",
838 },
839 {
840 key: "model_providers.<id>.auth.refresh_interval_ms",
841 type: "number",
842 description:
843 "How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.",
844 },
845 {
846 key: "model_providers.<id>.auth.cwd",
847 type: "string (path)",
848 description: "Working directory for the token command.",
849 },
850 {
851 key: "model_providers.amazon-bedrock.aws.profile",
852 type: "string",
853 description:
854 "AWS profile name used by the built-in `amazon-bedrock` provider.",
855 },
856 {
857 key: "model_providers.amazon-bedrock.aws.region",
858 type: "string",
859 description: "AWS region used by the built-in `amazon-bedrock` provider.",
860 },
861 {
862 key: "model_reasoning_effort",
863 type: "minimal | low | medium | high | xhigh",
864 description:
865 "Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).",
866 },
867 {
868 key: "plan_mode_reasoning_effort",
869 type: "none | minimal | low | medium | high | xhigh",
870 description:
871 "Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default.",
872 },
873 {
874 key: "model_reasoning_summary",
875 type: "auto | concise | detailed | none",
876 description:
877 "Select reasoning summary detail or disable summaries entirely.",
878 },
879 {
880 key: "model_verbosity",
881 type: "low | medium | high",
882 description:
883 "Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.",
884 },
885 {
886 key: "model_supports_reasoning_summaries",
887 type: "boolean",
888 description: "Force Codex to send or not send reasoning metadata.",
889 },
890 {
891 key: "shell_environment_policy.inherit",
892 type: "all | core | none",
893 description:
894 "Baseline environment inheritance when spawning subprocesses.",
895 },
896 {
897 key: "shell_environment_policy.ignore_default_excludes",
898 type: "boolean",
899 description:
900 "Keep variables containing KEY/SECRET/TOKEN before other filters run.",
901 },
902 {
903 key: "shell_environment_policy.exclude",
904 type: "array<string>",
905 description:
906 "Glob patterns for removing environment variables after the defaults.",
907 },
908 {
909 key: "shell_environment_policy.include_only",
910 type: "array<string>",
911 description:
912 "Whitelist of patterns; when set only matching variables are kept.",
913 },
914 {
915 key: "shell_environment_policy.set",
916 type: "map<string,string>",
917 description:
918 "Explicit environment overrides injected into every subprocess.",
919 },
920 {
921 key: "shell_environment_policy.experimental_use_profile",
922 type: "boolean",
923 description: "Use the user shell profile when spawning subprocesses.",
924 },
925 {
926 key: "project_root_markers",
927 type: "array<string>",
928 description:
929 "List of project root marker filenames; used when searching parent directories for the project root.",
930 },
931 {
932 key: "project_doc_max_bytes",
933 type: "number",
934 description:
935 "Maximum bytes read from `AGENTS.md` when building project instructions.",
936 },
937 {
938 key: "project_doc_fallback_filenames",
939 type: "array<string>",
940 description: "Additional filenames to try when `AGENTS.md` is missing.",
941 },
942 {
943 key: "profile",
944 type: "string",
945 description:
946 "Default profile applied at startup (equivalent to `--profile`).",
947 },
948 {
949 key: "profiles.<name>.*",
950 type: "various",
951 description:
952 "Profile-scoped overrides for any of the supported configuration keys.",
953 },
954 {
955 key: "profiles.<name>.service_tier",
956 type: "string",
957 description: "Profile-scoped service tier preference for new turns.",
958 },
959 {
960 key: "profiles.<name>.plan_mode_reasoning_effort",
961 type: "none | minimal | low | medium | high | xhigh",
962 description: "Profile-scoped Plan-mode reasoning override.",
963 },
964 {
965 key: "profiles.<name>.web_search",
966 type: "disabled | cached | live",
967 description:
968 'Profile-scoped web search mode override (default: `"cached"`).',
969 },
970 {
971 key: "profiles.<name>.personality",
972 type: "none | friendly | pragmatic",
973 description:
974 "Profile-scoped communication style override for supported models.",
975 },
976 {
977 key: "profiles.<name>.model_catalog_json",
978 type: "string (path)",
979 description:
980 "Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).",
981 },
982 {
983 key: "profiles.<name>.model_instructions_file",
984 type: "string (path)",
985 description:
986 "Profile-scoped replacement for the built-in instruction file.",
987 },
988 {
989 key: "profiles.<name>.experimental_use_unified_exec_tool",
990 type: "boolean",
991 description:
992 "Legacy name for enabling unified exec; prefer `[features].unified_exec`.",
993 },
994 {
995 key: "profiles.<name>.oss_provider",
996 type: "lmstudio | ollama",
997 description: "Profile-scoped OSS provider for `--oss` sessions.",
998 },
999 {
1000 key: "profiles.<name>.tools_view_image",
1001 type: "boolean",
1002 description: "Enable or disable the `view_image` tool in that profile.",
1003 },
1004 {
1005 key: "profiles.<name>.analytics.enabled",
1006 type: "boolean",
1007 description: "Profile-scoped analytics enablement override.",
1008 },
1009 {
1010 key: "profiles.<name>.windows.sandbox",
1011 type: "unelevated | elevated",
1012 description: "Profile-scoped Windows sandbox mode override.",
1013 },
1014 {
1015 key: "history.persistence",
1016 type: "save-all | none",
1017 description:
1018 "Control whether Codex saves session transcripts to history.jsonl.",
1019 },
1020 {
1021 key: "tool_output_token_limit",
1022 type: "number",
1023 description:
1024 "Token budget for storing individual tool/function outputs in history.",
1025 },
1026 {
1027 key: "background_terminal_max_timeout",
1028 type: "number",
1029 description:
1030 "Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.",
1031 },
1032 {
1033 key: "history.max_bytes",
1034 type: "number",
1035 description:
1036 "If set, caps the history file size in bytes by dropping oldest entries.",
1037 },
1038 {
1039 key: "file_opener",
1040 type: "vscode | vscode-insiders | windsurf | cursor | none",
1041 description:
1042 "URI scheme used to open citations from Codex output (default: `vscode`).",
1043 },
1044 {
1045 key: "otel.environment",
1046 type: "string",
1047 description:
1048 "Environment tag applied to emitted OpenTelemetry events (default: `dev`).",
1049 },
1050 {
1051 key: "otel.exporter",
1052 type: "none | otlp-http | otlp-grpc",
1053 description:
1054 "Select the OpenTelemetry exporter and provide any endpoint metadata.",
1055 },
1056 {
1057 key: "otel.trace_exporter",
1058 type: "none | otlp-http | otlp-grpc",
1059 description:
1060 "Select the OpenTelemetry trace exporter and provide any endpoint metadata.",
1061 },
1062 {
1063 key: "otel.metrics_exporter",
1064 type: "none | statsig | otlp-http | otlp-grpc",
1065 description:
1066 "Select the OpenTelemetry metrics exporter (defaults to `statsig`).",
1067 },
1068 {
1069 key: "otel.log_user_prompt",
1070 type: "boolean",
1071 description:
1072 "Opt in to exporting raw user prompts with OpenTelemetry logs.",
1073 },
1074 {
1075 key: "otel.exporter.<id>.endpoint",
1076 type: "string",
1077 description: "Exporter endpoint for OTEL logs.",
1078 },
1079 {
1080 key: "otel.exporter.<id>.protocol",
1081 type: "binary | json",
1082 description: "Protocol used by the OTLP/HTTP exporter.",
1083 },
1084 {
1085 key: "otel.exporter.<id>.headers",
1086 type: "map<string,string>",
1087 description: "Static headers included with OTEL exporter requests.",
1088 },
1089 {
1090 key: "otel.trace_exporter.<id>.endpoint",
1091 type: "string",
1092 description: "Trace exporter endpoint for OTEL logs.",
1093 },
1094 {
1095 key: "otel.trace_exporter.<id>.protocol",
1096 type: "binary | json",
1097 description: "Protocol used by the OTLP/HTTP trace exporter.",
1098 },
1099 {
1100 key: "otel.trace_exporter.<id>.headers",
1101 type: "map<string,string>",
1102 description: "Static headers included with OTEL trace exporter requests.",
1103 },
1104 {
1105 key: "otel.exporter.<id>.tls.ca-certificate",
1106 type: "string",
1107 description: "CA certificate path for OTEL exporter TLS.",
1108 },
1109 {
1110 key: "otel.exporter.<id>.tls.client-certificate",
1111 type: "string",
1112 description: "Client certificate path for OTEL exporter TLS.",
1113 },
1114 {
1115 key: "otel.exporter.<id>.tls.client-private-key",
1116 type: "string",
1117 description: "Client private key path for OTEL exporter TLS.",
1118 },
1119 {
1120 key: "otel.trace_exporter.<id>.tls.ca-certificate",
1121 type: "string",
1122 description: "CA certificate path for OTEL trace exporter TLS.",
1123 },
1124 {
1125 key: "otel.trace_exporter.<id>.tls.client-certificate",
1126 type: "string",
1127 description: "Client certificate path for OTEL trace exporter TLS.",
1128 },
1129 {
1130 key: "otel.trace_exporter.<id>.tls.client-private-key",
1131 type: "string",
1132 description: "Client private key path for OTEL trace exporter TLS.",
1133 },
1134 {
1135 key: "tui",
1136 type: "table",
1137 description:
1138 "TUI-specific options such as enabling inline desktop notifications.",
1139 },
1140 {
1141 key: "tui.notifications",
1142 type: "boolean | array<string>",
1143 description:
1144 "Enable TUI notifications; optionally restrict to specific event types.",
1145 },
1146 {
1147 key: "tui.notification_method",
1148 type: "auto | osc9 | bel",
1149 description:
1150 "Notification method for terminal notifications (default: auto).",
1151 },
1152 {
1153 key: "tui.notification_condition",
1154 type: "unfocused | always",
1155 description:
1156 "Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`.",
1157 },
1158 {
1159 key: "tui.animations",
1160 type: "boolean",
1161 description:
1162 "Enable terminal animations (welcome screen, shimmer, spinner) (default: true).",
1163 },
1164 {
1165 key: "tui.alternate_screen",
1166 type: "auto | always | never",
1167 description:
1168 "Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).",
1169 },
1170 {
1171 key: "tui.vim_mode_default",
1172 type: "boolean",
1173 description:
1174 "Start the composer in Vim normal mode instead of insert mode (default: false). You can still toggle it per session with `/vim`.",
1175 },
1176 {
1177 key: "tui.raw_output_mode",
1178 type: "boolean",
1179 description:
1180 "Start the TUI in raw scrollback mode for copy-friendly terminal selection (default: false). You can toggle it with `/raw` or the default `alt-r` key binding.",
1181 },
1182 {
1183 key: "tui.show_tooltips",
1184 type: "boolean",
1185 description:
1186 "Show onboarding tooltips in the TUI welcome screen (default: true).",
1187 },
1188 {
1189 key: "tui.status_line",
1190 type: "array<string> | null",
1191 description:
1192 "Ordered list of TUI footer status-line item identifiers. `null` disables the status line.",
1193 },
1194 {
1195 key: "tui.terminal_title",
1196 type: "array<string> | null",
1197 description:
1198 'Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates.',
1199 },
1200 {
1201 key: "tui.theme",
1202 type: "string",
1203 description:
1204 "Syntax-highlighting theme override (kebab-case theme name).",
1205 },
1206 {
1207 key: "tui.keymap.<context>.<action>",
1208 type: "string | array<string>",
1209 description:
1210 "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`.",
1211 },
1212 {
1213 key: "tui.keymap.<context>.<action> = []",
1214 type: "empty array",
1215 description:
1216 "Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, `page-down`, or `minus`.",
1217 },
1218 {
1219 key: "plugins.<plugin>.mcp_servers.<server>.enabled",
1220 type: "boolean",
1221 description:
1222 "Enable or disable an MCP server bundled by an installed plugin without changing the plugin manifest.",
1223 },
1224 {
1225 key: "plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode",
1226 type: "auto | prompt | approve",
1227 description:
1228 "Default approval behavior for tools on a plugin-provided MCP server.",
1229 },
1230 {
1231 key: "plugins.<plugin>.mcp_servers.<server>.enabled_tools",
1232 type: "array<string>",
1233 description:
1234 "Allow list of tools exposed from a plugin-provided MCP server.",
1235 },
1236 {
1237 key: "plugins.<plugin>.mcp_servers.<server>.disabled_tools",
1238 type: "array<string>",
1239 description:
1240 "Deny list applied after `enabled_tools` for a plugin-provided MCP server.",
1241 },
1242 {
1243 key: "plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode",
1244 type: "auto | prompt | approve",
1245 description:
1246 "Per-tool approval behavior override for a plugin-provided MCP tool.",
1247 },
1248 {
1249 key: "tui.model_availability_nux.<model>",
1250 type: "integer",
1251 description: "Internal startup-tooltip state keyed by model slug.",
1252 },
1253 {
1254 key: "hide_agent_reasoning",
1255 type: "boolean",
1256 description:
1257 "Suppress reasoning events in both the TUI and `codex exec` output.",
1258 },
1259 {
1260 key: "show_raw_agent_reasoning",
1261 type: "boolean",
1262 description:
1263 "Surface raw reasoning content when the active model emits it.",
1264 },
1265 {
1266 key: "disable_paste_burst",
1267 type: "boolean",
1268 description: "Disable burst-paste detection in the TUI.",
1269 },
1270 {
1271 key: "windows_wsl_setup_acknowledged",
1272 type: "boolean",
1273 description: "Track Windows onboarding acknowledgement (Windows only).",
1274 },
1275 {
1276 key: "chatgpt_base_url",
1277 type: "string",
1278 description: "Override the base URL used during the ChatGPT login flow.",
1279 },
1280 {
1281 key: "cli_auth_credentials_store",
1282 type: "file | keyring | auto",
1283 description:
1284 "Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).",
1285 },
1286 {
1287 key: "mcp_oauth_credentials_store",
1288 type: "auto | file | keyring",
1289 description: "Preferred store for MCP OAuth credentials.",
1290 },
1291 {
1292 key: "mcp_oauth_callback_port",
1293 type: "integer",
1294 description:
1295 "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.",
1296 },
1297 {
1298 key: "mcp_oauth_callback_url",
1299 type: "string",
1300 description:
1301 "Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.",
1302 },
1303 {
1304 key: "experimental_use_unified_exec_tool",
1305 type: "boolean",
1306 description:
1307 "Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.",
1308 },
1309 {
1310 key: "tools.web_search",
1311 type: 'boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }',
1312 description:
1313 "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.",
1314 },
1315 {
1316 key: "tools.view_image",
1317 type: "boolean",
1318 description: "Enable the local-image attachment tool `view_image`.",
1319 },
1320 {
1321 key: "web_search",
1322 type: "disabled | cached | live",
1323 description:
1324 '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.',
1325 },
1326 {
1327 key: "default_permissions",
1328 type: "string",
1329 description:
1330 "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.",
1331 },
1332 {
1333 key: "permissions.<name>.filesystem",
1334 type: "table",
1335 description:
1336 "Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.",
1337 },
1338 {
1339 key: "permissions.<name>.filesystem.glob_scan_max_depth",
1340 type: "number",
1341 description:
1342 "Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set.",
1343 },
1344 {
1345 key: "permissions.<name>.filesystem.<path-or-glob>",
1346 type: '"read" | "write" | "none" | table',
1347 description:
1348 '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.',
1349 },
1350 {
1351 key: 'permissions.<name>.filesystem.":project_roots".<subpath-or-glob>',
1352 type: '"read" | "write" | "none"',
1353 description:
1354 'Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`.',
1355 },
1356 {
1357 key: "permissions.<name>.network.enabled",
1358 type: "boolean",
1359 description: "Enable network access for this named permissions profile.",
1360 },
1361 {
1362 key: "permissions.<name>.network.proxy_url",
1363 type: "string",
1364 description:
1365 "HTTP listener URL used when this permissions profile enables sandboxed networking.",
1366 },
1367 {
1368 key: "permissions.<name>.network.enable_socks5",
1369 type: "boolean",
1370 description:
1371 "Expose SOCKS5 support when this permissions profile enables sandboxed networking.",
1372 },
1373 {
1374 key: "permissions.<name>.network.socks_url",
1375 type: "string",
1376 description: "SOCKS5 proxy endpoint used by this permissions profile.",
1377 },
1378 {
1379 key: "permissions.<name>.network.enable_socks5_udp",
1380 type: "boolean",
1381 description: "Allow UDP over the SOCKS5 listener when enabled.",
1382 },
1383 {
1384 key: "permissions.<name>.network.allow_upstream_proxy",
1385 type: "boolean",
1386 description:
1387 "Allow sandboxed networking to chain through another upstream proxy.",
1388 },
1389 {
1390 key: "permissions.<name>.network.dangerously_allow_non_loopback_proxy",
1391 type: "boolean",
1392 description:
1393 "Permit non-loopback bind addresses for sandboxed networking listeners. Enabling it can expose listeners beyond localhost.",
1394 },
1395 {
1396 key: "permissions.<name>.network.dangerously_allow_all_unix_sockets",
1397 type: "boolean",
1398 description:
1399 "Allow arbitrary Unix socket destinations instead of the default restricted set. Use only in tightly controlled environments.",
1400 },
1401 {
1402 key: "permissions.<name>.network.domains",
1403 type: "map<string, allow | deny>",
1404 description:
1405 "Domain rules for sandboxed networking. Supports exact hosts, `*.example.com` for subdomains only, `**.example.com` for apex plus subdomains, and global `*` allow rules. `deny` wins on conflicts.",
1406 },
1407 {
1408 key: "permissions.<name>.network.unix_sockets",
1409 type: "map<string, allow | none>",
1410 description:
1411 "Unix socket rules for sandboxed networking. Use socket paths as keys, with `allow` or `none` values.",
1412 },
1413 {
1414 key: "permissions.<name>.network.allow_local_binding",
1415 type: "boolean",
1416 description:
1417 "Permit broader local/private-network access through sandboxed networking. Exact local IP literal or `localhost` allow rules can still permit specific local targets when this stays `false`.",
1418 },
1419 {
1420 key: "projects.<path>.trust_level",
1421 type: "string",
1422 description:
1423 '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.',
1424 },
1425 {
1426 key: "notice.hide_full_access_warning",
1427 type: "boolean",
1428 description: "Track acknowledgement of the full access warning prompt.",
1429 },
1430 {
1431 key: "notice.hide_world_writable_warning",
1432 type: "boolean",
1433 description:
1434 "Track acknowledgement of the Windows world-writable directories warning.",
1435 },
1436 {
1437 key: "notice.hide_rate_limit_model_nudge",
1438 type: "boolean",
1439 description: "Track opt-out of the rate limit model switch reminder.",
1440 },
1441 {
1442 key: "notice.hide_gpt5_1_migration_prompt",
1443 type: "boolean",
1444 description: "Track acknowledgement of the GPT-5.1 migration prompt.",
1445 },
1446 {
1447 key: "notice.hide_gpt-5.1-codex-max_migration_prompt",
1448 type: "boolean",
1449 description:
1450 "Track acknowledgement of the gpt-5.1-codex-max migration prompt.",
1451 },
1452 {
1453 key: "notice.model_migrations",
1454 type: "map<string,string>",
1455 description: "Track acknowledged model migrations as old->new mappings.",
1456 },
1457 {
1458 key: "forced_login_method",
1459 type: "chatgpt | api",
1460 description: "Restrict Codex to a specific authentication method.",
1461 },
1462 {
1463 key: "forced_chatgpt_workspace_id",
1464 type: "string (uuid)",
1465 description: "Limit ChatGPT logins to a specific workspace identifier.",
1466 },
1467 ]}
1468 client:load
1469/>
1978 1470
1979You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).1471You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).
1980 1472
1988 1480
1989## `requirements.toml`1481## `requirements.toml`
1990 1482
19911483`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 1484
1993For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched1485For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched
1994requirements. See the security page for precedence details.1486requirements. See the security page for precedence details.
1995 1487
19961488| Key | Type / Values | Details |Use `[features]` in `requirements.toml` to pin feature flags by the same
19971489| --- | --- | --- |canonical keys that `config.toml` uses. Omitted keys remain unconstrained.
19981490| `allowed_approval_policies` | `array<string>` | Allowed values for `approval\_policy`. |
19991491| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |<ConfigTable
20001492| `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={[
20011493| `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. | {
20021494| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). | key: "allowed_approval_policies",
20031495| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. | type: "array<string>",
20041496| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. | description:
20051497| `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`).",
20061498| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. | },
20071499| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). | {
20081500| `rules.prefix_rules[].justification` | `string` | Optional non-empty rationale surfaced in approval prompts or rejection messages. | key: "allowed_approvals_reviewers",
20091501| `rules.prefix_rules[].pattern` | `array<table>` | Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`. | type: "array<string>",
20101502| `rules.prefix_rules[].pattern[].any_of` | `array<string>` | A list of allowed alternative tokens at this position. | description:
20111503| `rules.prefix_rules[].pattern[].token` | `string` | A single literal token at this position. | "Allowed values for `approvals_reviewer`, such as `user` and `auto_review`.",
20121504 },
20131505Key {
20141506 key: "guardian_policy_config",
20151507`allowed_approval_policies` type: "string",
20161508 description:
20171509Type / Values "Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored.",
20181510 },
20191511`array<string>` {
20201512 key: "allowed_sandbox_modes",
20211513Details type: "array<string>",
20221514 description: "Allowed values for `sandbox_mode`.",
20231515Allowed values for `approval\_policy`. },
20241516 {
20251517Key key: "remote_sandbox_config",
20261518 type: "array<table>",
20271519`allowed_sandbox_modes` description:
20281520 "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.",
20291521Type / Values },
20301522 {
20311523`array<string>` key: "remote_sandbox_config[].hostname_patterns",
20321524 type: "array<string>",
20331525Details description:
20341526 "Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character.",
20351527Allowed values for `sandbox_mode`. },
20361528 {
20371529Key key: "remote_sandbox_config[].allowed_sandbox_modes",
20381530 type: "array<string>",
20391531`allowed_web_search_modes` description:
20401532 "Allowed sandbox modes to apply when this host-specific entry matches.",
20411533Type / Values },
20421534 {
20431535`array<string>` key: "allowed_web_search_modes",
20441536 type: "array<string>",
20451537Details description:
20461538 "Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`.",
20471539Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. },
20481540 {
20491541Key key: "features",
20501542 type: "table",
20511543`mcp_servers` description:
20521544 "Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.",
20531545Type / Values },
20541546 {
20551547`table` key: "features.<name>",
20561548 type: "boolean",
20571549Details description:
20581550 "Require a specific canonical feature key to stay enabled or disabled.",
20591551Allowlist 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. },
20601552 {
20611553Key key: "features.in_app_browser",
20621554 type: "boolean",
20631555`mcp_servers.<id>.identity` description:
20641556 "Set to `false` in `requirements.toml` to disable the in-app browser pane.",
20651557Type / Values },
20661558 {
20671559`table` key: "features.browser_use",
20681560 type: "boolean",
20691561Details description:
20701562 "Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability.",
20711563Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). },
20721564 {
20731565Key key: "features.computer_use",
20741566 type: "boolean",
20751567`mcp_servers.<id>.identity.command` description:
20761568 "Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.",
20771569Type / Values },
20781570 {
20791571`string` key: "experimental_network",
20801572 type: "table",
20811573Details description:
20821574 "Network access requirements enforced from `requirements.toml`. These constraints are separate from `features.network_proxy` and can configure sandboxed networking without the user feature flag.",
20831575Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. },
20841576 {
20851577Key key: "experimental_network.enabled",
20861578 type: "boolean",
20871579`mcp_servers.<id>.identity.url` description:
20881580 "Enable sandboxed networking requirements. This does not grant network access when the active sandbox keeps command networking off.",
20891581Type / Values },
20901582 {
20911583`string` key: "experimental_network.http_port",
20921584 type: "integer",
20931585Details description:
20941586 "Loopback HTTP listener port to use for `[experimental_network]` requirements.",
20951587Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. },
20961588 {
20971589Key key: "experimental_network.socks_port",
20981590 type: "integer",
20991591`rules` description:
21001592 "Loopback SOCKS5 listener port to use for `[experimental_network]` requirements.",
21011593Type / Values },
21021594 {
21031595`table` key: "experimental_network.allow_upstream_proxy",
21041596 type: "boolean",
21051597Details description:
21061598 "Allow sandboxed networking to chain through an upstream proxy from the environment.",
21071599Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. },
21081600 {
21091601Key key: "experimental_network.dangerously_allow_non_loopback_proxy",
21101602 type: "boolean",
21111603`rules.prefix_rules` description:
21121604 "Permit non-loopback listener addresses for `[experimental_network]` requirements. Enabling it can expose listeners beyond localhost.",
21131605Type / Values },
21141606 {
21151607`array<table>` key: "experimental_network.dangerously_allow_all_unix_sockets",
21161608 type: "boolean",
21171609Details description:
21181610 "Permit arbitrary Unix socket destinations instead of allowlist-only access. Use only in tightly controlled environments.",
21191611List of enforced prefix rules. Each rule must include `pattern` and `decision`. },
21201612 {
21211613Key key: "experimental_network.domains",
21221614 type: "map<string, allow | deny>",
21231615`rules.prefix_rules[].decision` description:
21241616 "Map-shaped administrator domain policy for sandboxed networking. Supports exact hosts, `*.example.com` for subdomains only, `**.example.com` for apex plus subdomains, and global `*` allow rules; prefer scoped rules because `*` broadly opens public outbound access. `deny` wins on conflicts. Do not combine this with `experimental_network.allowed_domains` or `experimental_network.denied_domains`.",
21251617Type / Values },
21261618 {
21271619`prompt | forbidden` key: "experimental_network.allowed_domains",
21281620 type: "array<string>",
21291621Details description:
21301622 "List-shaped administrator allow rules for sandboxed networking. Do not combine this with `experimental_network.domains`.",
21311623Required. Requirements rules can only prompt or forbid (not allow). },
21321624 {
21331625Key key: "experimental_network.denied_domains",
21341626 type: "array<string>",
21351627`rules.prefix_rules[].justification` description:
21361628 "List-shaped administrator deny rules for sandboxed networking. Do not combine this with `experimental_network.domains`.",
21371629Type / Values },
21381630 {
21391631`string` key: "experimental_network.managed_allowed_domains_only",
21401632 type: "boolean",
21411633Details description:
21421634 "When `true`, only administrator-managed allow rules remain effective while sandboxed networking requirements are active; user allowlist additions are ignored. Without managed allow rules, user-added domain allow rules do not remain effective.",
21431635Optional non-empty rationale surfaced in approval prompts or rejection messages. },
21441636 {
21451637Key key: "experimental_network.unix_sockets",
21461638 type: "map<string, allow | none>",
21471639`rules.prefix_rules[].pattern` description:
21481640 "Administrator-managed Unix socket policy for sandboxed networking.",
21491641Type / Values },
21501642 {
21511643`array<table>` key: "experimental_network.allow_local_binding",
21521644 type: "boolean",
21531645Details description:
21541646 "Permit broader local/private-network access for sandboxed networking. Exact local IP literal or `localhost` allow rules can still permit specific local targets when this stays `false`.",
21551647Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`. },
21561648 {
21571649Key key: "hooks",
21581650 type: "table",
21591651`rules.prefix_rules[].pattern[].any_of` description:
21601652 "Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`.",
21611653Type / Values },
21621654 {
21631655`array<string>` key: "hooks.managed_dir",
21641656 type: "string (absolute path)",
21651657Details description:
21661658 "Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks.",
21671659A list of allowed alternative tokens at this position. },
21681660 {
21691661Key key: "hooks.windows_managed_dir",
21701662 type: "string (absolute path)",
21711663`rules.prefix_rules[].pattern[].token` description:
21721664 "Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks.",
21731665Type / Values },
21741666 {
21751667`string` key: "hooks.<Event>",
21761668 type: "array<table>",
21771669Details description:
21781670 "Matcher groups for a hook event such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, or `Stop`.",
21791671A single literal token at this position. },
21801672 {
21811673Expand to view all key: "hooks.<Event>[].hooks",
1674 type: "array<table>",
1675 description:
1676 "Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped.",
1677 },
1678 {
1679 key: "permissions.filesystem.deny_read",
1680 type: "array<string>",
1681 description:
1682 "Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config.",
1683 },
1684 {
1685 key: "mcp_servers",
1686 type: "table",
1687 description:
1688 "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.",
1689 },
1690 {
1691 key: "mcp_servers.<id>.identity",
1692 type: "table",
1693 description:
1694 "Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP).",
1695 },
1696 {
1697 key: "mcp_servers.<id>.identity.command",
1698 type: "string",
1699 description:
1700 "Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command.",
1701 },
1702 {
1703 key: "mcp_servers.<id>.identity.url",
1704 type: "string",
1705 description:
1706 "Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL.",
1707 },
1708 {
1709 key: "rules",
1710 type: "table",
1711 description:
1712 "Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive.",
1713 },
1714 {
1715 key: "rules.prefix_rules",
1716 type: "array<table>",
1717 description:
1718 "List of enforced prefix rules. Each rule must include `pattern` and `decision`.",
1719 },
1720 {
1721 key: "rules.prefix_rules[].pattern",
1722 type: "array<table>",
1723 description:
1724 "Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`.",
1725 },
1726 {
1727 key: "rules.prefix_rules[].pattern[].token",
1728 type: "string",
1729 description: "A single literal token at this position.",
1730 },
1731 {
1732 key: "rules.prefix_rules[].pattern[].any_of",
1733 type: "array<string>",
1734 description: "A list of allowed alternative tokens at this position.",
1735 },
1736 {
1737 key: "rules.prefix_rules[].decision",
1738 type: "prompt | forbidden",
1739 description:
1740 "Required. Requirements rules can only prompt or forbid (not allow).",
1741 },
1742 {
1743 key: "rules.prefix_rules[].justification",
1744 type: "string",
1745 description:
1746 "Optional non-empty rationale surfaced in approval prompts or rejection messages.",
1747 },
1748 ]}
1749 client:load
1750/>