OpenClaw Model Failover Guide

Failover is an availability policy, not a substitute for a broken primary configuration. Confirm each route independently before placing it in an ordered fallback list.

Define model roles

Choose:

• One primary model for normal agent turns
• Ordered fallbacks that can handle the same required tools
• An optional utility model for summaries or other small supporting work

Do not mix a strong tool-calling primary with a fallback that cannot emit the same tool schema. A successful text response can still be an operational failure if the task required tools.

Inspect the resolved configuration:

openclaw models status
openclaw config get agents.defaults.model
openclaw config get agents.defaults.models

Use the Control UI to save the primary and ordered fallbacks together, or follow the exact CLI shape documented by the installed version.

Test each route

Temporarily select each candidate as primary and run the same harmless task. Record authentication, latency, tool behavior, and context limits. Restore the intended primary before testing failure handling.

Provider cooldowns and session-specific overrides can make a later turn resolve differently from a fresh session. When investigating, compare a clean session with the existing failing session.

Test a controlled failure

Use a non-destructive provider test or a temporary invalid route in an isolated environment. Confirm the failure is categorized, the intended fallback is selected, and recovery returns to the primary according to the documented policy.

Expected result

• Every configured route works alone.
• Fallback order is visible and intentional.
• Tool-required tasks remain tool-capable after failover.
• Logs identify the failed route and selected replacement.
• A new healthy session resolves to the intended primary again.