|
|
---
|
|
|
summary: "CLI reference for `openclaw models` (status/list/set/scan, aliases, fallbacks, auth)"
|
|
|
read_when:
|
|
|
- You want to change default models or view provider auth status
|
|
|
- You want to scan available models/providers and debug auth profiles
|
|
|
title: "models"
|
|
|
---
|
|
|
|
|
|
# `openclaw models`
|
|
|
|
|
|
Model discovery, scanning, and configuration (default model, fallbacks, auth profiles).
|
|
|
|
|
|
Related:
|
|
|
|
|
|
- Providers + models: [Models](/providers/models)
|
|
|
- Provider auth setup: [Getting started](/start/getting-started)
|
|
|
|
|
|
## Common commands
|
|
|
|
|
|
```bash
|
|
|
openclaw models status
|
|
|
openclaw models list
|
|
|
openclaw models set <model-or-alias>
|
|
|
openclaw models scan
|
|
|
```
|
|
|
|
|
|
`openclaw models status` shows the resolved default/fallbacks plus an auth overview.
|
|
|
When provider usage snapshots are available, the OAuth/token status section includes
|
|
|
provider usage windows and quota snapshots.
|
|
|
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 inspect a configured agent’s model/auth state. When omitted,
|
|
|
the command uses `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` if set, otherwise the
|
|
|
configured default agent.
|
|
|
|
|
|
Notes:
|
|
|
|
|
|
- `models set <model-or-alias>` accepts `provider/model` or an alias.
|
|
|
- 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 treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID).
|
|
|
- `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.
|
|
|
|
|
|
### `models status`
|
|
|
|
|
|
Options:
|
|
|
|
|
|
- `--json`
|
|
|
- `--plain`
|
|
|
- `--check` (exit 1=expired/missing, 2=expiring)
|
|
|
- `--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>`
|
|
|
- `--agent <id>` (configured agent id; overrides `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
|
|
|
|
|
|
## Aliases + fallbacks
|
|
|
|
|
|
```bash
|
|
|
openclaw models aliases list
|
|
|
openclaw models fallbacks list
|
|
|
```
|
|
|
|
|
|
## Auth profiles
|
|
|
|
|
|
```bash
|
|
|
openclaw models auth add
|
|
|
openclaw models auth login --provider <id>
|
|
|
openclaw models auth setup-token --provider <id>
|
|
|
openclaw models auth paste-token
|
|
|
```
|
|
|
|
|
|
`models auth add` 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.
|
|
|
|
|
|
`models auth login` runs a provider plugin’s auth flow (OAuth/API key). Use
|
|
|
`openclaw plugins list` to see which providers are installed.
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
```bash
|
|
|
openclaw models auth login --provider anthropic --method cli --set-default
|
|
|
openclaw models auth login --provider openai-codex --set-default
|
|
|
```
|
|
|
|
|
|
Notes:
|
|
|
|
|
|
- `login --provider anthropic --method cli --set-default` reuses a local Claude
|
|
|
CLI login and rewrites the main Anthropic default-model path to `claude-cli/...`.
|
|
|
- `setup-token` and `paste-token` remain generic token commands for providers
|
|
|
that expose token auth methods.
|
|
|
- `paste-token` accepts a token string generated elsewhere or from automation.
|
|
|
- Anthropic billing note: Anthropic changed third-party harness billing on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST**. Anthropic says Claude subscription limits no longer cover OpenClaw, and Claude CLI traffic in OpenClaw now requires **Extra Usage** billed separately from the subscription.
|
|
|
- Existing legacy Anthropic token profiles still run if already configured, but Anthropic no longer supports `setup-token` or `paste-token` as a new OpenClaw auth path.
|