Token Budget & Optimization

+15 Mana ✨
OpenClaw Token Management(DOCUMENTATION)OpenClaw Prompt Optimization Tips(DOCUMENTATION)

Introduction

Every token in the system prompt costs money and consumes context window space that could be used for conversation. OpenClaw enforces a 150,000-token budget for the total system prompt and a 20,000-token limit per individual file. Managing these limits effectively is the difference between an agent that runs smoothly and one that constantly hits truncation issues or produces degraded responses.

Key Concepts

  • Token Budget: The maximum number of tokens the system prompt can consume (150,000 total, 20,000 per file)
  • Token Counting: How OpenClaw measures token usage (model-specific tokenizer, not character count)
  • Priority-Based Trimming: When the budget is exceeded, lower-priority sections are reduced first
  • Content Compression: Techniques for conveying the same information in fewer tokens
  • Budget Monitoring: Using openclaw prompt stats to track token usage across all prompt sections

Real World Context

A team has a 500-line AGENTS.md, 200-line SOUL.md, 15 loaded skills, and comprehensive tool documentation. Their system prompt hits 160K tokens, exceeding the budget. The documentation section gets silently trimmed, causing the agent to lose access to important API references mid-conversation. Understanding token optimization would have prevented this by identifying the bloat before it caused problems.

Deep Dive

Token counting in OpenClaw uses the target model's tokenizer. This is important because different models tokenize text differently:

markdown
Token counts for the same text vary by model:
- "function calculateTotal(items)" 
  - Claude tokenizer: ~6 tokens
  - GPT tokenizer: ~5 tokens
  - The exact count depends on the model's vocabulary

OpenClaw uses the primary model's tokenizer to calculate token usage. You can check your current usage with the prompt stats command:

bash
openclaw prompt stats

This command outputs a breakdown of token usage by section:

markdown
System Prompt Token Usage:
  Safety & Compliance:     1,200 tokens  (0.8%)
  Identity (IDENTITY.md):    350 tokens  (0.2%)
  Persona (SOUL.md):       2,800 tokens  (1.9%)
  User (USER.md):            600 tokens  (0.4%)
  Instructions (AGENTS.md): 8,500 tokens  (5.7%)
  Tool Definitions:        12,000 tokens  (8.0%)
  Tool Conventions:         1,500 tokens  (1.0%)
  Skills:                  35,000 tokens (23.3%)
  Workspace Context:        8,000 tokens  (5.3%)
  Documentation:           45,000 tokens (30.0%)
  Memory (MEMORY.md):       5,000 tokens  (3.3%)
  Total:                  119,950 tokens (80.0% of 150K budget)
  Remaining:               30,050 tokens

In this example, Documentation (30%) and Skills (23.3%) consume over half the budget. If you needed to free tokens, these would be the first places to optimize.

When the total exceeds 150K tokens, OpenClaw trims sections in reverse priority order:

markdown
Trimming priority (trimmed first to last):
1. Documentation      (lowest priority, trimmed first)
2. Workspace Context
3. Skills
4. Memory
5. Tool Conventions
6. Tool Definitions
7. Operating Instructions
8. User Context
9. Persona
10. Identity
11. Safety            (highest priority, trimmed last)

To optimize your token usage, apply these compression techniques to your bootstrap files:

markdown
# Before optimization (verbose):
When the user asks you to create a new API endpoint,
you should first check if a similar endpoint already
exists by searching the routes directory. If one exists,
ask the user if they want to modify the existing endpoint
instead of creating a new one. If they confirm they want
a new endpoint, proceed with creation.

# After optimization (compressed):
New API endpoint workflow:
1. Search `routes/` for similar endpoints
2. If found, confirm user wants a new one vs modifying existing
3. Proceed with creation on confirmation

The compressed version conveys the same instruction in roughly one-third the tokens. The model understands structured lists just as well as prose paragraphs, often better.

Common Pitfalls

  • Treating tokens like characters: A 20,000-character file is not necessarily 20,000 tokens. Tokens are typically 3-4 characters each, so a 20K character file might be only 5-6K tokens.
  • Loading too many skills simultaneously: Each loaded skill contributes to the token budget. Only load skills that are relevant to the current workspace.
  • Writing documentation as prose when lists suffice: Bullet points and structured lists use fewer tokens than narrative paragraphs while being equally clear to the model.

Best Practices

  • Run openclaw prompt stats weekly: Track your token usage trends and address growth before it causes truncation.
  • Use the 80% rule: Keep your total system prompt at or below 80% of the 150K budget (120K tokens) to leave room for runtime additions and conversation context.
  • Prefer structured formats over prose: Lists, tables, and concise headers convey instructions more token-efficiently than paragraphs.

Summary

  • OpenClaw enforces a 150K total token budget and 20K per-file limit, measured using the model's tokenizer
  • Priority-based trimming removes lower-priority sections first when the budget is exceeded
  • Use openclaw prompt stats to monitor token usage by section
  • Compress verbose prose into structured lists and concise instructions to reduce token consumption
  • Follow the 80% rule: keep total usage below 120K tokens to maintain headroom for conversation
✓ Completed