config-reference.md +1719 −2413
6 6
7User-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.7User-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.
8 8
99For 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).Project-scoped config can't override machine-local provider, auth,
1010 notification, profile, or telemetry routing keys. Codex ignores
1111| Key | Type / Values | Details |`openai_base_url`, `chatgpt_base_url`, `model_provider`, `model_providers`,
1212| --- | --- | --- |`notify`, `profile`, `profiles`, `experimental_realtime_ws_base_url`, and
1313| `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. |`otel` when they appear in a project-local `.codex/config.toml`; put those in
1414| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |user-level config instead.
15| `agents.job_max_runtime_seconds` | `number` | Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker. |
16| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |
17| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |
18| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |
19| `approval_policy` | `untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to 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. |
20| `approval_policy.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |
21| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |
22| `approval_policy.reject.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are auto-rejected. |
23| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |
24| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |
25| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |
26| `apps.<id>.default_tools_approval_mode` | `auto | prompt | approve` | Default approval behavior for tools in this app unless a per-tool override exists. |
27| `apps.<id>.default_tools_enabled` | `boolean` | Default enabled state for tools in this app unless a per-tool override exists. |
28| `apps.<id>.destructive_enabled` | `boolean` | Allow or block tools in this app that advertise `destructive_hint = true`. |
29| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |
30| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |
31| `apps.<id>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. |
32| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |
33| `background_terminal_max_timeout` | `number` | Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key. |
34| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |
35| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |
36| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |
37| `compact_prompt` | `string` | Inline override for the history compaction prompt. |
38| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |
39| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |
40| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |
41| `experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`. |
42| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |
43| `features.apply_patch_freeform` | `boolean` | Expose the freeform `apply_patch` tool (experimental). |
44| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |
45| `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). |
46| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |
47| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |
48| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default). |
49| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |
50| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |
51| `features.remote_models` | `boolean` | Refresh remote model list before showing readiness (experimental). |
52| `features.request_rule` | `boolean` | Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default). |
53| `features.runtime_metrics` | `boolean` | Show runtime metrics summary in TUI turn separators (experimental). |
54| `features.search_tool` | `boolean` | Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental). |
55| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (beta). |
56| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |
57| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (beta). |
58| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |
59| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |
60| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |
61| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |
62| `feedback.enabled` | `boolean` | Enable feedback submission via `/feedback` across Codex surfaces (default: true). |
63| `file_opener` | `vscode | vscode-insiders | windsurf | cursor | none` | URI scheme used to open citations from Codex output (default: `vscode`). |
64| `forced_chatgpt_workspace_id` | `string (uuid)` | Limit ChatGPT logins to a specific workspace identifier. |
65| `forced_login_method` | `chatgpt | api` | Restrict Codex to a specific authentication method. |
66| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |
67| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |
68| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |
69| `include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |
70| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |
71| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |
72| `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. |
73| `mcp_oauth_callback_url` | `string` | Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port. |
74| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |
75| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |
76| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |
77| `mcp_servers.<id>.command` | `string` | Launcher command for an MCP stdio server. |
78| `mcp_servers.<id>.cwd` | `string` | Working directory for the MCP stdio server process. |
79| `mcp_servers.<id>.disabled_tools` | `array<string>` | Deny list applied after `enabled_tools` for the MCP server. |
80| `mcp_servers.<id>.enabled` | `boolean` | Disable an MCP server without removing its configuration. |
81| `mcp_servers.<id>.enabled_tools` | `array<string>` | Allow list of tool names exposed by the MCP server. |
82| `mcp_servers.<id>.env` | `map<string,string>` | Environment variables forwarded to the MCP stdio server. |
83| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |
84| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |
85| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |
86| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |
87| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |
88| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |
89| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |
90| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |
91| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |
92| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |
93| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |
94| `model_context_window` | `number` | Context window tokens available to the active model. |
95| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |
96| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |
97| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |
98| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |
99| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |
100| `model_providers.<id>.env_key_instructions` | `string` | Optional setup guidance for the provider API key. |
101| `model_providers.<id>.experimental_bearer_token` | `string` | Direct bearer token for the provider (discouraged; use `env_key`). |
102| `model_providers.<id>.http_headers` | `map<string,string>` | Static HTTP headers added to provider requests. |
103| `model_providers.<id>.name` | `string` | Display name for a custom model provider. |
104| `model_providers.<id>.query_params` | `map<string,string>` | Extra query parameters appended to provider requests. |
105| `model_providers.<id>.request_max_retries` | `number` | Retry count for HTTP requests to the provider (default: 4). |
106| `model_providers.<id>.requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). |
107| `model_providers.<id>.stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). |
108| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |
109| `model_providers.<id>.wire_api` | `chat | responses` | Protocol used by the provider (defaults to `chat` if omitted). |
110| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |
111| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |
112| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |
113| `model_verbosity` | `low | medium | high` | Control GPT-5 Responses API verbosity (defaults to `medium`). |
114| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |
115| `notice.hide_gpt-5.1-codex-max_migration_prompt` | `boolean` | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |
116| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |
117| `notice.hide_rate_limit_model_nudge` | `boolean` | Track opt-out of the rate limit model switch reminder. |
118| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |
119| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |
120| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |
121| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |
122| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |
123| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |
124| `otel.exporter.<id>.endpoint` | `string` | Exporter endpoint for OTEL logs. |
125| `otel.exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL exporter requests. |
126| `otel.exporter.<id>.protocol` | `binary | json` | Protocol used by the OTLP/HTTP exporter. |
127| `otel.exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL exporter TLS. |
128| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |
129| `otel.exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL exporter TLS. |
130| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |
131| `otel.trace_exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |
132| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |
133| `otel.trace_exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL trace exporter requests. |
134| `otel.trace_exporter.<id>.protocol` | `binary | json` | Protocol used by the OTLP/HTTP trace exporter. |
135| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |
136| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |
137| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |
138| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |
139| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |
140| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |
141| `profiles.<name>.experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |
142| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |
143| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |
144| `profiles.<name>.model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |
145| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |
146| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |
147| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |
148| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |
149| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |
150| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |
151| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers. |
152| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |
153| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |
154| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |
155| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |
156| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |
157| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |
158| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |
159| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |
160| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |
161| `shell_environment_policy.include_only` | `array<string>` | Whitelist of patterns; when set only matching variables are kept. |
162| `shell_environment_policy.inherit` | `all | core | none` | Baseline environment inheritance when spawning subprocesses. |
163| `shell_environment_policy.set` | `map<string,string>` | Explicit environment overrides injected into every subprocess. |
164| `show_raw_agent_reasoning` | `boolean` | Surface raw reasoning content when the active model emits it. |
165| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |
166| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |
167| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |
168| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |
169| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |
170| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |
171| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |
172| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |
173| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |
174| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |
175| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |
176| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |
177| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |
178| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |
179| `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. |
180| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |
181| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |
182
183Key
184
185`agents.<name>.config_file`
186
187Type / Values
188
189`string (path)`
190
191Details
192
193Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.
194
195Key
196
197`agents.<name>.description`
198
199Type / Values
200
201`string`
202
203Details
204
205Role guidance shown to Codex when choosing and spawning that agent type.
206
207Key
208
209`agents.job_max_runtime_seconds`
210
211Type / Values
212
213`number`
214
215Details
216
217Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.
218
219Key
220
221`agents.max_depth`
222
223Type / Values
224
225`number`
226
227Details
228
229Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).
230
231Key
232
233`agents.max_threads`
234
235Type / Values
236
237`number`
238
239Details
240
241Maximum number of agent threads that can be open concurrently.
242
243Key
244
245`allow_login_shell`
246
247Type / Values
248
249`boolean`
250
251Details
252
253Allow 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.
254
255Key
256
257`approval_policy`
258
259Type / Values
260
261`untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }`
262
263Details
264
265Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to 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.
266
267Key
268
269`approval_policy.reject.mcp_elicitations`
270
271Type / Values
272
273`boolean`
274
275Details
276
277When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.
278
279Key
280
281`approval_policy.reject.rules`
282
283Type / Values
284
285`boolean`
286
287Details
288
289When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.
290
291Key
292
293`approval_policy.reject.sandbox_approval`
294
295Type / Values
296
297`boolean`
298
299Details
300
301When `true`, sandbox escalation approval prompts are auto-rejected.
302
303Key
304
305`apps._default.destructive_enabled`
306
307Type / Values
308
309`boolean`
310
311Details
312
313Default allow/deny for app tools with `destructive_hint = true`.
314
315Key
316
317`apps._default.enabled`
318
319Type / Values
320
321`boolean`
322
323Details
324
325Default app enabled state for all apps unless overridden per app.
326
327Key
328
329`apps._default.open_world_enabled`
330
331Type / Values
332
333`boolean`
334
335Details
336
337Default allow/deny for app tools with `open_world_hint = true`.
338
339Key
340
341`apps.<id>.default_tools_approval_mode`
342
343Type / Values
344
345`auto | prompt | approve`
346
347Details
348
349Default approval behavior for tools in this app unless a per-tool override exists.
350
351Key
352
353`apps.<id>.default_tools_enabled`
354
355Type / Values
356
357`boolean`
358
359Details
360
361Default enabled state for tools in this app unless a per-tool override exists.
362
363Key
364
365`apps.<id>.destructive_enabled`
366
367Type / Values
368
369`boolean`
370
371Details
372
373Allow or block tools in this app that advertise `destructive_hint = true`.
374
375Key
376
377`apps.<id>.enabled`
378
379Type / Values
380
381`boolean`
382
383Details
384
385Enable or disable a specific app/connector by id (default: true).
386
387Key
388
389`apps.<id>.open_world_enabled`
390
391Type / Values
392
393`boolean`
394
395Details
396
397Allow or block tools in this app that advertise `open_world_hint = true`.
398
399Key
400
401`apps.<id>.tools.<tool>.approval_mode`
402
403Type / Values
404
405`auto | prompt | approve`
406
407Details
408
409Per-tool approval behavior override for a single app tool.
410
411Key
412
413`apps.<id>.tools.<tool>.enabled`
414
415Type / Values
416
417`boolean`
418
419Details
420
421Per-tool enabled override for an app tool (for example `repos/list`).
422
423Key
424
425`background_terminal_max_timeout`
426
427Type / Values
428
429`number`
430
431Details
432
433Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.
434
435Key
436
437`chatgpt_base_url`
438
439Type / Values
440
441`string`
442
443Details
444
445Override the base URL used during the ChatGPT login flow.
446
447Key
448
449`check_for_update_on_startup`
450
451Type / Values
452
453`boolean`
454
455Details
456
457Check for Codex updates on startup (set to false only when updates are centrally managed).
458
459Key
460
461`cli_auth_credentials_store`
462
463Type / Values
464
465`file | keyring | auto`
466
467Details
468
469Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).
470
471Key
472
473`compact_prompt`
474
475Type / Values
476
477`string`
478
479Details
480
481Inline override for the history compaction prompt.
482
483Key
484
485`developer_instructions`
486
487Type / Values
488
489`string`
490
491Details
492
493Additional developer instructions injected into the session (optional).
494
495Key
496
497`disable_paste_burst`
498
499Type / Values
500
501`boolean`
502
503Details
504
505Disable burst-paste detection in the TUI.
506
507Key
508
509`experimental_compact_prompt_file`
510
511Type / Values
512
513`string (path)`
514
515Details
516
517Load the compaction prompt override from a file (experimental).
518
519Key
520
521`experimental_use_freeform_apply_patch`
522
523Type / Values
524
525`boolean`
526
527Details
528
529Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.
530
531Key
532
533`experimental_use_unified_exec_tool`
534
535Type / Values
536
537`boolean`
538
539Details
540
541Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.
542
543Key
544
545`features.apply_patch_freeform`
546
547Type / Values
548
549`boolean`
550
551Details
552
553Expose the freeform `apply_patch` tool (experimental).
554
555Key
556
557`features.apps`
558
559Type / Values
560
561`boolean`
562
563Details
564
565Enable ChatGPT Apps/connectors support (experimental).
566
567Key
568
569`features.apps_mcp_gateway`
570
571Type / Values
572
573`boolean`
574
575Details
576
577Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).
578
579Key
580
581`features.child_agents_md`
582
583Type / Values
584
585`boolean`
586
587Details
588
589Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).
590
591Key
592
593`features.collaboration_modes`
594
595Type / Values
596
597`boolean`
598
599Details
600
601Enable collaboration modes such as plan mode (stable; on by default).
602
603Key
604
605`features.multi_agent`
606
607Type / Values
608
609`boolean`
610
611Details
612
613Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default).
614
615Key
616
617`features.personality`
618
619Type / Values
620
621`boolean`
622
623Details
624
625Enable personality selection controls (stable; on by default).
626
627Key
628
629`features.powershell_utf8`
630
631Type / Values
632
633`boolean`
634
635Details
636
637Force PowerShell UTF-8 output (defaults to true).
638
639Key
640
641`features.remote_models`
642
643Type / Values
644
645`boolean`
646
647Details
648
649Refresh remote model list before showing readiness (experimental).
650
651Key
652
653`features.request_rule`
654
655Type / Values
656
657`boolean`
658
659Details
660
661Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).
662
663Key
664
665`features.runtime_metrics`
666
667Type / Values
668
669`boolean`
670
671Details
672
673Show runtime metrics summary in TUI turn separators (experimental).
674
675Key
676
677`features.search_tool`
678
679Type / Values
680
681`boolean`
682
683Details
684
685Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).
686
687Key
688
689`features.shell_snapshot`
690
691Type / Values
692
693`boolean`
694
695Details
696
697Snapshot shell environment to speed up repeated commands (beta).
698
699Key
700
701`features.shell_tool`
702
703Type / Values
704
705`boolean`
706
707Details
708
709Enable the default `shell` tool for running commands (stable; on by default).
710
711Key
712
713`features.unified_exec`
714
715Type / Values
716
717`boolean`
718
719Details
720
721Use the unified PTY-backed exec tool (beta).
722
723Key
724
725`features.use_linux_sandbox_bwrap`
726
727Type / Values
728
729`boolean`
730
731Details
732
733Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).
734
735Key
736
737`features.web_search`
738
739Type / Values
740
741`boolean`
742
743Details
744
745Deprecated legacy toggle; prefer the top-level `web_search` setting.
746
747Key
748
749`features.web_search_cached`
750
751Type / Values
752
753`boolean`
754
755Details
756
757Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.
758
759Key
760
761`features.web_search_request`
762
763Type / Values
764
765`boolean`
766
767Details
768
769Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.
770
771Key
772
773`feedback.enabled`
774
775Type / Values
776
777`boolean`
778
779Details
780
781Enable feedback submission via `/feedback` across Codex surfaces (default: true).
782
783Key
784
785`file_opener`
786
787Type / Values
788
789`vscode | vscode-insiders | windsurf | cursor | none`
790
791Details
792
793URI scheme used to open citations from Codex output (default: `vscode`).
794
795Key
796
797`forced_chatgpt_workspace_id`
798
799Type / Values
800
801`string (uuid)`
802
803Details
804
805Limit ChatGPT logins to a specific workspace identifier.
806
807Key
808
809`forced_login_method`
810
811Type / Values
812
813`chatgpt | api`
814
815Details
816
817Restrict Codex to a specific authentication method.
818
819Key
820
821`hide_agent_reasoning`
822
823Type / Values
824
825`boolean`
826
827Details
828
829Suppress reasoning events in both the TUI and `codex exec` output.
830
831Key
832
833`history.max_bytes`
834
835Type / Values
836
837`number`
838
839Details
840
841If set, caps the history file size in bytes by dropping oldest entries.
842
843Key
844
845`history.persistence`
846
847Type / Values
848
849`save-all | none`
850
851Details
852
853Control whether Codex saves session transcripts to history.jsonl.
854
855Key
856
857`include_apply_patch_tool`
858
859Type / Values
860
861`boolean`
862
863Details
864
865Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.
866
867Key
868
869`instructions`
870
871Type / Values
872
873`string`
874
875Details
876
877Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.
878
879Key
880
881`log_dir`
882
883Type / Values
884
885`string (path)`
886
887Details
888
889Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.
890
891Key
892
893`mcp_oauth_callback_port`
894
895Type / Values
896
897`integer`
898
899Details
900
901Optional 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.
902
903Key
904
905`mcp_oauth_callback_url`
906
907Type / Values
908
909`string`
910
911Details
912
913Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.
914
915Key
916
917`mcp_oauth_credentials_store`
918
919Type / Values
920
921`auto | file | keyring`
922
923Details
924
925Preferred store for MCP OAuth credentials.
926
927Key
928
929`mcp_servers.<id>.args`
930
931Type / Values
932
933`array<string>`
934
935Details
936
937Arguments passed to the MCP stdio server command.
938
939Key
940
941`mcp_servers.<id>.bearer_token_env_var`
942
943Type / Values
944
945`string`
946
947Details
948
949Environment variable sourcing the bearer token for an MCP HTTP server.
950
951Key
952
953`mcp_servers.<id>.command`
954
955Type / Values
956
957`string`
958
959Details
960
961Launcher command for an MCP stdio server.
962
963Key
964
965`mcp_servers.<id>.cwd`
966
967Type / Values
968
969`string`
970
971Details
972
973Working directory for the MCP stdio server process.
974
975Key
976
977`mcp_servers.<id>.disabled_tools`
978
979Type / Values
980
981`array<string>`
982
983Details
984
985Deny list applied after `enabled_tools` for the MCP server.
986
987Key
988
989`mcp_servers.<id>.enabled`
990
991Type / Values
992
993`boolean`
994
995Details
996
997Disable an MCP server without removing its configuration.
998
999Key
1000
1001`mcp_servers.<id>.enabled_tools`
1002
1003Type / Values
1004
1005`array<string>`
1006
1007Details
1008
1009Allow list of tool names exposed by the MCP server.
1010
1011Key
1012
1013`mcp_servers.<id>.env`
1014
1015Type / Values
1016
1017`map<string,string>`
1018
1019Details
1020
1021Environment variables forwarded to the MCP stdio server.
1022
1023Key
1024
1025`mcp_servers.<id>.env_http_headers`
1026
1027Type / Values
1028
1029`map<string,string>`
1030
1031Details
1032
1033HTTP headers populated from environment variables for an MCP HTTP server.
1034
1035Key
1036
1037`mcp_servers.<id>.env_vars`
1038
1039Type / Values
1040
1041`array<string>`
1042
1043Details
1044
1045Additional environment variables to whitelist for an MCP stdio server.
1046
1047Key
1048
1049`mcp_servers.<id>.http_headers`
1050
1051Type / Values
1052
1053`map<string,string>`
1054
1055Details
1056
1057Static HTTP headers included with each MCP HTTP request.
1058
1059Key
1060
1061`mcp_servers.<id>.required`
1062
1063Type / Values
1064
1065`boolean`
1066
1067Details
1068
1069When true, fail startup/resume if this enabled MCP server cannot initialize.
1070
1071Key
1072
1073`mcp_servers.<id>.startup_timeout_ms`
1074
1075Type / Values
1076
1077`number`
1078
1079Details
1080
1081Alias for `startup_timeout_sec` in milliseconds.
1082
1083Key
1084
1085`mcp_servers.<id>.startup_timeout_sec`
1086
1087Type / Values
1088
1089`number`
1090
1091Details
1092
1093Override the default 10s startup timeout for an MCP server.
1094
1095Key
1096
1097`mcp_servers.<id>.tool_timeout_sec`
1098
1099Type / Values
1100
1101`number`
1102
1103Details
1104
1105Override the default 60s per-tool timeout for an MCP server.
1106
1107Key
1108
1109`mcp_servers.<id>.url`
1110
1111Type / Values
1112
1113`string`
1114
1115Details
1116
1117Endpoint for an MCP streamable HTTP server.
1118
1119Key
1120
1121`model`
1122
1123Type / Values
1124
1125`string`
1126
1127Details
1128
1129Model to use (e.g., `gpt-5-codex`).
1130
1131Key
1132
1133`model_auto_compact_token_limit`
1134
1135Type / Values
1136
1137`number`
1138
1139Details
1140
1141Token threshold that triggers automatic history compaction (unset uses model defaults).
1142
1143Key
1144
1145`model_catalog_json`
1146
1147Type / Values
1148
1149`string (path)`
1150
1151Details
1152
1153Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.
1154
1155Key
1156
1157`model_context_window`
1158
1159Type / Values
1160
1161`number`
1162
1163Details
1164
1165Context window tokens available to the active model.
1166
1167Key
1168
1169`model_instructions_file`
1170
1171Type / Values
1172
1173`string (path)`
1174
1175Details
1176
1177Replacement for built-in instructions instead of `AGENTS.md`.
1178
1179Key
1180
1181`model_provider`
1182
1183Type / Values
1184
1185`string`
1186
1187Details
1188
1189Provider id from `model_providers` (default: `openai`).
1190
1191Key
1192
1193`model_providers.<id>.base_url`
1194
1195Type / Values
1196
1197`string`
1198
1199Details
1200
1201API base URL for the model provider.
1202
1203Key
1204
1205`model_providers.<id>.env_http_headers`
1206
1207Type / Values
1208
1209`map<string,string>`
1210
1211Details
1212
1213HTTP headers populated from environment variables when present.
1214
1215Key
1216
1217`model_providers.<id>.env_key`
1218
1219Type / Values
1220
1221`string`
1222
1223Details
1224
1225Environment variable supplying the provider API key.
1226
1227Key
1228
1229`model_providers.<id>.env_key_instructions`
1230
1231Type / Values
1232
1233`string`
1234
1235Details
1236
1237Optional setup guidance for the provider API key.
1238
1239Key
1240
1241`model_providers.<id>.experimental_bearer_token`
1242
1243Type / Values
1244
1245`string`
1246
1247Details
1248
1249Direct bearer token for the provider (discouraged; use `env_key`).
1250
1251Key
1252
1253`model_providers.<id>.http_headers`
1254
1255Type / Values
1256
1257`map<string,string>`
1258
1259Details
1260
1261Static HTTP headers added to provider requests.
1262
1263Key
1264
1265`model_providers.<id>.name`
1266
1267Type / Values
1268
1269`string`
1270
1271Details
1272
1273Display name for a custom model provider.
1274
1275Key
1276
1277`model_providers.<id>.query_params`
1278
1279Type / Values
1280
1281`map<string,string>`
1282
1283Details
1284
1285Extra query parameters appended to provider requests.
1286
1287Key
1288
1289`model_providers.<id>.request_max_retries`
1290
1291Type / Values
1292
1293`number`
1294
1295Details
1296
1297Retry count for HTTP requests to the provider (default: 4).
1298
1299Key
1300
1301`model_providers.<id>.requires_openai_auth`
1302
1303Type / Values
1304
1305`boolean`
1306
1307Details
1308
1309The provider uses OpenAI authentication (defaults to false).
1310
1311Key
1312
1313`model_providers.<id>.stream_idle_timeout_ms`
1314
1315Type / Values
1316
1317`number`
1318
1319Details
1320
1321Idle timeout for SSE streams in milliseconds (default: 300000).
1322
1323Key
1324
1325`model_providers.<id>.stream_max_retries`
1326
1327Type / Values
1328
1329`number`
1330
1331Details
1332
1333Retry count for SSE streaming interruptions (default: 5).
1334
1335Key
1336
1337`model_providers.<id>.wire_api`
1338
1339Type / Values
1340
1341`chat | responses`
1342
1343Details
1344
1345Protocol used by the provider (defaults to `chat` if omitted).
1346
1347Key
1348
1349`model_reasoning_effort`
1350
1351Type / Values
1352
1353`minimal | low | medium | high | xhigh`
1354
1355Details
1356
1357Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).
1358
1359Key
1360
1361`model_reasoning_summary`
1362
1363Type / Values
1364
1365`auto | concise | detailed | none`
1366
1367Details
1368
1369Select reasoning summary detail or disable summaries entirely.
1370
1371Key
1372
1373`model_supports_reasoning_summaries`
1374
1375Type / Values
1376
1377`boolean`
1378
1379Details
1380
1381Force Codex to send or not send reasoning metadata.
1382
1383Key
1384
1385`model_verbosity`
1386
1387Type / Values
1388
1389`low | medium | high`
1390
1391Details
1392
1393Control GPT-5 Responses API verbosity (defaults to `medium`).
1394
1395Key
1396
1397`notice.hide_full_access_warning`
1398
1399Type / Values
1400
1401`boolean`
1402
1403Details
1404
1405Track acknowledgement of the full access warning prompt.
1406
1407Key
1408
1409`notice.hide_gpt-5.1-codex-max_migration_prompt`
1410
1411Type / Values
1412
1413`boolean`
1414
1415Details
1416
1417Track acknowledgement of the gpt-5.1-codex-max migration prompt.
1418
1419Key
1420
1421`notice.hide_gpt5_1_migration_prompt`
1422
1423Type / Values
1424
1425`boolean`
1426
1427Details
1428
1429Track acknowledgement of the GPT-5.1 migration prompt.
1430
1431Key
1432
1433`notice.hide_rate_limit_model_nudge`
1434
1435Type / Values
1436
1437`boolean`
1438
1439Details
1440
1441Track opt-out of the rate limit model switch reminder.
1442
1443Key
1444
1445`notice.hide_world_writable_warning`
1446
1447Type / Values
1448
1449`boolean`
1450
1451Details
1452
1453Track acknowledgement of the Windows world-writable directories warning.
1454
1455Key
1456
1457`notice.model_migrations`
1458
1459Type / Values
1460
1461`map<string,string>`
1462
1463Details
1464
1465Track acknowledged model migrations as old->new mappings.
1466
1467Key
1468
1469`notify`
1470
1471Type / Values
1472
1473`array<string>`
1474
1475Details
1476
1477Command invoked for notifications; receives a JSON payload from Codex.
1478
1479Key
1480
1481`oss_provider`
1482
1483Type / Values
1484
1485`lmstudio | ollama`
1486
1487Details
1488
1489Default local provider used when running with `--oss` (defaults to prompting if unset).
1490
1491Key
1492
1493`otel.environment`
1494
1495Type / Values
1496
1497`string`
1498
1499Details
1500
1501Environment tag applied to emitted OpenTelemetry events (default: `dev`).
1502
1503Key
1504
1505`otel.exporter`
1506
1507Type / Values
1508
1509`none | otlp-http | otlp-grpc`
1510
1511Details
1512
1513Select the OpenTelemetry exporter and provide any endpoint metadata.
1514
1515Key
1516
1517`otel.exporter.<id>.endpoint`
1518
1519Type / Values
1520
1521`string`
1522
1523Details
1524
1525Exporter endpoint for OTEL logs.
1526
1527Key
1528
1529`otel.exporter.<id>.headers`
1530
1531Type / Values
1532
1533`map<string,string>`
1534
1535Details
1536
1537Static headers included with OTEL exporter requests.
1538
1539Key
1540
1541`otel.exporter.<id>.protocol`
1542
1543Type / Values
1544
1545`binary | json`
1546
1547Details
1548
1549Protocol used by the OTLP/HTTP exporter.
1550
1551Key
1552
1553`otel.exporter.<id>.tls.ca-certificate`
1554
1555Type / Values
1556
1557`string`
1558
1559Details
1560
1561CA certificate path for OTEL exporter TLS.
1562
1563Key
1564
1565`otel.exporter.<id>.tls.client-certificate`
1566
1567Type / Values
1568
1569`string`
1570
1571Details
1572
1573Client certificate path for OTEL exporter TLS.
1574
1575Key
1576
1577`otel.exporter.<id>.tls.client-private-key`
1578
1579Type / Values
1580
1581`string`
1582
1583Details
1584
1585Client private key path for OTEL exporter TLS.
1586
1587Key
1588
1589`otel.log_user_prompt`
1590
1591Type / Values
1592
1593`boolean`
1594
1595Details
1596
1597Opt in to exporting raw user prompts with OpenTelemetry logs.
1598
1599Key
1600
1601`otel.trace_exporter`
1602
1603Type / Values
1604
1605`none | otlp-http | otlp-grpc`
1606
1607Details
1608
1609Select the OpenTelemetry trace exporter and provide any endpoint metadata.
1610
1611Key
1612
1613`otel.trace_exporter.<id>.endpoint`
1614
1615Type / Values
1616
1617`string`
1618
1619Details
1620
1621Trace exporter endpoint for OTEL logs.
1622
1623Key
1624
1625`otel.trace_exporter.<id>.headers`
1626
1627Type / Values
1628
1629`map<string,string>`
1630
1631Details
1632
1633Static headers included with OTEL trace exporter requests.
1634
1635Key
1636
1637`otel.trace_exporter.<id>.protocol`
1638
1639Type / Values
1640
1641`binary | json`
1642
1643Details
1644
1645Protocol used by the OTLP/HTTP trace exporter.
1646
1647Key
1648
1649`otel.trace_exporter.<id>.tls.ca-certificate`
1650
1651Type / Values
1652
1653`string`
1654
1655Details
1656
1657CA certificate path for OTEL trace exporter TLS.
1658
1659Key
1660
1661`otel.trace_exporter.<id>.tls.client-certificate`
1662
1663Type / Values
1664
1665`string`
1666
1667Details
1668
1669Client certificate path for OTEL trace exporter TLS.
1670
1671Key
1672
1673`otel.trace_exporter.<id>.tls.client-private-key`
1674
1675Type / Values
1676
1677`string`
1678
1679Details
1680
1681Client private key path for OTEL trace exporter TLS.
1682
1683Key
1684
1685`personality`
1686
1687Type / Values
1688
1689`none | friendly | pragmatic`
1690
1691Details
1692
1693Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.
1694
1695Key
1696
1697`profile`
1698
1699Type / Values
1700
1701`string`
1702
1703Details
1704
1705Default profile applied at startup (equivalent to `--profile`).
1706
1707Key
1708
1709`profiles.<name>.*`
1710
1711Type / Values
1712
1713`various`
1714
1715Details
1716
1717Profile-scoped overrides for any of the supported configuration keys.
1718
1719Key
1720
1721`profiles.<name>.experimental_use_freeform_apply_patch`
1722
1723Type / Values
1724
1725`boolean`
1726
1727Details
1728
1729Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.
1730
1731Key
1732
1733`profiles.<name>.experimental_use_unified_exec_tool`
1734
1735Type / Values
1736
1737`boolean`
1738
1739Details
1740
1741Legacy name for enabling unified exec; prefer `[features].unified_exec`.
1742
1743Key
1744
1745`profiles.<name>.include_apply_patch_tool`
1746
1747Type / Values
1748
1749`boolean`
1750
1751Details
1752
1753Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.
1754
1755Key
1756
1757`profiles.<name>.model_catalog_json`
1758
1759Type / Values
1760
1761`string (path)`
1762
1763Details
1764
1765Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).
1766
1767Key
1768
1769`profiles.<name>.oss_provider`
1770
1771Type / Values
1772
1773`lmstudio | ollama`
1774
1775Details
1776
1777Profile-scoped OSS provider for `--oss` sessions.
1778
1779Key
1780
1781`profiles.<name>.personality`
1782
1783Type / Values
1784
1785`none | friendly | pragmatic`
1786
1787Details
1788
1789Profile-scoped communication style override for supported models.
1790
1791Key
1792
1793`profiles.<name>.web_search`
1794
1795Type / Values
1796
1797`disabled | cached | live`
1798
1799Details
1800
1801Profile-scoped web search mode override (default: `"cached"`).
1802
1803Key
1804
1805`project_doc_fallback_filenames`
1806
1807Type / Values
1808
1809`array<string>`
1810
1811Details
1812
1813Additional filenames to try when `AGENTS.md` is missing.
1814
1815Key
1816
1817`project_doc_max_bytes`
1818
1819Type / Values
1820
1821`number`
1822
1823Details
1824
1825Maximum bytes read from `AGENTS.md` when building project instructions.
1826
1827Key
1828
1829`project_root_markers`
1830
1831Type / Values
1832
1833`array<string>`
1834
1835Details
1836
1837List of project root marker filenames; used when searching parent directories for the project root.
1838
1839Key
1840
1841`projects.<path>.trust_level`
1842
1843Type / Values
1844
1845`string`
1846
1847Details
1848
1849Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers.
1850
1851Key
1852
1853`review_model`
1854
1855Type / Values
1856
1857`string`
1858
1859Details
1860
1861Optional model override used by `/review` (defaults to the current session model).
1862
1863Key
1864
1865`sandbox_mode`
1866
1867Type / Values
1868
1869`read-only | workspace-write | danger-full-access`
1870
1871Details
1872
1873Sandbox policy for filesystem and network access during command execution.
1874
1875Key
1876
1877`sandbox_workspace_write.exclude_slash_tmp`
1878
1879Type / Values
1880
1881`boolean`
1882
1883Details
1884
1885Exclude `/tmp` from writable roots in workspace-write mode.
1886
1887Key
1888
1889`sandbox_workspace_write.exclude_tmpdir_env_var`
1890
1891Type / Values
1892 15
189316`boolean`For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).
1894
1895Details
1896
1897Exclude `$TMPDIR` from writable roots in workspace-write mode.
1898
1899Key
1900
1901`sandbox_workspace_write.network_access`
1902
1903Type / Values
1904
1905`boolean`
1906
1907Details
1908
1909Allow outbound network access inside the workspace-write sandbox.
1910
1911Key
1912
1913`sandbox_workspace_write.writable_roots`
1914
1915Type / Values
1916
1917`array<string>`
1918
1919Details
1920
1921Additional writable roots when `sandbox_mode = "workspace-write"`.
1922
1923Key
1924
1925`shell_environment_policy.exclude`
1926
1927Type / Values
1928
1929`array<string>`
1930
1931Details
1932
1933Glob patterns for removing environment variables after the defaults.
1934
1935Key
1936
1937`shell_environment_policy.experimental_use_profile`
1938
1939Type / Values
1940
1941`boolean`
1942
1943Details
1944
1945Use the user shell profile when spawning subprocesses.
1946
1947Key
1948
1949`shell_environment_policy.ignore_default_excludes`
1950
1951Type / Values
1952
1953`boolean`
1954
1955Details
1956
1957Keep variables containing KEY/SECRET/TOKEN before other filters run.
1958
1959Key
1960
1961`shell_environment_policy.include_only`
1962
1963Type / Values
1964
1965`array<string>`
1966
1967Details
1968
1969Whitelist of patterns; when set only matching variables are kept.
1970
1971Key
1972
1973`shell_environment_policy.inherit`
1974
1975Type / Values
1976
1977`all | core | none`
1978
1979Details
1980
1981Baseline environment inheritance when spawning subprocesses.
1982
1983Key
1984
1985`shell_environment_policy.set`
1986
1987Type / Values
1988
1989`map<string,string>`
1990
1991Details
1992
1993Explicit environment overrides injected into every subprocess.
1994
1995Key
1996
1997`show_raw_agent_reasoning`
1998
1999Type / Values
2000
2001`boolean`
2002
2003Details
2004
2005Surface raw reasoning content when the active model emits it.
2006
2007Key
2008
2009`skills.config`
2010
2011Type / Values
2012
2013`array<object>`
2014
2015Details
2016
2017Per-skill enablement overrides stored in config.toml.
2018
2019Key
2020
2021`skills.config.<index>.enabled`
2022
2023Type / Values
2024
2025`boolean`
2026
2027Details
2028
2029Enable or disable the referenced skill.
2030
2031Key
2032
2033`skills.config.<index>.path`
2034
2035Type / Values
2036
2037`string (path)`
2038
2039Details
2040
2041Path to a skill folder containing `SKILL.md`.
2042
2043Key
2044
2045`sqlite_home`
2046
2047Type / Values
2048
2049`string (path)`
2050
2051Details
2052
2053Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.
2054
2055Key
2056
2057`suppress_unstable_features_warning`
2058
2059Type / Values
2060
2061`boolean`
2062
2063Details
2064
2065Suppress the warning that appears when under-development feature flags are enabled.
2066
2067Key
2068
2069`tool_output_token_limit`
2070
2071Type / Values
2072
2073`number`
2074
2075Details
2076
2077Token budget for storing individual tool/function outputs in history.
2078
2079Key
2080
2081`tools.web_search`
2082
2083Type / Values
2084
2085`boolean`
2086
2087Details
2088
2089Deprecated legacy toggle for web search; prefer the top-level `web_search` setting.
2090
2091Key
2092
2093`tui`
2094
2095Type / Values
2096
2097`table`
2098
2099Details
2100
2101TUI-specific options such as enabling inline desktop notifications.
2102
2103Key
2104
2105`tui.alternate_screen`
2106
2107Type / Values
2108
2109`auto | always | never`
2110
2111Details
2112
2113Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).
2114
2115Key
2116
2117`tui.animations`
2118
2119Type / Values
2120
2121`boolean`
2122
2123Details
2124
2125Enable terminal animations (welcome screen, shimmer, spinner) (default: true).
2126
2127Key
2128
2129`tui.notification_method`
2130
2131Type / Values
2132
2133`auto | osc9 | bel`
2134
2135Details
2136
2137Notification method for unfocused terminal notifications (default: auto).
2138
2139Key
2140
2141`tui.notifications`
2142
2143Type / Values
2144
2145`boolean | array<string>`
2146
2147Details
2148
2149Enable TUI notifications; optionally restrict to specific event types.
2150
2151Key
2152
2153`tui.show_tooltips`
2154
2155Type / Values
2156
2157`boolean`
2158
2159Details
2160
2161Show onboarding tooltips in the TUI welcome screen (default: true).
2162
2163Key
2164
2165`tui.status_line`
2166
2167Type / Values
2168
2169`array<string> | null`
2170
2171Details
2172
2173Ordered list of TUI footer status-line item identifiers. `null` disables the status line.
2174
2175Key
2176
2177`web_search`
2178
2179Type / Values
2180
2181`disabled | cached | live`
2182
2183Details
2184
2185Web 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.
2186
2187Key
2188
2189`windows_wsl_setup_acknowledged`
2190
2191Type / Values
2192
2193`boolean`
2194
2195Details
2196
2197Track Windows onboarding acknowledgement (Windows only).
2198
2199Key
2200
2201`windows.sandbox`
2202
2203Type / Values
2204
2205`unelevated | elevated`
2206
2207Details
2208
2209Windows-only native sandbox mode when running Codex natively on Windows.
2210 17
221118Expand to view all<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/>
2212 1470
2213You 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).
2214 1472
2230Use `[features]` in `requirements.toml` to pin feature flags by the same1488Use `[features]` in `requirements.toml` to pin feature flags by the same
2231canonical keys that `config.toml` uses. Omitted keys remain unconstrained.1489canonical keys that `config.toml` uses. Omitted keys remain unconstrained.
2232 1490
22331491| Key | Type / Values | Details |<ConfigTable
22341492| --- | --- | --- | options={[
22351493| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`). | {
22361494| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. | key: "allowed_approval_policies",
22371495| `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`. | type: "array<string>",
22381496| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. | description:
22391497| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. | "Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`).",
22401498| `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. | },
22411499| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). | {
22421500| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. | key: "allowed_approvals_reviewers",
22431501| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. | type: "array<string>",
22441502| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. | description:
22451503| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. | "Allowed values for `approvals_reviewer`, such as `user` and `auto_review`.",
22461504| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). | },
22471505| `rules.prefix_rules[].justification` | `string` | Optional non-empty rationale surfaced in approval prompts or rejection messages. | {
22481506| `rules.prefix_rules[].pattern` | `array<table>` | Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`. | key: "guardian_policy_config",
22491507| `rules.prefix_rules[].pattern[].any_of` | `array<string>` | A list of allowed alternative tokens at this position. | type: "string",
22501508| `rules.prefix_rules[].pattern[].token` | `string` | A single literal token at this position. | description:
22511509 "Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored.",
22521510Key },
22531511 {
22541512`allowed_approval_policies` key: "allowed_sandbox_modes",
22551513 type: "array<string>",
22561514Type / Values description: "Allowed values for `sandbox_mode`.",
22571515 },
22581516`array<string>` {
22591517 key: "remote_sandbox_config",
22601518Details type: "array<table>",
22611519 description:
22621520Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`). "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.",
22631521 },
22641522Key {
22651523 key: "remote_sandbox_config[].hostname_patterns",
22661524`allowed_sandbox_modes` type: "array<string>",
22671525 description:
22681526Type / Values "Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character.",
22691527 },
22701528`array<string>` {
22711529 key: "remote_sandbox_config[].allowed_sandbox_modes",
22721530Details type: "array<string>",
22731531 description:
22741532Allowed values for `sandbox_mode`. "Allowed sandbox modes to apply when this host-specific entry matches.",
22751533 },
22761534Key {
22771535 key: "allowed_web_search_modes",
22781536`allowed_web_search_modes` type: "array<string>",
22791537 description:
22801538Type / Values "Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`.",
22811539 },
22821540`array<string>` {
22831541 key: "features",
22841542Details type: "table",
22851543 description:
22861544Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. "Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.",
22871545 },
22881546Key {
22891547 key: "features.<name>",
22901548`features` type: "boolean",
22911549 description:
22921550Type / Values "Require a specific canonical feature key to stay enabled or disabled.",
22931551 },
22941552`table` {
22951553 key: "features.in_app_browser",
22961554Details type: "boolean",
22971555 description:
22981556Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. "Set to `false` in `requirements.toml` to disable the in-app browser pane.",
22991557 },
23001558Key {
23011559 key: "features.browser_use",
23021560`features.<name>` type: "boolean",
23031561 description:
23041562Type / Values "Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability.",
23051563 },
23061564`boolean` {
23071565 key: "features.computer_use",
23081566Details type: "boolean",
23091567 description:
23101568Require a specific canonical feature key to stay enabled or disabled. "Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.",
23111569 },
23121570Key {
23131571 key: "experimental_network",
23141572`mcp_servers` type: "table",
23151573 description:
23161574Type / Values "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.",
23171575 },
23181576`table` {
23191577 key: "experimental_network.enabled",
23201578Details type: "boolean",
23211579 description:
23221580Allowlist 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. "Enable sandboxed networking requirements. This does not grant network access when the active sandbox keeps command networking off.",
23231581 },
23241582Key {
23251583 key: "experimental_network.http_port",
23261584`mcp_servers.<id>.identity` type: "integer",
23271585 description:
23281586Type / Values "Loopback HTTP listener port to use for `[experimental_network]` requirements.",
23291587 },
23301588`table` {
23311589 key: "experimental_network.socks_port",
23321590Details type: "integer",
23331591 description:
23341592Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). "Loopback SOCKS5 listener port to use for `[experimental_network]` requirements.",
23351593 },
23361594Key {
23371595 key: "experimental_network.allow_upstream_proxy",
23381596`mcp_servers.<id>.identity.command` type: "boolean",
23391597 description:
23401598Type / Values "Allow sandboxed networking to chain through an upstream proxy from the environment.",
23411599 },
23421600`string` {
23431601 key: "experimental_network.dangerously_allow_non_loopback_proxy",
23441602Details type: "boolean",
23451603 description:
23461604Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. "Permit non-loopback listener addresses for `[experimental_network]` requirements. Enabling it can expose listeners beyond localhost.",
23471605 },
23481606Key {
23491607 key: "experimental_network.dangerously_allow_all_unix_sockets",
23501608`mcp_servers.<id>.identity.url` type: "boolean",
23511609 description:
23521610Type / Values "Permit arbitrary Unix socket destinations instead of allowlist-only access. Use only in tightly controlled environments.",
23531611 },
23541612`string` {
23551613 key: "experimental_network.domains",
23561614Details type: "map<string, allow | deny>",
23571615 description:
23581616Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. "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`.",
23591617 },
23601618Key {
23611619 key: "experimental_network.allowed_domains",
23621620`rules` type: "array<string>",
23631621 description:
23641622Type / Values "List-shaped administrator allow rules for sandboxed networking. Do not combine this with `experimental_network.domains`.",
23651623 },
23661624`table` {
23671625 key: "experimental_network.denied_domains",
23681626Details type: "array<string>",
23691627 description:
23701628Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. "List-shaped administrator deny rules for sandboxed networking. Do not combine this with `experimental_network.domains`.",
23711629 },
23721630Key {
23731631 key: "experimental_network.managed_allowed_domains_only",
23741632`rules.prefix_rules` type: "boolean",
23751633 description:
23761634Type / Values "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.",
23771635 },
23781636`array<table>` {
23791637 key: "experimental_network.unix_sockets",
23801638Details type: "map<string, allow | none>",
23811639 description:
23821640List of enforced prefix rules. Each rule must include `pattern` and `decision`. "Administrator-managed Unix socket policy for sandboxed networking.",
23831641 },
23841642Key {
23851643 key: "experimental_network.allow_local_binding",
23861644`rules.prefix_rules[].decision` type: "boolean",
23871645 description:
23881646Type / Values "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`.",
23891647 },
23901648`prompt | forbidden` {
23911649 key: "hooks",
23921650Details type: "table",
23931651 description:
23941652Required. Requirements rules can only prompt or forbid (not allow). "Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`.",
23951653 },
23961654Key {
23971655 key: "hooks.managed_dir",
23981656`rules.prefix_rules[].justification` type: "string (absolute path)",
23991657 description:
24001658Type / Values "Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks.",
24011659 },
24021660`string` {
24031661 key: "hooks.windows_managed_dir",
24041662Details type: "string (absolute path)",
24051663 description:
24061664Optional non-empty rationale surfaced in approval prompts or rejection messages. "Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks.",
24071665 },
24081666Key {
24091667 key: "hooks.<Event>",
24101668`rules.prefix_rules[].pattern` type: "array<table>",
24111669 description:
24121670Type / Values "Matcher groups for a hook event such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, or `Stop`.",
24131671 },
24141672`array<table>` {
24151673 key: "hooks.<Event>[].hooks",
24161674Details type: "array<table>",
24171675 description:
24181676Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`. "Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped.",
24191677 },
24201678Key {
24211679 key: "permissions.filesystem.deny_read",
24221680`rules.prefix_rules[].pattern[].any_of` type: "array<string>",
24231681 description:
24241682Type / Values "Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config.",
24251683 },
24261684`array<string>` {
24271685 key: "mcp_servers",
24281686Details type: "table",
24291687 description:
24301688A list of allowed alternative tokens at this position. "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.",
24311689 },
24321690Key {
24331691 key: "mcp_servers.<id>.identity",
24341692`rules.prefix_rules[].pattern[].token` type: "table",
24351693 description:
24361694Type / Values "Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP).",
24371695 },
24381696`string` {
24391697 key: "mcp_servers.<id>.identity.command",
24401698Details type: "string",
24411699 description:
24421700A single literal token at this position. "Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command.",
24431701 },
24441702Expand to view all {
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/>