config-reference.md Codex Docs, 2026-02-27 18:15 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/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).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 10 

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

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.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |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.personality` | `boolean` | Enable personality selection controls (stable; on by default). |49| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |

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

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

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

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

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

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

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

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

204 206 

205Key207Key

206 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 

207`agents.max_depth`221`agents.max_depth`

208 222 

209Type / Values223Type / Values

596 610 

597Details611Details

598 612 

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

600 614 

601Key615Key

602 616 

2028 2042 

2029Key2043Key

2030 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 

2031`suppress_unstable_features_warning`2057`suppress_unstable_features_warning`

2032 2058 

2033Type / Values2059Type / Values

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

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

2203 2229 

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

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

2232 

2204| Key | Type / Values | Details |2233| Key | Type / Values | Details |

2205| --- | --- | --- |2234| --- | --- | --- |

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

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

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

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

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

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

2256 2287 

2257Key2288Key

2258 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 

2259`mcp_servers`2314`mcp_servers`

2260 2315 

2261Type / Values2316Type / Values