skip to content

Model Providers & Failover

OpenClaw calls Anthropic, OpenAI, Gemini or a local Ollama through auth profiles, and falls back to another model when one fails. Interviewers ask about cost, privacy and outage behaviour.

part ofAI coding toolsread it →
on this pageshow

explore

questions

6

When OpenClaw's primary model provider fails overnight during a scheduled run, what does failover try, in what order, and does the fallback stick?

level: middleimportance: must knowfreq 12%

answer

  1. retry first, then switch
  2. same provider before next model
  3. fallbacks tried in listed order
  4. the switch lasts one turn
  5. some errors never advance

basics

~20 s

OpenClaw first retries the same model briefly, then rotates to another auth profile of the same provider, then walks agents.defaults.model.fallbacks in order. The winning fallback answers only that turn; the next turn starts from the selected primary again.

solid answer

~50 s

OpenClaw handles a failing provider in stages. As of 2026.9.9 it first retries the same model within a bounded budget, continuing the transcript rather than replaying the request. If that fails, it **rotates auth profiles** within the provider — another key or account for the same provider. When that provider is exhausted with a failover-worthy error (auth, rate limit, overload, timeout, billing, missing model), it moves to the **next model in `agents.defaults.model.fallbacks`**. Fallback is **turn-local**: the winning model answers this turn without changing the session's selected model, and `/status` shows both. A cron job that sets its own model still uses the configured fallbacks unless the job sets its own `fallbacks`. Context overflow, explicit aborts and final provider refusals do not advance the chain. A fallback on a second provider is what survives a whole-provider outage.

code

json · 10 lines
json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-5-5",
        "fallbacks": ["openai/gpt-5.5", "ollama/gemma4"]
      }
    }
  }
}

go deeper

for a junior

Remember the order: retry the same model, try another credential for the same provider, then the next model in the fallbacks list.

for a middle

Explain the candidate chain, which error classes advance it, and why the fallback lasts one turn rather than replacing the session's model.

for a senior

Design a fallback list that survives a provider-wide outage and explain why a cron job's model still uses fallbacks unless the job opts out.

for a principal

Weigh what a cross-provider fallback costs, a second bill, different model behaviour and data going to another provider, against a scheduled report that does not arrive.

## The scenario A scheduled job is due at night and the primary provider starts returning errors. What OpenClaw does next depends on the error and on where the model selection came from. For the **configured default** (`agents.defaults.model.primary`) and for a **cron job's own model**, the full failover path applies. This answer assumes OpenClaw 2026.9.9; the retry budget was reworked in the 2026.9 releases. ## The order of attempts 1. **Same-model recovery.** Before changing anything, the runner retries the same model within a bounded budget and continues the existing transcript, keeping partial output and completed work. As of 2026.9.9, rate limits get up to 10 total attempts with jittered waits capped at 30 seconds, while a provider's retry-after hint still sets a minimum wait; other transient failures get eight retries within a 90-second window. 2. **Auth-profile rotation.** An **auth profile** is one stored credential for a provider (an API key, an OAuth login or a token). If the provider has several, OpenClaw moves to the next eligible one and puts the failing one in **cooldown**. Overloaded and rate-limit errors allow one same-provider rotation by default before the next model is tried. 3. **Model fallback.** When the provider is exhausted with a failover-worthy error, OpenClaw tries the next candidate. The chain starts with the requested model, then the configured fallbacks in order (deduplicated, and not filtered by the model allowlist), and, when no explicit override was given, the configured primary is appended at the end. 4. **Terminal failure.** If every candidate fails, the run reports the failure with per-attempt details and, when known, the soonest cooldown expiry. ## What advances the chain, and what does not | Advances to the next model | Does not advance | |---|---| | Auth failures | Context overflow (handled by compaction and retry) | | Rate limits and exhausted cooldowns | Explicit aborts that are not timeout-shaped | | Overloaded or provider-busy errors | Final provider refusals | | Timeout-shaped failures | A final unknown error with no candidates left | | Billing disables | Format or invalid-request errors (usually terminal) | | `model_not_found`, including eligible HTTP 404s | | ## Fallback is turn-local - The winning fallback answers **this turn only**. OpenClaw does not write it into the session's model selection, so the next turn starts from the selected primary again. - `/status` shows the selected model and, when they differ, the active fallback model and the reason. - In private chats OpenClaw posts a one-line fallback notice once per state change and a second notice when the primary recovers; group and channel conversations keep the same state without posting it. ## Making the night job survive - Put at least one model from a **different provider** in `agents.defaults.model.fallbacks`. Fallbacks on the same provider share a provider-wide outage, although a rate limit scoped to one model can still leave a sibling model usable. - Add a second credential for the primary provider if the failure you fear is one key's rate limit or quota, because profile rotation happens before any model switch. - Manage the list with `openclaw models fallbacks add`, `remove`, `list` and `clear`. - A cron job's `--model` (its payload `model`) is a **job primary**, not a user override: it still walks the configured fallbacks unless the job sets payload `fallbacks`, and `fallbacks: []` makes that run strict. ```bash openclaw models fallbacks add openai/gpt-5.5 openclaw models fallbacks add ollama/gemma4 openclaw models fallbacks list ``` ## Reading what happened afterwards The morning after, the operator wants to know whether the report came from the primary or a fallback, and why: - `/status` in the session shows the selected model and, if a fallback is active, which one and the reason. - Each attempt is recorded with the provider and model tried, a reason such as `rate_limit`, `overloaded`, `billing`, `auth` or `model_not_found`, and an optional status code. - Structured `model_fallback_decision` log events carry flat fields such as `fallbackStepFromModel`, `fallbackStepToModel` and `fallbackStepFromFailureReason`, so the primary's failure can be reconstructed even if the last fallback also failed. ## What does not fall back The path above is for configured and automatic selections. A model a user picked with `/model`, a per-agent model written without a fallbacks list, and a cron job with `fallbacks: []` are strict: after same-provider profile rotation they report the failure instead of answering from another model. Plan the night job's model source with that in mind.

  • Why is a fallback model from the same provider weak protection against an outage?
    A provider-wide outage fails every model on that provider, so a same-provider fallback fails too. It still helps when a rate limit is scoped to one model, because OpenClaw records the cooldown against that model and a sibling can be tried. For a real outage, list a model from a different provider in `agents.defaults.model.fallbacks`.
  • A night run answered from the fallback. Will the morning's first chat also use the fallback?
    No. Fallback is turn-local: OpenClaw does not persist the fallback as the session's model, so the next turn starts from the selected primary and only falls back again if the primary still fails. `/status` shows the selected and active model when they differ.
  • Which failures stop the run instead of trying the next model?
    Context-overflow errors stay inside compaction and retry logic, explicit aborts end the run, and a final provider refusal ends the turn without switching to an unrelated model. Format or invalid-request errors are usually terminal too, because the same payload would fail again on retry.

