config-reference.md +272 −38
12| --- | --- | --- |12| --- | --- | --- |
13| `agents.<name>.config_file` | `string (path)` | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |13| `agents.<name>.config_file` | `string (path)` | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |
14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |
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). |
15| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |17| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |
1618| `approval_policy` | `untrusted | on-request | never` | Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. || `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. |
1719| `apps.<id>.disabled_reason` | `unknown | user` | Optional reason attached when an app/connector is disabled. || `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`. |
18| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: 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. |
19| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |34| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |
20| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |35| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |
21| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |36| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |
30| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |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). |
31| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |46| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |
32| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |47| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |
3348| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). || `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). |
34| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |
35| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |
36| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |49| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |
37| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |50| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |
38| `features.remote_models` | `boolean` | Refresh remote model list before showing readiness (experimental). |51| `features.remote_models` | `boolean` | Refresh remote model list before showing readiness (experimental). |
57| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |70| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |
58| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |71| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |
59| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |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. |
60| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |74| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |
61| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |75| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |
62| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |76| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |
76| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |90| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |
77| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |91| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |
78| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |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. |
79| `model_context_window` | `number` | Context window tokens available to the active model. |94| `model_context_window` | `number` | Context window tokens available to the active model. |
80| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |95| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |
81| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |96| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |
126| `profiles.<name>.experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |141| `profiles.<name>.experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |
127| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |142| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |
128| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |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). |
129| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |145| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |
130| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |146| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |
131| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |147| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |
149| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |165| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |
150| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |166| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |
151| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |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. |
152| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |169| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |
153| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |170| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |
154| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |171| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |
161| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |178| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |
162| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |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. |
163| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |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. |
164 182
165Key183Key
166 184
188 206
189Key207Key
190 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
191`agents.max_threads`233`agents.max_threads`
192 234
193Type / Values235Type / Values
200 242
201Key243Key
202 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
203`approval_policy`257`approval_policy`
204 258
205Type / Values259Type / Values
206 260
207261`untrusted | on-request | never``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`
208 358
209Details359Details
210 360
211361Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.Default enabled state for tools in this app unless a per-tool override exists.
212 362
213Key363Key
214 364
215365`apps.<id>.disabled_reason``apps.<id>.destructive_enabled`
216 366
217Type / Values367Type / Values
218 368
219369`unknown | user``boolean`
220 370
221Details371Details
222 372
223373Optional reason attached when an app/connector is disabled.Allow or block tools in this app that advertise `destructive_hint = true`.
224 374
225Key375Key
226 376
236 386
237Key387Key
238 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
239`chatgpt_base_url`437`chatgpt_base_url`
240 438
241Type / Values439Type / Values
404 602
405Key603Key
406 604
407`features.elevated_windows_sandbox`
408
409Type / Values
410
411`boolean`
412
413Details
414
415Enable the elevated Windows sandbox pipeline (experimental).
416
417Key
418
419`features.experimental_windows_sandbox`
420
421Type / Values
422
423`boolean`
424
425Details
426
427Run the Windows restricted-token sandbox (experimental).
428
429Key
430
431`features.multi_agent`605`features.multi_agent`
432 606
433Type / Values607Type / Values
436 610
437Details611Details
438 612
439613Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default).
440 614
441Key615Key
442 616
728 902
729Key903Key
730 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
731`mcp_oauth_credentials_store`917`mcp_oauth_credentials_store`
732 918
733Type / Values919Type / Values
956 1142
957Key1143Key
958 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
959`model_context_window`1157`model_context_window`
960 1158
961Type / Values1159Type / Values
1556 1754
1557Key1755Key
1558 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
1559`profiles.<name>.oss_provider`1769`profiles.<name>.oss_provider`
1560 1770
1561Type / Values1771Type / Values
1832 2042
1833Key2043Key
1834 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
1835`suppress_unstable_features_warning`2057`suppress_unstable_features_warning`
1836 2058
1837Type / Values2059Type / Values
1974 2196
1975Track Windows onboarding acknowledgement (Windows only).2197Track Windows onboarding acknowledgement (Windows only).
1976 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
1977Expand to view all2211Expand to view all
1978 2212
1979You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).2213You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).
1988 2222
1989## `requirements.toml`2223## `requirements.toml`
1990 2224
19912225`requirements.toml` is an admin-enforced configuration file that constrains security-sensitive settings users can’t override. For details, locations, and examples, see [Admin-enforced requirements](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).`requirements.toml` is an admin-enforced configuration file that constrains security-sensitive settings users can't override. For details, locations, and examples, see [Admin-enforced requirements](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).
1992 2226
1993For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched2227For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched
1994requirements. See the security page for precedence details.2228requirements. See the security page for precedence details.
1995 2229
1996| Key | Type / Values | Details |2230| Key | Type / Values | Details |
1997| --- | --- | --- |2231| --- | --- | --- |
19982232| `allowed_approval_policies` | `array<string>` | Allowed values for `approval\_policy`. || `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`). |
1999| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2233| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |
2000| `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`. |2234| `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`. |
2001| `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. |2235| `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. |
2020 2254
2021Details2255Details
2022 2256
20232257Allowed values for `approval\_policy`.Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`).
2024 2258
2025Key2259Key
2026 2260