OpenClaw Models CLI: Manage Models, Fallbacks, and Auth

openclaw models

Discovering models, scanning for them, and setting them up (default model, fallbacks, auth profiles).

See also:

• Provider and model details: Models
• Selection logic plus the /models slash command: Models concept
• Configuring provider auth: Getting started

Common commands

openclaw models --json
openclaw models status
openclaw models list
openclaw models refresh
openclaw models set <model-or-alias>
openclaw models set-image <model-or-alias>
openclaw models scan

To point at a particular configured agent, the status, list, and auth subcommands take --agent <id>; fallbacks/image-fallbacks always operate on the configured default agent, while set, set-image, scan, refresh, and aliases refuse --agent entirely because they are global and never scoped to an agent. When the flag is left out, commands that are --agent-aware fall back to OPENCLAW_AGENT_DIR if it is set, or else to the configured default agent.

The provider must be declared by an installed plugin or set up under models.providers for models set and models set-image to work. An unrecognized provider exits with a nonzero code and leaves the config untouched. If the provider is recognized but the model is not in the local catalog, the selection is saved and a warning is printed, since newly released and self-hosted models may not yet be cataloged. Unknown providers that are configured are listed by openclaw doctor --json; adding --severity-min info also shows active models that the local catalog cannot verify.

Status

Running openclaw models on its own does the same thing as openclaw models status. The object returned by openclaw models --json is identical to openclaw models status --json.

The resolved default and fallbacks, along with an auth summary, are shown by openclaw models status. Cooldowns on active profiles appear under Unavailable auth profiles with the stored reason and recovery action; the same data is exposed in auth.unusableProfiles for JSON output. For plugin-owned agent runtimes like Codex, status also verifies that the owning plugin is enabled and passed startup payload verification. A route with valid credentials but an unavailable runtime reports status: unavailable rather than usable; JSON output carries separate authStatus, runtimeStatus, and bounded runtime diagnostics. When provider usage snapshots exist, the OAuth/API-key status section includes provider usage windows and quota snapshots. Providers with current usage windows: Anthropic, GitHub Copilot, OpenAI, MiniMax, Xiaomi, and z.ai. Usage auth is drawn from provider-specific hooks when available; otherwise OpenClaw falls back to matching OAuth/API-key credentials from auth profiles, env, or config.

In --json output, auth.providers is the provider overview that is aware of env, config, and the store, whereas auth.oauth covers only auth-store profile health.

Options:

Probe rows may be sourced from auth profiles, environment credentials, or models.json. The status buckets for probes are ok, auth, rate_limit, billing, timeout, format, unknown, and no_model.

When you run models status --probe directly, temporary internal sessions are created in the canonical database of the chosen agent, which means the command needs exclusive control over the configured state directory. Before probing, stop any active Gateway with openclaw gateway stop; once the command finishes or gets interrupted, it cleans up its internal sessions and frees the state lock.

Here are the detail and reason codes you might encounter when a probe fails to reach a model call:

• excluded_by_auth_order: a stored profile exists, but an explicit auth.order.<provider> left it out, so the probe reports the exclusion rather than attempting it.
• missing_credential, invalid_expires, expired, unresolved_ref: the profile is present, yet it is either ineligible or cannot be resolved.
• ineligible_profile: the profile does not match the provider configuration for some other reason.
• no_model: provider authentication is present, but OpenClaw could not identify a probeable model candidate for that provider.

