Blog / Codex CLI
How to Reduce Token Usage in Codex CLI
OpenAI's Codex CLI bills reasoning tokens, output verbosity, and prompt caching as three separate, independently-controllable levers. Here's what each config.toml setting actually changes about your bill.
Published August 17, 2026
Codex CLI’s config.toml exposes three settings that move your bill independently of each other — model_reasoning_effort, model_verbosity, and whatever you’ve left in AGENTS.md — and none of them are things you’d notice unless you went looking. I went looking. Here’s what each one actually costs.
None of this requires changing how you use Codex day to day. It’s mostly about knowing which of its settings are silently expensive and which of its automatic behaviors are actually saving you money.
1. Stop defaulting to xhigh reasoning effort
model_reasoning_effort takes five values — minimal, low, medium, high, xhigh — and every step up runs the model’s hidden reasoning chain longer before it produces a visible answer. That reasoning is billed as output tokens, at the output rate, the same trap as extended thinking in Claude Code and thinking tokens in Gemini CLI — you’re paying full output price for tokens you never see printed. A lot of setup guides tell you to pin xhigh for “better results” and leave it there; that’s the right call for a gnarly refactor and a waste of money for a routine rename. Set it per-profile instead of globally, and drop to medium or low for anything mechanical.
2. Set model_verbosity to low for anything routine
Separate from reasoning effort, model_verbosity controls how terse the visible output itself is — low, medium, or high — and it’s specific to the GPT-5 Responses API models Codex runs on. low isn’t a hard ceiling on length, but it measurably cuts the explanatory prose the model tacks onto a diff, and for a CLI agent you’re mostly reading for pass/fail, that prose is pure overhead. Leave medium or high for sessions where you actually want the walkthrough.
3. Keep stable content at the front so caching actually triggers
Prompt caching in Codex CLI is automatic — no flag, no setup — but it only fires once the shared prefix between your current request and a recent one crosses a minimum (1,024 tokens on GPT-5.6-generation models, higher on some older ones). Cross that bar and the cached portion bills at roughly 0.1× the normal input rate on current-generation models, a 90% discount that adds up fast across a long session. The practical implication: whatever’s stable — AGENTS.md, system instructions, unchanging file context — belongs at the front of what Codex sends, with the part that actually changes turn to turn at the end. Reorder that and you’re paying full price for tokens that should’ve been a cache hit.
4. Don’t let AGENTS.md become a second CLAUDE.md nobody prunes
AGENTS.md is Codex’s version of Claude Code’s CLAUDE.md — an instructions file that loads automatically into every session, and it stacks: a personal one in ~/.codex, a repo-level one, and subdirectory-specific ones on top. Every line in all of them gets paid for on every request whether or not that particular task touches the part it’s relevant to. OpenAI’s own guidance is blunt about this: keep it short and accurate, and add to it only when Codex makes the same mistake twice — not as a running log of every preference that’s crossed your mind. A bloated AGENTS.md is a tax you pay per request forever, not a one-time cost.
5. Don’t wire in every MCP tool you own
Each MCP server you connect adds its tool definitions to every request’s context, whether or not the current task touches it. The guidance that matters here is starting with one or two tools that clearly remove a manual loop you already do often, not connecting everything you have access to because it’s available. This is the same tax as OpenCode’s provider sprawl — capability you’re not using in a given session is still capability you’re paying to describe.
6. Use /compact before auto-compaction decides for you
Codex CLI tracks model_auto_compact_token_limit and summarizes history automatically once a session crosses it — useful as a backstop, but it fires on its own schedule, not necessarily the moment that makes sense for what you’re doing. Running /compact yourself once you’ve finished a research or debugging detour and are about to move into implementation keeps stale exploration out of the context you’re now paying to re-send on every subsequent turn, the same discipline that pays off in Cursor and every other agent that re-sends full history per turn.
7. Skip the screenshot when you mean a specific element
Codex CLI takes image input like any multimodal agent, and OpenAI prices that input by patches: the image is divided into 32×32px tiles, counted as ceil(width/32) × ceil(height/32), then resized down if it exceeds the active model’s patch budget before a per-model multiplier gets applied. OpenAI’s own docs example: a 1024×1024 image comes to 1,024 patches un-resized, while a 1800×2400 image — well over budget — gets scaled down to 1,452 patches before the multiplier even applies. The exact final token count depends on which model and budget you’re on, which is itself the problem: you can’t easily predict what a screenshot is going to cost you before you send it, only that it’s costing more than the selector you actually meant.
That’s the gap UICuts fills: point at any element on a live page and it copies out the real selector, computed styles, and DOM structure as text, ready to paste into Codex instead of a screenshot. No patch math, no resizing, no guessing which model’s budget you landed in.
Key lessons learned
model_reasoning_effortandmodel_verbosityare two separate levers billed two separate ways — reasoning depth as output tokens, output style as prose length — and neither should be left at a guide’s recommended default without checking what your actual task needs.- Automatic prompt caching is real money (up to 90% off on cached input) but only triggers if stable content — AGENTS.md, system instructions — stays at the front of what you send.
- AGENTS.md and MCP tool definitions both load into every request whether the current task needs them or not; treat both as a per-request tax, not a one-time setup cost.
Related reading
The reasoning-tokens-as-output-tokens trap shows up under a different name in almost every agent — see how it plays out in Claude Code and Gemini CLI. If you’re comparing Codex against other CLI-first agents, OpenCode’s provider flexibility and Gemini CLI’s Auto routing both hit the same model-tier cost question from a different angle, and Cursor’s Agent vs. Chat mode is the IDE-integrated version of the same trade-off. Full configuration details are in Codex’s own config reference and prompt caching docs if you want the primary source, and current GPT-5.3-Codex pricing is worth checking directly since per-token rates shift as OpenAI ships new model variants.
Install UICuts free if UI feedback is part of your Codex CLI workflow — thirty seconds to install, no account required.
Frequently asked
How much does Codex CLI actually cost? +
It bills as OpenAI API usage on top of whatever plan you're running it under — ChatGPT Plus/Pro/Business includes some usage, or you can point Codex CLI at a standalone API key and pay per token. GPT-5.3-Codex, the default for most agentic coding tasks, runs about $1.75 per million input tokens and $14 per million output tokens; lighter variants like GPT-5.4-Mini are priced well below that for mechanical work that doesn't need the flagship model.
What does model_reasoning_effort actually change? +
It controls how long the model's hidden reasoning chain runs before it produces a visible response — accepted values are minimal, low, medium, high, and xhigh. That reasoning isn't free: it's billed as output tokens at the output rate, so pushing every request to xhigh because it's the default in some setup guide means paying for reasoning depth that a routine edit doesn't need.
Does Codex CLI cache tokens automatically? +
Yes — prompt caching kicks in automatically once the shared prefix of a request hits the model's minimum (1,024 tokens on GPT-5.6 and newer, up to 2,048 on some earlier variants), no setup required. On GPT-5.6-family models the cached portion bills at roughly 0.1× the uncached input rate, a 90% discount, which is also why keeping stable content — AGENTS.md, system instructions — at the front of the prompt and the changing part at the end matters more than it looks like it should.
Does a bloated AGENTS.md cost me tokens? +
Yes — Codex loads it automatically into every session (personal file in ~/.codex, repo-level, and subdirectory-level ones all stack), so anything in there gets paid for on every single request, not just the ones that need it. OpenAI's own guidance is to keep it short and accurate rather than long and vague, and to add to it only when Codex makes the same mistake twice — not as a running journal of every preference you have.
Is there a cheaper way to run bulk, non-interactive Codex-style work? +
Route it through OpenAI's Batch API instead of an interactive Codex CLI session. Batch requests get a flat 50% discount on both input and output tokens, but the trade-off is asynchronous turnaround — it's built for non-urgent, high-volume jobs like generating similar output across many files, not the back-and-forth of an interactive coding session.