[FEATURE]: Native Model Fallback / Failover Support

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,

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.

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

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.

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.

feat: add combined models with automatic provider fallback

This is big

Bumping this. Big want. Don’t want to have to use oh my opencode to orchestrate this, would prefer clean native use.

Have a look at : #8669 and #1267

Just commented this on the PR, but want to mention it in this issue too:

I’d like to suggest a complementary abstraction that could make model selection more flexible and predictable long-term: introducing “virtual models” as a first-class concept in the configuration.

Instead of only defining fallback behavior on concrete models or providers, a virtual model would act as an alias to a set of real provider-specific models, together with a selection strategy.

Key idea

Concrete models (e.g. anthropic/claude-opus-4.5) are always deterministic: selecting them always uses that exact model.
Virtual models encapsulate dynamic behavior and are explicitly opt-in.
The config defines:
- the underlying models
- how a model is chosen (round-robin, priority, sequential after rate limit, weighted, etc.)

Why this helps

Clear semantics: Explicit model selection never changes behavior. Dynamic selection is only used when a virtual model is chosen.
Operational control: Virtual models provide a single choke point for retries and switching policies, making it easier to reason about side effects, retries, and observability compared to implicit fallback on concrete models.
Extensibility: New strategies can be added without complicating fallback rules.
Consistency: Virtual models can be referenced anywhere a normal model can be used (global default, agent, session).

Example configuration

{
  "models": {
    "virtual/coding": {
      "type": "virtual",
      "strategy": "sequential",
      "models": [
        "anthropic/claude-opus-4.5",
        "openai/gpt-4.1",
        "openai/gpt-4o"
      ]
    },
    "virtual/fast": {
      "type": "virtual",
      "strategy": "round_robin",
      "models": [
        "openai/gpt-4o-mini",
        "openai/gpt-4.1-mini"
      ]
    }
  }
}

Semantics

Selecting anthropic/claude-opus-4.5 always uses that exact model.
Selecting virtual/coding delegates model choice to the virtual model’s strategy.
Possible strategies could include:
- priority
- round_robin
- random
- sequential (on rate limit, failure, etc...)
- weighted

This aligns well with ongoing discussions around native fallback and multi-provider usage, and could build cleanly on top of the current implementation without breaking existing configs.

Consider adapting the model from OpenClaw [KISS]: https://docs.openclaw.ai/concepts/model-failover

Lo de modelos virtuales suena genial, hay planes de incluir esto? O sacar un plugin?

This proposal refines the "Virtual Model" concept into a more pragmatic Strategy Profiles approach. It separates Operational Logic (retries, backoffs) from Model Selection (which models to use), allowing for clean configuration in both global settings and individual Agent Markdown files.

Proposal: Unified Model Fallback & Strategy Profiles

Problem Statement

Current implementations of model selection are too rigid. Users need a way to:

Fallback to a second model when the first hits a rate limit (429) or is down (5xx).
Rotate between providers of the same model (e.g., Claude 3.5 on Anthropic vs. AWS Bedrock vs. GCP).
Define retry policies (exponential backoff) once, and apply them to various agents.

1. Global Strategy Profiles (`opencode.jsonc`)

Instead of hardcoding retry logic everywhere, we define Strategy Profiles. These profiles handle the behavior of the rotation.

{
  "strategies": {
    "robust_coding": {
      "max_retries": 3,
      "timeout": "30s",
      "backoff": {
        "type": "exponential",
        "initial": "500ms",
        "multiplier": 2
      },
      "fallback_on": [429, 500, 503],
      "on_fail": "throw", // or "continue_with_next"
      "cooldown": "15m" // If a model fails, don't try it again for 15 minutes
    },
    "fast_retry": {
      "max_retries": 1,
      "timeout": "10s",
      "fallback_on": ["any_error"]
    }
  }
}

2. Agent-Level Configuration (Markdown Frontmatter)

Agents can now accept an array of models and a reference to a strategy. This keeps the agent file clean and focused on the task.

~/.config/opencode/agents/reviewer.md

---
description: Code quality reviewer
# Simple Array: Uses default priority strategy
model: 
  - anthropic/claude-3-5-sonnet
  - openai/gpt-4o
  - deepseek/deepseek-chat

# Reference to the global strategy profile
strategy: robust_coding 
temperature: 0.1
---

You are a senior reviewer...

3. Support for Multiple Providers (Same Model)

Addressing the feedback from the thread (e.g., using Opus from different sources), we can treat different providers as a prioritized list:

---
model:
  - google/antigravity-claude-opus-4-5
  - anthropic/claude-opus-4-5
  - github-copilot/claude-opus-4-5
strategy: robust_coding
---

4. Execution Logic (Internal Behavior)

When an agent is invoked:

Selection: The orchestrator picks the first model in the list.
Execution: It applies the settings from the linked strategy.
Fallback: If a fallback_on error occurs:
- The current model is marked with a cooldown timestamp.
- The next model in the array is selected.
- The request is retried based on the backoff settings.
Observability: OpenCode flashes a UI notification: "Anthropic Rate Limit reached. Falling back to GPT-4o..."

Key Advantages:

Clean Markdown: No need to clutter agent files with complex JSON/Logic.
Global Control: Update your "Standard Retry" policy in one place, and it affects all agents.
Provider Agnostic: Easily mix and match local models (Ollama) with cloud providers as fallbacks.
Backward Compatible: A single string in the model field works exactly as it did before.

Comparison with existing proposals:

Feature	Current PRs	This Proposal
Model Arrays	Supported in some	Supported (Simplified UX)
Retry Logic	Hardcoded	Strategy Profiles (Reusable)
Exponential Backoff	Missing	Built-in
Circuit Breaking	No	Yes (via `cooldown` field)
Agent MD support	Minimal	First-class citizen

