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. 1. Generate optimized AGENTS.md (BIGGEST WIN!):

1. 2. Check what context you ACTUALLY need:

1. 3. Install optimized heartbeat:

1. 4. Enforce cheaper models for casual chat:

1. 5. Check current token budget:

Expected savings: 50-80% reduction in token costs for typical workloads (context optimization is the biggest factor!).

Core Capabilities

0. Lazy Skill Loading (NEW in v3.0 — BIGGEST WIN!)

The single highest-impact optimization available. Most agents burn 3,000–15,000 tokens per session loading skill files they never use. Stop that first.

The pattern:

1. 1. Create a lightweight SKILLS.md catalog in your workspace (~300 tokens — list of skills + when to load them)
2. Only load individual SKILL.md files when a task actually needs them
3. Apply the same logic to memory files — load MEMORY.md at startup, daily logs only on demand

Token savings:

Quick implementation in AGENTS.md:

CODEBLOCK5

Full implementation (with catalog template + optimizer script):

CODEBLOCK6

The companion skill openclaw-skill-lazy-loader includes a SKILLS.md.template, an AGENTS.md.template lazy-loading section, and a context_optimizer.py CLI that recommends exactly which skills to load for any given task.

Lazy loading handles context loading costs. The remaining capabilities below handle runtime costs. Together they cover the full token lifecycle.

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

Examples:
CODEBLOCK8

Output format:
CODEBLOCK9

Integration pattern:
Before loading context for a new session:
CODEBLOCK10

Generate optimized AGENTS.md:
CODEBLOCK11

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

Examples:
CODEBLOCK13

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

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

Commands:
CODEBLOCK16

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

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:

Example (good):
CODEBLOCK18

Example (bad):
CODEBLOCK19

Savings: Using Haiku instead of Opus for 10 daily cronjobs = $17.70/month saved per agent.

Integration with model_router:
CODEBLOCK20

5. Token Budget Tracking

Monitor usage and alert when approaching limits:

Setup:
CODEBLOCK21

Output format:
CODEBLOCK22

Status levels:

• - ok: Below 80% of daily limit
• INLINECODE12: 80-99% of daily limit
• INLINECODE13: Over daily limit

Integration pattern:
Before starting expensive operations, check budget:
CODEBLOCK23

Customization:
Edit daily_limit_usd and warn_threshold parameters in function calls.

6. Multi-Provider Strategy

See references/PROVIDERS.md for comprehensive guide on:

• - Alternative providers (OpenRouter, Together.ai, Google AI Studio)
• Cost comparison tables
• Routing strategies by task complexity
• Fallback chains for rate-limited scenarios
• API key management

Quick reference:

Configuration Patches

See assets/config-patches.json for advanced optimizations:

Implemented by this skill:

• - ✅ Heartbeat optimization (fully functional)
• ✅ Token budget tracking (fully functional)
• ✅ Model routing logic (fully functional)

Native OpenClaw 2026.2.15 — apply directly:

• - ✅ Session pruning (contextPruning: cache-ttl) — auto-trims old tool results after Anthropic cache TTL expires
• ✅ Bootstrap size limits (bootstrapMaxChars / bootstrapTotalMaxChars) — caps workspace file injection size
• ✅ Cache retention long (cacheRetention: "long" for Opus) — amortizes cache write costs

Requires OpenClaw core support:

• - ⏳ Prompt caching (Anthropic API feature — verify current status)
• ⏳ Lazy context loading (use context_optimizer.py script today)
• ⏳ Multi-provider fallback (partially supported)

Apply config patches:
CODEBLOCK24

Native OpenClaw Diagnostics (2026.2.15+)

OpenClaw 2026.2.15 added built-in commands that complement this skill's Python scripts. Use these first for quick diagnostics before reaching for the scripts.

Context breakdown

