config-reference.md Codex Docs, 2026-02-19 20:53 UTC → 2026-02-24 06:27 UTC

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 

9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).

10 

9| Key | Type / Values | Details |11| Key | Type / Values | Details |

10| --- | --- | --- |12| --- | --- | --- |

11| `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. |

12| `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.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |

13| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |16| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |

14| `approval_policy` | `untrusted | on-request | never` | Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |17| `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. |

15| `apps.<id>.disabled_reason` | `unknown | user` | Optional reason attached when an app/connector is disabled. |18| `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. |

19| `approval_policy.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |

20| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |

21| `approval_policy.reject.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are auto-rejected. |

22| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |

23| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |

24| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |

25| `apps.<id>.default_tools_approval_mode` | `auto | prompt | approve` | Default approval behavior for tools in this app unless a per-tool override exists. |

26| `apps.<id>.default_tools_enabled` | `boolean` | Default enabled state for tools in this app unless a per-tool override exists. |

27| `apps.<id>.destructive_enabled` | `boolean` | Allow or block tools in this app that advertise `destructive_hint = true`. |

16| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |28| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |

29| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |

30| `apps.<id>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. |

31| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |

32| `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. |

17| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |33| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |

18| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |34| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |

19| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |35| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |

28| `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). |44| `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). |

29| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |45| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |

30| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |46| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |

31| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |

32| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |

33| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |47| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |

34| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |48| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |

35| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |49| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |

55| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |69| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |

56| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |70| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |

57| `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. |71| `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_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. |

58| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |73| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |

59| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |74| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |

60| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |75| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |

74| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |89| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |

75| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |90| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |

76| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |91| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |

92| `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. |

77| `model_context_window` | `number` | Context window tokens available to the active model. |93| `model_context_window` | `number` | Context window tokens available to the active model. |

78| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |94| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |

79| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |95| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |

124| `profiles.<name>.experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |140| `profiles.<name>.experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |

125| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |141| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |

126| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |142| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |

143| `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). |

127| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |144| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |

128| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |145| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |

129| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |146| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |

159| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |176| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

160| `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. |177| `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. |

161| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |178| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

179| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |

162 180 

163Key181Key

164 182 

186 204 

187Key205Key

188 206 

207`agents.max_depth`

208 

209Type / Values

210 

211`number`

212 

213Details

214 

215Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).

216 

217Key

218 

189`agents.max_threads`219`agents.max_threads`

190 220 

191Type / Values221Type / Values

198 228 

199Key229Key

200 230 

231`allow_login_shell`

232 

233Type / Values

234 

235`boolean`

236 

237Details

238 

239Allow 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.

240 

241Key

242 

201`approval_policy`243`approval_policy`

202 244 

203Type / Values245Type / Values

204 246 

205`untrusted | on-request | never`247`untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }`

248 

249Details

250 

251Controls 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.

252 

253Key

254 

255`approval_policy.reject.mcp_elicitations`

256 

257Type / Values

258 

259`boolean`

260 

261Details

262 

263When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.

264 

265Key

266 

267`approval_policy.reject.rules`

268 

269Type / Values

270 

271`boolean`

272 

273Details

274 

275When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.

276 

277Key

278 

279`approval_policy.reject.sandbox_approval`

280 

281Type / Values

282 

283`boolean`

284 

285Details

286 

287When `true`, sandbox escalation approval prompts are auto-rejected.

288 

289Key

290 

291`apps._default.destructive_enabled`

292 

293Type / Values

294 

295`boolean`

296 

297Details

298 

299Default allow/deny for app tools with `destructive_hint = true`.

300 

301Key

302 

303`apps._default.enabled`

304 

305Type / Values

306 

307`boolean`

308 

309Details

310 

311Default app enabled state for all apps unless overridden per app.

312 

313Key

314 

315`apps._default.open_world_enabled`

316 

317Type / Values

318 

319`boolean`

206 320 

207Details321Details

208 322 

209Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.323Default allow/deny for app tools with `open_world_hint = true`.

210 324 

211Key325Key

212 326 

213`apps.<id>.disabled_reason`327`apps.<id>.default_tools_approval_mode`

214 328 

215Type / Values329Type / Values

216 330 

217`unknown | user`331`auto | prompt | approve`

218 332 

219Details333Details

220 334 

