Models
CLI reference for openclaw models (status/list/set/scan, aliases, fallback, auth).
Model discovery, scanning, and configuration (default model, fallback, auth profiles).
Related:
- Providers + models: ''Models''
- Provider auth setup: ''Getting Started''
Common commands
openclaw models status openclaw models list openclaw models set <model-or-alias> openclaw models scan
''openclaw models status'' shows resolved default/fallback plus auth overview.
When provider usage snapshot is available, OAuth/token status section includes
provider usage headers.
Add ''--probe'' to run live auth probes against each configured provider profile.
Probes are real requests (may consume tokens and trigger rate limits).
Use ''--agent <id>'' to check model/auth status for configured agent. When omitted,
''OPENCLAW_AGENT_DIR''/''PI_CODING_AGENT_DIR'' is used if set for the command, otherwise
the configured default agent.
Notes:
- ''models set <model-or-alias>'' accepts ''provider/model'' or alias.
- Model references are resolved by splitting on the ''first'' ''/''. If model ID contains ''/'' (OpenRouter style), include provider prefix (e.g., ''openrouter/moonshotai/kimi-k2'').
- If provider is omitted, OpenClaw treats input as alias or model for ''default provider'' (only valid when model ID has no ''/'').
`models status`
Options:
- ''--json''
- ''--plain''
- ''--check'' (exit 1=expired/missing, 2=expired)
- ''--probe'' (live probe of configured auth profiles)
- ''--probe-provider <name>'' (probe one provider)
- ''--probe-profile <id>'' (repeat or comma-separated profile IDs)
- ''--probe-timeout <ms>''
- ''--probe-concurrency <n>''
- ''--probe-max-tokens <n>''
Aliases + Fallbacks
openclaw models aliases list openclaw models fallbacks list
Auth profiles
openclaw models auth add openclaw models auth login --provider <id> openclaw models auth setup-token openclaw models auth paste-token
''models auth login'' runs provider plugin's auth flow (OAuth/API key). Use
''openclaw plugins list'' to see which providers are installed.
Notes:
- ''setup-token'' prompts for setup token value (generate it with ''claude setup-token'' on any machine).
- ''paste-token'' accepts token string from elsewhere or auto-generated.