config-reference.md Codex Docs, 2026-02-24 00:33 UTC → 2026-03-06 00:38 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.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. |

15| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |16| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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. |179| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |

180| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |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. |

181 182 

182Key183Key

183 184 

205 206 

206Key207Key

207 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 

208`agents.max_depth`221`agents.max_depth`

209 222 

210Type / Values223Type / Values

589 602 

590Key603Key

591 604 

592`features.elevated_windows_sandbox`

593 

594Type / Values

595 

596`boolean`

597 

598Details

599 

600Enable the elevated Windows sandbox pipeline (experimental).

601 

602Key

603 

604`features.experimental_windows_sandbox`

605 

606Type / Values

607 

608`boolean`

609 

610Details

611 

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

613 

614Key

615 

616`features.multi_agent`605`features.multi_agent`

617 606 

618Type / Values607Type / Values

621 610 

622Details611Details

623 612 

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

625 614 

626Key615Key

627 616 

2053 2042 

2054Key2043Key

2055 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 

2056`suppress_unstable_features_warning`2057`suppress_unstable_features_warning`

2057 2058 

2058Type / Values2059Type / Values

2195 2196 

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

2197 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 

2198Expand to view all2211Expand to view all

2199 2212 

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

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

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

2216 2229 

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

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

2232 

2217| Key | Type / Values | Details |2233| Key | Type / Values | Details |

2218| --- | --- | --- |2234| --- | --- | --- |

2219| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`). |2235| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`). |

2220| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2236| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |

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

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

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

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

2269 2287 

2270Key2288Key

2271 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 

2272`mcp_servers`2314`mcp_servers`

2273 2315 

2274Type / Values2316Type / Values