Problem

Currently, moltbot has a static default model configuration. When Claude API rate limits are hit, the system rotates through configured auth profiles but doesn't automatically switch to a cheaper/faster model to reduce load and token consumption.

Gap: No mechanism to auto-downgrade model (opus → sonnet → haiku) when rate limits spike.

Proposed Solution

Automatically downgrade default model tier when rate limit errors are detected, and gradually upgrade back when errors subside.

Research & Design Document

Full research document with 4 design approaches: specs/spec-dynamic-model-switching-rate-limits.md

Design Approaches

1. Phase 1: Extend Cooldown (MVP) - Integrate model downgrade with existing auth profile cooldown system
2. Phase 2: Metrics-Based - Track error rates over time windows, switch on configurable thresholds
3. Phase 3: Proactive Headers - Parse RateLimit-* headers to switch before hitting 429
4. Phase 4: ML/Predictive - Learn patterns to predict and prevent rate limits

Current Rate Limiting Architecture

• Rate limits detected via error classification: "rate_limit", "429", "exceeded quota"
• Per-profile cooldown: exponential backoff (1m → 5m → 25m → 1hr)
• Model fallback chain configured in moltbot.json
• State stored in: ~/.clawdbot/auth-profiles.json (encrypted)

Key Files

• Rate limit detection: src/agents/pi-embedded-helpers/errors.ts:414-416
• Profile cooldown: src/agents/auth-profiles/usage.ts:70-76
• Model selection: src/agents/pi-embedded-runner/model.ts:48-101
• Fallback chain: src/agents/model-fallback.ts:193-299
• Config types: src/config/types.auth.ts

Questions for Design Review

• Which approach to start with? (Recommend Phase 1)
• Per-provider or global model switching?
• Per-model or per-tier tracking?
• Where to store metrics state?
• What thresholds make sense? (% error rate, consecutive errors, time-based?)
• How long should model be downgraded? (same as profile cooldown? different?)
• Should users see model downgrades in logs/events?
• Should there be manual override capability?

Recommended Next Steps

1. Review spec-dynamic-model-switching-rate-limits.md
2. Align on Phase 1 design (extend profile cooldown)
3. Answer design review questions
4. Sketch Phase 1 implementation
5. Test with rate limit scenarios

Related Documentation

• Rate limit detection: src/agents/pi-embedded-helpers/errors.ts
• Auth profile cooldown: src/agents/auth-profiles/
• Model fallback: src/agents/model-fallback.ts