Complete reference for openclaw models, checking model status, setting primary and image models, configuring fallback chains, managing aliases, and handling provider authentication.
What does Openclaw Models Manage?
It’s the control surface for everything related to which AI model OpenClaw uses and how it authenticates with model providers. This command group is the primary interface for OpenClaw AI Model Integration, allowing you to inspect what model is currently active, swap providers, and configure fallback chains so agents automatically retry during outages.
You can also create short aliases for frequently used models and run or refresh provider OAuth flows—all without touching configuration files directly. Changes made here are reflected in ~/openclaw/config.json and take effect on the next Gateway restart.
Finding the Right Subcommand
For a quick health check, “is my model working and is my auth still valid?”, run models status –probe. To switch models, use models set. If you’re setting up resilient multi-provider configs, go to Fallbacks & Aliases.
For provider login issues or OAuth expiry, Auth has the relevant commands. One critical detail before you start: model references must always use provider/model format, see Syntax Rules, especially if you’re using OpenRouter where model IDs contain their own slash.
Basic Commands
Core commands for inspecting and switching your model configuration.
| openclaw models statusread-only Shows the resolved primary model, fallbacks, image model, and an overview of configured provider authentication. Also warns about expiring OAuth profiles. –json | –plain | –probe | –check | –agent <id> –check is automation-friendly: exits 1 when auth is expired/missing, exits 2 when expiring soon. –probe runs a live auth probe against configured providers rather than relying on cached state. |
| openclaw models list Displays all configured models. Defaults to your configured set, use –all to see the full catalog. –all | –local | –provider <name> | –plain | –json |
| openclaw models set <provider/model> Changes your primary text model. Accepts the provider/model format. Example: openclaw models set anthropic/claude-opus-4-6 |
| openclaw models set-image <provider/model> Changes your primary image model. Same provider/model format as set. |
| openclaw models scan Inspects and probes the OpenRouter free model catalog. Useful for discovering available free-tier models before setting one as your primary or adding it to a fallback chain. |
common status and set patterns
# Live probe — check auth state against providers openclaw models status --probe # CI/automation health check (exits non-zero on auth issues) openclaw models status --check # Switch primary model openclaw models set anthropic/claude-opus-4-6 # List all available models for a provider openclaw models list --provider anthropic
Fallbacks & Aliases
Configure a fallback chain so OpenClaw automatically tries the next model on provider outages or rate limits. Create aliases to reference models with shorter names.
ALIASES
| openclaw models aliases list | List all configured model aliases. |
| openclaw models aliases add <alias> <provider/model> | Create a shortcut alias for a provider/model reference. |
| openclaw models aliases remove <alias> | Delete a named alias. |
TEXT MODEL FALLBACKS
| openclaw models fallbacks list | Show the current fallback chain for text models. |
| openclaw models fallbacks add <provider/model> | Append a model to the end of the fallback chain. |
| openclaw models fallbacks remove <provider/model> | Remove a specific model from the fallback chain. |
| openclaw models fallbacks clear | Remove all fallback entries, reverting to primary-only behavior. |
IMAGE MODEL FALLBACKS
| openclaw models image-fallbacks list | Show the current fallback chain for image models. Also supports add, remove, and clear sub-actions. |
Fallback order matters, models are tried in the order they appear in the list. Use fallbacks list to verify the chain before relying on it in production. Cheaper or more available models typically belong at the end of the chain.
Managing Authentication Profiles
Interactive login flows and credential management for model providers, no manual config file editing required.
| openclaw models auth login –provider <id> Runs a provider plugin’s specific auth flow, OAuth, API key wizard, or similar. The exact flow depends on the provider plugin. Use this for initial setup or re-authentication after token expiry. |
| openclaw models auth setup-token / auth paste-token Used for pasting subscription tokens such as Anthropic setup-tokens. setup-token guides the flow; paste-token accepts a token directly from stdin or a prompt. |
| openclaw models auth order Explicitly pins or sets the rotation order of authentication profiles for a single provider, for example, trying a work profile before a default profile. Append –agent <id> to scope the order to a specific agent. |
AUTH ORDER SUBCOMMANDS
| openclaw models auth order get –provider <name> | Show the current profile rotation order for a provider. |
| openclaw models auth order set –provider <name> <profileId1> [profileId2] | Set an explicit ordered list of profile IDs for the provider. |
| openclaw models auth order clear –provider <name> | Remove the explicit order, reverting to default profile selection. |
Important Syntax Rules
Three rules that govern how model references are parsed. Getting these wrong causes silent misrouting or command errors.
Rule 1: provider/model format is always required
Model references must always use the provider/model format. OpenClaw parses this by splitting on the first /.
Correct
anthropic/claude-opus-4-6
Wrongclaude-opus-4-6
Rule 2: OpenRouter models need a triple-segment path
If the model ID itself contains a slash (common for OpenRouter models like moonshotai/kimi-k2), you must still include the openrouter prefix, resulting in a three-segment path.
Correct
openrouter/moonshotai/kimi-k2
Wrongmoonshotai/kimi-k2
Rule 3: omitting provider uses alias or default provider
If you omit the provider entirely, OpenClaw treats the input as an alias first, then falls back to looking for the model on the default provider. This is useful for short references once aliases are set up, but can cause unexpected routing if the alias doesn’t exist.
Alias resolve
opus → resolves to alias target
No alias
tries default provider
The split-on-first-slash rule means moonshotai/kimi-k2 is parsed as provider moonshotai, model kimi-k2, not as an OpenRouter model. Always prefix with openrouter/ for OpenRouter model IDs that contain their own slash.
