Codex credits, usage limits and cost optimization

Codex cost management means making plan allowances, credits and API spend last by controlling four levers: the model and reasoning effort each job runs at, the context every turn re-sends, the number of agents running unattended, and which billing path a run uses. /status, /usage, codex exec --json and OpenTelemetry show where the usage goes.

This page is for the developer or tech lead who owns Codex for a team. It is Wednesday, the weekly allowance is nearly gone, and nobody can say whether the cause was one long cloud task, a nightly automation, or everyone running GPT-6 Astra at high effort on routine edits. Commands and config keys here were checked against Codex CLI 0.157.1 on 2026-09-26. Spend policy across vendors lives in AI usage cost governance.

What you get from managing Codex costs

• A way to see usage per session (/status, /usage), per headless run (codex exec --json) and per team (OpenTelemetry)
• A model-and-effort policy in config.toml profiles that routes routine work away from the most expensive setting
• Context settings that stop every turn from re-sending instructions and tool output nobody needs
• A pattern for bounding unattended codex exec runs, which have no spend-cap flag
• A check that proves a cheaper setup did not lower quality: cost per accepted change, not cost alone

Where does Codex usage go?

How you sign in decides where usage is metered and where you can limit it. Find your row first:

How Codex runs	Where you see usage	What limits it
Signed in with ChatGPT (Plus, Pro, Business, Edu or Enterprise plans include Codex)	/status and /usage in the CLI; the rate-limit banner	Plan allowances on five-hour and weekly windows; after that, credits or a usage-limit reset where your plan offers them
Signed in with an OpenAI API key	Your OpenAI API account’s billing	Pay per token at API rates; set budget alerts on that account
Codex with the Amazon Bedrock provider	Your AWS bill	AWS budget controls

Plan prices and how the tools compare are on pricing analysis, and per-token model prices are on the models hub. This page does not repeat them, because they change more often than the advice below.

Whatever the path, the same four levers drive consumption:

• Model and effort. GPT-6 Astra is the bundled default since CLI 0.153.4 and runs at low reasoning effort unless you raise it. Codex’s own labels place GPT-6 Sol as the “Workhorse model for coding and everyday work” and GPT-6 Luna as the “Fast and affordable model for easier tasks”. The Fast tier on Astra is labelled “2x speed, increased usage”. On GPT-6 Sol and GPT-6 Luna the Fast tier is the default service tier, and Codex labels it only “1.5x speed”; the “increased usage” label applies to Astra’s Fast tier.
• Context per turn. Every turn re-sends the AGENTS.md chain (up to project_doc_max_bytes, 32 KiB by default), the conversation so far and the tool output it holds. In Codex the model context window is 272K tokens by default.
• Agents you are not watching. Subagents, automations and cloud tasks each run their own turns. Best-of-N cloud attempts (codex cloud exec --env <ENV_ID> --attempts N "<task>") run the task N times.
• Unattended runs. codex exec has no spend-cap flag in 0.157.1 (checked with codex exec --help on 2026-09-26), so a CI loop runs until it finishes or the job is killed.

Set up Codex cost visibility, then limits

1. Record the CLI version on every machine. Run codex --version. /usage needs 0.156.0 or later, and GPT-6 Sol and GPT-6 Luna need 0.155.0 or later. Teammates on different versions may not run the same default model (GPT-6 Astra became the bundled default in 0.153.4), so their usage is not comparable until versions match. Run codex update to align them.

2. Read one session. In a session, /status shows the session configuration and token usage and, for eligible workspaces, estimated thread credits or cost (since 0.148.0). /usage shows account usage and offers a usage-limit reset where one is available (since 0.156.0). The 0.153.0 release notes say Plus and Team users (Team is the release notes’ name for what the table calls Business) get an earlier warning when less than half of their allowance remains.

