Models CLI

​

Selection order

• agents.defaults.models is the allowlist/catalog of models OpenClaw can use, plus aliases. Use provider/* entries to allow every discovered model from a provider without listing each one.
• agents.defaults.utilityModel is an optional lower-cost model for short internal tasks such as generated dashboard session titles and supported channel thread/topic titles. Per-agent agents.list[].utilityModel overrides it. When unset, these tasks use the agent’s primary model. Utility tasks are separate model calls and may send bounded task content to the selected model provider.
• agents.defaults.imageModel is used only when the primary model cannot accept images.
• agents.defaults.pdfModel is used by the pdf tool. If unset, the tool falls back to imageModel, then the resolved session/default model.
• agents.defaults.imageGenerationModel, musicGenerationModel, and videoGenerationModel back the shared media-generation tools. If unset, each tool infers an auth-backed provider default: current default provider first, then the remaining registered providers for that capability in provider-id order. Set agents.defaults.mediaGenerationAutoProviderFallback: false to disable that cross-provider inference while keeping explicit fallbacks.
• Per-agent agents.list[].model (plus bindings) overrides agents.defaults.model — see Multi-agent routing.

​

Selection source and fallback strictness

• Changing agents.defaults.model.primary does not rewrite existing session pins. If status reports This session is pinned to X; config primary Y will apply to new/unpinned sessions., run /model default to clear the pin.
• CLI default-model and allowlist pickers respect models.mode: "replace" by listing only models.providers.*.models instead of the full built-in catalog.
• The Control UI model picker asks the Gateway for its configured model view: agents.defaults.models when set (including provider/* wildcard entries), otherwise models.providers.*.models plus providers with usable auth. The full built-in catalog is reserved for explicit browse views (models.list with view: "all", or openclaw models list --all).

​

Quick model policy

• Set your primary to the strongest latest-generation model available to you.
• Use fallbacks for cost/latency-sensitive tasks and lower-stakes chat.
• For tool-enabled agents or untrusted inputs, avoid older/weaker model tiers.

​

Onboarding

openclaw onboard

​

”Model is not allowed” (and why replies stop)

Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

{
  agents: {
    defaults: {
      models: {
        "openai/*": {},
        "vllm/*": {},
      },
    },
  },
}

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4-6" },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
      },
    },
  },
}

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge

​

/model in chat

/model
/model list
/model 3
/model openai/gpt-5.4
/model default
/model status

• /model and /model list show a compact numbered picker (model family + available providers); /model <#> selects from it. On Discord this opens provider/model dropdowns with a Submit step; on Telegram, picker selections are session-scoped and never rewrite the agent’s persistent default in openclaw.json. /models add is deprecated and returns a message instead of registering models from chat.
• /model persists the new session selection immediately. If the agent is idle, the next run uses it right away; if a run is already active, the switch is queued for the next clean retry point (or a later one, if tool activity or reply output already started).
• /model default clears the session selection so it inherits the configured primary again.
• A user-selected /model ref is strict for that session: if it becomes unreachable, the reply fails visibly instead of silently falling back through agents.defaults.model.fallbacks. Configured defaults and cron job primaries still use fallback chains.
• /model status is the detailed view: auth candidates per provider, and (when configured) the provider endpoint baseUrl plus api mode.
• Model refs are parsed by splitting on the first /; type provider/model. If the model ID itself contains / (OpenRouter-style), include the provider prefix, e.g. /model openrouter/moonshotai/kimi-k2. If you omit the provider, OpenClaw tries: (1) alias match, (2) unique configured-provider match for that exact unprefixed model id, (3) the configured default provider (deprecated fallback) — and if that provider no longer exposes the configured default model, the first configured provider/model instead, to avoid surfacing a stale removed-provider default.
• Model refs are normalized to lowercase; provider IDs are otherwise exact, so use the ID advertised by the plugin.

​

CLI

openclaw models status
openclaw models list
openclaw models set <provider/model>
openclaw models set-image <provider/model>
openclaw models scan
openclaw models aliases list|add|remove
openclaw models fallbacks list|add|remove|clear
openclaw models image-fallbacks list|add|remove|clear
openclaw models auth list|add|login|paste-api-key|paste-token|setup-token|order

​

Models registry (models.json)

​

Related

• Agent runtimes — OpenClaw, Codex, and other agent loop runtimes
• Configuration reference — model config keys
• Image generation — image model configuration
• Model failover — fallback chains
• Model providers — provider routing and auth
• Models CLI reference — full command and flag reference
• Music generation — music model configuration
• Video generation — video model configuration