A substitute teacher covers one lesson when the regular teacher is out, but the timetable still names the regular teacher, so the next lesson starts with them again.

  • OpenClaw jumps to the next fallback model before trying other keys
  • Once a fallback answers, the session stays on it until /new
  • A fallback on the same provider covers a provider-wide outage
  • A context-overflow error moves the turn to the next fallback model
  • A cron job's own model never uses the configured fallbacks

Assumes OpenClaw 2026.9.9; the transient retry budget (10 attempts for rate limits, eight retries in a 90-second window otherwise) was reworked in the 2026.9 releases.

open as a page

In OpenClaw, which `openclaw models` commands set the default model and check that its credentials work, and what does each one prove?

level: juniorimportance: should knowfreq 10%

basics

~20 s

openclaw models set writes the default model; openclaw models list shows the catalog; openclaw models status reports the resolved default, fallbacks and auth health without calling a model. Of these, only openclaw models status --probe sends real requests.

open as a page

In OpenClaw, how does an API-key auth profile differ from a subscription token saved with `openclaw models auth setup-token`, and when do you choose each?

level: middleimportance: should knowfreq 7%

basics

~20 s

Both are OpenClaw auth profiles. An API key bills the provider account per use; a setup token ties requests to a subscription plan's limits and is a static token that OpenClaw never refreshes. API keys suit shared, predictable automation.

open as a page

Why can an OpenClaw session fail outright during a provider outage even though `agents.defaults.model.fallbacks` is configured, and how do you fix it?

level: seniorimportance: should knowfreq 5%

basics

~20 s

Fallback depends on where the model choice came from. A model picked with /model, a per-agent model without a fallbacks list, or a cron job with empty fallbacks is strict: it reports the failure instead of switching models.

open as a page

With several auth profiles for one provider, how does OpenClaw order, pin and cool them down, and why does it not rotate on every request?

level: seniorimportance: nice to knowfreq 3%

basics

~20 s

OpenClaw pins one auth profile per session to keep provider caches warm, moving on when the session resets or that profile is cooling down. A first failure cools it for 30 seconds; billing failures disable it for ten minutes.

open as a page

An owner wants private OpenClaw chats kept on a local Ollama model while other chats use a hosted model; how do you decide, configure it, and weigh the cost?

level: principalimportance: nice to knowfreq 6%

basics

~20 s

Give private chats their own agent with a strict local Ollama model, no hosted fallback, a local-only model allowlist and no hosted utility route. The price is weaker tool use, a smaller context and local hardware to keep running.

open as a page