Models, Reasoning Effort & Compaction

Before any model names, fix the mental model, because the names will change but the model won't: Codex's intelligence is governed by two independent dials.

1. Which model runs the agent — the brain you put in the loop. Frontier brains reason harder and handle bigger, gnarlier tasks; smaller brains are faster and cheaper.
2. How much reasoning effort that model spends per turn — how long it thinks before acting. Even one model behaves very differently at low versus xhigh.

Think of it like hiring: picking the model is choosing who does the work; setting effort is telling them how carefully to think it through. A junior who deliberates carefully can beat a senior who rushes — and vice versa. You tune both to the job.

A third concern rides alongside these two: context — how much the model can hold in its head at once, and what happens when a long task overruns it. That's where compaction comes in, and it's what turns Codex from a one-shot assistant into something that can grind on a migration for hours. We'll take the dials first, then context.

One hard truth up front, because this is the fastest-moving corner of the whole Codex product: exact model names (the gpt-5.x strings), the recommended default, per-model effort defaults, and context-window numbers change every few weeks. Everything concrete in this lesson is a June 2026 snapshot. Learn the mechanisms — they're stable — and check the live models page for today's values.

Codex exposes a small family of models. The identifiers below are the strings you pass to -m / --model / model =, and this is the June 2026 snapshot — names rot, so confirm against the live models page.

The naming convention is the durable part — once you can read a suffix, you can place a model you've never seen:

• plain gpt-5.x — general frontier model (coding + computer use + knowledge work).
• -codex — that generation further optimized for agentic coding in Codex: long-horizon work, big refactors/migrations, terminal use, Windows.
• -mini — smaller, faster, cheaper; great for subagents and responsive tasks.
• -spark — text-only, ultra-low-latency research-preview variant for real-time iteration.
• -max (historical) — long-horizon variant natively trained for compaction; the suffix is retired but the capability lives on in newer models.

The lineup churns: as of June 2026 the entire gpt-5.1 family, gpt-5.1-codex-max, gpt-5.1-codex-mini, and gpt-5.2-codex have been retired from Codex, and the old codex-mini line is superseded by gpt-5.4-mini. If a tutorial tells you to run gpt-5.1-codex-max or codex-mini, treat it as historical and check the live page.

Don't confuse this family with the other two "Codexes": the 2021 Codex language model (a GPT-3 code variant, behind the original Copilot, deprecated 2023) and today's 2026 Codex agent. The gpt-5.x models here are the brains inside the 2026 agent — a completely different thing from the 2021 model that shares the name.

There are exactly three places to set the model, ordered from most local to most global. Pick by how long you want the choice to stick.

1. Per-launch, with a flag — for one thread or one codex exec run:

codex -m gpt-5.5                                   # short form
codex --model gpt-5.4                              # long form
codex exec --model gpt-5.4-mini "fix the failing tests"   # headless

2. As your default, in ~/.codex/config.toml — sticks across every session until you change it:

model = "gpt-5.5"

3. Mid-session, with /model — switch the brain inside the current thread without restarting. /model also lets you adjust reasoning effort in the same place. (In the IDE extension, use the model selector under the input box.)

/model            # opens the picker: choose model + effort for this thread

The precedence is the usual config story: a flag beats config.toml, and an in-session /model overrides both for that thread. Reach for the flag when you want a one-off ("this one task needs the big brain"), config when you have a steady preference, and /model when you're mid-task and realize you under- or over-provisioned.

One genuinely useful default-management trick: if you sign in with a ChatGPT account, the docs advise leaving model unset. With no model = line, Codex automatically tracks OpenAI's recommended default (today gpt-5.5) and you'll silently inherit the next recommended model when it ships — no config edit, no stale pin. Hard-coding model = "gpt-5.5" freezes you on that name even after it's superseded. Unset = always current.

The same model can think briefly or deliberate at length. That's the reasoning-effort dial, set in ~/.codex/config.toml (or via /model in-session, or --config on the CLI). It only applies to models that use the Responses API — which the current gpt-5.x line does.

model = "gpt-5.5"
model_reasoning_effort = "high"   # minimal | low | medium | high | xhigh

