[FEATURE]: Native Model Fallback / Failover Support

[arisgrout]

Problem

OpenCode supports:

• Provider fallback only when the model ID is the same
• Static agent-level model overrides

There is no way to define fallback between different models, e.g.:

“If model A errors or rate-limits → automatically retry with model B”

This causes long-running agent workflows to fail on transient provider/model issues and forces users to rely on external routers or proxies (like litellm).

---

Request

Add first-class model fallback support to OpenCode.

Example (global)

{
  "models": {
    "coder": {
      "fallback": [
        "anthropic/claude-3.5-sonnet",
        "openai/gpt-4o",
        "deepseek/deepseek-r1"
      ]
    }
  }
}

Example (agent-level)

{
  "agents": {
    "build": {
      "model": {
        "fallback": ["claude-sonnet", "gpt-4o-mini"]
      }
    }
  }
}

---

Behavior

• Switch models on: rate limits, provider/model unavailability, 5xx errors
• Do not retry on prompt or validation errors
• Optional retry limit

---

Why in Core

• Model routing is an orchestration concern
• External routers break plugin auth flows and agent semantics
• Complements existing provider-order routing (e.g. Feature Request: Add Vercel AI Gateway Provider Routing Support (only and order filters) #2153)

---

Status

• No existing plugin or PR implements true model fallback

Thanks,

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Retry w/ different model #310: Retry w/ different model
• [Feature Request] Configurable Retry Mechanism via opencode.json #3011: [Feature Request] Configurable Retry Mechanism via opencode.json
• Implement exponential back-off when hitting rate limits #1712: Implement exponential back-off when hitting rate limits

Feel free to ignore if none of these address your specific case.