Model Strategy Engine

Merged from: free-tier-models + model-strategy-engine (2026-05-11) Previous locations:

• projects/free-tier-models/PROJECT.md — active, provider-focused
• projects/free-tier-models/ARCHITECTURE.md — architecture doc (now merged into projects/model-strategy-engine/ARCHITECTURE.md)
• projects/model-strategy-engine/PROJECT.md — planning, strategy-focused

---

The Vision (from Maxime)#

"Instead of configuring fallback per agent, define a global strategy where we classify what to use based on the models' capabilities. Agents can switch when relevant, depending on quota left, complexity, and importance. Keep some models reserved for manual selection. End of day: use remaining quota for extra thinking, strategic or cleaning tasks. Monitor, configure, and track optimizations."

Key operational goal: Leverage free tiers from Google Gemini, Groq, and GitHub Models to save on paid DeepSeek calls while expanding agent capabilities (vision, speed, alternative quality). All routing is configurable — Maxime decides what to activate and in what order.

---

Current State#

• Gemini provider already registered in OpenClaw config (11 models)
• Agents run DeepSeek only: Main (reasoner), Debbie/Chris/Vera/Oscar (chat), Kelly (reasoner)
• Fallback chain: primary → deepseek-chat → deepseek-pro → qwen local
• No Groq or GitHub Models configured yet
• Strategy engine libraries (lib/strategy-engine.ts, lib/switch-engine.ts, etc.) are built but not wired into the dispatch pipeline
• Docs should be audited for consistency vs actual config

---

Providers#

GitHub Models note: Uses GitHub PAT with models:read scope. Free tier is genuinely free (no credit card) but rate-limited per model. The playground AND API share the same limits — once hit, must wait for daily reset.

Source: GitHub Docs — Rate limits

GitHub Models — Tier Classification#

---

Architecture#

See ARCHITECTURE.md for full architecture, provider tiers, built components, data flow, and gap analysis.

Quick summary: Task dispatched → Strategy Engine (classifier + selector + switch engine) → Fallback chain (Gemini → Groq → GitHub → DeepSeek → Qwen) → Agent runs → Model Tracker logs usage → End-of-day drain at 23:00 SGT.

---

Gap Analysis (Planned Phases)#

Phase 1 — Routing History & Monitoring (High Priority, t-3328)#

Without data, we can't optimise.

• Add routing log writer → .strategy-routing/YYYY-MM-DD.jsonl
• Add routing log reader API (GET /api/models/routing-history)
• Add savings estimation to routing log
• Tests

Phase 2 — Agent Dispatch Integration (Critical, t-3329)#

Make the strategy engine control routing.

• Pre-run hook in MC dispatch: /api/tasks/[id]/run calls selectModel()
• Set agent model for single run via API
• Fallback to default model if engine fails
• Log every routing decision
• Tests

Phase 3 — Strategy Dashboard Page (High Priority, t-3330)#

Central UI for strategy management.

