# How to Reduce OpenClaw Token Usage

> OpenClaw rebuilds its system prompt on every run, so your bootstrap files are billed again every turn. Here are the caps that control that, and the setting that reprices a whole request.

Source: https://tokenade.net/en/articles/reduce-openclaw-token-usage · Updated: 2026-10-15

Part of the [reduce AI coding agent token usage](https://tokenade.net/en/articles/reduce-ai-coding-agent-token-usage) pillar. This page is the cost-control page; [what OpenClaw is and what it costs to run](https://tokenade.net/en/articles/openclaw) 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](https://docs.openclaw.ai/reference/token-use), 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.**

| Setting | Default | What it bounds |
|---|---|---|
| `agents.defaults.bootstrapMaxChars` | 20000 | Any single injected file |
| `agents.defaults.bootstrapTotalMaxChars` | 60000 | All bootstrap injection combined |
| `skills.limits.maxSkillsPromptChars` | — | The skills block in the prompt |
| `agents.defaults.imageMaxDimensionPx` | 1200 | Longest image side before provider calls |
| `contextLimits.memoryGetMaxChars` | — | What `memory_get` returns before truncation |

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](https://tokenade.net/en/articles/output-filtering-command-logs).

**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](https://tokenade.net/en/articles/measure-agent-token-usage) covers catching it.

## Frequently asked questions

### How do I optimize OpenClaw for lower token costs?

Start with what is injected on every run. Run `/context detail`, trim `AGENTS.md` and `MEMORY.md` to what a typical turn needs, and lower `bootstrapMaxChars` and `bootstrapTotalMaxChars` from their defaults of 20,000 and 60,000 characters. Then set `cacheRetention` per agent and leave the long-context budget off unless you have a measured reason.

### Does switching models reduce OpenClaw's token usage?

It changes the price per token, not the number of tokens. OpenClaw rebuilds its system prompt from your bootstrap files on every turn, so a heavy workspace costs the same token count on any model. Shrink the standing prompt first, then pick the model.

---

**See also**:
- [Reduce AI coding agent token usage](https://tokenade.net/en/articles/reduce-ai-coding-agent-token-usage) — the pillar
- [OpenClaw: what it is and what it costs](https://tokenade.net/en/articles/openclaw) — the explainer, including the always-on cost profile
- [How to reduce opencode token usage](https://tokenade.net/en/articles/reduce-opencode-token-usage) — the same exercise on a session-based agent