2026-07-20

OpenClaw Models: Configure Providers, Fallbacks, and Failover

Configure OpenClaw models, provider authentication, allowlists, aliases, ordered fallbacks, strict session pins, live probes, and recovery verification.

A green model row is inventory evidence, not an execution result. On one live OpenClaw 2026.7.1-2 installation, the configuration validated cleanly and models list returned 39 rows: 36 available, three unavailable, none missing. A one-token probe of the resolved primary succeeded in about 15.1 seconds. The same status report showed zero text fallbacks. The primary route worked at that moment; the installation still had no cross-model recovery path for an ordinary text turn.

That distinction is the useful way to think about OpenClaw models. Catalog discovery, model policy, credentials, live inference, fallback membership, and session selection are separate gates. Collapsing them into “the model is configured” makes incident response slower and encourages risky fixes such as deleting credentials or widening policy before the rejecting boundary is known.

The missing proof was recovery.

The live check in this review made a real provider request. It used one provider, one auth profile, a best-effort one-token limit, and a 15-second timeout. Raw profile identifiers, account labels, and credential fragments were not retained. No default, alias, allowlist, auth profile, fallback, or session pin was changed.

What the status output actually proved

The clean configuration result eliminated schema mistakes. The resolved default showed which provider/model reference new, unpinned sessions should inherit. The auth section found no missing provider in use and no unusable stored profile. Those are valuable facts, but they remain control-plane facts until a probe or a real agent turn reaches the provider.

Surface	What it can prove	What it cannot prove
`config validate`	The current file matches the installed schema.	A credential works or a model accepts inference.
`models list`	Catalog and configured rows, availability metadata, tags, and context metadata.	Exact execution readiness; the command is intentionally read-only and does not call providers.
`models status`	Resolved primary, ordered fallbacks, aliases, model policy, and credential eligibility.	That a provider will answer the next request.
`models status --probe`	A bounded live request through a specific provider/auth route.	Future uptime, fallback quality, or recovery from a different error class.
Real agent task	The selected model can handle the actual channel, prompt, and harmless tool contract.	That every fallback behaves the same way.

Failure modes hidden by an available row

The three unavailable rows in the observed list were not marked missing. That is not contradictory. “Known to the catalog” and “usable by the current runtime” are different states. The CLI documentation makes the same warning in another form: provider-owned catalog rows can exist without positive runtime or account evidence, and a list view never proves a complete model call.

Inventory comes first. It does not come last.

Even an available row can fail later because the selected credential is cooling down, the account cannot use that exact route, the plugin runtime is unavailable, the provider rejects the request shape, or the model lacks the tool behavior the agent expects. Treat the list as an inventory snapshot. The next gate is credential eligibility, then bounded inference, then the real workload.

A central request router connected only to approved luminous model cores inside a guarded circular boundary — Catalog visibility, policy permission, and live reachability overlap, but none substitutes for the other two.

Availability is not a fallback plan

OpenClaw handles provider trouble in two stages. It first rotates eligible authentication profiles inside the selected provider. Only after that route is exhausted by a failover-worthy condition does it advance through agents.defaults.model.fallbacks. A second credential for one provider and a second model on another provider solve different failures.

The inspected installation had a healthy OAuth profile and a successful primary probe, but its text fallback array was empty. That is a coherent strict policy, not a broken configuration. It also means a provider outage becomes visible downtime. Adding fallbacks would trade some of that downtime for a more complex contract: every alternate needs adequate tool support, context capacity, latency, safety behavior, and output quality.

Strict failure is a valid production choice.

Do not add a cheap chat model merely to make the fallback list non-empty. A recovery answer from a model that cannot honor the agent’s tools or security constraints is often worse than an explicit failure. Availability belongs after the workload’s minimum capability floor, not before it.

The route order is also selection-source dependent. A configured default can use its fallback list. A per-agent primary is strict unless that agent declares its own fallbacks. A cron model normally uses configured fallbacks unless its payload supplies a different list. A model chosen explicitly by a user for one session is strict: if that exact route fails, OpenClaw reports the failure instead of silently answering from an unrelated model.

The route matrix worth approving

A production review should fit on one page. The following matrix is more useful than a long model catalog because each row answers one operational question.