• /models/strategy page with:
  • Strategy rules (complexity → reasoning tier, importance → speed preference)
  • Agent routing table (who's on what, why, savings)
  • Quota utilization grid (all models, free tiers, reserves)
  • Routing history (last 50 decisions)
  • Drain status & manual trigger

Phase 4 — Optimization Tracking & Reports (Medium Priority)#

• .model-optimization/YYYY-MM-DD.jsonl logging
• Weekly aggregation cron (Debbie, Saturdays)
• WhatsApp report: "This week: routed N tasks, saved $X"
• Optimization tracking page

Phase 5 — End-of-Day Drain with Real Work (Medium Priority)#

• Drain task queue registry (reflections, stale review, doc audit, reindex)
• Wire drain scheduler to actual task dispatch
• Exclusion rules: no drain on reserved/critical paths
• Log drain results with savings
• Auto-trigger at 23:00 SGT

Phase 6 — Manual Override Dashboard & Pool Management (Low Priority)#

• Reserved models section on strategy page
• Manual override log
• Quota remaining on reserved models
• Alert when reserved model usage is high

---

Implementation Tasks#

ℹ️ The original free-tier-models project had placeholder task IDs (t-332 to t-339). These were never created as real task files. The actual tasks above (t-3307, t-3328–3330, t-3339–3343) are the real implementation tasks.

---

Configuration Schema#

Global Strategy Config (~/.openclaw/strategy-config.json)#

{
  "global": {
    "enabled": true,
    "defaultStrategy": "reserve-balanced",
    "taskClassification": "auto",
    "quotaCheckInterval": "realtime",
    "drainEnabled": true,
    "drainTime": "23:00",
    "drainTaskQueue": ["reflections", "stale_review", "doc_audit", "reindex"],
    "fallbackOnReserved": false,
    "logRouting": true,
    "logOptimization": true
  },
  "complexityMapping": {
    "trivial": "none",
    "simple": "basic",
    "moderate": "moderate",
    "complex": "deep",
    "critical": "frontier"
  },
  "importanceSpeedPreference": {
    "low": ["realtime", "fast", "moderate", "slow"],
    "normal": ["fast", "moderate", "realtime", "slow"],
    "high": ["moderate", "fast", "slow", "realtime"],
    "critical": ["moderate", "slow", "fast", "realtime"]
  },
  "costBudget": {
    "dailyCap": 5.00,
    "monthlyCap": 100.00,
    "priorityBudget": 1.00,
    "reserveBudget": 0.50
  },
  "reserveModels": {
    "deepseek-v4-pro": "manual_only",
    "claude-sonnet-4-6": "manual_only",
    "claude-opus-4-7": "last_resort"
  }
}

Per-Agent Strategy Config (~/.openclaw/switch-config.json)#

{
  "chris": {
    "strategy": "reserve-balanced",
    "fallbacks": ["gemini-2.5-flash", "groq-llama", "qwen"],
    "tier": "code",
    "drainEnabled": false
  },
  "debbie": {
    "strategy": "fallback",
    "fallbacks": ["groq-llama", "qwen"],
    "tier": "analysis",
    "drainEnabled": true
  },
  "oscar": {
    "strategy": "fallback",
    "fallbacks": ["qwen"],
    "tier": "simple",
    "drainEnabled": true
  }
}

---

Monitoring Dashboard#

Section 1: Status Bar#

╔══════════════════════════════════════════════════════════════════╗
║  ⚙️ STRATEGY ENGINE  ● Active   ● 9.4k routed today           ║
║  💰 $1.42 spent today (cap $5.00)   📊 71% free-tier utilized  ║
║  🔄 Dispatching in 2/6 agents    🗑️ Drain pending at 23:00     ║
╚══════════════════════════════════════════════════════════════════╝

Section 2: Agent Routing Table#

┌─────────┬──────────────┬──────────────┬────────────────┬────────────┐
│ Agent   │ Primary      │ Current      │ Reason         │ Savings    │
├─────────┼──────────────┼──────────────┼────────────────┼────────────┤
│ Chris   │ deepseek-chat│ gemini-2.5-flash │ free quota avail │ $0.42   │
│ Debbie  │ deepseek-chat│ qwen (local) │ local → free   │ $0.00     │
│ Kelly   │ deepseek-reasoner │ deepseek-reasoner │ primary (manual) │ $0.00 │
│ Oscar   │ qwen (local) │ qwen (local) │ local only     │ $0.00     │
│ Vera    │ deepseek-chat│ deepseek-chat│ primary avail  │ $0.00     │
│ Robbie  │ deepseek-reasoner │ deepseek-reasoner │ high-importance │ $0.00 │
└─────────┴──────────────┴──────────────┴────────────────┴────────────┘

Section 3: Quota Utilization#

┌────────────────────┬───────┬──────┬───────────┬────────┐
│ Model              │ Quota │ Used │ Remaining │ %      │
├────────────────────┼───────┼──────┼───────────┼────────┤
│ gemini-2.5-flash   │ 10000 │ 2841 │ 7159      │ 28% ██│
│ gemini-2.0-flash   │ 1500  │ 520  │ 980       │ 35% ██│
│ gemma-4-31b-it     │ ∞     │ 12   │ ∞         │ —     │
│ qwen (local)       │ ∞     │ 47   │ ∞         │ —     │
│ deepseek-chat      │ $budget│ $0.84│ $3.16     │ 21% █│
│ deepseek-reasoner  │ $budget│ $0.42│ $3.74     │ 10% ░│
└────────────────────┴──────────────┴───────────┴────────┘

Section 4: Routing History (today)#

[09:42] t-3327 → deepseek-chat (complexity: moderate, importance: normal)
[10:15] t-3328 → gemini-2.5-flash (free tier, saved $0.14)
[11:03] t-3329 → qwen-coder (local, code task)
[12:30] t-3330 → deepseek-reasoner (manual override, high importance)

📊 Today: 4 routed | $0.42 estimated savings | 2 models avoided

Section 5: Drain Status#

🗑️ End-of-Day Drain @ 23:00 SGT
  - Models with remaining quota: gemini-2.5-flash (7,159), gemini-2.0-flash (980)
  - Drainable tasks: 3 (reflections, stale review, doc audit)
  - Estimated drain: ~100 requests
  - ⏱️ Manual drain available: [Drain Now] [Dry Run]

---

Related#

• ARCHITECTURE.md — full architecture, provider tiers, built components, data flow, integration points
• app/api/models/route.ts — model registry API (MODEL_META entries with dailyFreeQuota)
• app/api/models/strategy/route.ts — strategy API
• components/ModelsClient.tsx — model listing UI with free tier toggle
• components/FinanceClient.tsx — cost/finance UI
• lib/strategy-engine.ts — core selection algorithm
• lib/switch-engine.ts — quota-aware fallback routing
• lib/switch-config.ts — per-agent switch config
• lib/drain-scheduler.ts — end-of-day drain
• lib/model-tracker.ts — usage logging
• lib/model-recommender.ts — usage-based recommendations
• ~/.openclaw/workspace/docs/global-model-strategy.md — workspace-level model strategy
• app/api/models/route.ts#freeTierModels — GitHub Models MODEL_META entries with freeTier and dailyFreeQuota