Models

text

Copy

openclaw models

Model discovery, scanning, and configuration (default model, fallbacks, auth profiles).

Related:

• Providers + models: Models
• Model selection concepts +
  text

  Copy

  /models
  slash command: Models concept
• Provider auth setup: Getting started

Common commands

bash
Copy
openclaw models status
openclaw models list
openclaw models set <model-or-alias>
openclaw models scan

shows the resolved default/fallbacks plus an auth overview. When provider usage snapshots are available, the OAuth/API-key status section includes provider usage windows and quota snapshots. Current usage-window providers: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi, and z.ai. Usage auth comes from provider-specific hooks when available; otherwise OpenClaw falls back to matching OAuth/API-key credentials from auth profiles, env, or config. In output, is the env/config/store-aware provider overview, while is auth-store profile health only. Add to run live auth probes against each configured provider profile. Probes are real requests (may consume tokens and trigger rate limits). Use to inspect a configured agent’s model/auth state. When omitted, the command uses / if set, otherwise the configured default agent. Probe rows can come from auth profiles, env credentials, or .

Notes:

• text

  Copy

  models set <model-or-alias>
  accepts
  text

  Copy

  provider/model
  or an alias.
• text

  Copy

  models list
  is read-only: it reads config, auth profiles, existing catalog state, and provider-owned catalog rows, but it does not rewrite
  text

  Copy

  models.json
  .
• The
  text

  Copy

  Auth
  column is provider-level and read-only. It is computed from local auth profile metadata, env markers, configured provider keys, local-provider markers, AWS Bedrock env/profile markers, and plugin synthetic-auth metadata; it does not load provider runtime, read keychain secrets, call provider APIs, or prove exact per-model execution readiness.
• text

  Copy

  models list --all --provider <id>
  can include provider-owned static catalog rows from plugin manifests or bundled provider catalog metadata even when you have not authenticated with that provider yet. Those rows still show as unavailable until matching auth is configured.
• text

  Copy

  models list
  keeps the control plane responsive while provider catalog discovery is slow. The default and configured views fall back to configured or synthetic model rows after a short wait and let discovery finish in the background. Use
  text

  Copy

  --all
  when you need the exact full discovered catalog and are willing to wait for provider discovery.
• Broad
  text

  Copy

  models list --all
  merges manifest catalog rows over registry rows without loading provider runtime supplement hooks. Provider-filtered manifest fast paths use only providers marked
  text

  Copy

  static
  ; providers marked
  text

  Copy

  refreshable
  stay registry/cache-backed and append manifest rows as supplements, while providers marked
  text

  Copy

  runtime
  stay on registry/runtime discovery.
• text

  Copy

  models list
  keeps native model metadata and runtime caps distinct. In table output,
  text

  Copy

  Ctx
  shows
  text

  Copy

  contextTokens/contextWindow
  when an effective runtime cap differs from the native context window; JSON rows include
  text

  Copy

  contextTokens
  when a provider exposes that cap.
• text

  Copy

  models list --provider <id>
  filters by provider id, such as
  text

  Copy

  moonshot
  or
  text

  Copy

  openai-codex
  . It does not accept display labels from interactive provider pickers, such as
  text

  Copy

  Moonshot AI
  .
