Token Optimizer

🪙 Token Optimizer

Reduce OpenClaw token usage and API costs by 85-95%

One-Line Installation

git clone https://github.com/Asif2BD/OpenClaw-Token-Optimizer.git ~/.openclaw/skills/token-optimizer

That's it! The skill is now available. Tell your agent:

"I have the token-optimizer skill installed. Use it to optimize my token usage."

Or manually run the scripts to start saving immediately.

What This Skill Does

Quick Start Commands

1. Generate Optimized AGENTS.md (Biggest Win!)

python3 ~/.openclaw/skills/token-optimizer/scripts/context_optimizer.py generate-agents
# Review AGENTS.md.optimized and replace your current AGENTS.md

2. Route Tasks to Appropriate Models

# Simple greeting → Use cheap model (Haiku/Nano/Flash)
python3 ~/.openclaw/skills/token-optimizer/scripts/model_router.py "thanks!"

# Complex task → Use smart model (Opus/GPT-4.1/Pro)  
python3 ~/.openclaw/skills/token-optimizer/scripts/model_router.py "design a microservices architecture"

3. Install Optimized Heartbeat

cp ~/.openclaw/skills/token-optimizer/assets/HEARTBEAT.template.md ~/.openclaw/workspace/HEARTBEAT.md

4. Check Token Budget

python3 ~/.openclaw/skills/token-optimizer/scripts/token_tracker.py check

Scripts Reference

context_optimizer.py

Recommends minimal context files based on prompt complexity.

# Recommend context for a prompt
context_optimizer.py recommend "hi"
# → Load only: SOUL.md, IDENTITY.md (savings: ~80%)

context_optimizer.py recommend "analyze our codebase"
# → Load: SOUL.md, IDENTITY.md, MEMORY.md, memory/TODAY.md (savings: ~30%)

# Generate optimized AGENTS.md
context_optimizer.py generate-agents
# Creates AGENTS.md.optimized with lazy loading instructions

# View usage statistics
context_optimizer.py stats

model_router.py

Routes tasks to appropriate model tiers. Supports multiple providers.

# Auto-detect provider and route
model_router.py "read the config file"
# → cheap tier (Haiku/Nano/Flash)

model_router.py "write a Python function"
# → balanced tier (Sonnet/Mini/Flash)

model_router.py "design system architecture"
# → smart tier (Opus/GPT-4.1/Pro)

# Force specific provider
model_router.py "thanks" --provider openai
# → openai/gpt-4.1-nano

# Compare all providers
model_router.py compare

# List providers
model_router.py providers

Supported Providers:

heartbeat_optimizer.py

Manages heartbeat check intervals with quiet hours.

# Plan which checks should run now
heartbeat_optimizer.py plan

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

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

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

# Reset all state
heartbeat_optimizer.py reset

Default Intervals:

• Email: 60 minutes
• Calendar: 2 hours
• Weather: 4 hours
• Social: 2 hours
• Monitoring: 30 minutes

Quiet Hours: 23:00-08:00 (skips non-urgent checks)

token_tracker.py

Monitors daily token budget and usage.

# Check current usage
token_tracker.py check

# Get model suggestions for task type
token_tracker.py suggest general

# Reset daily tracking
token_tracker.py reset

Status Levels:

• ok — Below 80% of daily limit
• warning — 80-99% of daily limit
• exceeded — Over limit, switch to cheaper models

Configuration

Environment Variables

Set your preferred provider's API key:

# Anthropic (default)
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI
export OPENAI_API_KEY="sk-proj-..."

# Google
export GOOGLE_API_KEY="AIza..."

# OpenRouter (unified API)
export OPENROUTER_API_KEY="sk-or-v1-..."

The model router auto-detects which provider to use based on available keys.

Customization

Edit patterns in scripts/model_router.py:

• COMMUNICATION_PATTERNS — Patterns that always use cheap tier
• BACKGROUND_TASK_PATTERNS — Heartbeat/cron patterns
• ROUTING_RULES — Task classification rules
• PROVIDER_MODELS — Model mappings per provider

Integration Patterns

Before Every Response

# 1. Get context recommendation
from context_optimizer import recommend_context_bundle
rec = recommend_context_bundle(user_prompt)

# 2. Load only recommended files
if rec["context_level"] == "minimal":
    load_only(["SOUL.md", "IDENTITY.md"])
    # Skip everything else!

# 3. Get model recommendation
from model_router import route_task
routing = route_task(user_prompt)

# 4. Use recommended model
model = routing["recommended_model"]

In HEARTBEAT.md

# Check if we should run any checks
result=$(python3 scripts/heartbeat_optimizer.py plan)
should_run=$(echo $result | jq -r .should_run)

if [ "$should_run" = "false" ]; then
    echo "HEARTBEAT_OK"
    exit 0
fi

# Run only planned checks
# ...

In Cronjobs

Always specify the cheapest model that can handle the task:

# Good: Use Haiku for routine tasks
cron add --schedule "0 * * * *" \
  --payload '{"kind":"agentTurn","message":"Check server health","model":"anthropic/claude-haiku-4"}' \
  --sessionTarget isolated

# Bad: Using Opus for simple checks (60x more expensive!)

Expected Savings

Why 85-95% Savings? (v1.2.0 Analysis)

Combined effect is multiplicative:

• Context reduction: ~78% (loads 22% of original)
• Model cost reduction: ~64% (pays 36% of original rate)
• Combined: 1 - (0.22 × 0.36) = 92% savings

Example: 100K tokens/day workload

Cronjob Savings

Using Haiku instead of Opus for 10 daily cronjobs:

• Opus: 10 × 5K tokens × $15/MTok = $0.75/day = $22.50/month
• Haiku: 10 × 5K tokens × $0.25/MTok = $0.0125/day = $0.38/month
• Savings: $22/month per agent (98% reduction)

Troubleshooting

Scripts fail with "module not found" → Ensure Python 3.7+ is installed. Scripts use stdlib only.

State files not persisting → Check ~/.openclaw/workspace/memory/ exists and is writable.

Routing suggests wrong tier → Customize patterns in scripts/model_router.py.

Budget shows $0.00 → Token tracker needs manual usage recording or integration with session_status.

Files Included

token-optimizer/
├── SKILL.md              # This file
├── README.md             # Quick start guide
├── CHANGELOG.md          # Version history
├── LICENSE               # MIT License
├── scripts/
│   ├── context_optimizer.py   # Context loading optimization
│   ├── model_router.py        # Multi-provider model routing
│   ├── heartbeat_optimizer.py # Heartbeat interval management
│   └── token_tracker.py       # Budget monitoring
├── assets/
│   ├── HEARTBEAT.template.md  # Drop-in heartbeat template
│   ├── cronjob-model-guide.md # Cronjob model selection guide
│   └── config-patches.json    # Advanced config examples
├── docs/
│   └── RESEARCH-NOTES.md      # Research and methodology
└── references/
    └── PROVIDERS.md           # Provider comparison guide

Requirements

• Python 3.7+ (stdlib only, no external dependencies)
• OpenClaw installation
• Write access to ~/.openclaw/workspace/memory/

Credits

Part of the SuperSkills collection for OpenClaw.

Created by:

• Oracle — Research, analysis, and documentation
• Morpheus — Code review and publication

"The best token is the one you don't spend." 🪙