[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.

[smashah]

Now that antigravity limits have been adjusted, and claude is limiting usage, this is needed now more than ever

[imqqmi]

I've created a duplicate feature, here's my proposal:
Problem:
some models/providers may have issues, ie service is temporarily offline or you've hit rate limits.

Solution:
Instead of having one model, use an array so that multiple models can be given as a fallback, when one model fails, the second or third can be attempted (and remember using the second for 15 minutes, then retry primary model).
This avoids manual switching between models, and subagents that don't offer the option to switch models/providers can try other models/providers.
A message can be flashed to the user that opencode is switching to a different model so the user knows what's going on.

This is not the same as the feature request for dynamic model switching where the agent takes initiative, this is a configuration setting where fallback models/providers can be given and opencode decides when to use them (running into issues > fallback).

---

Differences:

• I think it's simpler to just add an array of models in the same "model": ["primary model","secondary model"] etc property instead of a fallback property.
• Add a time out of 15 minutes to retry primary model(s) once the issues are fixed/rate limits are cleared.

[stickerdaniel]

Describe the enhancement you want to request

it would be great if users could specify multiple models in the config (opencode.jsonc / agent/*md) so that an array like

    "$schema": "https://opencode.ai/config.json",
    "default_agent": "plan",
    "model": [
        "anthropic/claude-opus-4-5",
        "google/antigravity-claude-opus-4-5",
        "github-copilot/claude-opus-4-5"
    ],

would be a valid config option.

Why?

• Users that dont have a specific provider connected have a fallback model
• Ideally, opencode detects if provider limits are reached and selects the other model as default when starting a new session
• This way you can continue using e.g. Opus 4.5 without switching the model manually through other providers even if Anthropic's ridiculous rate limits are reached.