OpenClaw models

Model selection looks like one setting and is actually a small system: a primary, a fallback chain, credential rotation inside a provider, a policy that can restrict overrides, and a chat command whose scope depends on flags and authority. Getting the mental model right removes most of the confusing failures, starting with the difference between a configured default and something you selected yourself.

How a reference resolves

• The order is simple: the configured primary is tried first, then the configured fallbacks in order, and auth-profile rotation happens inside a provider before OpenClaw moves on to the next fallback model.
• Around that sit several related surfaces: an aliases and per-model settings map, a selection scope that decides what an unscoped command changes, an optional allow policy, a lower-cost utility model for short internal tasks such as generated titles and progress narration, an image model used only when the primary cannot accept images, a document model for the file tool, and media models for generation tools.
• When the utility model is unset, OpenClaw uses the primary provider's declared small-model default when one exists and otherwise the primary itself; setting it to an empty string disables utility routing, and a generated title retries once with the primary when a distinct utility model fails.
• Where a selection came from changes how strict it is: a configured default uses the fallback chain, an automatic fallback is temporary recovery state that is periodically reprobed and cleared on recovery, a scheduled job supplies its own primary while still using configured fallbacks unless it passes an empty list, and a user selection is exact.

A model ref (provider/model) chooses a provider and model, not the low-level agent runtime.

Not allowed, and why replies stop

With no allow policy set, you can select an explicit provider and model even when it is absent from the picker catalog, because the catalog supplies browse choices and metadata rather than acting as an implicit allowlist, while availability, runtime compatibility and authentication are checked separately. When the policy is non-empty it becomes the allowlist for the chat command, session overrides and the command-line flag, and selecting outside it returns before any reply is generated with a message naming the exact key to edit. The fix is adding the model, adding a provider wildcard, emptying the list, or picking from the list command. Wildcards are trailing prefixes, so a provider-wide entry matches every model under that provider and a narrower namespace prefix matches only that namespace, which lets new models appear without editing the policy. Local models need the full provider-prefixed reference rather than a bare filename.

The chat command

• Without a scope flag the command changes only the current session; the session flag is explicit, the agent flag also requests an update to that agent's configured model, and the global flag also requests an update to the shared default, with both configured writes requiring owner or administrator authority.
• A user-selected reference is strict for that session: if it becomes unreachable the reply fails visibly rather than falling through the configured fallbacks, and explicit model and profile pins survive resets, rollover, compaction and cooldown windows while they remain valid.
• References are parsed by splitting on the first separator, so a model id containing a separator needs its provider prefix; omitting the provider tries an alias, then a unique configured-provider match, then the configured default provider as a deprecated fallback, with exact case winning over case-insensitive matches.

OpenClaw model providers covers the provider side and OpenClaw model failover the rotation and cooldown rules behind the chain.

Switching a live session

The docs are unusually direct about this: choose the model when you create a session whenever possible, because changing it mid-session is an advanced operation. The transcript survives, but the next model may have a different context window, prompt and tool behaviour, or cache implementation, so the switch can reduce continuity, force earlier compaction, or lose cache reuse and cost more. Keeping the reasoning level stable matters for the same reason, since on some providers changing the effort changes the reusable request state and forces the next turn to reprocess the conversation. The catalog itself is prepared once by the gateway for every surface, so opening a picker reads published rows rather than starting provider discovery, and an explicit refresh is what asks for new models. OpenClaw model authentication is the credential behind the selection and OpenClaw configuration the keys that hold it.

On Diali

On Diali the model catalog and its credentials are managed by the platform, with the runtime configuration generated from the dashboard and replaced at each release, so selection is a dashboard choice rather than a config file edit. Hosted OpenClaw on Diali describes the hosted assistant and Diali pricing the plans it ships in.

• Primary, then fallbacks, with credential rotation inside a provider.
• Your own selection is strict and fails visibly.
• Pick the model when you open the session, not halfway through.