Decision	Evidence to keep	Reject when
Primary model	Exact provider/model ref, intended workload, context and tool requirements.	The selection is based only on a display name or benchmark rank.
Model policy	Exact allowed refs or documented provider-prefix wildcards.	A wildcard exposes models that have not passed the workload review.
Authentication	Provider, profile type, eligibility, expiry state, and routing order—never the secret.	The route depends on an unknown shell environment or an expired profile.
Fallback order	Short ordered chain plus a capability test for every entry.	An alternate loses required tools, context, safety controls, or acceptable output quality.
Session behavior	Whether the session inherits config, is user-pinned, or is on automatic fallback.	An operator assumes a default change rewrote existing session pins.
Recovery proof	One bounded probe and one harmless real task, followed by a controlled failure drill.	Only static status output was collected.

Capture the baseline before proposing a change. These commands are read-only except for the probe, which sends a real request and can consume tokens or encounter rate limits:

openclaw --version
openclaw config validate --json
openclaw models status --json
openclaw models list --json

# Real provider request: scope it deliberately
openclaw models status --json --probe \
  --probe-provider <provider> \
  --probe-timeout 15000 \
  --probe-max-tokens 1

Store a sanitized summary rather than the raw status document. Even masked output can expose provider choices, local paths, profile labels, account email addresses, quota windows, and the shape of your recovery policy.

Testing failover without sacrificing production credentials

Deleting a production key is an impressively direct way to learn that a production key was important. It is not a good failover test. Use a disposable agent, a staging profile, or a scheduled maintenance window where the expected route and rollback are explicit.

No probe can certify the next outage.

Record the resolved primary, auth eligibility, fallback order, and selection source.
Probe the primary provider with a small, non-sensitive request and a bounded timeout.
Run one real task that includes the least dangerous tool behavior the workload requires, such as reading a known public page.
In the isolated test context, make the primary route fail in the planned way. Do not alter the live agent’s only credential.
Confirm the fallback notice, active provider/model, tool result, and total latency. A successful text reply is not enough when the agent normally uses tools.
Restore the primary and observe the recovery notice on a later turn. Confirm that the selected primary did not silently become the fallback.

Error class matters. Authentication failures, rate limits, billing disables, overload, and timeout-shaped failures can advance the chain. An invalid request normally should not: repeating malformed input through another provider does not repair the payload. Context overflow follows compaction and retry handling rather than acting as a general license to change models.

A luminous request encountering a guarded primary model core before continuing through two ordered fallback cores — OpenClaw exhausts eligible auth routes inside the provider before advancing through the ordered model chain.

Common issues: why the current chat may ignore a new default

Changing agents.defaults.model.primary affects new or unpinned sessions. It does not rewrite a user’s explicit selection. Inspect the chat-level state with /model status; use /model default when the session should inherit configured policy again.

This strictness is intentional. A user who selected one model asked for that route, not “something vaguely similar if it is down.” Automatic fallback state is different: it applies to the turn, preserves the selected primary, and lets OpenClaw announce both the fallback transition and later recovery.

Config inherited

The session starts from the configured or per-agent primary and can use the fallback policy allowed for that source.

User selected

The provider/model choice is exact and strict. Failure stays visible until the user clears or changes it.

Cron primary

The job model can use configured fallbacks; an explicit empty payload list makes that job strict.

Automatic fallback

The alternate answers the affected turn while the selected primary remains the origin for later recovery.

Decision: keep the chain explainable

The inspected route passed its static checks and one bounded live probe. It did not have a text fallback, so no claim about cross-model failover would be honest. That is the right stopping point for the evidence. A resilient redesign would require a candidate fallback, the same harmless tool test on both models, an isolated failure drill, and an explicit judgment about quality and cost.

For most operators, the defensible policy is one strong primary and a short fallback chain whose members are boringly well understood. Keep aliases readable, policy entries narrow, credential order private, and session pins visible. If no alternate meets the workload contract, document strict failure instead of installing a decorative fallback.

If you need persistent agents without maintaining provider credentials, model routing, and recovery drills yourself, deploy an AI agent on GolemWorkers. For adjacent operational boundaries, see OpenClaw Gateway setup, OpenClaw multi-agent routing, and OpenClaw tool policy.

Documentation behind the routing model

Models CLI reference — status, list, probes, aliases, authentication, and fallback commands.
Model selection concepts — primary selection, policy allowlists, per-agent overrides, session pins, and cron behavior.
Model failover — auth-profile rotation, cooldowns, error classes, ordered model fallbacks, and recovery notices.
Model providers — provider references, authentication options, discovery, and routing configuration.