• Model refs are parsed by splitting on the first
  text

  Copy

  /
  . If the model ID includes
  text

  Copy

  /
  (OpenRouter-style), include the provider prefix (example:
  text

  Copy

  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.
• text

  Copy

  models status
  may show
  text

  Copy

  marker(<value>)
  in auth output for non-secret placeholders (for example
  text

  Copy

  OPENAI_API_KEY
  ,
  text

  Copy

  secretref-managed
  ,
  text

  Copy

  minimax-oauth
  ,
  text

  Copy

  oauth:chutes
  ,
  text

  Copy

  ollama-local
  ) instead of masking them as secrets.

Models scan

reads OpenRouter's public 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

models still require for probes and inference.

Options:

• text

  Copy

  --no-probe
  (metadata only; no config/secrets lookup)
• text

  Copy

  --min-params <b>
• text

  Copy

  --max-age-days <days>
• text

  Copy

  --provider <name>
• text

  Copy

  --max-candidates <n>
• text

  Copy

  --timeout <ms>
  (catalog request and per-probe timeout)
• text

  Copy

  --concurrency <n>
• text

  Copy

  --yes
• text

  Copy

  --no-input
• text

  Copy

  --set-default
• text

  Copy

  --set-image
• text

  Copy

  --json

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

Models status

Options:

• text

  Copy

  --json
• text

  Copy

  --plain
• text

  Copy

  --check
  (exit 1=expired/missing, 2=expiring)
• text

  Copy

  --probe
  (live probe of configured auth profiles)
• text

  Copy

  --probe-provider <name>
  (probe one provider)
• text

  Copy

  --probe-profile <id>
  (repeat or comma-separated profile ids)
• text

  Copy

  --probe-timeout <ms>
• text

  Copy

  --probe-concurrency <n>
• text

  Copy

  --probe-max-tokens <n>
• text

  Copy

  --agent <id>
  (configured agent id; overrides
  text

  Copy

  OPENCLAW_AGENT_DIR
  /
  text

  Copy

  PI_CODING_AGENT_DIR
  )

keeps stdout reserved for the JSON payload. Auth-profile, provider, and startup diagnostics are routed to stderr so scripts can pipe stdout directly into tools such as .

Probe status buckets:

• text

  Copy

  ok
• text

  Copy

  auth
• text

  Copy

  rate_limit
• text

  Copy

  billing
• text

  Copy

  timeout
• text

  Copy

  format
• text

  Copy

  unknown
• text

  Copy

  no_model

Probe detail/reason-code cases to expect:

• text

  Copy

  excluded_by_auth_order
  : a stored profile exists, but explicit
  text

  Copy

  auth.order.<provider>
  omitted it, so probe reports the exclusion instead of trying it.
• text

  Copy

  missing_credential
  ,
  text

  Copy

  invalid_expires
  ,
  text

  Copy

  expired
  ,
  text

  Copy

  unresolved_ref
  : profile is present but not eligible/resolvable.
• text

  Copy

  no_model
  : provider auth exists, but OpenClaw could not resolve a probeable model candidate for that provider.

Aliases + fallbacks

bash
Copy
openclaw models aliases list
openclaw models fallbacks list

Auth profiles

bash
Copy
openclaw models auth add
openclaw models auth login --provider <id>
openclaw models auth setup-token --provider <id>
openclaw models auth paste-token

is the interactive auth helper. It can launch a provider auth flow (OAuth/API key) or guide you into manual token paste, depending on the provider you choose.

runs a provider plugin’s auth flow (OAuth/API key). Use to see which providers are installed. Use to write auth results to a specific configured agent store. The parent flag is honored by , , , , and .

Examples:

bash
Copy
openclaw models auth login --provider openai-codex --set-default

Notes:

• text

  Copy

  setup-token
  and
  text

  Copy

  paste-token
  remain generic token commands for providers that expose token auth methods.
• text

  Copy

  setup-token
  requires an interactive TTY and runs the provider's token-auth method (defaulting to that provider's
  text

  Copy

  setup-token
  method when it exposes one).
• text

  Copy

  paste-token
  accepts a token string generated elsewhere or from automation.
• text

  Copy

  paste-token
  requires
  text

  Copy

  --provider
  , prompts for the token value, and writes it to the default profile id
  text

  Copy

  <provider>:manual
  unless you pass
  text

  Copy

  --profile-id
  .
• text

  Copy

  paste-token --expires-in <duration>
  stores an absolute token expiry from a relative duration such as
  text

  Copy

  365d
  or
  text

  Copy

  12h
  .
• Anthropic note: Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so OpenClaw treats Claude CLI reuse and
  text

  Copy

  claude -p
  usage as sanctioned for this integration unless Anthropic publishes a new policy.
• Anthropic
  text

  Copy

  setup-token
  /
  text

  Copy

  paste-token
  remain available as a supported OpenClaw token path, but OpenClaw now prefers Claude CLI reuse and
  text

  Copy

  claude -p
  when available.

Related

• CLI reference
• Model selection
• Model failover