3. Measure every headless run. Save the JSONL event stream and sum the token counts from each turn.completed event:

   # Terminal or CI step. Prints tokens for one codex exec run.
   codex exec --json --ephemeral --sandbox workspace-write "Fix the failing test in tests/billing/" > events.jsonl
   jq -s '[.[] | select(.type=="turn.completed") | .usage]
          | {input: (map(.input_tokens // 0) | add),
             cached: (map(.cached_input_tokens // 0) | add),
             output: (map(.output_tokens // 0) | add)}' events.jsonl

   A low cached share on a long run means context changes on every turn and nothing gets reused. That is usually a sign that the task was too broad.

   Permission profiles (-c default_permissions=":workspace", beta) are OpenAI’s preferred replacement for --sandbox; do not combine the two.

4. Export OpenTelemetry for the team view. Codex reads an [otel] table from config.toml and emits codex.turn.token_usage.* (input, cached, output, total) and codex.turn.cost_microusd metrics, which you can slice by user, model and reasoning effort in your own backend. In 0.157.1 metrics_exporter defaults to statsig, a Codex-internal destination, so set it explicitly. The full configuration and dashboard are on observing the agents.

5. Decide the limit for your row. On a ChatGPT plan, the allowance is the ceiling; decide who may buy credits or use a reset, and write that down. On an API key, set budget alerts on the account and use a separate key per pipeline so one job’s spend is visible on its own. On Bedrock, use AWS budgets. Team-wide constraints (requirements.toml, allowed MCP servers, managed config) are on Codex enterprise governance.

Copy-paste prompt: turn a week of Codex runs into a budget report

Read every events-*.jsonl file in ci-artifacts/codex/. Each file is the output of one
`codex exec --json` run and its file name contains the CI job name.
Do not edit anything. For each file, sum usage.input_tokens, usage.cached_input_tokens and
usage.output_tokens over all turn.completed events, and note whether any turn.failed or
error event occurred.
Report a table sorted by total tokens: job name, runs, median and maximum tokens per run,
cached share, failed runs.
Then list the three jobs where a cheaper model or a narrower prompt would save the most,
and the evidence for each. If a file has no turn.completed event, list it separately
instead of guessing.

Set a model and effort policy for Codex

The rule this site follows everywhere: start on the default model, tune effort before switching model, and switch model only when your own evals say so. For Codex that means GPT-6 Astra at its default low effort for interactive work, a higher effort only for the tasks that need it, and GPT-6 Sol or GPT-6 Luna for routine jobs once they pass your checks.

Job	Model	Effort	Why
Hard, multi-file agentic work	GPT-6 Astra (default)	low, raised per task with /model	Tune effort on the default model before you switch model
Everyday edits, tests, reviews	GPT-6 Sol	medium (its default)	Codex’s migration prompt says Sol makes “usage limits go further”
Renames, docstrings, lint fixes, triage	GPT-6 Luna	medium (its default)	Codex’s rate-limit prompt recommends Luna when you run short
GPT-5.6 Sol, Terra or Luna in old configs	Move to GPT-6 Sol or GPT-6 Luna	—	Codex labels the GPT-5.6 models “Older” and prompts the move

Put the policy in files rather than a wiki page. codex --profile <name> (or -p) layers $CODEX_HOME/<name>.config.toml on top of your base config:

# ~/.codex/config.toml — interactive default
model = "gpt-6-astra"
model_reasoning_effort = "low"

# ~/.codex/routine.config.toml — used with: codex -p routine
model = "gpt-6-luna"
model_reasoning_effort = "medium"

For one run, override on the command line: codex exec -m gpt-6-sol "Add tests for src/billing/invoice.ts". In a session, /model changes both model and effort. On GPT-6 Astra, /fast turns on the Fast tier, which Codex describes as “our fastest inference with increased plan usage”; leave it off for Astra work nobody is waiting on. Sol and Luna runs are already on their Fast tier by default.

Trim the context every Codex turn re-sends

Context is paid for on every turn, so a line in AGENTS.md costs more than the same line in a prompt.

• Split AGENTS.md by scope. Codex concatenates AGENTS.md files from the repository root down to the working directory and stops at project_doc_max_bytes. Keep what is true everywhere in the root, keep package-specific rules in the package, and move long procedures into skills that load only when used. The method is in AGENTS.md optimization.

• Turn off MCP servers you are not using, and narrow the ones you keep. A disabled server does not start, and enabled_tools exposes only the tools you name. Large tool results stay in the conversation, so tool_output_token_limit caps how much of each result is kept:

  # ~/.codex/config.toml (keys accepted by `codex exec --strict-config`, 0.157.1)
  tool_output_token_limit = 8000
  
  [mcp_servers.sentry]
  command = "npx"
  args = ["-y", "@sentry/mcp-server"]
  enabled = false            # re-enable while debugging production
  
  [mcp_servers.linear]
  url = "https://mcp.linear.app/mcp"
  enabled_tools = ["READ_TOOL_1", "READ_TOOL_2"]

  codex mcp list shows each server as enabled or disabled. Replace READ_TOOL_1 and READ_TOOL_2 with the tool names the server itself lists; names differ per server and change between releases. More techniques are in reducing MCP token cost.

• Start a new session per task. A thread that carries yesterday’s work re-sends it on every turn. Use /compact when you must continue a long thread, and a fresh session when the task changes.

• Scope the task, not only the model. “Refactor authentication” reads the whole service; “change src/middleware/auth.ts to accept JWTs, keep its interface, run tests/auth/” reads three files.

Copy-paste prompt: split a broad task into cheap, checkable steps

Do not change any files yet. I want to migrate session-cookie auth to JWT in this repository.
Read only what you need to plan it. Split the work into steps that each:
- touch at most five files, named explicitly,
- name the one command that proves the step works (a test file, the type check, or the linter),
- say which model is enough for it: gpt-6-luna for mechanical edits, gpt-6-sol for ordinary
  code changes, gpt-6-astra only where the step needs cross-module reasoning.
Output a numbered list and nothing else. Stop after the plan.

Bound unattended Codex runs

Automations, cloud tasks and CI jobs have no person watching the turn count. Because codex exec has no spend cap in 0.157.1, bound it from outside:

# CI step. OPENAI_API_KEY comes from the CI secret store, never from the file.
timeout 20m codex exec --json --ephemeral --sandbox workspace-write \
  -m gpt-6-sol "Fix the failing unit tests in tests/billing/. Change nothing outside src/billing/ and tests/billing/." \
  > events.jsonl
# Uncached input + output: the part that grows when context churns; cached input is billed too, at a discount.
UNCACHED=$(jq -s '[.[] | select(.type=="turn.completed") | .usage
  | ((.input_tokens // 0) - (.cached_input_tokens // 0) + (.output_tokens // 0))] | add // 0' events.jsonl)
if [ "$UNCACHED" -gt 2000000 ]; then echo "Uncached input + output tokens $UNCACHED over this job's budget"; exit 1; fi

The threshold fails the job after the fact, which is enough to stop a runaway job from repeating nightly. Pick it from the median of your last 20 runs, not from a guess. The job’s own timeout (for example timeout-minutes in GitHub Actions) is the hard stop. Headless patterns are on non-interactive Codex.

For the other unattended paths:

• Automations. Run reports daily, not hourly, unless someone reads them hourly. Scope the prompt to “files changed in the last 24 hours”, not “the whole codebase”. See Codex automations.
• Cloud tasks. Use --attempts above 1 only when you will compare the attempts; otherwise you pay for work you discard. See cloud environments.
• Long /goal tasks. [goals] max_goal_token_budget sets a token budget for a goal, and since 0.151.0 tokens spent by nested subagents count toward it. Set it before a task you expect to run for hours.

How do you prove the savings did not cost quality?

Cheaper runs that produce more rework cost more. Measure cost per accepted change: the tokens or credits a task used, divided by the changes that merged and were not reverted. The method, including seats and review time, is in the economics of agent-built software.

Prove a routing change with the gates you already run, not by reading every diff:

1. Pick 10 tasks Codex completed last month that merged cleanly, with their tests.
2. Re-run each one on the cheaper setting (for example codex exec -p routine --sandbox workspace-write) in a fresh worktree.
3. Count how many pass the same gates: the test suite, the type check, the linter and codex review against the base branch.
4. Adopt the cheaper setting for that task type only if it passes at least as many as the original. The tech lead signs off on the routing table; developers can raise effort for any single task without asking.

Re-run the comparison when a new model ships; the new-model playbook covers the full process.

Copy-paste prompt: check a cheaper model against last month's work

Read tasks/routing-eval.md. It lists 10 merged tasks, each with its original prompt and the
test command that proves it. For each task, in a separate git worktree created from the
commit before the task's merge:
1. Run the original prompt with `codex exec -p routine --sandbox workspace-write --json --ephemeral`.
2. Run the task's test command, then `npm run typecheck` and `npm run lint`.
3. Record pass or fail for each gate and the output tokens from turn.completed events.
Do not fix failures by hand and do not edit the tests. Write a table to
tasks/routing-eval-results.md with task, gates passed, output tokens, and a one-line reason
for every failure. End with: adopt, adopt for some task types (name them), or reject.

When Codex cost controls break down

Symptom	Likely cause	Recovery
The weekly allowance is gone by Wednesday	Broad exploratory tasks, high effort on every task, or Astra’s Fast tier left on	Check /status on the heaviest threads, split tasks, set effort per task, and turn /fast off for background Astra work
One developer burns through usage faster than everyone else	An older CLI running a different default model, or a large personal MCP setup	Compare codex --version and codex mcp list with a teammate’s
A CI job’s token count doubles overnight	A prompt change widened the scope, or a flaky test makes the agent loop	Diff the prompt, read the command_execution items in events.jsonl, and keep the token threshold in place
OpenTelemetry shows no Codex cost data	metrics_exporter left on its default	Set the exporter explicitly and confirm codex.turn.cost_microusd arrives from one run before building panels. Headless codex exec runs may not emit OTel metrics (openai/codex#12913, unconfirmed as of 0.157.1): keep the JSONL token sum from step 3 as the CI source of truth
Usage looks low but the invoice is high	Runs on an API key or Bedrock bill outside the ChatGPT plan view	List every key and provider in use; give each pipeline its own key
Luna-routed tasks keep coming back from review	The task type needs more reasoning than Luna gives	Move that task type back to GPT-6 Sol and re-run the 10-task comparison

Next steps

• Operate Codex in production: the other operating signals, and where this page fits among them
• Observing the agents: the OpenTelemetry setup behind the team view
• AI usage cost governance: budgets and attribution across Codex, Claude Code and Cursor
• Context cost optimization: the cross-tool techniques behind trimming context
• Claude Code cost control: the same job for Claude Code, including its --max-budget-usd cap