config-reference.md Codex Docs, 2026-02-19 20:53 UTC → 2026-03-07 00:33 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/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).

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

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

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

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

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

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

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

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

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

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

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

31| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |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). |

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

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

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

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

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

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

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

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

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

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

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

75| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |91| `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). |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. |

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

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

79| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |96| `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`. |141| `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`. |142| `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`. |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). |

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

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

129| `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"`). |

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

148| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |166| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |

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

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

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

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

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

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

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

162 182 

163Key183Key

164 184 

186 206 

187Key207Key

188 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 

189`agents.max_threads`233`agents.max_threads`

190 234 

191Type / Values235Type / Values

198 242 

199Key243Key

200 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 

201`approval_policy`257`approval_policy`

202 258 

203Type / Values259Type / Values

204 260 

205`untrusted | on-request | never`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`

206 358 

207Details359Details

208 360 

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.361Default enabled state for tools in this app unless a per-tool override exists.

210 362 

211Key363Key

212 364 

213`apps.<id>.disabled_reason`365`apps.<id>.destructive_enabled`

214 366 

215Type / Values367Type / Values

216 368 

217`unknown | user`369`boolean`

218 370 

219Details371Details

220 372 

221Optional reason attached when an app/connector is disabled.373Allow or block tools in this app that advertise `destructive_hint = true`.

222 374 

223Key375Key

224 376 

234 386 

235Key387Key

236 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 

237`chatgpt_base_url`437`chatgpt_base_url`

238 438 

239Type / Values439Type / Values

402 602 

403Key603Key

404 604 

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`605`features.multi_agent`

430 606 

431Type / Values607Type / Values

434 610 

435Details611Details

436 612 

437Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).613Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default).

438 614 

439Key615Key

440 616 

726 902 

727Key903Key

728 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 

729`mcp_oauth_credentials_store`917`mcp_oauth_credentials_store`

730 918 

731Type / Values919Type / Values

954 1142 

955Key1143Key

956 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 

957`model_context_window`1157`model_context_window`

958 1158 

959Type / Values1159Type / Values

1554 1754 

1555Key1755Key

1556 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 

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

1558 1770 

1559Type / Values1771Type / Values

1830 2042 

1831Key2043Key

1832 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 

1833`suppress_unstable_features_warning`2057`suppress_unstable_features_warning`

1834 2058 

1835Type / Values2059Type / Values

1972 2196 

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

1974 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 

1975Expand to view all2211Expand to view all

1976 2212 

1977You 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).

1986 2222 

1987## `requirements.toml`2223## `requirements.toml`

1988 2224 

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).2225`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 2226 

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

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

1993 2229 

2230Use `[features]` in `requirements.toml` to pin feature flags by the same

2231canonical keys that `config.toml` uses. Omitted keys remain unconstrained.

2232 

1994| Key | Type / Values | Details |2233| Key | Type / Values | Details |

1995| --- | --- | --- |2234| --- | --- | --- |

1996| `allowed_approval_policies` | `array<string>` | Allowed values for `approval\_policy`. |2235| `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`. |2236| `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`. |2237| `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`. |

2238| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |

2239| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or 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. |2240| `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. |

2000| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |2241| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |

2001| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |2242| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |

2018 2259 

2019Details2260Details

2020 2261 

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

2022 2263 

2023Key2264Key

2024 2265 

2046 2287 

2047Key2288Key

2048 2289 

2290`features`

2291 

2292Type / Values

2293 

2294`table`

2295 

2296Details

2297 

2298Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.

2299 

2300Key

2301 

2302`features.<name>`

2303 

2304Type / Values

2305 

2306`boolean`

2307 

2308Details

2309 

2310Require a specific canonical feature key to stay enabled or disabled.

2311 

2312Key

2313 

2049`mcp_servers`2314`mcp_servers`

2050 2315 

2051Type / Values2316Type / Values