Multi-model automatic fallback system. Monitors model availability and automatically falls back to backup models when the primary model fails. Supports MiniMax, Kimi, Zhipu and other OpenAI-compatible APIs. Use when: (1) Primary model API is unavailable, (2) Model response time is too slow, (3) Rate limit exceeded, (4) Need to optimize costs by using cheaper models for simple tasks.
Multi-model automatic fallback system. Monitors model availability and automatically falls back to backup models when the primary model fails. Supports MiniMax, Kimi, Zhipu and other OpenAI-compatible APIs. Use when: (1) Primary model API is unavailable, (2) Model response time is too slow, (3) Rate limit exceeded, (4) Need to optimize costs by using cheaper models for simple tasks.
Model Fallback Skill
Multi-model automatic fallback system for AI agents
Overview
This skill provides automatic model fallback functionality for OpenClaw agents. When the primary model fails (unavailable, slow, or rate-limited), it automatically switches to backup models in a predefined priority order.
Features
Automatic Fallback: Seamlessly switch to backup models on failure
Configurable Priority: Define your own model fallback order
Health Monitoring: Track model availability and response times
Cost Optimization: Use cheaper models for simple tasks
The skill automatically handles model failures. No explicit calls needed.
# Trigger a model call (fallback happens automatically on failure)
Manual Fallback
# Force fallback to next model
/scripts/model-fallback.sh --force-next
# Check current model status
/scripts/model-fallback.sh --status
# Reset to primary model
/scripts/model-fallback.sh --reset
1. User makes request with primary model
2. Model call fails (error, timeout, rate limit)
3. Skill detects failure
4. Wait 3 seconds (debounce)
5. Switch to next model in chain
6. Retry request with new model
7. If successful, return result
8. If failed, repeat steps 4-7
9. If all models fail, return error with details
Fallback Triggers
Trigger
Condition
Action
API Unavailable
Connection timeout
Fallback
Rate Limit
429 response
Fallback + wait
Slow Response
> timeout seconds
Fallback
Invalid Response
Parse error
Fallback
Auth Error
401/403 response
Log + stop
Logging
Logs are written to:
~/.openclaw/logs/model-fallback.log
Log Format
[2026-02-27 14:00:00] [INFO] Primary model MiniMax-M2.5 called
[2026-02-27 14:00:05] [WARN] Model failed: rate limit exceeded
[2026-02-27 14:00:05] [INFO] Falling back to Kimi K2.5
[2026-02-27 14:00:10] [INFO] Fallback successful
