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?
answer
- where the model choice came from
- a user pick is exact
- a string agent model has no fallbacks
- pins survive /new
- /model default -s
basics
~20 sFallback 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.
solid answer
~40 sOpenClaw applies `agents.defaults.model.fallbacks` only to some **selection sources**. The configured default, a cron job's own model and an automatic fallback can walk the chain. A **user session selection** — `/model`, the model picker, `session_status(model=...)` or `sessions.patch` — is stored with `modelOverrideSource: "user"` and is **exact and strict**: after the same provider's auth profiles are exhausted the turn fails visibly. A per-agent `agents.entries.<id>.model` written as a string, or as an object without `fallbacks`, is strict too, and a cron job with `fallbacks: []` opts out. User pins survive `/new` and `/reset`. The fix is to clear the pin with `/model default -s`, or to give the agent its own `fallbacks` list. This holds for OpenClaw 2026.9.9.
go deeper
Recall that a model someone picked with /model does not fall back, and that /model default -s returns the chat to the configured default.
Explain selection sources: the configured default and cron job models use fallbacks, user picks and string-form agent models do not.
Diagnose a chat that errors while others fall back: read /model status, recognise a pin or a strict agent model, and fix it without breaking intent.
Decide where strictness is a feature, a private agent that must never leave a local model, and where it is an outage risk to document.
## The symptom During a provider outage, one chat answers from a fallback model while another chat on the same install just reports an error. Both run on the same Gateway with the same `agents.defaults.model.fallbacks`. The difference is **where each session's model came from**: OpenClaw treats a model choice differently depending on its selection source. This answer assumes OpenClaw 2026.9.9; the `modelOverrideSource` field these rules read was introduced in v2026.4.26. ## Selection sources | Source | Uses the fallback chain? | |---|---| | Configured default, `agents.defaults.model.primary` | Yes, `agents.defaults.model.fallbacks` | | Cron job model (`--model` or payload `model`) | Yes, unless the job sets payload `fallbacks`; `[]` makes it strict | | Automatic fallback state | Yes, it is temporary recovery state | | Per-agent `agents.entries.<id>.model` as a string | No, strict | | Per-agent model object without `fallbacks` | No, strict | | User session selection (`/model`, picker, `sessions.patch`) | No, exact and strict | ## Why a user choice is strict When someone selects a model with `/model`, the model picker, `session_status(model=...)` or `sessions.patch`, OpenClaw records `modelOverrideSource: "user"`. That is treated as an **exact selection**: - OpenClaw still rotates through other auth profiles of the **same provider** when one is in cooldown, because that changes the credential, not the model. - Once those are exhausted, it reports the failure instead of answering from an unrelated configured fallback. - The reasoning: a person who chose a specific model, for example a local model for privacy or a model they are testing, should see that it failed rather than get an answer from a model they did not pick. Selecting the effective configured default by name clears the session pin instead of creating one. Session entries written before v2026.4.26 that carry an override without a source are treated as user overrides for the same reason. ## Why an agent can be strict without anyone typing /model In a multi-agent install each agent can have its own model: - `"model": "ollama/gemma4"` (string form) sets a strict primary with **no** model fallback. - `"model": { "primary": "ollama/gemma4" }` is also strict. - `"model": { "primary": "ollama/gemma4", "fallbacks": ["openai/gpt-5.5"] }` opts that agent into fallback. - `"model": { "fallbacks": [...] }` overrides only the chain and keeps inheriting the shared primary; `"fallbacks": []` states strictness explicitly. An operator who adds a second agent with a one-line string model has, often without noticing, opted that agent out of failover. ## How pins persist, and how to clear them User model and auth-profile pins survive `/new`, `/reset`, session rollover, compaction and cooldown windows while they stay valid. So: 1. Inspect the chat with `/model status` or `/status`. Status may say the session is pinned to one model while the config primary applies to new or unpinned sessions. 2. Clear the pin with `/model default -s`. It removes the session's model selection without writing any configured default, keeps a compatible auth-profile pin and clears an incompatible one. 3. For an agent, add a `fallbacks` list to its model object, or deliberately leave it strict. Changing `agents.defaults.model.primary` does **not** rewrite existing pins, so editing the config alone does not rescue a pinned chat. ## A worked example Two chats run on the default agent, whose configured primary is `openai/gpt-5.5` with `anthropic/claude-opus-5-5` as a fallback. Last week the owner typed `/model openai/gpt-5.4` in the first chat to compare answers; the second chat never chose anything. Tonight OpenAI is down: 1. Both chats retry their model, then try any other OpenAI auth profile. 2. The second chat, on the configured default, moves to `anthropic/claude-opus-5-5` for the turn and answers. 3. The first chat holds an exact user selection, so it reports the failure. The provider and the configured fallbacks are identical; only the selection source differs. `/model default -s` in the first chat makes it behave like the second. ## Other reasons the chain is not walked - Context-overflow errors stay inside compaction and retry logic. - A final provider refusal ends the turn without switching models. - One-off CLI provider or model overrides are explicit selections and strict. - A failure that reaches the end of the chain reports the soonest cooldown expiry when one is known.
- Does sending `/new` put a pinned OpenClaw chat back on the configured default?No. Explicit model and auth-profile pins survive `/new`, `/reset`, session rollover and compaction while they stay valid. `/new` and `/reset` clear automatic fallback state, not a user's choice. Use `/model default -s` to clear the session's selection.
- How do you let a second agent keep the shared primary but use its own fallback list?Give the agent a model object with only `fallbacks`: `"model": { "fallbacks": ["openai/gpt-5.5"] }`. It keeps inheriting `agents.defaults.model.primary` and replaces only the chain. `"fallbacks": []` instead disables fallback for that agent without pinning a primary.
- Configured fallbacks apply to every session, whatever chose its model
- A per-agent model string inherits the shared fallbacks list
- Sending /new clears a model the user picked with /model
- A strict selection skips other credentials for the same provider
- Editing agents.defaults.model.primary moves pinned chats to it
Assumes OpenClaw 2026.9.9; selection sources are read from modelOverrideSource, introduced in v2026.4.26, and per-agent string models are strict.