config-reference.md Codex Docs, 2026-03-03 00:35 UTC → 2026-03-05 00:34 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.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