The ladder, from least to most thinking:

More effort means more reasoning tokens, slower turns, and higher cost — but better answers on genuinely hard problems. It is not a free "make it smarter" switch; on an easy task, high effort just burns time and tokens for no gain. The skill is matching effort to difficulty: medium for the bulk of interactive work, high when you feel the model thrashing on something genuinely hard, xhigh for a long background task where you'll walk away anyway.

Two wrinkles worth knowing:

• xhigh ("Extra High") is model-dependent. It was introduced with the compaction-trained gpt-5.1-codex-max for non-latency-sensitive work; not every model supports it. If a model doesn't, the value won't apply.
• There's a naming seam between surfaces. The CLI config documents the lowest tier as minimal; the API model pages call it none ("no reasoning"). They're effectively the same floor — treat the CLI list (minimal | low | medium | high | xhigh) as authoritative for Codex.

A related cosmetic key controls how much of the model's thinking you see:

model_reasoning_summary = "auto"   # auto | concise | detailed | none

This adjusts the reasoning-summary detail (or disables it) — it changes the display, not how hard the model thinks.

Here's the gotcha that trips people: each model ships with its own default reasoning effort. Two models that look interchangeable can behave very differently out of the box because one defaults to heavier thinking than the other.

So if you switch from gpt-5.5 to gpt-5.4 and don't set model_reasoning_effort, you've quietly dropped from medium thinking down to none — the model will feel faster but shallower, and you might wrongly conclude "gpt-5.4 is dumber." It isn't; you changed the effort dial by changing models. When you switch models, set effort explicitly unless you specifically want the new model's default.

These defaults are exactly the kind of volatile fact that rots — OpenAI tunes them per model and per release. The two facts that don't rot:

1. The config key is model_reasoning_effort, set in ~/.codex/config.toml (or /model).
2. Effort is per-model, so the default you get depends on which model you ran.

For the actual numbers, the live API model pages (e.g. the gpt-5.5 page) state each model's supported levels and default — that's the source of truth, not this table.

You can always see what you're running: /status shows the active model and effort in the session (something like gpt-5.5 medium · …), so a quick /status confirms whether a model switch silently changed your effort.

The third concern is context — the working memory the model reasons over. Two things surprise people here.

1. The window Codex uses is smaller than the model advertises. gpt-5.5 and gpt-5.4 advertise roughly 1,050,000-token windows in the API, but Codex defaults the effective window to 400,000 tokens — even for those 1M-token models. (gpt-5.3-codex is natively 400K; gpt-5.3-codex-spark is 128K.) You opt into a larger window explicitly in config:

model = "gpt-5.4"
model_context_window = 1000000           # raise the usable window
model_auto_compact_token_limit = 512000  # token threshold that triggers auto-compaction

That 1,000,000 + 512,000 pair is the documented way to run a true 1M window with gpt-5.4. (There's an open request to expose the same opt-in for gpt-5.5, which still defaults to 400K in Codex despite its 1M API window.) The relevant keys:

• model_context_window — context-window tokens available to the active model.
• model_auto_compact_token_limit — token threshold that triggers automatic history compaction (unset = model defaults).

2. Compaction lets one task outlive a single window. This is the headline capability. When Codex nears its context limit, it automatically compacts — prunes its own history while coherently preserving the most critical context — giving itself a fresh window, then repeats this process until the task is done. A single task can thus span multiple context windows and millions of tokens.

This was first natively trained into the compaction-tuned -max model and carried forward into the current line. It's why Codex can run genuinely long-horizon work: OpenAI observed these models iterating autonomously for more than 24 hours — fixing test failures, retrying, and delivering a result — on a single task. You can also tune the compaction prompt itself with compact_prompt (inline) or experimental_compact_prompt_file (path), and trigger it manually with the /compact slash command.

The mental model: a fixed window is a desk that only holds so many papers. Compaction is the agent periodically summarizing the stack into a tight set of notes, clearing the desk, and carrying on — so the task isn't capped by the window. All the numbers here (1.05M, 400K, 512K) are volatile; the models page and config reference hold the live values, and issue #19464 tracks the 1M opt-in.