Models CLI: Provider/Model Resolution

Model failover, How auth profiles rotate, cooldown timers behave, and the way those interact with fallback logic.
Model providers, A brief rundown of supported providers along with sample configurations.
Models CLI reference, The complete openclaw models command reference, including every flag.
Configuration reference, Model configuration keys, their defaults, and usage examples.

A model ref (provider/model) picks out a provider and a model, not the underlying agent runtime. When runtime policy is left unset or set to auto, OpenAI's provider-owned routing may assign Codex only for an exact official HTTPS Platform Responses or ChatGPT Responses route, provided no authored request override exists; the openai/* prefix by itself never triggers Codex. Completions adapters, custom endpoints, and authored request behavior remain on OpenClaw. Plaintext official HTTP endpoints are refused. Refer to OpenAI implicit agent runtime.

Subscription Copilot refs (github-copilot/*) can be enabled for the external GitHub Copilot agent runtime plugin, yet that route is always explicit, never chosen by auto. Runtime overrides belong on provider/model policy, not on the whole agent or session. Billing is unaffected by runtime selection: OpenAI API-key and ChatGPT/Codex subscription credentials stay separate. See Agent runtimes and GitHub Copilot agent runtime.

Selection order

Primary model

agents.defaults.model.primary (or agents.defaults.model as a plain string).

Fallbacks

agents.defaults.model.fallbacks, attempted sequentially.

Auth failover

Auth-profile rotation occurs within a provider before OpenClaw proceeds to the next fallback model.

Related model-config surfaces:

agents.defaults.models holds aliases and per-model settings. Adding an entry does not restrict model overrides.
agents.defaults.modelPolicy.allow serves as the optional override allowlist. Use exact refs or trailing prefix wildcards like provider/* and provider/namespace/*; omit it or set [] to permit any model. Per-agent agents.entries.*.modelPolicy.allow replaces the default policy for that agent.
agents.defaults.utilityModel is an optional lower-cost model for brief internal tasks such as generated dashboard session titles, supported channel thread/topic titles, and progress narration. Per-agent agents.entries.*.utilityModel overrides it. When unset, OpenClaw uses the primary provider's declared small-model default if one exists (OpenAI → gpt-5.6-luna, Anthropic → claude-haiku-4-5), otherwise the agent's primary model; set it to an empty string to disable utility routing. Generated titles retry once with the primary model when a distinct utility model fails. For dashboard titles, automatic utility derivation and the regular fallback follow the effective session provider and auth profile; an explicit utility model keeps its configured provider/auth. An empty utility model skips only the alternate small-model route, not dashboard title generation. Utility tasks are separate model calls and may send bounded task content to the selected model provider.
agents.defaults.imageModel is used only when the primary model cannot accept images.
agents.defaults.pdfModel is used by the pdf tool. If unset, the tool falls back to imageModel, then the resolved session/default model.
agents.defaults.mediaModels.{image,music,video} backs the shared media-generation tools. If unset, each tool infers an auth-backed provider default: current default provider first, then the remaining registered providers for that capability in provider-id order. Cross-provider fallback is the fixed default behavior.
Per-agent agents.entries.*.model (plus bindings) overrides agents.defaults.model, see Multi-agent routing.

Full key reference, defaults, and JSON5 examples: Configuration reference.

Selection source and fallback strictness

The same provider/model behaves differently depending on where it came from:

Source	Behavior
Configured default (`agents.defaults.model.primary`, per-agent primary)	Normal starting point; uses `agents.defaults.model.fallbacks`.
Auto fallback	Temporary recovery state, stored as `modelOverrideSource: "auto"`. OpenClaw periodically reprobes the original primary, clears the auto selection on recovery, and announces fallback/recovery transitions once per state change.
User session selection	Exact and strict. `/model`, the model picker, `session_status(model=...)`, and `sessions.patch` store `modelOverrideSource: "user"`. If that provider/model becomes unreachable, the run fails visibly instead of falling through to another configured model.
Cron `--model` / payload `model`	Per-job primary. Still uses configured fallbacks unless the job supplies its own payload `fallbacks` (`fallbacks: []` forces a strict run).

Other selection rules:

Modifying agents.defaults.model.primary leaves existing session pins untouched. When status reports This session is pinned to X; config primary Y will apply to new/unpinned sessions., clear the pin by running /model default.
Both the CLI default-model selector and the allowlist pickers honor models.mode: "replace", showing only models.providers.*.models rather than the complete built-in set.
The Control UI begins from the Gateway's prepared configured model view, so opening chat skips provider discovery. A model picker opened or refreshed may discover models needed by a trailing provider/* policy entry. Default and configured picker views omit catalog rows flagged deprecated or disabled unless that specific model is set as a primary, fallback, utility/tool model, alias/settings key, or exact policy entry. Those hidden rows stay selectable through an exact provider/model ref. The full built-in catalog, hidden rows included, appears only in explicit browse views (models.list with view: "all", or openclaw models list --all).
Provider inventory UIs rely on models.list with view: "provider-config" to present source-authored models.providers.*.models rows without enforcing picker allowlists.

Full mechanics: Model failover.

Quick model policy

Assign your primary to the strongest latest-generation model you have access to.
Reserve fallbacks for cost/latency-sensitive work and lower-stakes chat.
For tool-enabled agents or untrusted inputs, steer clear of older/weaker model tiers.

Onboarding

openclaw onboard

Configures model and auth for common providers without manual config editing, covering OpenAI Codex subscription OAuth and Anthropic (API key or Claude CLI reuse).

With no primary model configured, fresh OpenAI API-key and ChatGPT/Codex OAuth setup selects the exact openai/gpt-5.6-sol catalog ref. The bare direct-API openai/gpt-5.6 alias remains supported and resolves to the Sol tier. Reauthentication keeps an existing explicit primary model, including openai/gpt-5.5. If GPT-5.6 is unavailable to the account, choose openai/gpt-5.5 explicitly; OpenClaw does not silently downgrade it.

"Model is not allowed" (and why replies stop)

When agents.defaults.modelPolicy.allow is non-empty, it acts as the allowlist for /model, session overrides, and --model. Picking a model outside that allowlist returns before any normal reply is generated. A per-agent agents.entries.*.modelPolicy.allow replaces the default policy for that agent.

Model override "provider/model" is not allowed by agents.defaults.modelPolicy.allow.
Add "provider/model", "provider/*", or a narrower "provider/namespace/*" prefix to agents.defaults.modelPolicy.allow, or remove/empty the list to allow any model.

Resolve it by adding the model or a provider wildcard to the named modelPolicy.allow key, removing or emptying that list, or selecting a model from /model list. If the rejected command carried a runtime override like /model openai/gpt-5.5 --runtime codex, fix the allowlist first, then retry the same command.

For local/GGUF models, the allowlist requires the full provider-prefixed ref, for example ollama/gemma4:26b or lmstudio/Gemma4-26b-a4-it-gguf, check openclaw models list --provider <provider> for the exact string. Bare filenames or display names are insufficient once the allowlist is active.

To restrict providers without enumerating every model, use trailing prefix wildcard entries. A provider-wide provider/* matches every model under that provider; a narrower prefix such as clawrouter/anthropic/* matches only that namespace:

{
  agents: {
    defaults: {
      modelPolicy: {
        allow: ["openai/*", "vllm/*"],
      },
    },
  },
}

/model, /models, and model pickers then display the discovered catalog for those providers only, and new models can appear without editing the allowlist. Mix exact provider/model entries with provider/* entries to pull in one specific model from another provider.

Example allowlist with aliases and per-model settings:

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4-6" },
      modelPolicy: {
        allow: ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
      },
    },
  },
}

Edit the allowlist explicitly

Set the complete list directly:

openclaw config set agents.defaults.modelPolicy.allow '["openai/gpt-5.4","anthropic/*"]' --strict-json

openclaw models set, provider setup, and openclaw models aliases add can add entries under agents.defaults.models, but they never alter modelPolicy.allow. This keeps model metadata and aliases separate from override policy.

Choose a model for a session

Choose the model when you create a session whenever possible. The Control UI's New Chat composer includes the model picker for this reason: a fresh session gives the selected model a clean conversation boundary.

Changing the model for an established session is an advanced operation. The session transcript remains available, but the next model may have a different context window, prompt and tool behavior, or prompt-cache implementation. A mid-session switch can therefore reduce continuity, require earlier compaction, or lose prompt-cache reuse and increase latency or cost. For a planned model change, prefer a new session; use /model or the active-session model picker when you intentionally want the existing transcript to continue with another model.

Keep the thinking or reasoning level stable for the session when cache reuse matters. On OpenAI, changing the reasoning effort changes the reusable request state and can force the next turn to process the full conversation again. Other providers may also include thinking configuration in their cache identity, so changing only the thinking level can increase latency and input-token cost even when the model itself stays the same.

`/model` in chat

Direct owner/admin /model <model> requests default scope: it changes this session and starts a best-effort configured-default update. Adding -s uses session scope: only this session changes. If the agent has no explicit primary model, its effective default is the shared global agents.defaults.model fallback.

/model
/model list
/model 3
/model openai/gpt-5.4
/model openai/gpt-5.4 -s
/model default -s
/model default
/model status

/model and /model list render a compact numbered selector that pairs each model family with its available providers, and /model <#> picks from that list. The Telegram callback picker only applies within the current session. The Discord picker follows the direct command flow, so when an owner or admin submits, it requests an update to the configured default. /models add has been deprecated; it now replies with a message rather than registering models from chat.
Configured default: A direct owner/admin /model <model> alters the active session and asks for a best-effort refresh of the effective configured default. OpenClaw aims at the agent's explicit primary if one is set; otherwise it aims at the shared agents.defaults.model fallback. Immutable configuration stays untouched, and asynchronous write failures are logged without rolling back the session selection.
Current session only: /model <model> -s (or --session) modifies just the current session, leaving both configured defaults intact. A non-owner's bare /model <model> is also session-only, since that caller cannot write configured defaults. An explicitly user-chosen model and auth profile remain fixed across /new, /reset, session rollover, compaction, and cooldown windows while they stay valid for the provider; automatic profile pins may rotate or be cleared.
Use the configured default: /model default (with or without -s) removes the current session's model selection so it picks up the current effective configured default. A compatible auth-profile pin stays; an incompatible one is dropped. It does not bring back an older configured default that a prior owner/admin /model <model> replaced.
When the agent is idle, a model change applies to the next run right away. If a run is already in progress, the switch waits for the next clean retry point (or a later one, if tool activity or reply output has already begun).
A user-selected /model ref is strict for that session: if it becomes unreachable, the reply fails visibly instead of quietly falling back through agents.defaults.model.fallbacks. Configured defaults and cron job primaries still rely on fallback chains.
/model status is the detailed view: it lists auth candidates per provider and, when configured, the provider endpoint baseUrl plus api mode.
Model refs are parsed by cutting at the first /; type provider/model. If the model ID itself contains / (OpenRouter-style), prepend the provider prefix, e.g. /model openrouter/moonshotai/kimi-k2. If you leave off the provider, OpenClaw tries: (1) alias match, (2) unique configured-provider match for that exact unprefixed model id, (3) the configured default provider (deprecated fallback), and if that provider no longer exposes the configured default model, the first configured provider/model instead, so a stale removed-provider default is not surfaced.
Model refs are lowercased; provider IDs are otherwise exact, so use the ID advertised by the plugin.

Full command behavior and config: Slash commands.

CLI

openclaw models status
openclaw models list
openclaw models set <provider/model>
openclaw models set-image <provider/model>
openclaw models scan
openclaw models aliases list|add|remove
openclaw models fallbacks list|add|remove|clear
openclaw models image-fallbacks list|add|remove|clear
openclaw models auth list|add|login|paste-api-key|paste-token|setup-token|order

openclaw models with no subcommand acts as a shortcut for models status, which also exposes OAuth expiry for auth-store profiles (warns within 24h by default). Full flags, JSON shapes, and auth-profile subcommands: Models CLI reference.

Scanning (OpenRouter free models)

openclaw models scan inspects OpenRouter's public free-model catalog and can probe candidates for tool and image support live. The catalog itself is public, so metadata-only scans (--no-probe) need no key; live probing and --set-default/--set-image require an OpenRouter API key (auth profile or OPENROUTER_API_KEY) and fail closed to metadata-only output without one.

Results rank by: image support, then tool latency, then context size, then parameter count. In a TTY, probed results prompt an interactive fallback selection; non-interactive mode needs --yes to accept defaults.

Models registry (`models.json`)

Hosted catalog updates

OpenClaw can refresh the model metadata shipped by installed provider plugins without waiting for a new OpenClaw release. The Gateway makes one background JSON GET at startup and then checks at most every six hours. The request sends no prompts, credentials, model usage, or configuration payload beyond the normal HTTP user agent and conditional cache headers.

The downloaded bundle is stored in the shared SQLite state database and becomes visible after the next Gateway restart. Remote data can update or add models only for providers declared by installed plugin manifests. It cannot supply API base URLs or request headers, and a catalog older than the installed release's build stamp is ignored.

The hosted file is published from the public openclaw/catalog GitHub repository. Its scheduled workflow refreshes from OpenClaw's shipped plugin manifests and pricing sources; every catalog content change is preserved as a public commit.

Run openclaw models refresh for an immediate metadata and pricing check, or disable every hosted catalog request with models.catalogRefresh.enabled: false. When disabled, pricing stays at bundled and explicitly configured values. A self-hosted mirror can be selected with an HTTPS models.catalogRefresh.url (or localhost HTTP for testing); see configuration reference.

Custom providers configured under models.providers are written into models.json under the agent directory (default ~/.openclaw/agents/<agentId>/agent/models.json). Provider-plugin catalogs are stored separately as generated plugin-owned catalog shards and load automatically. This file is merged with config by default; set models.mode: "replace" to use only your configured providers.

Merge mode precedence

For matching provider IDs:

When the agent models.json already carries a non-empty baseUrl, that value takes precedence.
A non-empty apiKey inside models.json only applies if the provider is not managed through SecretRef in the current config/auth-profile context.
For SecretRef-managed apiKey values, the refresh pulls from source markers rather than storing resolved secrets: env refs use the environment variable name, while file/exec/store refs rely on secretref-managed.
Header values under SecretRef management refresh in the same manner, with env refs depending on secretref-env:ENV_VAR_NAME.
If apiKey or baseUrl in models.json is empty or absent, the fallback goes to config models.providers.
Remaining provider fields refresh using config and normalized catalog data.

Marker persistence follows the source as the authority: whenever OpenClaw regenerates models.json, including through command-driven flows like openclaw agent, it writes markers from the active source config snapshot (before resolution), not from the resolved runtime secret values.

Agent runtimes, OpenClaw, Codex, and other agent loop runtimes
Configuration reference, model config keys
Image generation, image model configuration
Model failover, fallback chains
Model providers, provider routing and auth
Models CLI reference, full command and flag reference
Music generation, music model configuration
Video generation, video model configuration