model_auto_compact_token_limit
model defaultsPublished Jul 15, 2026 · Verified against the official config docs
Sets the token count where Codex automatically compacts session history to free up context. Unset by default; each model ships its own threshold and the docs don't publish the numbers. You can raise or lower it, but anything above 90% of the context window gets silently clamped. The only way to turn compaction off entirely is the codex --disable auto_compaction flag; no config key exists for it.
Values
| Key | Type | Default |
|---|---|---|
model_auto_compact_token_limit |
number | unset (model defaults) |
model_auto_compact_token_limit_scope |
"total" or "body_after_prefix" |
"total" |
compact_prompt |
string | built-in compaction prompt |
experimental_compact_prompt_file |
path | unset, experimental |
The scope key controls what counts toward the limit: total counts the full active context, body_after_prefix counts only growth after the carried compaction-window prefix, per the config reference. The docs don’t say when you’d pick body_after_prefix. The two prompt keys swap out the text Codex uses when it compacts; compact_prompt is inline, experimental_compact_prompt_file reads from a file and carries the experimental label, so expect it to move.
# ~/.codex/config.toml
model_auto_compact_token_limit = 150000
model_auto_compact_token_limit_scope = "total"When to change it
Raise it when compaction keeps firing mid-task and dropping detail you still needed. That buys more runway before the squeeze, up to the 90% clamp below.
If you want compaction off entirely, no config key does it. PR #28260 shipped codex --disable auto_compaction as a feature flag (the PR says skipping a public config key was deliberate). With it off, Codex skips compaction at pre-turn, model-switch, and mid-turn, you hit the raw context-window error instead, and manual /compact still works.
Gotchas
The 90% clamp is the big one. Codex takes the lower of your value and 90% of the context window, so a limit above that line gets silently ignored. Issue #11805 pins the change to v0.100.0 and asked for explicit values to be respected; it was closed as not planned.
Profiles don’t pick it up. Issue #14456 reports the key gets ignored when set inside a profile. Set it top-level in config.toml until that’s fixed.
The docs don’t publish per-model defaults. One issue thread ballparks the threshold around 220k tokens; no maintainer has confirmed a number.
Related settings
model_context_windowis the window the 90% clamp is computed from.- With compaction disabled, long sessions end at the input exceeds context window error instead.