For troubleshooting OpenAI ChatGPT/Codex OAuth, openclaw models status, openclaw models auth list --provider openai, and openclaw config get agents.defaults.model --json offer the fastest way to verify whether an agent holds a usable openai OAuth profile for openai/* via the native Codex runtime. Refer to OpenAI provider setup for details.

List

openclaw models list operates in read-only mode: it reads configuration, auth profiles, existing catalog state, and provider-owned catalog rows, but it never modifies models.json.

openclaw models refresh [--json] triggers an immediate hosted catalog check. Similar to scan, it refuses --agent because the hosted catalog is global rather than agent-scoped. After a running Gateway restarts, updated rows take effect. When models.catalogRefresh.enabled is set to false, the command prints a clear disabled result. The public change history for the catalog is maintained in openclaw/catalog, where the scheduled publisher commits each content update.

Options include: --all (full catalog), --local (limit to local models), --provider <id>, --agent <id>, --json, and --plain. --agent picks that agent's auth store, workspace, and provider catalog context; when it is present, explicit multi-agent fleets do not require a default owner.

Notes:

• The Auth column relies on read-only validation. For OpenAI routes, it compares every API and base URL against eligible profiles, credentials, and command-scoped SecretRefs. When route policy is missing, an OpenAI row is marked unknown rather than falling back to provider-level authentication. Other providers and legacy checks operate at the provider level. For a configured native CLI route, a full or provider-filtered list can execute the provider's local auth-status check. That native outcome takes precedence; a separate provider credential does not confirm the CLI login. The default list remains lazy and reports native CLI authentication as unknown. Synthetic-auth metadata does not verify native account authentication. The command avoids loading the full provider runtime. It does not access keychain secrets or invoke provider APIs. It does not confirm exact execution readiness.
• models list --all --provider <id> may include provider-owned static catalog rows from plugin manifests or bundled provider catalog metadata even before you authenticate with that provider. Those rows remain marked unavailable until matching auth is set up.
• models list keeps the control plane responsive while provider catalog discovery runs slowly. The default and configured views switch to configured or synthetic model rows after a brief wait and let discovery proceed in the background. Use --all when you require the exact full discovered catalog and can tolerate waiting for provider discovery.
• Broad models list --all overlays manifest catalog rows onto registry rows without loading provider runtime supplement hooks. Provider-filtered manifest fast paths use only providers marked static; providers marked refreshable stay registry/cache-backed and add manifest rows as supplements, while providers marked runtime remain on registry/runtime discovery.
• models list separates native model metadata from runtime caps. In table output, Ctx displays contextTokens/contextWindow when an effective runtime cap differs from the native context window; JSON rows include contextTokens when a provider exposes that cap.
• For provider-owned routes, models list maps one logical provider/model row onto the selected route. Input and Ctx come only from an exact physical-route catalog row, with explicit configured logical overrides applied last; unresolved route selection shows unknown capability fields instead of borrowing sibling-route metadata.
• models list --provider <id> filters by provider id, such as moonshot or openai. It does not accept display labels from interactive provider pickers, such as Moonshot AI.
• Model refs are parsed by splitting on the first /. If the model ID includes / (OpenRouter-style), include the provider prefix (example: openrouter/moonshotai/kimi-k2).
• If you omit the provider, OpenClaw resolves the input as an alias first, then as a unique configured-provider match for that exact model id, and only then falls back to the configured default provider with a deprecation warning. If that provider no longer exposes the configured default model, OpenClaw falls back to the first configured provider/model instead of surfacing a stale removed-provider default.
• models status may show marker(<value>) in auth output for non-secret placeholders (for example OPENAI_API_KEY, secretref-managed, minimax-oauth, oauth:chutes, ollama-local) instead of masking them as secrets.

Set default / image model

openclaw models set <model-or-alias>
openclaw models set-image <model-or-alias>

set writes agents.defaults.model.primary; set-image writes agents.defaults.imageModel.primary. Both accept provider/model or a configured alias. set also repairs Codex/Copilot runtime plugin installs when the newly selected model needs one; set-image does not. Neither command accepts --agent; they always write agent defaults.

Scan

models scan reads OpenRouter's public :free catalog and ranks candidates for fallback use. The catalog itself is public, so metadata-only scans do not need an OpenRouter key.

By default OpenClaw tries to probe tool and image support with live model calls. If no OpenRouter key is configured, the command falls back to metadata-only output and explains that :free models still require OPENROUTER_API_KEY for probes and inference.

Options:

• --no-probe (metadata only; no config/secrets lookup)
• --min-params <b>
• --max-age-days <days>
• --provider <name>
• --max-candidates <n>
• --timeout <ms> (catalog request and per-probe timeout)
• --concurrency <n>
• --yes
• --no-input
• --set-default
• --set-image
• --json

--set-default and --set-image require live probes; metadata-only scan results are informational and are not applied to config.

Aliases

openclaw models aliases list [--json] [--plain]
openclaw models aliases add <alias> <model-or-alias>
openclaw models aliases remove <alias>

Aliases are attached to each model entry via agents.defaults.models.<key>.alias. When resolving <model-or-alias>, add first maps it to a canonical provider/model key, which means aliasing an existing alias repoints that alias instead of creating a chain. Adding an alias leaves agents.defaults.modelPolicy.allow untouched and does not constrain model overrides.

Fallbacks

openclaw models fallbacks list [--json] [--plain]
openclaw models fallbacks add <model-or-alias>
openclaw models fallbacks remove <model-or-alias>
openclaw models fallbacks clear

Handles agents.defaults.model.fallbacks. The parallel agents.defaults.imageModel.fallbacks list is managed by openclaw models image-fallbacks list|add|remove|clear, which uses the same subcommand structure.

Auth profiles

openclaw models auth add
openclaw models auth list [--provider <id>] [--json]
openclaw models auth login --provider <id> [--agent <agentId>]
openclaw models auth login --provider openai --profile-id openai:work
openclaw models auth login-github-copilot
openclaw models auth logout <profileId> [--yes]
openclaw models auth paste-api-key --provider <id>
openclaw models auth setup-token --provider <id>
openclaw models auth paste-token --provider <id>
openclaw models auth order get --provider <id>
openclaw models auth order set --provider <id> <profileIds...>
openclaw models auth order clear --provider <id>

For interactive authentication, models auth add is the helper to use. Depending on the provider you select, it can start an OAuth/API-key auth flow or walk you through pasting a token manually.

Saved auth profiles for the chosen agent are listed by models auth list, which never reveals token, API-key, or OAuth secret content. Cooldown and disable entries that are active show both the reason and the recovery step. Legacy Gemini CLI OAuth cooldowns point you to the supported Google AI Studio API-key setup rather than offering a Gemini CLI login flow that no longer exists. To narrow the output to a single provider, pass --provider <id> with something like openai; for automation, use --json.

A provider plugin's auth flow (OAuth/API key) is executed by models auth login. To find out which providers are installed, run openclaw plugins list. Providers that support named profiles during login can take --profile-id <id> via login (useful for keeping several logins for the same provider distinct), while --method <id> selects a particular auth method, --device-code is shorthand for --method device-code, --set-default applies the provider's recommended default model, and --force clears existing profiles for that provider first (handy when a cached OAuth profile is stuck or you need to change accounts).

Removing a saved auth profile from the selected agent's auth store is done with models auth logout <profileId>. The profile id shown by models auth list is what you use. That profile is also dropped from auth.profiles and from every auth.order list in your config, so no stale reference remains, and an auth.order.<provider> entry that would otherwise be emptied gets deleted (an authored empty order means "select no profiles" and would turn the provider off). On a TTY it asks for confirmation; scripts and agents should pass --yes. Logout fails if the profile is missing from the store, or if a models.providers.<id>.apiKey entry names it, so change that config value first.

For the GitHub device flow, models auth login-github-copilot is a shortcut for models auth login --provider github-copilot --method device; it takes --yes to overwrite an existing profile without any prompt.

To aim at a specific configured agent store, use either openclaw models auth --agent <id> <subcommand> or openclaw models auth <subcommand> --agent <id>. Both forms work with add, list, login, logout, paste-api-key, setup-token, paste-token, login-github-copilot, and order get/set/clear.

With OpenAI models, --provider openai defaults to ChatGPT/Codex account login. Only use --method api-key when you specifically need to add an OpenAI API-key profile, typically as a fallback for Codex subscription limits. Running openclaw doctor --fix migrates older legacy OpenAI Codex prefix auth/profile state over to openai.

Examples:

openclaw models auth login --provider openai --set-default
openclaw models auth login --provider openai --method api-key
openclaw models auth paste-api-key --provider openai
openclaw models auth list --provider openai
openclaw models auth logout openai:manual --yes

Notes:

• paste-api-key accepts API keys generated elsewhere, prompts for the key value, and writes it to the default profile id <provider>:manual unless you pass --profile-id. In automation, pipe the key on stdin, for example printf "%s\n" "$OPENAI_API_KEY" | openclaw models auth paste-api-key --provider openai.
• setup-token and paste-token remain generic token commands for providers that expose token auth methods.
• setup-token requires an interactive TTY and runs the provider's token-auth method (defaulting to that provider's setup-token method when it exposes one).
• paste-token requires --provider, prompts for the token value by default, and writes it to the default profile id <provider>:manual unless you pass --profile-id. In automation, pipe the token on stdin instead of passing it as an argument so provider credentials do not appear in shell history or process lists.
• paste-token --expires-in <duration> stores an absolute token expiry from a relative duration such as 365d or 12h.
• For openai, OpenAI API keys and ChatGPT/OAuth token material are different auth shapes. Use paste-api-key for sk-... OpenAI API keys and paste-token only for token auth material.
• Anthropic: setup-token/paste-token are supported OpenClaw auth paths for anthropic, but OpenClaw prefers reusing the Claude CLI (claude -p) on the host when it is available.
• auth order get/set/clear manages a per-agent auth profile order override for one provider in the SQLite auth store, separate from the auth.order.<provider> config key. set takes one or more profile ids in priority order. The stored order takes precedence over config for profile selection and CLI runtime routing; clear falls back to config/round-robin ordering.

Related

• CLI reference
• Model selection
• Model failover