# Send Multi-model automatic fallback system to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "model-fallback",
    "name": "Multi-model automatic fallback system",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/azure5100/model-fallback",
    "canonicalUrl": "https://clawhub.ai/azure5100/model-fallback",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/model-fallback",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=model-fallback",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "model-fallback",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-02T15:41:38.190Z",
      "expiresAt": "2026-05-09T15:41:38.190Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=model-fallback",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=model-fallback",
        "contentDisposition": "attachment; filename=\"model-fallback-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "model-fallback"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/model-fallback"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/model-fallback",
    "downloadUrl": "https://openagent3.xyz/downloads/model-fallback",
    "agentUrl": "https://openagent3.xyz/skills/model-fallback/agent",
    "manifestUrl": "https://openagent3.xyz/skills/model-fallback/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/model-fallback/agent.md"
  }
}
```
## Documentation

### 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
Logging: Full audit trail of fallback events

### Supported Models

ProviderModelContextUse CaseMiniMaxM2.5200KPrimary (reasoning)MiniMaxM2.1200KBackupKimiK2.5256KLong documentsKimiK2128KStandardZhipuGLM-4-Air128KLow costZhipuGLM-4-Flash1MHigh volume

### Default Fallback Chain

{
  "fallback_chain": [
    {
      "provider": "minimax-portal",
      "model": "MiniMax-M2.5",
      "priority": 1,
      "timeout": 30,
      "max_retries": 3
    },
    {
      "provider": "moonshot",
      "model": "kimi-k2.5",
      "priority": 2,
      "timeout": 30,
      "max_retries": 2
    },
    {
      "provider": "zhipu",
      "model": "glm-4-air",
      "priority": 3,
      "timeout": 20,
      "max_retries": 2
    }
  ]
}

### Environment Variables

VariableRequiredDescriptionMODEL_FALLBACK_ENABLEDNoEnable/disable fallback (default: true)MODEL_FALLBACK_LOG_LEVELNoLog level: debug, info, warn, error

### Basic Usage

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

### Configuration

Edit config.json to customize the fallback chain:

{
  "fallback_chain": [
    {"provider": "...", "model": "...", "priority": 1}
  ],
  "health_check": {
    "enabled": true,
    "interval_seconds": 300
  }
}

### How It Works

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

TriggerConditionActionAPI UnavailableConnection timeoutFallbackRate Limit429 responseFallback + waitSlow Response> timeout secondsFallbackInvalid ResponseParse errorFallbackAuth Error401/403 responseLog + 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

### Cost Optimization

Use cheaper models for simple tasks:

{
  "task_routing": {
    "simple_query": ["glm-4-air", "glm-4-flash"],
    "complex_reasoning": ["MiniMax-M2.5", "kimi-k2.5"],
    "long_context": ["kimi-k2.5", "MiniMax-M2.1"]
  }
}

### OpenClaw Configuration

Add to openclaw.json:

{
  "models": {
    "mode": "merge",
    "fallback": {
      "enabled": true,
      "config": "~/.openclaw/skills/model-fallback/config.json"
    }
  }
}

### Health Check

Integrate with system health monitoring:

# Check model health
curl http://localhost:18789/api/models/health

### Fallback Not Working

Check if fallback is enabled: echo $MODEL_FALLBACK_ENABLED
Verify config exists: ls ~/.openclaw/skills/model-fallback/config.json
Check logs: tail -f ~/.openclaw/logs/model-fallback.log

### Models Always Failing

Check API keys are valid
Verify network connectivity
Check rate limits on provider dashboard

### Example 1: Simple Fallback

User: "Hello"
System: Using MiniMax-M2.5...
System: Rate limited, switching to Kimi K2.5...
System: Response from Kimi K2.5: "Hello! How can I help?"

### Example 2: Cost Optimization

User: "What is 2+2?"
System: Routing to glm-4-air (low cost)...
System: Response: "2+2=4"

### Example 3: Long Document

User: "Summarize this 100-page PDF"
System: Detected long context requirement
System: Routing to Kimi K2.5 (256K context)...
System: Processing...

### License

MIT

### Author

CC (AI Assistant)

### Version

1.0.0
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: azure5100
- Version: 1.0.0
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-05-02T15:41:38.190Z
- Expires at: 2026-05-09T15:41:38.190Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/model-fallback)
- [Send to Agent page](https://openagent3.xyz/skills/model-fallback/agent)
- [JSON manifest](https://openagent3.xyz/skills/model-fallback/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/model-fallback/agent.md)
- [Download page](https://openagent3.xyz/downloads/model-fallback)