openclaw - 💡(How to fix) Fix user-switched model has no fallback chain, causing session deadlock on provider outage [1 pull requests]

Summary

When a user manually switches the active model (e.g., /model deepseek/deepseek-v4-pro), OpenClaw disables the fallback chain entirely. If that model becomes unavailable (provider 503, timeout, 5xx), the session deadlocks — the Gateway retries the same model in a loop with no recovery path.

Root Cause

resolveEffectiveModelFallbacks() in src/agents/agent-scope.ts returns [] when modelOverrideSource === "user". The function treats any non-auto override as a signal to disable fallbacks, on the assumption that the user explicitly chose their model and no substitution should be made.

The downstream effect: persistFallbackCandidateSelection() in the agent runner also returns early for user-switched models, preventing fallback persistence. Between empty fallbacks and blocked persistence, the session has zero recovery options.

Real Incident Data (2026-05-21, 14:00–14:14 CST)

Timeline

Provider error evidence

Confirmed DeepSeek outage at the time:

503 Service is too busy. We advise users to temporarily switch to alternative LLM API service providers.

Gateway diagnostic logs

13:59:25 [diagnostic] long-running session: age=577s queueDepth=1 reason=queued_behind_active_work
14:02:25 [diagnostic] stalled session: age=757s reason=active_work_without_progress
14:02:28 [agent/embedded] embedded run failover decision: decision=surface_error reason=timeout
  rawError="LLM idle timeout (120s): no response from model" fallbackConfigured=false

The fallbackConfigured=false flag confirms the session had no fallback path for the user-switched model.

Proposed Fix

In resolveEffectiveModelFallbacks(): when modelOverrideSource === "user", return the agent's configured fallbacks instead of an empty array. This gives user-switched models a per-call recovery path. The existing persistFallbackCandidateSelection guard ensures the fallback selection is NOT persisted to session state, so the user's model preference is preserved for the next message.

Related

• PR: #TBD (to be linked)