How to Use OpenClaw Model Failover

Model failover in OpenClaw is not a vague “try something else” behavior. The official docs describe a specific two-stage system: first rotate auth profiles within the current provider, then move through a model fallback chain if the provider is exhausted with a failover-worthy error. Understanding that order saves you from chasing the wrong thing when a run recovers on its own.

When this is the right move

Use this feature when you depend on OpenClaw for real work and want resilience across rate limits, auth problems, or provider-side transient failures. It matters most when you have more than one credential profile, more than one model candidate, or a long-lived session where a recovered run is much better than a hard stop.

The practical workflow

1. Set a primary model and define a fallback chain in the documented model config path instead of assuming OpenClaw will invent backup candidates for you.
2. Let OpenClaw rotate usable auth profiles inside the provider first. That is the cheapest recovery path because it keeps the model and provider stable when only one credential is cooling down.
3. Use explicit per-session profile pinning only when you really mean to lock the run to that profile. The docs say user-pinned profiles do not auto-rotate the same way session-selected preferences do.
4. Remember that the session may stay sticky to the chosen auth profile until reset, compaction, or cooldown rather than re-rolling on every message.
5. When diagnosing a failure, look at profile state, session overrides, and fallback order together instead of treating them as separate systems.

Grounded command or config pattern

The docs name the exact config and session-owned fields involved in model failover. A minimal shape looks like this.

{
  agents: {
    defaults: {
      model: {
        fallbacks: ["provider/backup-model"],
      },
    },
  },
  auth: {
    order: {
      provider: ["provider:default"],
    },
  },
}

# Session-owned fallback fields:
providerOverride
modelOverride
authProfileOverride
authProfileOverrideSource
authProfileOverrideCompactionCount

The docs also explain why OpenClaw only persists those fallback-owned session fields during a retry: it avoids clobbering unrelated session changes such as a manual model switch that happened while the fallback attempt was running.

Operator notes

Auth profiles live in auth-profiles.json, runtime routing state lives in auth-state.json, and config-side auth.profiles or auth.order is metadata rather than secret storage. Cooldowns can be triggered by more than obvious 429s; the docs include timeouts and several provider-specific transient failure patterns in the same recovery bucket. If every candidate fails, OpenClaw throws a FallbackSummaryError with per-attempt detail instead of silently swallowing the whole failure.

Rollout approach

For model failover, the safest rollout is to keep the chain short and intentional. One primary model, one or two backups, and a known auth profile order is easier to reason about than a long mystery list. Recovery is only helpful when you still understand which fallback actually fired and why.

Common mistake

The common mistake is treating the command or config key as the whole feature. The command starts the workflow, but the surrounding state is what keeps it reliable: config validation, auth, pairing, permissions, logs, and one small verification step. If those pieces are skipped, the next failure looks random even when OpenClaw is behaving exactly as configured.

Maintenance rhythm

Once this is working, write down the exact command, config path, or approval decision you used. Future you will not remember the tiny detail that made the setup safe. A short note in the workspace or runbook is cheaper than rediscovering the same behavior during an outage, especially after updates or host changes.

Safety checks

Do not confuse a user-pinned profile with OpenClaw's normal session-selected preference. The docs make that distinction clear, and it changes what the runtime is allowed to rotate automatically. Also remember that fallback can recover availability but not policy mistakes. If your backup model or profile should not be used for a given agent, do not leave it in the chain just because it is technically reachable.

How to verify it worked

The practical verification is to observe a real cooldown or controlled failure and confirm that OpenClaw advances through the expected profile and model order. If a session recovers on a backup candidate, make sure subsequent readers of that session see the same override state instead of flipping back unpredictably.

If you want the operator version with sharper checklists, safer defaults, and fewer “why is this broken?” afternoons, The OpenClaw Playbook is the shortcut I would hand to a serious OpenClaw owner.