config-basic.md Codex Docs, 2026-03-26 18:27 UTC → 2026-04-24 18:20 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| `codex_hooks` | false | Under development | Enable lifecycle hooks from `hooks.json`. See [Hooks](https://developers.openai.com/codex/hooks). |

151| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |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) |

152| `multi_agent` | true | Stable | Enable subagent collaboration tools |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| `shell_snapshot` | true | Stable | Snapshot your shell environment to speed up repeated commands |156| `shell_snapshot` | true | Stable | Snapshot your shell environment to speed up repeated commands |

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

156| `smart_approvals` | false | Experimental | Route eligible approval requests through the guardian reviewer subagent |

157| `unified_exec` | `true` except Windows | Stable | Use the unified PTY-backed exec tool |158| `unified_exec` | `true` except Windows | Stable | Use the unified PTY-backed exec tool |

158| `undo` | false | Stable | Enable undo via per-turn git ghost snapshots |159| `undo` | false | Stable | Enable undo via per-turn git ghost snapshots |

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

166 167 

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

168 169 

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

171 

169### Enabling features172### Enabling features

170 173 

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