221Optional reason attached when an app/connector is disabled.335Default approval behavior for tools in this app unless a per-tool override exists.

336 

337Key

338 

339`apps.<id>.default_tools_enabled`

340 

341Type / Values

342 

343`boolean`

344 

345Details

346 

347Default enabled state for tools in this app unless a per-tool override exists.

348 

349Key

350 

351`apps.<id>.destructive_enabled`

352 

353Type / Values

354 

355`boolean`

356 

357Details

358 

359Allow or block tools in this app that advertise `destructive_hint = true`.

222 360 

223Key361Key

224 362 

234 372 

235Key373Key

236 374 

375`apps.<id>.open_world_enabled`

376 

377Type / Values

378 

379`boolean`

380 

381Details

382 

383Allow or block tools in this app that advertise `open_world_hint = true`.

384 

385Key

386 

387`apps.<id>.tools.<tool>.approval_mode`

388 

389Type / Values

390 

391`auto | prompt | approve`

392 

393Details

394 

395Per-tool approval behavior override for a single app tool.

396 

397Key

398 

399`apps.<id>.tools.<tool>.enabled`

400 

401Type / Values

402 

403`boolean`

404 

405Details

406 

407Per-tool enabled override for an app tool (for example `repos/list`).

408 

409Key

410 

411`background_terminal_max_timeout`

412 

413Type / Values

414 

415`number`

416 

417Details

418 

419Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.

420 

421Key

422 

237`chatgpt_base_url`423`chatgpt_base_url`

238 424 

239Type / Values425Type / Values

402 588 

403Key589Key

404 590 

405`features.elevated_windows_sandbox`

406 

407Type / Values

408 

409`boolean`

410 

411Details

412 

413Enable the elevated Windows sandbox pipeline (experimental).

414 

415Key

416 

417`features.experimental_windows_sandbox`

418 

419Type / Values

420 

421`boolean`

422 

423Details

424 

425Run the Windows restricted-token sandbox (experimental).

426 

427Key

428 

429`features.multi_agent`591`features.multi_agent`

430 592 

431Type / Values593Type / Values

726 888 

727Key889Key

728 890 

891`mcp_oauth_callback_url`

892 

893Type / Values

894 

895`string`

896 

897Details

898 

899Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.

900 

901Key

902 

729`mcp_oauth_credentials_store`903`mcp_oauth_credentials_store`

730 904 

731Type / Values905Type / Values

954 1128 

955Key1129Key

956 1130 

1131`model_catalog_json`

1132 

1133Type / Values

1134 

1135`string (path)`

1136 

1137Details

1138 

1139Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.

1140 

1141Key

1142 

957`model_context_window`1143`model_context_window`

958 1144 

959Type / Values1145Type / Values

1554 1740 

1555Key1741Key

1556 1742 

1743`profiles.<name>.model_catalog_json`

1744 

1745Type / Values

1746 

1747`string (path)`

1748 

1749Details

1750 

1751Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).

1752 

1753Key

1754 

1557`profiles.<name>.oss_provider`1755`profiles.<name>.oss_provider`

1558 1756 

1559Type / Values1757Type / Values

1972 2170 

1973Track Windows onboarding acknowledgement (Windows only).2171Track Windows onboarding acknowledgement (Windows only).

1974 2172 

2173Key

2174 

2175`windows.sandbox`

2176 

2177Type / Values

2178 

2179`unelevated | elevated`

2180 

2181Details

2182 

2183Windows-only native sandbox mode when running Codex natively on Windows.

2184 

1975Expand to view all2185Expand to view all

1976 2186 

1977You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).2187You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).

1986 2196 

1987## `requirements.toml`2197## `requirements.toml`

1988 2198 

1989`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).2199`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).

1990 2200 

1991For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched2201For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched

1992requirements. See the security page for precedence details.2202requirements. See the security page for precedence details.

1993 2203 

1994| Key | Type / Values | Details |2204| Key | Type / Values | Details |

1995| --- | --- | --- |2205| --- | --- | --- |

1996| `allowed_approval_policies` | `array<string>` | Allowed values for `approval\_policy`. |2206| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`). |

1997| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2207| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |

1998| `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`. |2208| `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`. |

1999| `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. |2209| `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. |

2018 2228 

2019Details2229Details

2020 2230 

2021Allowed values for `approval\_policy`.2231Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`).

2022 2232 

2023Key2233Key

2024 2234