--- summary: "CLI reference for `openclaw models` (status/list/set/scan, aliases, fallbacks, shared auth, personal accounts)" read_when: - You want to change default models or view provider auth status - You want to scan available models/providers and debug auth profiles - You want to sign in to or select a personal model account on a shared Gateway title: "Models" --- # `openclaw models` Model discovery, scanning, and configuration (default model, fallbacks, auth profiles). Related: - Providers + models: [Models](/providers/models) - Model selection concepts + `/models` slash command: [Models concept](/concepts/models) - Provider auth setup: [Getting started](/start/getting-started) ## Common commands ```bash openclaw models --json openclaw models status openclaw models list openclaw models refresh openclaw models set openclaw models set-image openclaw models scan ``` `status`, `list`, and `auth` subcommands accept `--agent ` to target a configured agent. Without it, model inspection uses `agents.defaults.systemAgent.agentId` when configured, otherwise the sole configured agent. Auth mutations require `--agent ` when multiple agents are configured. For `models status`, `OPENCLAW_AGENT_DIR` overrides the inspected auth directory when `--agent` is omitted. A matching configured `agentDir` retains that agent's ownership during credential refresh. An explicit `--agent ` takes precedence over the environment override. `fallbacks`/`image-fallbacks` manage global defaults. `set`, `set-image`, `scan`, `refresh`, and `aliases` also operate globally and reject `--agent`. `models set` and `models set-image` require the provider to be declared by an installed plugin or configured under `models.providers`. An unknown provider exits nonzero without changing config. If the provider is known but the model is absent from the local catalog, the command saves the selection and prints a warning because newly released and self-hosted models may not be cataloged yet. Writing `agents.defaults.model` with [`openclaw config set`](/cli/config#values) is stricter than `models set`: it rejects a model reference it cannot resolve instead of warning. That check is text-model only; `config set` does not validate `agents.defaults.imageModel` at all, so it is not the stricter path for the `set-image` setting. `openclaw doctor --json` reports configured unknown providers; add `--severity-min info` to also see active models that the local catalog cannot confirm. Default-model, alias, and fallback changes resolve provider-owned model aliases using the current plugin configuration. When stored entries resolve to the selected model, their settings move to its canonical key; existing canonical settings take precedence. Adding an alias replaces the model's previous alias. If config changes during that preparation, the command rejects the write; rerun it against the updated config. ### Status Bare `openclaw models` is equivalent to `openclaw models status`. `openclaw models --json` returns the same object as `openclaw models status --json`. `openclaw models status` shows the resolved default/fallbacks plus an auth overview. Active profile cooldowns appear under **Unavailable auth profiles** with the stored reason and recovery action; JSON output exposes the same data in `auth.unusableProfiles`. For plugin-owned agent runtimes such as Codex, status also checks whether the owning plugin is enabled and passed startup payload verification. A route with valid credentials but an unavailable runtime reports `status: unavailable` instead of `usable`; JSON output includes separate `authStatus`, `runtimeStatus`, and bounded runtime diagnostics. 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, OpenAI, MiniMax, SuperGrok via xAI OAuth, 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. Use an explicit agent when diagnosing that agent's selection: ```bash openclaw models list --agent openclaw models status --agent openclaw models status --agent --json --check ``` The list shows model inventory. Status explains the configured default, fallbacks, and authentication for their routes. It does not inspect a chat session's model override; use [`/model status`](/concepts/models#model-in-chat) in that session. #### Read status correctly These sections answer different questions: | Output | Meaning | | ------------------------------------------------ | ----------------------------------------------------------------------------------------- | | **Auth overview** / `auth.providers` | Credential sources found in the environment, provider config, or auth store. | | **OAuth/token status** / `auth.oauth` | Stored profile health and expiry. The JSON object also includes API-key profiles. | | **Model route issues** / `auth.modelRouteIssues` | Incompatible routes, missing route credentials, or readiness that could not be confirmed. | | **Runtime auth** / `auth.runtimeAuthRoutes` | Authentication and runtime availability for routes that use a separate agent runtime. | A stored profile or `static` health entry does not prove that its credential can be used now. For example, a stored `file` or `exec` SecretRef (a reference to a secret) can appear in the overview while its route remains `indeterminate`. That means readiness could not be confirmed in this command path; it does not mean the provider rejected the credential. Inspect the route diagnostic and the configured secret source before replacing credentials. Status without `--probe` is not a model-call test. It can still resolve targeted config secrets and inspect provider-owned auth state. Use `--probe` only when you intend to make the live requests described below. With `--check`, exit codes are: - `0`: no configured-route auth or runtime issue was found, and no selected credential is expiring. This does not prove that a model request will succeed. - `1`: a route has missing or expired auth, an incompatible route, an unavailable runtime, or indeterminate readiness. - `2`: a selected credential is expiring, with no condition that requires exit code `1`. Command failures, such as failure to resolve a required config secret, also exit nonzero. In JSON mode, these can return a command error instead of the status object; check the process exit code as well as the output. Non-secret placeholders can appear as `marker()`, such as `secretref-managed` or an environment variable name. These labels describe the credential source; they are not the resolved secret. Options: | Flag | Effect | | ------------------------- | ------------------------------------------------------------------------------------------------------------- | | `--json` | JSON output; auth-profile, provider, and startup diagnostics go to stderr so stdout stays pipeable into `jq`. | | `--plain` | Plain text output. | | `--check` | Return the auth/runtime check exit code described above, including `1` for indeterminate readiness. | | `--probe` | Live probe of configured auth profiles. Real requests; may consume tokens and trigger rate limits. | | `--probe-provider ` | Probe one provider only. | | `--probe-profile ` | Probe specific auth profile ids (repeat or comma-separated). | | `--probe-timeout ` | Per-probe timeout. | | `--probe-concurrency ` | Concurrent probes. | | `--probe-max-tokens ` | Probe max tokens (best effort). | | `--agent ` | Configured agent id; overrides `OPENCLAW_AGENT_DIR`. | `--probe-timeout` requires a positive number; `--probe-concurrency` and `--probe-max-tokens` require positive integers. Omit these options to use their defaults (`8000`, `2`, and `8`, respectively); explicitly empty values are rejected. Probe rows can come from auth profiles, env credentials, or `models.json`. Probe status buckets: `ok`, `auth`, `rate_limit`, `billing`, `timeout`, `format`, `unknown`, `no_model`. Direct `models status --probe` runs create temporary internal sessions in the selected agent's canonical database, so the command requires exclusive ownership of the configured state directory. Stop a running Gateway with `openclaw gateway stop` before probing. Probe results can be reported before slow cleanup finishes. Temporary auth directories, internal sessions, and the state lock remain held until accepted work and cleanup settle, including after interruption. Cleanup failures are reported; a timeout does not certify that resources have closed. Probe detail/reason codes to expect when a probe never reaches a model call: - `excluded_by_auth_order`: a stored profile exists, but explicit `auth.order.` omitted it, so probe reports the exclusion instead of trying it. - `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`: profile is present but not eligible or resolvable. - `ineligible_profile`: profile is incompatible with provider config for another reason. - `no_model`: provider auth exists, but OpenClaw could not resolve a probeable model candidate for that provider. For OpenAI ChatGPT/Codex OAuth troubleshooting, `openclaw models status`, `openclaw models auth list --provider openai`, and `openclaw config get agents.defaults.model --json` are the quickest way to confirm whether an agent has a usable `openai` OAuth profile for `openai/*` through the native Codex runtime. See [OpenAI provider setup](/providers/openai/setup#check-and-recover-codex-oauth-routing). ### List `openclaw models list` reads published model inventory. It does not start model provider discovery or rewrite `models.json`. This also applies to `--all` and `--provider `. ```bash openclaw models list --agent openclaw models list --agent --provider --json openclaw models list --agent --refresh ``` When a local Gateway is running, or a remote Gateway is selected by configuration or environment, the command reads that Gateway's catalog. `--agent` selects an agent on that Gateway. Provider filtering, model visibility and availability use the Gateway's captured config and auth facts. The command does not resolve local model-provider secrets for that request. A selected Gateway must advertise `published-model-catalog`. If it does not, update or restart it and retry. Connection, authorization and capability errors are reported directly; they do not switch the command to a different local list. Without a running local Gateway or an explicit Gateway target, the command identifies that it is showing the local cached catalog. This fallback can prepare configured and static facts and resolve its configured authentication, but starts model discovery only when `--refresh` is supplied. Use `--refresh` to acquire provider inventory before listing. A failed refresh warns while showing available published rows. Successful empty acquisition stays empty; it does not restore the old discovered rows. If the published owner is not ready, retry after Gateway startup or the current refresh finishes. Options: `--all` (full published catalog), `--refresh` (provider discovery), `--local` (local endpoints), `--provider `, `--agent `, `--json`, and `--plain`. A provider filter reads the full published inventory for that provider, so it does not require `--all`. Notes: - The `Auth` column uses prepared credential and runtime evidence. A separate API key does not prove a native CLI login. Unknown readiness stays unknown, and catalog metadata does not prove that a model request will succeed. See [Read status correctly](/cli/models#read-status-correctly). - A provider-level `models.providers..baseUrl` outside the plugin’s declared native endpoints excludes its implicit catalog rows, including cached discovery. Add the models supported by your proxy to `models.providers..models`; explicitly authored rows, names, defaults, and aliases remain intact. A model-level URL override alone does not exclude the provider catalog. - Static catalog rows can remain visible without authentication. Listing them does not grant permission to select a restricted model or change `modelPolicy.allow`. - In merge mode, refreshing generated catalogs preserves manual root models, including models whose provider also has a generated catalog. Explicit replace mode keeps its existing replacement behavior. - For plugins that load only when needed (`activation.onStartup: false`), an eligible provider in the cached catalog needs current profile, environment, or provider-config authentication before the catalog contributes implicit rows. Credentials retained only inside a generated catalog do not qualify. Explicit model declarations remain visible. - `Ctx` shows `contextTokens/contextWindow` when a runtime cap differs from the native context window. JSON retains `contextTokens` when provided. - `Input` and `Ctx` use the selected physical route plus explicit configured logical overrides. Unresolved route metadata stays unknown instead of borrowing another route's capabilities. - Configured model IDs retain case. For example, `Reader` and `reader` remain distinct. Provider-owned aliases still apply, and configured aliases remain in the table tags and JSON output. - `--provider` takes a provider ID, such as `moonshot`, rather than a picker label such as `Moonshot AI`. - Model refs split on the first `/`. Include the provider prefix when the model ID contains `/`, for example `openrouter/moonshotai/kimi-k2`. Provider discovery through `models list --refresh` is separate from the hosted metadata download performed by `models refresh`, described below. See the [Gateway catalog request](/gateway/protocol/operator-methods#models-list-views) for the wire controls. ### Refresh the hosted catalog `openclaw models refresh [--json]` checks the hosted metadata catalog. It does not sign in to providers, test credentials, or activate downloaded rows in a running Gateway. It rejects `--agent` because the hosted catalog is global. Restart the Gateway to use downloaded updates. The Gateway reports when a checked catalog needs a restart, including an update downloaded by another process. A successful refresh result describes the download, not live activation. If `models.catalogRefresh.enabled` is `false`, the command reports that refresh is disabled. See [Hosted catalog updates](/concepts/models#hosted-catalog-updates) for the update lifecycle. The public change history is in [`openclaw/catalog`](https://github.com/openclaw/catalog). ### Set default / image model ```bash openclaw models set openclaw models set-image ``` `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. If you omit the provider when selecting a model, OpenClaw tries a configured alias, then a unique configured-provider match for that exact model ID, and finally the configured default provider with a deprecation warning. If that provider no longer exposes the configured default, the first configured provider/model is used. ### 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 ` - `--max-age-days ` - `--provider ` - `--max-candidates ` - `--timeout ` (catalog request and per-probe timeout) - `--concurrency ` - `--yes` - `--no-input` - `--set-default` - `--set-image` - `--json` Numeric scan options reject empty and whitespace-only values. Omit a flag to retain its default behavior. `--set-default` and `--set-image` require live probes; metadata-only scan results are informational and are not applied to config. ## Aliases ```bash openclaw models aliases list [--json] [--plain] openclaw models aliases add openclaw models aliases remove ``` Aliases are stored per model entry as `agents.defaults.models..alias`. `add` resolves `` to a canonical provider/model key first, so aliasing an alias repoints it rather than chaining. Adding an alias does not change `agents.defaults.modelPolicy.allow` or restrict model overrides. ## Fallbacks ```bash openclaw models fallbacks list [--json] [--plain] openclaw models fallbacks add openclaw models fallbacks remove openclaw models fallbacks clear ``` Manages `agents.defaults.model.fallbacks`. `openclaw models image-fallbacks list|add|remove|clear` manages the parallel `agents.defaults.imageModel.fallbacks` list with the same subcommand shape. ## Personal model accounts Use `models accounts` for accounts owned by your signed-in person on the selected Gateway. The CLI and **Settings → Profile → Connected accounts** use the same Gateway account store, including when the server is shared. | Scope | Command | Where the credential belongs | | -------------- | -------------------------------------------------- | ------------------------------------------------------------------- | | Personal | `models accounts login [provider]` | Your verified profile on the selected Gateway, which may be remote. | | System / agent | `models auth login --provider [--agent ]` | The OpenClaw installation on the machine running the command. | To configure system/agent credentials for a remote server, run `models auth` on that server with its OpenClaw state/config. Configuring a remote Gateway URL on your laptop does not make `models auth` write to the server. ```bash openclaw models accounts list openclaw models accounts login openclaw models accounts login anthropic --method api-key openclaw models accounts login openai --method device-code openclaw models accounts login xai --method api-key openclaw models accounts use openclaw models accounts clear-default ``` Every account command shows **Gateway**, **Person**, and **Scope: Personal** before accessing accounts or asking for provider credentials. This context goes to stderr so `--json` output stays pipeable. The person is the Gateway's saved, verified profile, not your operating-system username or an unsaved display-name edit. Gateway access and provider sign-in are separate. Account ownership follows the profile assigned by the Gateway on this connection. Single-user Control UI connections can use the durable **Owner** profile, but short-lived CLI connections are not assigned that profile automatically. The personal-account CLI therefore needs an identity-bearing endpoint, even when the local Control UI already shows **Owner**. For separate people on a shared server, use its identity-bearing WebSocket endpoint, such as [Tailscale Serve](/gateway/tailscale#tailscale-identity-headers-serve-only) or a [trusted proxy](/gateway/trusted-proxy-auth). Approve device pairing separately if requested: pairing grants device access, not a distinct person's identity. Supplying shared Gateway token/password credentials takes precedence over Tailscale identity authentication. A browser sign-in does not transfer its identity to the CLI. For an identity-aware edge, follow [remote edge authentication](/gateway/remote#gateway-behind-an-identity-aware-proxy). If no person is identified, the command stops before provider sign-in and explains how to use an identity-bearing endpoint. It does not infer ownership or change Gateway authentication. These commands do not accept `--agent` or an owner id, and they do not modify local shared auth stores or model config. The top-level `openclaw connect` command enrolls a node; it is not a personal-account login. `list` needs `operator.read` and returns one page of at most 50 saved accounts: id, provider, friendly label, auth type, and whether each is the new-session default. It never returns credentials. Use `--json` for structured output and `list --cursor ` for the next page. `login`, `use`, and `clear-default` need `operator.write`. `login` requires an interactive terminal and offers the same provider and sign-in methods as **Add account** in the Control UI. Omit the provider to choose from the Gateway's catalog; use `--method ` to select a method directly. The catalog includes only methods enabled for personal accounts by their provider plugin, not every system/agent setup method. Anthropic uses an API key for personal setup, not a Claude subscription token. OpenAI offers API key, browser sign-in, and device-code methods; Grok (`xai`) offers API key and device sign-in. Follow the steps shown by the selected Gateway. Credentials and authorization codes go into protected inputs, never command arguments or chat. During browser sign-in, the CLI keeps checking for completion even while a redirect prompt is open. Keep the command running until it reports a terminal result. Ctrl-C cancels that exact sign-in attempt and waits for the Gateway's acknowledgment; a closed connection must start a fresh attempt. Saving an account does not by itself prove that a model request will succeed. `use` selects an already-saved account for new sessions without signing in again. `clear-default` removes only the personal default for that provider: it keeps saved credentials and existing session selections. Neither operation revokes provider access. See [Per-person model accounts](/concepts/multi-user#per-person-model-accounts) for collaborator, fork, and failover behavior. All account subcommands accept `--url `, `--port `, `--token-file `, `--password-file `, `--timeout ` (default `30000`), and `--json`. The token/password files authenticate the **Gateway**, not the provider, and do not establish a personal identity for this CLI. An explicit `--url` can use an identity-bearing endpoint without supplying a shared token. It does not send ambient or configured shared credentials to the override; configured edge credentials remain bound to their own endpoint. Flags may precede or follow the leaf command: ```bash openclaw models accounts --timeout 45000 list --json openclaw models accounts list --timeout 45000 --json ``` ## Auth profiles These commands manage **System / agent** credentials, not personal Gateway accounts. Before provider sign-in, `models auth login` shows the selected agent and that it is operating on the machine running OpenClaw. Before a `models auth` command changes the local auth store, OpenClaw compares the selected CLI state/config paths with the local Gateway or its installed service. A proven mismatch stops before the write. A remote Gateway or an authenticated path that cannot be verified produces a warning instead. ```bash openclaw models auth add openclaw models auth list [--provider ] [--json] openclaw models auth login --provider [--agent ] openclaw models auth login --provider openai --profile-id openai:work openclaw models auth login-github-copilot openclaw models auth logout [--yes] openclaw models auth paste-api-key --provider openclaw models auth setup-token --provider openclaw models auth paste-token --provider openclaw models auth order get --provider openclaw models auth order set --provider openclaw models auth order clear --provider ``` `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 list` lists saved auth profiles for the selected agent without printing token, API-key, or OAuth secret material. Active cooldown and disable entries include their reason and recovery action. Legacy Gemini CLI OAuth cooldowns direct you to the supported Google AI Studio API-key setup instead of offering an unavailable Gemini CLI login flow. Use `--provider ` to filter to one provider, such as `openai`, and `--json` for scripting. `models auth login` runs a provider plugin's auth flow (OAuth/API key). Use `openclaw plugins list` to see which providers are installed. `login` accepts `--profile-id ` for providers that support named profiles during login (use this to keep multiple logins for the same provider separate), `--method ` to pick a specific auth method, `--device-code` as a shortcut for `--method device-code`, `--set-default` to apply the provider's recommended default model, and `--force` to remove existing profiles for that provider first (use when a cached OAuth profile is stuck or you want to switch accounts). After credentials are saved, an existing model restriction can prompt **Show all <Provider> models** or **Keep current restrictions**. Only the first choice adds that provider's wildcard to the current restriction. Credentials stay saved either way. The CLI, private-chat login, and Control UI use the same choice. No prompt appears when the provider is already unrestricted. If restrictions change during sign-in, OpenClaw preserves the newer settings and asks you to choose model access again. The CLI reports saved model access separately from confirmed Gateway application. If application is not confirmed, run `openclaw gateway restart` to apply the saved policy to the running Gateway. This is required when automatic config reload is disabled. Without `--set-default`, login preserves the current default, including an unset default, and keeps unrelated configuration edits made while login is running. If credentials are saved but provider settings cannot be applied, the error reports the saved credentials separately. Auth changes request a refresh from the running local Gateway; a refresh failure does not undo the saved change, and the command reports how to apply it. With an older Gateway, the CLI tries its legacy auth-status refresh. This cannot confirm that the saved change is active; follow the restart guidance. This fallback applies to auth changes, not to `models list`. For the shared-main agent, `--force` clears the provider's shared credentials and main-agent local overrides, including their order and health state. For another agent it clears only that agent's local profiles, leaving shared credentials unchanged. A busy auth store stops the command before login starts; close other OpenClaw commands using the same state directory and retry. SQLite lock diagnostics can name either the shared state database or an agent database, so checking only the legacy auth file for open handles does not rule out contention. `models auth logout ` removes one saved auth profile from the selected agent auth store. Use the profile id shown by `models auth list`. It also drops that profile from `auth.profiles` and from every `auth.order` list in your config, so no stale reference is left behind, and it deletes an `auth.order.` entry that would otherwise be emptied (an authored empty order means "select no profiles" and would disable the provider). It prompts for confirmation on a TTY; pass `--yes` for scripts and agents. Provider key references are cleared before the credential is removed. Model defaults and connection settings stay unchanged. Logout refuses when the profile is not in the store. `models auth login-github-copilot` is a shortcut for `models auth login --provider github-copilot --method device` (GitHub device flow); it accepts `--yes` to overwrite an existing profile without prompting. Use either `openclaw models auth --agent ` or `openclaw models auth --agent ` to target a specific configured agent store. Both forms are supported by `add`, `list`, `login`, `logout`, `paste-api-key`, `setup-token`, `paste-token`, `login-github-copilot`, and `order get`/`set`/`clear`. For OpenAI models, `--provider openai` defaults to ChatGPT/Codex account login. Use `--method api-key` only when you want to add an OpenAI API-key profile, usually as a backup for Codex subscription limits. Run `openclaw doctor --fix` to migrate older legacy OpenAI Codex prefix auth/profile state to `openai`. Examples: ```bash 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 uses the same credential writer as the Models page. It updates the configured profile or the active saved key, or creates `:manual` when neither exists. Use `--profile-id` to update a named profile or add a backup without changing the active provider connection. A configured provider stores the profile reference, while key material stays in the auth store. Saved changes report any Gateway refresh failure with a recovery step. 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 `: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 ` 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.` 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](/cli) - [Model selection](/concepts/model-providers) - [Model failover](/concepts/model-failover) - [`openclaw promos`](/cli/promos) — list and claim promotional model offers