How to Reduce OpenClaw Token Usage

Part of the reduce AI coding agent token usage pillar. This page is the cost-control page; what OpenClaw is and what it costs to run is the explainer.

How do you reduce OpenClaw token usage?

Shrink what gets injected on every run before you touch anything else: OpenClaw rebuilds its system prompt from your bootstrap files on every single turn, so a fat AGENTS.md is not paid once, it is paid again and again for the life of the session. This is the property that makes OpenClaw's cost profile different from a session-based coding agent. It assembles its own prompt each run rather than carrying one forward, and that prompt includes your workspace files, the tool list, and the skills list. Everything you put in those files is a standing charge. The good news is that OpenClaw exposes real numeric caps for all of it, with documented defaults. Most of the advice you will find for this tool is about model choice. The caps move more.

Why does OpenClaw burn tokens?

Because four separate things are re-sent or re-read on a schedule, and only one of them is the conversation. Per OpenClaw's own token-use reference, every run's system prompt carries:

• the tool list with short descriptions,
• the skills list as metadata (instructions load on demand),
• self-update instructions,
• your workspace and bootstrap files — AGENTS.md, SOUL.md, IDENTITY.md, USER.md, BOOTSTRAP.md when new, and MEMORY.md when present,
• time, reply tags, heartbeat behaviour, and runtime metadata.

On top of that, the context window counts conversation history, tool calls and their results, attachments and transcripts, compaction summaries, and provider wrappers you never see. The pattern to hold on to: OpenClaw counts tokens, not characters, and most OpenAI-style models average roughly four characters per token for English. A 20,000-character AGENTS.md is therefore on the order of 5,000 tokens, arriving on every turn.

Which caps actually control it?

Five, and their defaults are published. The two bootstrap numbers are the ones to look at first. A default of 60,000 characters of combined injection is roughly 15,000 tokens of standing prompt before the conversation starts. If your workspace files come anywhere near that ceiling, you are paying it every turn, and lowering the cap is a one-line change with an immediate, permanent effect. imageMaxDimensionPx matters more than it looks on screenshot-heavy work. Lower values reduce vision-token usage and payload size directly; higher values buy OCR detail you often do not need. Tool results have a cap OpenClaw derives from the model rather than from your config: 16,000 characters below a 100K context window, 32,000 at 100K+, and 64,000 at 200K+. There is also a runtime context-share guard that caps any single tool result at 30% of the context window. Both are ceilings, not targets — a tool result that arrives just under the cap is still an enormous line item.

What is the setting that silently reprices a request?

The long-context opt-in. Crossing an input threshold can reprice the entire request, not just the tokens above the line. This is the single most expensive thing in OpenClaw's documentation and it is easy to walk into. Direct OpenAI GPT-5.5 and GPT-5.6 models publish a 1,050,000-token total window. OpenClaw deliberately defaults their active runtime budget to 272,000 tokens instead. The opt-in 922,000-token input budget reserves the full 128,000 output allowance. Here is the trap, in OpenClaw's own words: OpenAI applies higher long-context pricing to the entire request once input exceeds 272,000 tokens. Not to the excess. To all of it. So a session that drifts one token past that boundary does not pay a little more, it reprices everything it just sent. OpenClaw not enabling the large window automatically is a deliberate cost decision on their part, and overriding it is a decision you should make on purpose, with a reason, and not because a bigger number looked better in a config file. Anthropic's side is less dramatic: OpenClaw sizes GA-capable Claude 4.x models with the 1M window already, so params.context1m: true is no longer needed for those, and the credential has to be eligible or the provider answers with a rate-limit error.

How do you see where the tokens went?

/context detail for the prompt, /usage for the turn, /usage cost for the session. Four commands, each answering a different question:

• /context list and /context detail break down the prompt itself — per injected file, tools, skills, and total system prompt size. This is the one to run first, because it tells you whether your standing cost is the problem before you go optimising the conversation.
• /status gives a status card: session model, context usage, last response input/output tokens, and cost.
• /usage tokens appends a per-response footer with turn token and cache detail; /usage full adds model, context and cost. The setting persists per session, and /usage reset puts it back to the configured default.
• /usage cost summarises cost from OpenClaw's own session logs.

One caveat worth knowing before you trust the dollar figure: if you authenticate with OAuth, the system hides dollar costs and shows token counts only. On an OAuth setup, tokens are your currency.

What about caching and the heartbeat?

Cache retention is configurable per agent, and a heartbeat exists partly to keep a long cache warm. OpenClaw exposes cacheRetention in a model's params, and agents.entries.*.params merges on top of the selected model's defaults, so you can override retention alone and inherit the rest. Their documented example is instructive about intent: a research agent with heartbeat: every: "55m" to keep long cache warm for deep sessions, and an alerts agent set to cacheRetention: "none" to avoid cache writes for bursty notifications. That is the right instinct generalised: caching pays on long, repetitive contexts and costs on short bursty ones. An always-on assistant with proactive schedules has both shapes running at once, which is why setting retention per agent rather than globally is worth the ten minutes.

How to apply this today

1. Run /context detail before changing anything. You need to know whether your standing prompt or your conversation is the problem. Guessing here wastes the afternoon.
2. Measure your bootstrap files. Total their characters and divide by four for a token estimate. Against a 60,000-character default ceiling, you will usually find the answer immediately.
3. Cut AGENTS.md and MEMORY.md to what the agent actually needs on every turn. Everything else belongs behind a memory tool or a skill, loaded on demand. The test is simple: would this sentence change the agent's behaviour on a typical turn? If not, it is rent.
4. Lower bootstrapMaxChars and bootstrapTotalMaxChars to a ceiling you have chosen rather than the one you inherited.
5. Drop imageMaxDimensionPx if you paste screenshots. 1200 is generous for most UI work.
6. Leave the long-context budget alone unless you have a measured reason, and remember that crossing 272,000 input tokens reprices the whole request on GPT-5.5/5.6.
7. Set cacheRetention per agent, long for deep sessions, none for bursty ones.
8. Use /compact on long sessions rather than letting history accumulate.

What goes wrong (anti-patterns)

Treating AGENTS.md as documentation. It is not a README, it is a per-turn subscription. Teams write it once, at length, and never revisit it, which turns a thoughtful onboarding document into the largest fixed line on the invoice. Optimising the model before the prompt. Switching to a cheaper model multiplies a number you have not measured. Cutting 30,000 characters of standing injection reduces it. Do the second first. Enabling the big context window because it is available. The 922,000-token input budget is opt-in for a reason, and the repricing applies to the entire request, not the overflow. Reading a tool-result cap as a budget. 64,000 characters is the ceiling above which OpenClaw truncates, not a sensible amount of command output to put in front of a model. Filtering at the source is cheaper than being truncated at the boundary — see filtering command output. Assuming the caps cover re-reads. They bound the size of one injection or one tool result. They do nothing about the same file entering the context eleven times in a session, which is a different problem with a different fix — how to measure agent token usage covers catching it.

---

See also:

• Reduce AI coding agent token usage — the pillar
• OpenClaw: what it is and what it costs — the explainer, including the always-on cost profile
• How to reduce opencode token usage — the same exercise on a session-based agent