Feature Request: Multi-model fallback per agent with automatic rate limit switching

[UAEpro]

Problem

When using agents heavily, models hit rate limits (429 errors). Currently, the only option is to:

1. Wait for the rate limit to reset
2. Manually edit ~/.config/opencode/oh-my-opencode.json to switch models

This breaks workflow and wastes time.

Proposed Solution

Allow configuring multiple models per agent with automatic fallback on rate limits or errors.

Example Configuration

{
  "agents": {
    "explore": {
      "models": [
        { "model": "opencode/grok-code", "priority": 1 },
        { "model": "google/gemini-3-flash", "priority": 2 },
        { "model": "anthropic/claude-sonnet-4", "priority": 3 }
      ],
      "fallback_strategy": "sequential",
      "fallback_on": ["rate_limit", "timeout", "error"]
    },
    "librarian": {
      "model": "google/gemini-3-pro"  // backward compatible - single model still works
    }
  }
}

Fallback Strategies

Strategy	Behavior
sequential	Try models in priority order until one succeeds
round_robin	Distribute load across models to prevent hitting limits
random	Random selection from available models

Fallback Triggers

Trigger	Description
rate_limit	HTTP 429 or provider rate limit error
timeout	Request timeout exceeded
error	Any API error (5xx, connection failed, etc.)
token_limit	Context too large for model

Benefits

• Zero downtime: Agents keep working when primary model hits limits
• Cost optimization: Use cheaper models as fallbacks
• Reliability: Multiple providers = redundancy
• Backward compatible: Single "model": "string" still works

Implementation Hints

Based on existing codebase patterns:

1. Schema update (assets/oh-my-opencode.schema.json):

   • Change model from string to oneOf: [string, object]
   • Add models array option with priority/strategy

2. Model resolution (src/cli/config-manager.ts):

   • Already has fallback logic for install-time model selection
   • Could extend to runtime model resolution

3. Error handling (src/hooks/anthropic-auto-compact/executor.ts):

   • Already tracks RetryState and FallbackState
   • Could trigger model switch instead of just retry/compact

4. State tracking:

   • Track which models are currently rate-limited
   • Implement cooldown timers per model

Use Case

I run multiple parallel background agents (explore, librarian, oracle) and frequently hit rate limits on primary models. Having automatic fallback would let agents continue working without manual intervention.

Alternatives Considered

1. Manual config editing — Works but disrupts workflow
2. Single high-limit model — Expensive, still has limits
3. External proxy with fallback — Complex, adds latency

Native support in oh-my-opencode would be the cleanest solution.

[dpshade]

This has been a blocker for me, I'm going to make an attempt at implementing this!

[code-yeongyu]

@UAEpro Thanks for this well-thought-out enhancement request! 👍

This is a valuable feature that aligns with oh-my-opencode's goal of providing robust multi-agent orchestration. Your implementation hints are particularly helpful - you've clearly done your homework on the codebase.

Key observations:

1. Backward compatibility - Essential for existing users. Your model (string) vs models (array) approach works well.
2. Fallback strategies - Sequential, round-robin, and random cover the main use cases. I'd suggest also considering exponential_backoff for cooldown management.
3. State tracking - The cooldown timer per model is crucial to avoid rapid switching between rate-limited providers.
4. Integration points - You've identified the right places: schema, config-manager, and executor.

Additional considerations for implementation:

• Observability: Should we expose current model/fallback state via CLI or config dump?
• Metrics: Track fallback frequency per agent/model to help users optimize their config.
• Config validation: Warn if all configured models for an agent share the same provider (wouldn't help with provider-level rate limits).
• Per-agent defaults: If no explicit strategy specified, what should be the default? (I'd lean toward sequential with fallback_on: ["rate_limit", "error"]).

I'm marking this as enhancement and will keep it open for prioritization. This fits well with the existing rate limit handling work in anthropic-auto-compact.

@code-yeongyu For prioritization context: This addresses a real pain point for users running heavy workloads with multiple parallel agents. The implementation is self-contained and wouldn't break existing functionality.

[Mattwmaster58]

This would be pretty neat. Currently trialing Cerebras, I love the speed, but the rate limits are low. Z.AI coding plan to fill in the gaps sounds quite nice ;)

[prolific]

This is definitely something I feel need for frequently. Whenever I am working on something big enough, I find myself hitting the rate limits and that blocks me from proceeding further. The only solution is changing the config with all references to that model to a new model.

An option to pass the array of model configs would completely resolve this issue and let omo continue work even after rate limits.

Like I can switch to api mode (using openrouter or directly) when a certain subscription limit reaches.

[matt-ufpi]

see: anomalyco/opencode#7602

[code-yeongyu]

Consolidating model fallback discussions. This is the most detailed proposal but overlaps significantly with #296 (the original owner-filed issue) and #703. Please follow #296 for the canonical tracking of multi-model fallback. PR #1408 is the active implementation.