config-reference.md Codex Docs, 2026-02-23 18:27 UTC → 2026-02-24 00:33 UTC

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.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. |16| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |

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

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

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

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

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

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

57| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |71| `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`. |72| `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. |73| `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. |

74| `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. |75| `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. |76| `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. |77| `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. |91| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |

77| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |92| `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). |93| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |

94| `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. |95| `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`. |96| `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`). |97| `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`. |142| `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`. |143| `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`. |144| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |

145| `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. |146| `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. |147| `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"`). |148| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |

188 205 

189Key206Key

190 207 

208`agents.max_depth`

209 

210Type / Values

211 

212`number`

213 

214Details

215 

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

217 

218Key

219 

191`agents.max_threads`220`agents.max_threads`

192 221 

193Type / Values222Type / Values

200 229 

201Key230Key

202 231 

232`allow_login_shell`

233 

234Type / Values

235 

236`boolean`

237 

238Details

239 

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

241 

242Key

243 

203`approval_policy`244`approval_policy`

204 245 

205Type / Values246Type / Values

206 247 

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

208 249 

209Details250Details

210 251 

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

212 253 

213Key254Key

214 255 

215`apps.<id>.disabled_reason`256`approval_policy.reject.mcp_elicitations`

216 257 

217Type / Values258Type / Values

218 259 

219`unknown | user`260`boolean`

220 261 

221Details262Details

222 263 

223Optional reason attached when an app/connector is disabled.264When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.

265 

266Key

267 

268`approval_policy.reject.rules`

269 

270Type / Values

271 

272`boolean`

273 

274Details

275 

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

277 

278Key

279 

280`approval_policy.reject.sandbox_approval`

281 

282Type / Values

283 

284`boolean`

285 

286Details

287 

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

289 

290Key

291 

292`apps._default.destructive_enabled`

293 

294Type / Values

295 

296`boolean`

297 

298Details

299 

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

301 

302Key

303 

304`apps._default.enabled`

305 

306Type / Values

307 

308`boolean`

309 

310Details

311 

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

313 

314Key

315 

316`apps._default.open_world_enabled`

317 

318Type / Values

319 

320`boolean`

321 

322Details

323 

324Default allow/deny for app tools with `open_world_hint = true`.

325 

326Key

327 

328`apps.<id>.default_tools_approval_mode`

329 

330Type / Values

331 

332`auto | prompt | approve`

333 

334Details

335 

336Default approval behavior for tools in this app unless a per-tool override exists.

337 

338Key

339 

340`apps.<id>.default_tools_enabled`

341 

342Type / Values

343 

344`boolean`

345 

346Details

347 

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

349 

350Key

351 

352`apps.<id>.destructive_enabled`

353 

354Type / Values

355 

356`boolean`

357 

358Details

359 

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

224 361 

225Key362Key

226 363 

236 373 

237Key374Key

238 375 

376`apps.<id>.open_world_enabled`

377 

378Type / Values

379 

380`boolean`

381 

382Details

383 

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

385 

386Key

387 

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

389 

390Type / Values

391 

392`auto | prompt | approve`

393 

394Details

395 

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

397 

398Key

399 

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

401 

402Type / Values

403 

404`boolean`

405 

406Details

407 

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

409 

410Key

411 

412`background_terminal_max_timeout`

413 

414Type / Values

415 

416`number`

417 

418Details

419 

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

421 

422Key

423 

239`chatgpt_base_url`424`chatgpt_base_url`

240 425 

241Type / Values426Type / Values

728 913 

729Key914Key

730 915 

916`mcp_oauth_callback_url`

917 

918Type / Values

919 

920`string`

921 

922Details

923 

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

925 

926Key

927 

731`mcp_oauth_credentials_store`928`mcp_oauth_credentials_store`

732 929 

733Type / Values930Type / Values

956 1153 

957Key1154Key

958 1155 

1156`model_catalog_json`

1157 

1158Type / Values

1159 

1160`string (path)`

1161 

1162Details

1163 

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

1165 

1166Key

1167 

959`model_context_window`1168`model_context_window`

960 1169 

961Type / Values1170Type / Values

1556 1765 

1557Key1766Key

1558 1767 

1768`profiles.<name>.model_catalog_json`

1769 

1770Type / Values

1771 

1772`string (path)`

1773 

1774Details

1775 

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

1777 

1778Key

1779 

1559`profiles.<name>.oss_provider`1780`profiles.<name>.oss_provider`

1560 1781 

1561Type / Values1782Type / Values

1988 2209 

1989## `requirements.toml`2210## `requirements.toml`

1990 2211 

1991`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).2212`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 2213 

1993For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched2214For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched

1994requirements. See the security page for precedence details.2215requirements. See the security page for precedence details.

1995 2216 

1996| Key | Type / Values | Details |2217| Key | Type / Values | Details |

1997| --- | --- | --- |2218| --- | --- | --- |

1998| `allowed_approval_policies` | `array<string>` | Allowed values for `approval\_policy`. |2219| `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`. |2220| `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`. |2221| `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. |2222| `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 2241 

2021Details2242Details

2022 2243 

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

2024 2245 

2025Key2246Key

2026 2247