/context list    → token count per injected file (shows exactly what's eating your prompt)
/context detail  → full breakdown including tools, skills, and system prompt sections

Per-response usage tracking

/usage tokens    → append token count to every reply
/usage full      → append tokens + cost estimate to every reply
/usage cost      → show cumulative cost summary from session logs
/usage off       → disable usage footer

Session status

/status          → model, context %, last response tokens, estimated cost

Cache TTL Heartbeat Alignment (NEW in v1.4.0)

The problem: Anthropic charges ~3.75x more for cache writes than cache reads. If your agent goes idle and the 1h cache TTL expires, the next request re-writes the entire prompt cache — expensive.

The fix: Set heartbeat interval to 55min (just under the 1h TTL). The heartbeat keeps the cache warm, so every subsequent request pays cache-read rates instead.

CODEBLOCK28

Apply to your OpenClaw config:
CODEBLOCK29

Who benefits: Anthropic API key users only. OAuth profiles already default to 1h heartbeat (OpenClaw smart default). API key profiles default to 30min — bumping to 55min is both cheaper (fewer calls) and cache-warm.

Deployment Patterns

For Personal Use

1. 1. Install optimized INLINECODE28
2. Run budget checks before expensive operations
3. Manually route complex tasks to Opus only when needed

Expected savings: 20-30%

For Managed Hosting (xCloud, etc.)

1. 1. Default all agents to Haiku
2. Route user interactions to Sonnet
3. Reserve Opus for explicitly complex requests
4. Use Gemini Flash for background operations
5. Implement daily budget caps per customer

Expected savings: 40-60%

For High-Volume Deployments

1. 1. Use multi-provider fallback (OpenRouter + Together.ai)
2. Implement aggressive routing (80% Gemini, 15% Haiku, 5% Sonnet)
3. Deploy local Ollama for offline/cheap operations
4. Batch heartbeat checks (every 2-4 hours, not 30 min)

Expected savings: 70-90%

Integration Examples

Workflow: Smart Task Handling

Workflow: Optimized Heartbeat

Troubleshooting

Issue: Scripts fail with "module not found"

• - Fix: Ensure Python 3.7+ is installed. Scripts use only stdlib.

Issue: State files not persisting

• - Fix: Check that ~/.openclaw/workspace/memory/ directory exists and is writable.

Issue: Budget tracking shows $0.00

• - Fix: token_tracker.py needs integration with OpenClaw's session_status tool. Currently tracks manually recorded usage.

Issue: Routing suggests wrong model tier

• - Fix: Customize ROUTING_RULES in model_router.py for your specific patterns.

Maintenance

Daily:

• - Check budget status: INLINECODE34

Weekly:

• - Review routing accuracy (are suggestions correct?)
• Adjust heartbeat intervals based on activity

Monthly:

• - Compare costs before/after optimization
• Review and update PROVIDERS.md with new options

Cost Estimation

Example: 100K tokens/day workload

Without skill:

• - 50K context tokens + 50K conversation tokens = 100K total
• All Sonnet: 100K × $3/MTok = $0.30/day = $9/month

Key insight: Context optimization (50K → 10K tokens) saves MORE than model routing!

xCloud hosting scenario (100 customers, 50K tokens/customer/day):

• - Baseline (all Sonnet, full context): $450/month
• With token-optimizer: $135/month
• Savings: $315/month per 100 customers (70%)

Resources

Scripts (4 total)

• - context_optimizer.py — Context loading optimization and lazy loading (NEW!)
• model_router.py — Task classification, model suggestions, and communication enforcement (ENHANCED!)
• heartbeat_optimizer.py — Interval management and check scheduling
• token_tracker.py — Budget monitoring and alerts

References

• - PROVIDERS.md — Alternative AI providers, pricing, and routing strategies

Assets (3 total)

• - HEARTBEAT.template.md — Drop-in optimized heartbeat template with Haiku enforcement (ENHANCED!)
• cronjob-model-guide.md — Complete guide for choosing models in cronjobs (NEW!)
• config-patches.json — Advanced configuration examples

Future Enhancements

Ideas for extending this skill:

1. 1. Auto-routing integration — Hook into OpenClaw message pipeline
2. Real-time usage tracking — Parse session_status automatically
3. Cost forecasting — Predict monthly spend based on recent usage
4. Provider health monitoring — Track API latency and failures
5. A/B testing — Compare quality across different routing strategies