How to budget OpenClaw tokens when model prices move

Published May 25, 2026.

A team usually asks for one number: how much will OpenClaw cost next month? A model name and a price per million tokens do not answer that question for long. The request may include a growing conversation, workspace files, tool results, images, retries, compaction calls, and cached input. The provider may also change its prices, context tiers, cache rules, or billing mode.

The workable answer is a dated estimate for a defined workload. Keep the observed token mix, the rate card used to calculate it, and the uncertainty reserve as separate records. When any of them changes, refresh the estimate. That gives the team a number it can explain without pretending it is a permanent quote.

Start with the workload

Do not begin with a model catalogue. Begin with the job the team wants to run. A useful budget unit might be one support triage, one code review, one research brief, or one scheduled report. Each unit should have a clear input, an expected result, and a human review boundary.

1. Write down the task and the expected monthly volume.
2. Record whether the task needs files, images, web search, memory, or other tools.
3. Define what counts as a successful result and how much human correction is acceptable.
4. Choose a provider route and model for a representative test, then record the actual usage.

This matters because two teams using the same model can have very different bills. One may send a short prompt and accept the first answer. Another may let the agent inspect a repository, call tools repeatedly, compact a long session, and retry a failed request. A per-user token allowance hides those differences.

Count the token buckets OpenClaw exposes

The OpenClaw token-use reference says OpenClaw tracks tokens rather than characters. Its context can include the system prompt, conversation history, tool calls and results, files, images, and provider wrappers. A short visible answer does not prove that the request was small.

Use the documented usage surfaces before choosing a budget. In chat, /usage tokens shows token and cache details, /usage full can show estimated cost when usage metadata and local pricing exist, and /usage cost provides a local cost summary. The Control UI can break down transcript-derived usage by provider, model, agent, channel, and token type. The OpenClaw API usage and costs reference warns that these totals describe available local history, not a provider invoice.

Keep the last row separate. OpenClaw documents a difference between the live context snapshot and provider usage totals. A provider total can include cached input, output, and several model calls in one tool loop, while the context display describes the latest prompt. Treating either number as a universal cost counter produces a neat report with the wrong meaning.

Token counts also vary by model and encoding. OpenAI’s token-counting guidance notes that input, cached input, output, and reasoning tokens are different categories, and that tools, schemas, images, and files can affect the full request. Record the fields the provider actually returns. Do not fill an unknown value with zero.

Keep a rate card with a date

Store a small rate-card record beside each forecast. Include the date checked, provider, endpoint, account or authentication route, exact model identifier, currency, input rate, cache-read rate, cache-write rate, output rate, context tier, processing mode, region, batch setting, and any separate tool or media charge. Add the source URL. A model alias is not enough to reconstruct a bill later.

The OpenAI API pricing page shows why a single price per model is a weak planning input. Its tables distinguish input, cached input, cache writes, and output, and also vary prices by context length and processing mode. The same page lists some tool charges separately from token charges. This is one provider’s current structure, not a universal billing rule, but it is enough to show why a frozen spreadsheet ages badly.

Prompt caching adds another moving part. Anthropic’s prompt-caching documentation currently describes different multipliers for five-minute writes, one-hour writes, and cache reads, as well as expiry behavior. Google’s Gemini API pricing page separates standard and batch pricing and states that its listed output price includes thinking tokens for the relevant model tables. Keep those provider rules in the dated rate card. Do not copy them into a permanent OpenClaw price table.

OpenClaw can also use local pricing metadata. Its token-use documentation describes model cost fields under models.providers.<provider>.models[].cost, catalog updates, and precedence rules for explicit local values. A local override that was correct last quarter can make current usage look more certain than it is. Preserve the rate-card date and refresh the override when the route changes.

Turn one workload into a range

For a simple flat-rate estimate, use this structure:

estimated model cost = (input tokens * input rate + cache reads * cache-read rate + cache writes * cache-write rate + output tokens * output rate) / 1,000,000

Then add separate charges for tools, media, embeddings, hosting, or other services. If the provider uses tiers, calculate each request with the tier it actually selected. The OpenClaw reference says a tiered request can select a rate from total prompt input and apply that selected rate to the request’s token buckets. Do not add a month of tokens together and apply one guessed tier to the result.

Use observed percentiles instead of a single average. The median helps describe an ordinary job. A high percentile shows what a long document, large tool result, or retry looks like. The forecast should include volume, the observed token vector, and a reserve for the events that the average hides.

Worked example: a support queue

Suppose a team expects 10,000 support-triage jobs in a month. The following rates are fictional and are included only to show the arithmetic, not as a provider quote:

• 7,000 uncached input tokens per job at $2.00 per million
• 2,000 cache-read tokens per job at $0.20 per million
• 500 cache-write tokens per job at $2.50 per million
• 1,200 output tokens per job at $10.00 per million

The estimated cost per job is $0.014 for input, $0.0004 for cache reads, $0.00125 for cache writes, and $0.012 for output. Together that is $0.02765 per job, or $276.50 for 10,000 jobs. Add a proposed 15 percent reserve for retries, cache misses, and compaction, and the planning figure becomes about $317.98.

