Smart Model Router

Classify tasks → route to cheapest capable model → track costs. Save 60-80% on API spend.

Quick Start

# Analyze a task and recommend the best model
python3 scripts/smart-model-router.py route "Write a haiku about cats"

# Route with auto-execution (passes task to recommended model)
python3 scripts/smart-model-router.py route "Refactor this authentication module" --execute

# Show cost dashboard (last 24h / 7d / 30d)
python3 scripts/smart-model-router.py dashboard

# Show per-model cost breakdown
python3 scripts/smart-model-router.py dashboard --breakdown

# Configure model tiers and pricing
python3 scripts/smart-model-router.py config --show
python3 scripts/smart-model-router.py config --set-budget 5.00 --period daily

# Classify a task without routing
python3 scripts/smart-model-router.py classify "Debug this race condition in the async worker pool"

# View routing history
python3 scripts/smart-model-router.py history --last 20

Task Classification Tiers

The router classifies every task into one of 4 complexity tiers:

| Tier | Complexity | Default Model | Cost/1K tokens | Use Cases |

|------|-----------|---------------|-----------------|-----------|

| T1 | Simple | Haiku 4.5 | ~$0.001 | Formatting, simple Q&A, summaries, translations |

| T2 | Standard | Sonnet 4.6 | ~$0.015 | Writing, analysis, standard coding, research |

| T3 | Complex | GPT-5.4 / Opus | ~$0.075 | Architecture, debugging, multi-step reasoning |

| T4 | Critical | Opus 4.6 | ~$0.15 | Security analysis, strategic decisions, orchestration |

Classification Signals

The classifier examines:

• Keywords: "debug", "architect", "security" → higher tier; "format", "list", "summarize" → lower
• Token estimate: Short tasks tend lower, long complex prompts tend higher
• Domain markers: Code with error traces → T3+; prose writing → T1-T2
• User override: --tier T4 forces a specific tier
• History: If a T2 model failed the same task type before → auto-escalate

Budget Controls

# Set daily budget cap
python3 scripts/smart-model-router.py config --set-budget 5.00 --period daily

# Set monthly budget cap
python3 scripts/smart-model-router.py config --set-budget 180.00 --period monthly

# When budget exceeded, auto-downgrade to cheapest available
# Emergency override: --force bypasses budget

Configuration

Config stored at ~/.openclaw/workspace/model-router-config.json:

{
  "tiers": {
    "T1": {"models": ["haiku-4.5"], "max_cost_per_1k": 0.002},
    "T2": {"models": ["sonnet-4.6", "gpt-4o"], "max_cost_per_1k": 0.02},
    "T3": {"models": ["gpt-5.4", "sonnet-4.6"], "max_cost_per_1k": 0.08},
    "T4": {"models": ["opus-4.6"], "max_cost_per_1k": 0.20}
  },
  "budget": {"daily": 5.00, "monthly": 180.00},
  "fallback_chain": ["haiku-4.5", "local:gemma4", "cached"],
  "track_file": "~/.openclaw/workspace/model-router-usage.jsonl"
}

Cost Tracking

Every routed task logs to model-router-usage.jsonl:

{"ts": "2026-04-06T05:00:00Z", "task_hash": "a1b2c3", "tier": "T2", "model": "sonnet-4.6", "tokens_in": 450, "tokens_out": 1200, "cost_usd": 0.024, "latency_ms": 1830, "success": true}

Dashboard reads this file to compute:

• Total spend (daily/weekly/monthly)
• Per-model breakdown (cost, calls, avg latency)
• Savings estimate vs all-Opus baseline
• Budget remaining

Integration with OpenClaw

Add to your AGENTS.md or agent config:

### Model Routing
Before executing any task, classify it with smart-model-router.
Use the recommended model. Only escalate if the task fails on the recommended tier.

Fallback Chain

When a model is unavailable or over budget:

1. Try next model in the tier's model list

2. If all tier models fail → downgrade one tier

3. If budget exceeded → force T1 (Haiku)

4. Last resort → return cached response if available