model
unset (config-sample recommends gpt-5.6)Published Jul 15, 2026 · Verified against the official config docs
Sets which model Codex runs, as a plain string id like gpt-5.5 or gpt-5.6. The official reference doesn't publish a default; the annotated sample config recommends gpt-5.6 for most users, which is the closest thing to one. Set it once at the top of config.toml, or pin a different model per workflow with profile files at $CODEX_HOME/<name>.config.toml.
This is the top-level switch for which model Codex talks to. Everything else in the Models & reasoning block modifies whatever id you put here.
Values
Plain string, exact model id. The official reference describes it as “Model to use” and gives gpt-5.5 as its example. No default is published anywhere in the reference. The annotated sample config ships model = "gpt-5.6" and calls it the recommended example for most users, which is as close to an official default as you’ll get.
| Type | string (model id) |
| Default | not published in the reference |
| Sample’s recommendation | gpt-5.6 |
# ~/.codex/config.toml
# Primary model used by Codex.
model = "gpt-5.6"When to change it
- Your usage limit is draining too fast. A config thread on the tracker, #14593 “Burning tokens very fast”, opens with someone on GPT-5.3/5.4 at high reasoning effort watching quota vanish. This key plus model_reasoning_effort is the whole cost equation, and this one is the bigger lever.
- You want a cheaper model for automation. The sample docs show a
ci.config.tomlprofile pinned tomodel = "gpt-5.4"so scripted runs don’t burn flagship tokens. Profile files live at$CODEX_HOME/<name>.config.tomland override the top-level value. - A new model just shipped. One line to swap the whole CLI over (small edit, big blast radius).
Gotchas
- The docs don’t say what Codex runs when
modelis unset. The sample callinggpt-5.6“recommended for most users” hints the CLI ships with a sane built-in, but the reference never names it. Set the key explicitly if you care which model bills you. - The id has to exist on your provider.
modelresolves againstmodel_provider, which defaults toopenai. Point a model id at a provider that doesn’t serve it and you get errors like model not supported. - If your model keeps snapping back to something you didn’t set, check for an active profile file. Per-profile config wins over the top-level key.
Related settings
- model_reasoning_effort: how hard the model thinks, the other half of token burn
- Usage limit draining too fast: the symptom that usually sends people to this key
- Input exceeds context window: different models carry different context windows, and this key decides which one you get