That figure is useful only with its assumptions attached. If the team changes the provider, uses a longer context tier, loses cache hits after idle periods, or receives more verbose answers, the calculation must be rerun. If the provider changes its rates, the old number remains a historical estimate, not a promise about the next invoice.

Budget the calls around the model

Model tokens are only one line in an OpenClaw budget. The API usage reference lists other features that can call paid services, including media understanding, image and video generation, remote memory embeddings, web search, provider usage checks, compaction safeguards, model probes, and third-party skills.

Give those calls their own ledger entries. A workflow that looks cheap at the chat layer may still use a paid search provider or an embedding API. Conversely, a local or subscription-style route may expose token counts without producing a comparable dollar estimate inside OpenClaw. The planning record should say whether a line is an estimated provider charge, a plan quota, a local operating cost, or an unknown amount.

This separation also helps with procurement. The team can decide that a support workflow has a model allowance, a search allowance, and a hardware allowance without converting all of them into a questionable token equivalent.

Use pruning and compaction carefully

Long sessions are a common source of variance. OpenClaw’s session-pruning documentation says pruning trims old tool results from the model’s context while preserving the full history. It can reduce context bloat and help with prompt caching, but its behavior depends on the provider route, endpoint, authentication, and cache TTL. A team should measure the result on its own workflow instead of assuming that enabling pruning creates a fixed saving.

Compaction is a different operation. OpenClaw’s compaction reference describes it as a persistent summary of older conversation. That summary call uses a model, so it can add provider usage. A shorter context may reduce later requests while the compaction event itself adds another request. Record both sides when testing.

A useful proposed test is small and repeatable: run representative, non-sensitive tasks with the current session policy; record token buckets, context size, cache behavior, retries, compaction events, response quality, and reviewer corrections; then change one setting and repeat. The test can show whether a smaller prompt actually lowers the cost of a completed job without removing the detail a reviewer needs.

Put enforcement at the right layer

OpenClaw’s local cost display is an observation tool. The documentation says missing pricing can cause cost to be omitted and that the Control UI totals are based on local session history rather than a provider billing ledger. That makes the report useful for operations, but it should not be treated as an account-wide spending cutoff.

An official OpenClaw feature request opened on March 10, 2026 asks for daily and monthly per-agent cost budgets. Its description calls existing cost tracking observability-only and distinguishes concurrency and disk limits from spend limits. This is an open proposal, not a product contract, but it is a good reason to check the exact enforcement behavior of the build you run.

If a hard stop matters, use a provider-side budget, quota, alert, or gateway outside the estimate and verify its scope. Many provider controls are account-wide rather than per agent. An external per-workload gate may be needed for a shared team account. OpenClaw usage reports can tell you that a route is consuming more than expected; they do not automatically turn a forecast into an authorization boundary.

A review loop the team can keep

Make one person or team responsible for the rate card. Refresh it before changing a model or provider, after enabling a new cache or processing mode, and after a material change to prompts, workspace files, tools, skills, or scheduled volume. Keep the old snapshot so a later invoice can be explained against the prices known at the time.

Each review can follow the same short record:

1. What workload was measured, and over what period?
2. Which provider, endpoint, model, account route, and settings handled it?
3. What were the input, cache, output, retry, and compaction totals?
4. Which rate-card version produced the estimate?
5. What reserve was added, and what event would invalidate it?

Reconcile the local estimate with the provider’s own usage or invoice when that is available. If they disagree, investigate the route, billing category, tools, and time window before changing the budget. The provider’s billing record is the source of truth for a charge; OpenClaw’s estimate is the working explanation.

Failure paths and limits

Plan for the cases that make a budget look more precise than it is.

• Pricing is missing. Keep the token count and mark the dollar value unknown. A missing price is not a free request.
• The route uses a subscription, OAuth, or CLI plan. Track provider quota and token usage separately from API dollars when the provider does not expose a per-message price.
• The cache expires. The same conversation may contain more cache writes or uncached input on the next request.
• A tool loop retries. Count every completed model call, including calls made during recovery or compaction.
• The context overflows. A context error can trigger compaction and a retry, or remain terminal for a provider-specific request limit. Reserve for that path and test it.
• A model alias changes. Recheck the exact model, context tier, region, and mode instead of assuming the alias kept the old price.

The point of the reserve is not to predict every failure. It is to stop ordinary variance from being mistaken for a pricing trend.

Write the policy in plain language

A team policy can fit on one page: define the workload unit; store a token vector instead of one token total; attach a dated rate card; keep provider tools and plan quotas separate; add a visible reserve; and name the person who refreshes the record. Set provider alerts or external gates when the consequence of an overrun is serious.

The useful number is therefore a range with a date: this workload, on this route, produced this token mix, under these rates, with this reserve. That answer will need revision when the workload or provider changes. It is still more honest, and more actionable, than a permanent price per million tokens.

Sources

• OpenClaw: Token use and costs
• OpenClaw: API usage and costs
• OpenClaw: Session pruning
• OpenClaw: Compaction behavior and settings
• OpenAI Help: Understanding and counting tokens
• OpenAI API pricing
• Claude Platform: Prompt caching
• Google AI: Gemini API pricing
• OpenClaw issue #42475: Per-agent cost budget enforcement