Skip to main content

​
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. --plain prints only the resolved primary model.

​
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.