clawdbot/docs/concepts/models.md

summary, read_when

summary	read_when
Models CLI: list, set, aliases, fallbacks, scan, status	Adding or modifying models CLI (models list/set/scan/aliases/fallbacks) Changing model fallback behavior or selection UX Updating model scan probes (tools/images)

Models CLI

See /concepts/model-failover for auth profile rotation, cooldowns, and how that interacts with fallbacks.

How model selection works

Clawdbot selects models in this order:

1. Primary model (agent.model.primary or agent.model).
2. Fallbacks in agent.model.fallbacks (in order).
3. Provider auth failover happens inside a provider before moving to the next model.

Related:

• agent.models is the allowlist/catalog of models Clawdbot can use (plus aliases).
• agent.imageModel is used only when the primary model can’t accept images.

Config keys (overview)

• agent.model.primary and agent.model.fallbacks
• agent.imageModel.primary and agent.imageModel.fallbacks
• agent.models (allowlist + aliases + provider params)
• models.providers (custom providers written into models.json)

Model refs are normalized to lowercase. Provider aliases like z.ai/* normalize to zai/*.

CLI commands

clawdbot models list
clawdbot models status
clawdbot models set <provider/model>
clawdbot models set-image <provider/model>

clawdbot models aliases list
clawdbot models aliases add <alias> <provider/model>
clawdbot models aliases remove <alias>

clawdbot models fallbacks list
clawdbot models fallbacks add <provider/model>
clawdbot models fallbacks remove <provider/model>
clawdbot models fallbacks clear

clawdbot models image-fallbacks list
clawdbot models image-fallbacks add <provider/model>
clawdbot models image-fallbacks remove <provider/model>
clawdbot models image-fallbacks clear

clawdbot models (no subcommand) is a shortcut for models status.

models list

Shows configured models by default. Useful flags:

• --all: full catalog
• --local: local providers only
• --provider <name>: filter by provider
• --plain: one model per line
• --json: machine‑readable output

models status

Shows the resolved primary model, fallbacks, image model, and an auth overview of configured providers. It also surfaces OAuth expiry status for profiles found in the auth store (warns within 24h by default). --plain prints only the resolved primary model. OAuth status is always shown (and included in --json output). If a configured provider has no credentials, models status prints a Missing auth section. JSON includes auth.oauth (warn window + profiles) and auth.providers (effective auth per provider). Use --check for automation (exit 1 when missing/expired, 2 when expiring).

Scanning (OpenRouter free models)

clawdbot models scan inspects OpenRouter’s free model catalog and can optionally probe models for tool and image support.

Key flags:

• --no-probe: skip live probes (metadata only)
• --min-params <b>: minimum parameter size (billions)
• --max-age-days <days>: skip older models
• --provider <name>: provider prefix filter
• --max-candidates <n>: fallback list size
• --set-default: set agent.model.primary to the first selection
• --set-image: set agent.imageModel.primary to the first image selection

Probing requires an OpenRouter API key (from auth profiles or OPENROUTER_API_KEY). Without a key, use --no-probe to list candidates only.

Scan results are ranked by:

1. Image support
2. Tool latency
3. Context size
4. Parameter count

Input

• OpenRouter /models list (filter :free)
• Requires OpenRouter API key from auth profiles or OPENROUTER_API_KEY (see /environment)
• Optional filters: --max-age-days, --min-params, --provider, --max-candidates
• Probe controls: --timeout, --concurrency

When run in a TTY, you can select fallbacks interactively. In non‑interactive mode, pass --yes to accept defaults.

Models registry (models.json)

Custom providers in models.providers are written into models.json under the agent directory (default ~/.clawdbot/agents/<agentId>/models.json). This file is merged by default unless models.mode is set to replace.