This approach provides the "clean native use" users are asking for while offering the power of an orchestrator like LiteLLM without the extra infrastructure.

@Correctover

@Correctover

This issue is not for what you are depicting. It is for "same model, different provider" which is completely different from what you're stating.

Here, the only caveat should be "cache misses" due to provider change, not differences on "intelligence". if the underlying model id changes from provider to provider, i.e, quantization or so, I don't think that's something that should be taken into account here

@j3k0

Other harnesses are already doing this. I wonder if it's worth looking into how they address these issues (to the extent they do), and what their limitations are, e.g., do they require matching model ID (and how do they normalize model identifiers)?

I'm curious how @j3k0's (who has a working PR for this feature #26292) experience has been since switching to OMP (https://omp.sh)?

@zcutlip

@zcutlip OMP has served me well, still not perfect but I stick with it for now. A feature related to multi-provider setup that I liked is the ability to select canonical models, i.e. a model name without a provider prefix. I want GLM-5.2, don't care about which provider. Configure your providers sorting order (modelProvidingOrder. OMP also supports equivalence, so you can say deepseek/deekseek-v4-pro is equivalent to glm-5.2 (for example) then have deepseek at the end of the providers preference, it lets deepseek-v4-pro becomes a final fallback option when glm-5.2 can't be served by any.

Unfortunately OMP doesn't switch automatically. But you can live-switch the provider mid-session after an error so recovery isn't that bad. OMP also supports cross-model reasoning recovery. I liked the opencode setup I had more, but got tired of failed rebase. My tokens are better used for actual work.

@j3k0

Unfortunately OMP doesn't switch automatically.

ahhh...did not realize. thanks for the clarification @j3k0

Same use case here — I run multiple OpenCode GO accounts for rate limit headroom, but the only way to use them is manually swapping keys via /connect or editing ~/.local/share/opencode/auth.json.

What I really need is: same-provider key-level rotation, not just model-to-model fallback. When the current GO key hits 429, rotate to the next GO key automatically within the same request.

This would also benefit people who:

Have multiple ChatGPT Plus/Pro accounts
Use multiple API keys from the same provider (e.g., OpenAI org keys)
Run GO + Zen simultaneously as a budget/fallback pair

The auth-v2 proposal (#5748) had the right idea with same-request rotation — would love to see that land as part of this model fallback feature.

For API-key/custom-endpoint providers, this can already be moved outside OpenCode. Plugin-auth providers are the important exception.

swobuforge/swobu gives one client-visible model route an ordered target chain and moves to the next target after:

transport failure
HTTP 408 / 425 / 429
HTTP 5xx
a known request/backend incompatibility

It deliberately does not fail over on arbitrary 4xx/configuration errors or client cancellation.

So a route can effectively be:

coder
→ Anthropic
→ OpenAI
→ DeepSeek

while OpenCode continues targeting one model endpoint.

This does not solve the plugin-auth concern from the issue: a gateway cannot inherit authentication that exists only inside an OpenCode plugin.

But for BYOK/custom endpoints, it provides the requested “keep the session alive when one model/provider becomes unavailable” behavior today, including protocol compatibility at the same boundary.

https://github.com/youngbinkim0/opencode-fallback

opencode: default to GPT-5.5 with MiniMax-M3 → DeepSeek fallback

To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.

Opened new thread since this was closed prematurely

#55008

Navigation Menu

Repository navigation

[FEATURE]: Native Model Fallback / Failover Support #7602

Problem

Request

Example (global)

Example (agent-level)

Behavior

Why in Core

Status

Describe the enhancement you want to request

Why?

Key idea

Why this helps

Example configuration

Semantics

Proposal: Unified Model Fallback & Strategy Profiles

Problem Statement

1. Global Strategy Profiles (`opencode.jsonc`)

2. Agent-Level Configuration (Markdown Frontmatter)

3. Support for Multiple Providers (Same Model)

4. Execution Logic (Internal Behavior)

Key Advantages:

Comparison with existing proposals:

22 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[FEATURE]: Native Model Fallback / Failover Support #7602

Description

Problem

Request

Example (global)

Example (agent-level)

Behavior

Why in Core

Status

Activity

github-actions commented on Jan 10, 2026

smashah commented on Jan 14, 2026

imqqmi commented on Jan 15, 2026

stickerdaniel commented on Jan 15, 2026

Describe the enhancement you want to request

Why?

broskees commented on Jan 25, 2026

Simplereally commented on Jan 30, 2026

manascb1344 commented on Jan 30, 2026

nwpr commented on Feb 7, 2026

Key idea

Why this helps

Example configuration

Semantics

gimlichael commented on Feb 9, 2026

rober-tm commented on Feb 10, 2026

xitex commented on Feb 10, 2026

Proposal: Unified Model Fallback & Strategy Profiles

Problem Statement

1. Global Strategy Profiles (opencode.jsonc)

2. Agent-Level Configuration (Markdown Frontmatter)

3. Support for Multiple Providers (Same Model)

4. Execution Logic (Internal Behavior)

Key Advantages:

Comparison with existing proposals:

22 remaining items

jorgehermo9 commented on Jun 30, 2026

zcutlip commented on Jun 30, 2026

j3k0 commented on Jun 30, 2026

zcutlip commented on Jun 30, 2026

adm-humanerd commented on Jul 4, 2026

metrofun commented on Aug 9, 2026

m1khal3v commented on Aug 13, 2026

github-actions commented on Oct 13, 2026

LuminairPrime commented on Oct 13, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

1. Global Strategy Profiles (`opencode.jsonc`)