config-basic.md Codex Docs, 2026-03-17 18:24 UTC → 2026-04-25 06:37 UTC

1# Config basics1# Config basics

2 2 

3Codex reads configuration details from more than one location. Your personal defaults live in `~/.codex/config.toml`, and you can add project overrides with `.codex/config.toml` files. For security, Codex loads project config files only when you trust the project.3Codex reads configuration details from more than one location. Your personal defaults live in `~/.codex/config.toml`, and you can add project overrides with `.codex/config.toml` files. For security, Codex loads project `.codex/` layers only when you trust the project.

4 4 

5## Codex configuration file5## Codex configuration file

6 6 

27 27 

28Use that precedence to set shared defaults at the top level and keep profiles focused on the values that differ.28Use that precedence to set shared defaults at the top level and keep profiles focused on the values that differ.

29 29 

30If you mark a project as untrusted, Codex skips project-scoped `.codex/` layers (including `.codex/config.toml`) and falls back to user, system, and built-in defaults.30If you mark a project as untrusted, Codex skips project-scoped `.codex/` layers, including project-local config, hooks, and rules. User and system config still load, including user/global hooks and rules.

31 31 

32For one-off overrides via `-c`/`--config` (including TOML quoting rules), see [Advanced Config](https://developers.openai.com/codex/config-advanced#one-off-overrides-from-the-cli).32For one-off overrides via `-c`/`--config` (including TOML quoting rules), see [Advanced Config](https://developers.openai.com/codex/config-advanced#one-off-overrides-from-the-cli).

33 33 

46Choose the model Codex uses by default in the CLI and IDE.46Choose the model Codex uses by default in the CLI and IDE.

47 47 

48```toml48```toml

49model = "gpt-5.4"49model = "gpt-5.5"

50```50```

51 51 

52#### Approval prompts52#### Approval prompts

148| Key | Default | Maturity | Description |148| Key | Default | Maturity | Description |

149| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |149| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |

150| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |150| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |

151| `apps_mcp_gateway` | false | Experimental | Route Apps MCP calls through `https://api.openai.com/v1/connectors/mcp/` instead of legacy routing |151| `codex_hooks` | true | Stable | Enable lifecycle hooks from `hooks.json` or inline `[hooks]`. See [Hooks](https://developers.openai.com/codex/hooks). |

152| `collaboration_modes` | true | Stable | Enable collaboration modes such as plan mode |152| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |

153| `memories` | false | Stable | Enable [Memories](https://developers.openai.com/codex/memories) |

154| `multi_agent` | true | Stable | Enable subagent collaboration tools |

153| `personality` | true | Stable | Enable personality selection controls |155| `personality` | true | Stable | Enable personality selection controls |

154| `remote_models` | false | Experimental | Refresh remote model list before showing readiness |156| `shell_snapshot` | true | Stable | Snapshot your shell environment to speed up repeated commands |

155| `runtime_metrics` | false | Experimental | Show runtime metrics summaries in TUI turn separators |

156| `request_rule` | true | Stable | Enable Smart approvals (`prefix_rule` suggestions) |

157| `search_tool` | false | Experimental | Enable `search_tool_bm25` so Codex discovers Apps MCP tools via search before tool calls |

158| `shell_snapshot` | false | Beta | Snapshot your shell environment to speed up repeated commands |

159| `shell_tool` | true | Stable | Enable the default `shell` tool |157| `shell_tool` | true | Stable | Enable the default `shell` tool |

160| `use_linux_sandbox_bwrap` | false | Experimental | Use the bubblewrap-based Linux sandbox pipeline |158| `unified_exec` | `true` except Windows | Stable | Use the unified PTY-backed exec tool |

161| `unified_exec` | false | Beta | Use the unified PTY-backed exec tool |159| `undo` | false | Stable | Enable undo via per-turn git ghost snapshots |

162| `undo` | true | Stable | Enable undo via per-turn git ghost snapshots |

163| `web_search` | true | Deprecated | Legacy toggle; prefer the top-level `web_search` setting |160| `web_search` | true | Deprecated | Legacy toggle; prefer the top-level `web_search` setting |

164| `web_search_cached` | true | Deprecated | Legacy toggle that maps to `web_search = "cached"` when unset |161| `web_search_cached` | false | Deprecated | Legacy toggle that maps to `web_search = "cached"` when unset |

165| `web_search_request` | true | Deprecated | Legacy toggle that maps to `web_search = "live"` when unset |162| `web_search_request` | false | Deprecated | Legacy toggle that maps to `web_search = "live"` when unset |

166 163 

167The Maturity column uses feature maturity labels such as Experimental, Beta,164The Maturity column uses feature maturity labels such as Experimental, Beta,

168 and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to165 and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to

170 167 

171Omit feature keys to keep their defaults.168Omit feature keys to keep their defaults.

172 169 

170For the current lifecycle hooks MVP, see [Hooks](https://developers.openai.com/codex/hooks).

171 

173### Enabling features172### Enabling features

174 173 

175- In `config.toml`, add `feature_name = true` under `[features]`.174- In `config.toml`, add `feature_name = true` under `[features]`.