Token Optimizer
Comprehensive toolkit for reducing token usage and API costs in OpenClaw deployments. Combines smart model routing, optimized heartbeat intervals, usage tracking, and multi-provider strategies.
Quick Start
Immediate actions (no config changes needed):
-
Generate optimized AGENTS.md (BIGGEST WIN!):
python3 scripts/context_optimizer.py generate-agents
-
Check what context you ACTUALLY need:
python3 scripts/context_optimizer.py recommend "hi, how are you?"
-
Install optimized heartbeat:
cp assets/HEARTBEAT.template.md ~/.openclaw/workspace/HEARTBEAT.md
-
Enforce cheaper models for casual chat:
python3 scripts/model_router.py "thanks!"
-
Check current token budget:
python3 scripts/token_tracker.py check
Expected savings: 50-80% reduction in token costs for typical workloads (context optimization is the biggest factor!).
Core Capabilities
1. Context Optimization (NEW!)
Biggest token saver β Only load files you actually need, not everything upfront.
Problem: Default OpenClaw loads ALL context files every session:
- SOUL.md, AGENTS.md, USER.md, TOOLS.md, MEMORY.md
- docs/**/*.md (hundreds of files)
- memory/2026-*.md (daily logs)
- Total: Often 50K+ tokens before user even speaks!
Solution: Lazy loading based on prompt complexity.
Usage:
python3 scripts/context_optimizer.py recommend "<user prompt>"
Examples:
context_optimizer.py recommend "hi"
β Load: SOUL.md, IDENTITY.md
β Skip: Everything else
β Savings: ~80% of context
context_optimizer.py recommend "write a function"
β Load: SOUL.md, IDENTITY.md, memory/TODAY.md
β Skip: docs, old memory, knowledge base
β Savings: ~50% of context
context_optimizer.py recommend "analyze our entire architecture"
β Load: SOUL.md, IDENTITY.md, MEMORY.md, memory/TODAY+YESTERDAY.md
β Conditionally load: Relevant docs only
β Savings: ~30% of context
Output format:
{
"complexity": "simple",
"context_level": "minimal",
"recommended_files": ["SOUL.md", "IDENTITY.md"],
"file_count": 2,
"savings_percent": 80,
"skip_patterns": ["docs/**/*.md", "memory/20*.md"]
}
Integration pattern:
Before loading context for a new session:
from context_optimizer import recommend_context_bundle
user_prompt = "thanks for your help"
recommendation = recommend_context_bundle(user_prompt)
if recommendation["context_level"] == "minimal":
Generate optimized AGENTS.md:
context_optimizer.py generate-agents
Expected savings: 50-80% reduction in context tokens.
2. Smart Model Routing (ENHANCED!)
Automatically classify tasks and route to appropriate model tiers.
NEW: Communication pattern enforcement β Never waste Opus tokens on "hi" or "thanks"!
Usage:
python3 scripts/model_router.py "<user prompt>" [current_model] [force_tier]
Examples:
python3 scripts/model_router.py "thanks!"
python3 scripts/model_router.py "hi"
python3 scripts/model_router.py "ok got it"
β Enforced: Haiku (NEVER Sonnet/Opus for casual chat)
python3 scripts/model_router.py "read the log file"
python3 scripts/model_router.py "write a function to parse JSON"
python3 scripts/model_router.py "design a microservices architecture"
Patterns enforced to Haiku (NEVER Sonnet/Opus):
Communication:
- Greetings: hi, hey, hello, yo
- Thanks: thanks, thank you, thx
- Acknowledgments: ok, sure, got it, understood
- Short responses: yes, no, yep, nope
- Single words or very short phrases
Background tasks:
- Heartbeat checks: "check email", "monitor servers"
- Cronjobs: "scheduled task", "periodic check", "reminder"
- Document parsing: "parse CSV", "extract data from log", "read JSON"
- Log scanning: "scan error logs", "process logs"
Integration pattern:
from model_router import route_task
user_prompt = "show me the config"
routing = route_task(user_prompt)
if routing["should_switch"]:
Customization:
Edit ROUTING_RULES or COMMUNICATION_PATTERNS in scripts/model_router.py to adjust patterns and keywords.
3. Heartbeat Optimization
Reduce API calls from heartbeat polling with smart interval tracking:
Setup:
cp assets/HEARTBEAT.template.md ~/.openclaw/workspace/HEARTBEAT.md
python3 scripts/heartbeat_optimizer.py plan
Commands:
heartbeat_optimizer.py check email
heartbeat_optimizer.py check calendar
heartbeat_optimizer.py record email
heartbeat_optimizer.py interval email 7200
heartbeat_optimizer.py reset
How it works:
- Tracks last check time for each type (email, calendar, weather, etc.)
- Enforces minimum intervals before re-checking
- Respects quiet hours (23:00-08:00) β skips all checks
- Returns
HEARTBEAT_OK when nothing needs attention (saves tokens)
Default intervals:
- Email: 60 minutes
- Calendar: 2 hours
- Weather: 4 hours
- Social: 2 hours
- Monitoring: 30 minutes
Integration in HEARTBEAT.md:
## Email Check
Run only if: `heartbeat_optimizer.py check email` β `should_check: true`
After checking: `heartbeat_optimizer.py record email`
Expected savings: 50% reduction in heartbeat API calls.
Model enforcement: Heartbeat should ALWAYS use Haiku β see updated HEARTBEAT.template.md for model override instructions.
4. Cronjob Optimization (NEW!)
Problem: Cronjobs often default to expensive models (Sonnet/Opus) even for routine tasks.
Solution: Always specify Haiku for 90% of scheduled tasks.
See: assets/cronjob-model-guide.md for comprehensive guide with examples.
Quick reference:
| Task Type |
Model |
Example |
| Monitoring/alerts |
Haiku |
Check server health, disk space |
| Data parsing |
Haiku |
Extract CSV/JSON/logs |
| Reminders |
Haiku |
Daily standup, backup reminders |
| Simple reports |
Haiku |
Status summaries |
| Content generation |
Sonnet |
Blog summaries (quality matters) |
| Deep analysis |
Sonnet |
Weekly insights |
| Complex reasoning |
Never use Opus for cronjobs |
|
Example (good):
cron add --schedule "0 2 * * *" \
--payload '{
"kind":"agentTurn",
"message":"Parse yesterday error logs and summarize",
"model":"anthropic/claude-haiku-4"
}' \
--sessionTarget isolated
Example (bad):
cron add --schedule "*/15 * * * *" \
--payload '{
"kind":"agentTurn",
"message":"Check email",
"model":"anthropic/claude-opus-4"
}' \
--sessionTarget isolated
Savings: Using Haiku instead of Opus for 10 daily cronjobs = $17.70/month saved per agent.
Integration with model_router:
model_router.py "parse daily error logs"
5. Token Budget Tracking
Monitor usage and alert when approaching limits:
Setup:
python3 scripts/token_tracker.py check
python3 scripts/token_tracker.py suggest general
python3 scripts/token_tracker.py reset
Output format:
{
"date": "2026-02-06",
"cost": 2.50,
"tokens": 50000,
"limit": 5.00,
"percent_used": 50,
"status": "ok",
"alert": null
}
Status levels:
ok: Below 80% of daily limit
warning: 80-99% of daily limit
exceeded: Over daily limit
Integration pattern:
Before starting expensive operations, check budget:
import json
import subprocess
result = subprocess.run(
["python3", "scripts/token_tracker.py", "check"],
capture_output=True, text=True
)
budget = json.loads(result.stdout)
if budget["status"] == "exceeded":
use_model = "anthropic/claude-haiku-4"