[FEATURE]:Model de-duplication/grouping + provider priority routing with seamless failover (cost/quota-aware)

[Nikain]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Background / Problem

In OpenCode, the available model list can come from multiple providers/entry points (e.g., Claude Subscription, GitHub Copilot, various API providers). This often leads to:

1. Duplicate models in the UI: the same underlying model (e.g., Opus 4.6) appears multiple times because it is offered by different providers, making selection confusing.
2. No way to express billing/quota priority: users may want to consume the “cheapest / already-paid / subscription quota” first (e.g., Claude Pro subscription) and only fall back to pay-as-you-go APIs later.
3. Manual switching is disruptive: when a provider hits quota limits, rate limits, or temporary outages, users must manually change the provider/model, breaking workflow and reliability.

Request / Desired Behavior

Add a mechanism to group/merge models by the underlying model identity, and within a merged model, automatically route requests through a user-defined provider priority order, with transparent failover to the next provider offering the same model.

Example desired flow

• User selects a single merged model: “Opus 4.6”
• Actual routing priority configured by user:
  1. Claude Subscription Pro
  2. GitHub Copilot
  3. API Provider A
  4. API Provider B
• When the first provider is out of quota / unavailable / rate-limited, OpenCode automatically switches to the next provider for the same model.
• Switching should be seamless and “invisible” to the user (no manual action required).

Proposed Solution (High-level)

1) Model De-duplication / Grouping (Model Group / Alias)

Introduce a “Model Group / Alias” concept:

• UI/config shows one model entry: e.g., opus-4.6 (or user-defined alias like opus46)
• The group contains multiple provider-backed implementations of the same model:
  • provider=claude_subscription_pro, model=opus-4.6
  • provider=github_copilot, model=opus-4.6
  • provider=api_provider_a, model=opus-4.6
• Grouping rules:
  • Prefer provider-supplied canonical model id when available
  • Also allow manual mapping/merging, since naming can differ across providers

2) Provider Priority Order (Cost/Quota-aware)

For each model group, allow configuring a provider priority list (user adjustable), e.g.:

1. claude_subscription_pro
2. github_copilot
3. api_provider_a
4. api_provider_b

3) Seamless Failover (Transparent fallback)

At request time:

• Try the highest priority provider first
• Automatically fall back on:
  • quota/credits exhausted (quota exceeded, insufficient credits, etc.)
  • provider unavailable or timeout
  • 429 rate limit (optionally after retry/backoff)
  • auth failure (optionally surface a warning but still allow fallback where possible)
• Keep the user-facing selection stable:
  • The model remains “Opus 4.6” (merged model)
  • Optionally log/telemetry records the actual provider used (for debugging)

UX / UI Suggestions

• Default model list shows only merged models; add a toggle to “show all provider variants”
• Model details page:
  • list all providers available for the merged model
  • allow reordering provider priority
  • show provider health/status (available / rate limited / quota exhausted / missing token, etc.)
• Runtime (optional):
  • status indicator like: “Opus 4.6 (via Claude Pro)” (can be hidden)

Example Config (concept)

Illustrative only; adapt to OpenCode’s existing config format.

models:
  - alias: opus-4.6
    group:
      - provider: claude_subscription_pro
        model: opus-4.6
      - provider: github_copilot
        model: opus-4.6
      - provider: api_provider_a
        model: opus-4.6
    routing:
      sticky_mode: session   # optional: none | session | time_window
      allow_feature_downgrade: false
    failover:
      on:
        - quota_exceeded
        - rate_limited
        - provider_unavailable
        - timeout
      retry:
        attempts: 1
        backoff_ms: 300

[github-actions]

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

• [FEATURE]: Introduce ordered list for model options #13977: Proposes similar model grouping/tiering with provider fallback lists (e.g. defining an ordered list of models per agent, trying the first available and falling back to the next)

[Nikain]

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

• [FEATURE]: Introduce ordered list for model options #13977: Proposes similar model grouping/tiering with provider fallback lists (e.g. defining an ordered list of models per agent, trying the first available and falling back to the next)

Thanks — I reviewed #13977 and I think my request is related but not a duplicate.

Key difference: system-level model identity & provider routing, not project/agent-level lists

• [FEATURE]: Introduce ordered list for model options #13977: focuses on configuring an ordered list of model options per agent/project (i.e., the agent tries model A, then model B, etc.). This is primarily per-project / per-agent configuration of alternatives.
• My request: focuses on global (system-level) deduplication and management of the same underlying model across multiple providers.

What I’m asking for (system-level)

1. Merge/Deduplicate identical models across providers into a single “model identity” (alias/group) at the global config / system layer.

   • Example: “Opus 4.6” appears from:
     • Claude Subscription Pro
     • GitHub Copilot
     • API Provider(s)
   • These should be one merged model entry in UI/config, not multiple duplicates.

2. For that merged model identity, support a global provider priority order:

   • Claude Subscription Pro → GitHub Copilot → API Provider(s)

3. When quota is exhausted / rate-limited / provider unavailable, OpenCode should seamlessly fail over to the next provider for the same model, without the user having to change model selection.

   • This is provider-level failover within the same model, not “try a different model”.

Why system-level matters

• It simplifies the model list and avoids repetitive duplicates across projects.
• It enables cost/quota optimization globally (“use subscription quota first, then copilot, then API”).
• Projects/agents can still select the merged model identity, while routing is handled centrally.

Relationship to #13977

I see #13977 as potentially complementary:

• [FEATURE]: Introduce ordered list for model options #13977 could be used for project-level preference between different models (e.g., Opus vs Sonnet vs GPT).
• My request is for system-level identity & provider routing for the same model (Opus across providers), which reduces duplication and improves reliability.

If maintainers agree, I’m happy to reword this issue title/description to make the scope distinction clearer (system/global vs project/agent).

[github-actions]

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