Smart Model Router

Intelligent cost-aware model routing for OpenClaw agents.

Before executing any task via sessions_spawn or delegating to a sub-agent, classify the task complexity using the rules below and route to the optimal model. This saves 60-90% on LLM costs by using cheap models for simple work and reserving premium models for tasks that genuinely need them.

Core Principle

Route every request to the cheapest model that can handle it well.

Step 1: Classify Task Complexity

Score the task on these dimensions. Count how many COMPLEX/REASONING indicators are present:

SIMPLE indicators (route to Tier 1)

• Greetings, small talk, status checks, heartbeats
• Single factual questions ("What is X?", "Define Y")
• Simple translations, format conversions
• File lookups, directory listings, basic shell commands
• Calendar checks, weather queries
• Tasks under 50 tokens with no technical depth
• Keywords: "what is", "define", "translate", "list", "check", "hello", "status"

MODERATE indicators (route to Tier 2)

• Summarization of documents or conversations
• Single-file code edits, bug fixes, simple refactors
• Writing emails, messages, short-form content
• Data extraction, parsing, formatting
• Explaining concepts, answering "how to" questions
• Research requiring synthesis of a few sources
• Keywords: "summarize", "explain", "write", "fix this", "how to", "extract"

COMPLEX indicators (route to Tier 3)

• Multi-file code generation or refactoring
• Architecture design, system design
• Creative writing (stories, long-form, nuanced tone)
• Debugging complex issues across multiple systems
• Analysis requiring multiple perspectives
• Tasks with constraints ("optimize for X while maintaining Y")
• Keywords: "build", "design", "architect", "refactor", "create", "implement", "analyze"

REASONING indicators (route to Tier 4)

• Mathematical proofs, formal logic
• Multi-step reasoning chains ("first X, then Y, therefore Z")
• Security vulnerability analysis
• Performance optimization with tradeoffs
• Scientific analysis, hypothesis testing
• Any task with 2+ of: "prove", "derive", "why does", "compare and contrast", "evaluate tradeoffs", "step by step"
• Keywords: "prove", "derive", "reason", "why does", "evaluate", "theorem"

Special Rules

• 2+ reasoning keywords → always Tier 4 (high confidence)
• Code blocks or multi-file references → minimum Tier 2
• "Debug" + stack traces → Tier 3
• Heartbeats and /status → always Tier 1
• When uncertain, default to Tier 2 (fast, cheap, good enough)

Step 2: Select Model from Tier

Tier 0 — FREE (OpenRouter free tier)

Default Tier 0 model: openrouter/free (auto-selects from available free models)

Access via OpenRouter with model IDs like google/gemini-2.5-flash, deepseek/deepseek-v3.2-20251201, moonshotai/kimi-k2.5-0127. Or use openrouter/free to auto-route across all free models.

Note: Free models have rate limits and may have variable availability. Use for non-critical tasks only.

Tier 1 — SIMPLE (near-zero cost)

Default Tier 1 model: gemini-2.0-flash (best cost/reliability balance)

Tier 2 — MODERATE (balanced)

Default Tier 2 model: claude-haiku-4-5 (best quality-to-price at this tier)

Tier 3 — COMPLEX (premium)

*GPT-5.3 Codex API pricing not yet officially released; estimated from GPT-5.2 Codex rates.

Default Tier 3 model: claude-sonnet-4-5 (best balance of quality, coding, and cost)

Tier 4 — REASONING (maximum capability)

Default Tier 4 model: claude-opus-4-6 with extended thinking enabled

Step 3: Apply Optimization Mode

🟢 Balanced Mode (DEFAULT)

Use the default model for each tier as listed above. Escalate to next tier if the model produces low-quality output or fails.

🔵 Aggressive Mode (Maximum Savings)

Override tier defaults to cheapest option:

• Tier 0-1: openrouter/free ($0.00) for simple tasks, fall back to gemini-2.0-flash ($0.10/$0.40)
• Tier 2: gemini-2.5-flash ($0.15/$0.60)
• Tier 3: gemini-2.5-pro ($1.25/$10.00)
• Tier 4: deepseek-r1 ($0.55/$2.19)

Savings: 70-99% vs always using Opus

🟡 Quality Mode (Maximum Quality)

Override tier defaults to best-in-class:

• Tier 1: claude-haiku-4-5 ($1.00/$5.00)
• Tier 2: claude-sonnet-4-5 ($3.00/$15.00)
• Tier 3: claude-opus-4-6 ($5.00/$25.00) or gpt-5.3-codex for coding
• Tier 4: claude-opus-4-6 ($5.00/$25.00) with extended thinking

Step 4: Execute with sessions_spawn

# Simple task — Tier 1
sessions_spawn --task "What's on my calendar today?" --model gemini-2.0-flash

# Moderate task — Tier 2
sessions_spawn --task "Summarize this document" --model claude-haiku-4-5

# Complex task — Tier 3
sessions_spawn --task "Build a React auth component with tests" --model claude-sonnet-4-5

# Reasoning task — Tier 4
sessions_spawn --task "Prove this algorithm is O(n log n)" --model claude-opus-4-6

Progressive Escalation Pattern

When uncertain about complexity, start cheap and escalate:

# 1. Try Tier 1 with timeout
sessions_spawn --task "Fix this bug" --model gemini-2.0-flash --runTimeoutSeconds 60

# 2. If output is poor or times out, escalate to Tier 2
sessions_spawn --task "Fix this bug" --model claude-haiku-4-5

# 3. If still failing, escalate to Tier 3
sessions_spawn --task "Fix this complex bug" --model claude-sonnet-4-5

Maximum escalation chain: 3 attempts. If Tier 3 fails, surface the error to the user rather than burning tokens.

Parallel Processing for Batch Tasks

Route batch/parallel tasks to Tier 1 models for massive savings:

# Batch summaries in parallel with cheap model
sessions_spawn --task "Summarize doc A" --model gemini-2.0-flash &
sessions_spawn --task "Summarize doc B" --model gemini-2.0-flash &
sessions_spawn --task "Summarize doc C" --model gemini-2.0-flash &
wait

# Then analyze results with premium model
sessions_spawn --task "Synthesize findings from all summaries" --model claude-sonnet-4-5

Special Routing Rules

Cost Comparison (Typical Workload)

For a typical OpenClaw day (24 heartbeats + 20 sub-agent tasks + 10 user queries):

When NOT to Route Down

Always use Tier 3+ for:

• Security-sensitive code review
• Financial calculations where errors are costly
• Architecture decisions that affect the whole codebase
• Anything the user explicitly asks for premium quality
• Tasks where the user says "be thorough" or "take your time"

Mode Switching

Users can switch modes mid-conversation:

• "Use aggressive routing" → Switch to cheapest models per tier
• "Use quality mode" → Switch to best models per tier
• "Use balanced routing" → Return to defaults
• "Use [specific model] for this" → Override routing for one task

Pricing Reference (February 2026)

All prices per million tokens. Models are listed from cheapest to most expensive output:

*GPT-5.3 Codex pricing estimated from GPT-5.2 Codex; official API pricing pending.

Note: Prices change. Check provider pricing pages for current rates. Batch API discounts (50% off) and prompt caching (50-90% off) can reduce costs further. OpenRouter free models have rate limits — see openrouter.ai/collections/free-models for current availability.