OpenClaw Context Bloat: Your Agent Burns 20–30% of Tokens on Bootstrap Files Before You Say Anything

A GitHub issue filed yesterday (#67419) confirmed what many users suspected: OpenClaw re-injects all workspace bootstrap files (MEMORY.md, SOUL.md, USER.md, AGENTS.md, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md) on every single turn — not just session start. On a long conversation, that's 20–30% of your context window gone before your actual message even lands. Here's what to do about it.

What's Actually Happening

OpenClaw injects your workspace markdown files into the system prompt at session start — that's intentional and expected. The bug (issue #67419): these files are re-injected on every turn in the current implementation, not cached or deduplicated across the session. On multi-turn conversations, the overhead compounds. The webchat context meter has also been showing false overflow errors as a downstream symptom (issue #67135).

The numbers from the issue are concrete: MEMORY.md alone can run 1,500–2,000 tokens. Add SOUL.md (~500), USER.md (~200), AGENTS.md (~400), IDENTITY.md (~200), TOOLS.md (~300), HEARTBEAT.md (~300) and you're looking at 3,400–3,900 tokens per turn in overhead — on a 200K context window model that's ~2%, but on Claude Sonnet 4 or local models with smaller windows, it becomes a real constraint and a real cost.

Why This Matters for Cost

Every token in your context costs money on input pricing. If your bootstrap files total 4,000 tokens and you run 50 turns a day across 30 days, that's:

4,000 tokens × 50 turns × 30 days = 6,000,000 extra input tokens/month

At Claude Sonnet 4 pricing (~$3/million input tokens), that's $18/month in pure overhead — context you're paying for that isn't doing any work. Scale that to multi-agent setups and it compounds fast.

Fix #1 — Trim Your Workspace Files (Biggest Impact, Do This First)

The most effective fix is reducing the token weight of your bootstrap files themselves. Audit each file:

• MEMORY.md — should be a compact index, not a growing journal. Archive old entries to memory/archive/. Keep active facts under 500 tokens.
• SOUL.md — persona and tone, not a policy document. If it's over 200 tokens, it's too long.
• AGENTS.md — role definitions only. Remove prose explanations that belong in a README.
• BOOTSTRAP.md — delete it once you're set up. It has no ongoing value.
• TOOLS.md — short bullets only. Remove anything you know by heart.

Cutting from 4,000 to 1,500 tokens halves your overhead cost immediately, with no config changes needed.

Fix #2 — Move Stable Content to Skills Instead of Workspace Files

Skills are only loaded when called, not injected every turn. Any knowledge or instructions that don't need to be active on every single message should live in a skill, not in MEMORY.md or SOUL.md.

Good candidates to move to skills:

• Reference information (product specs, process docs, client details)
• Workflow instructions for specific tasks ("how to write a blog post")
• Contact lists, templates, FAQs

Keep in workspace files only: core identity, active project state, and anything the agent genuinely needs on every turn.

Fix #3 — Use the localModelLean Flag (4.15-beta.1+)

If you're on 4.15-beta.1, the new localModelLean: true experimental flag drops heavy default tools from the prompt (browser, cron, message) — reducing total prompt weight by another 500–1,500 tokens depending on your tool config. Not a direct fix for workspace file injection, but meaningfully reduces total overhead.

// openclaw.json
{
  "agents": {
    "defaults": {
      "experimental": {
        "localModelLean": true
      }
    }
  }
}

Fix #4 — Wait for the Official Fix

Issue #67419 is open and has maintainer attention. The proper fix is caching the bootstrap injection and only re-injecting when workspace files change, not on every turn. This will likely land in 4.15 stable or 4.16. Watch the issue for updates.

How to Measure Your Current Overhead

Run this to see your current workspace token weight:

# Count approximate tokens in your workspace bootstrap files
wc -w ~/.openclaw/workspace/MEMORY.md \
       ~/.openclaw/workspace/SOUL.md \
       ~/.openclaw/workspace/USER.md \
       ~/.openclaw/workspace/AGENTS.md \
       ~/.openclaw/workspace/IDENTITY.md \
       ~/.openclaw/workspace/TOOLS.md 2>/dev/null

Multiply the word count by ~1.3 for a rough token estimate. Anything over 2,000 tokens total is worth aggressively trimming.

TL;DR

• OpenClaw re-injects all workspace files every turn — ~4,000 tokens of overhead by default
• Fix now: trim MEMORY.md aggressively, delete BOOTSTRAP.md, move reference content to skills
• Target: under 1,500 tokens total across all workspace files
• Official fix in progress on GitHub issue #67419