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):

1. Generate optimized AGENTS.md (BIGGEST WIN!):

   python3 scripts/context_optimizer.py generate-agents
   # Creates AGENTS.md.optimized — review and replace your current AGENTS.md
   

2. Check what context you ACTUALLY need:

   python3 scripts/context_optimizer.py recommend "hi, how are you?"
   # Shows: Only 2 files needed (not 50+!)
   

3. Install optimized heartbeat:

   cp assets/HEARTBEAT.template.md ~/.openclaw/workspace/HEARTBEAT.md
   

4. Enforce cheaper models for casual chat:

   python3 scripts/model_router.py "thanks!"
   # Single-provider Anthropic setup: Use Sonnet, not Opus
   # Multi-provider setup (OpenRouter/Together): Use Haiku for max savings
   

5. 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:

# Simple greeting → minimal context (2 files only!)
context_optimizer.py recommend "hi"
→ Load: SOUL.md, IDENTITY.md
→ Skip: Everything else
→ Savings: ~80% of context

# Standard work → selective loading
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

# Complex task → full 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":
    # Load only SOUL.md + IDENTITY.md
    # Skip everything else
    # Save ~80% tokens!

Generate optimized AGENTS.md:

context_optimizer.py generate-agents
# Creates AGENTS.md.optimized with lazy loading instructions
# Review and replace your current AGENTS.md

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:

# Communication (NEW!) → ALWAYS Haiku
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)

# Simple task → suggests Haiku
python3 scripts/model_router.py "read the log file"

# Medium task → suggests Sonnet
python3 scripts/model_router.py "write a function to parse JSON"

# Complex task → suggests Opus
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"]:
    # Use routing["recommended_model"]
    # Save routing["cost_savings_percent"]

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:

# Copy template to workspace
cp assets/HEARTBEAT.template.md ~/.openclaw/workspace/HEARTBEAT.md

# Plan which checks should run
python3 scripts/heartbeat_optimizer.py plan

Commands:

# Check if specific type should run now
heartbeat_optimizer.py check email
heartbeat_optimizer.py check calendar

# Record that a check was performed
heartbeat_optimizer.py record email

# Update check interval (seconds)
heartbeat_optimizer.py interval email 7200  # 2 hours

# Reset state
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):

# Parse daily logs with Haiku
cron add --schedule "0 2 * * *" \
  --payload '{
    "kind":"agentTurn",
    "message":"Parse yesterday error logs and summarize",
    "model":"anthropic/claude-haiku-4"
  }' \
  --sessionTarget isolated

Example (bad):

# ❌ Using Opus for simple check (60x more expensive!)
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:

# Test if your cronjob should use Haiku
model_router.py "parse daily error logs"
# → Output: Haiku (background task pattern detected)

5. Token Budget Tracking

Monitor usage and alert when approaching limits:

Setup:

# Check current daily usage
python3 scripts/token_tracker.py check

# Get model suggestions
python3 scripts/token_tracker.py suggest general

# Reset daily tracking
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":
    # Switch to cheaper model or defer non-urgent work
    use_model = "anthropic/claude-haiku-4"