Models CLI

Model refs choose a provider and model. They do not usually choose the low-level agent runtime. For example, openai/gpt-5.5 can run through the normal OpenAI provider path or through the Codex app-server runtime, depending on agents.defaults.agentRuntime.id. In Codex runtime mode, the openai/gpt-* ref does not imply API-key billing; auth can come from a Codex account or openai-codex auth profile. See Agent runtimes.

# How model selection works

OpenClaw selects models in this order:

# Selection source and fallback behavior

The same provider/model can mean different things depending on where it came from:

• Configured defaults (agents.defaults.model.primary and agent-specific primaries) are the normal starting point and use agents.defaults.model.fallbacks.
• Auto fallback selections are temporary recovery state. They are stored with modelOverrideSource: "auto" so later turns can keep using the fallback chain without probing a known-bad primary first.
• User session selections are exact. /model, the model picker, session_status(model=...), and sessions.patch store modelOverrideSource: "user"; if that selected provider/model is unreachable, OpenClaw fails visibly instead of falling through to another configured model.
• Cron --model / payload model is a per-job primary. It still uses configured fallbacks unless the job supplies explicit payload fallbacks (use fallbacks: [] for a strict cron run).
• CLI default-model and allowlist pickers respect models.mode: "replace" by listing explicit models.providers.*.models instead of loading the full built-in catalog.
• The Control UI model picker asks the Gateway for its configured model view: agents.defaults.models when present, otherwise explicit models.providers.*.models plus providers with usable auth. The full built-in catalog is reserved for explicit browse views such as 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 (recommended)

If you don't want to hand-edit config, run onboarding:

openclaw onboard

It can set up model + auth for common providers, including OpenAI Code (Codex) subscription (OAuth) and Anthropic (API key or Claude CLI).

# Config keys (overview)

• agents.defaults.model.primary and agents.defaults.model.fallbacks
• agents.defaults.imageModel.primary and agents.defaults.imageModel.fallbacks
• agents.defaults.pdfModel.primary and agents.defaults.pdfModel.fallbacks
• agents.defaults.imageGenerationModel.primary and agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.videoGenerationModel.primary and agents.defaults.videoGenerationModel.fallbacks
• agents.defaults.models (allowlist + aliases + provider params)
• models.providers (custom providers written into models.json)

# Safe allowlist edits

Use additive writes when updating agents.defaults.models by hand:

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

# "Model is not allowed" (and why replies stop)

If agents.defaults.models is set, it becomes the allowlist for /model and for session overrides. When a user selects a model that isn't in that allowlist, OpenClaw returns:

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

When the rejected command included a runtime override such as /model openai/gpt-5.5 --runtime codex, fix the allowlist first, then retry the same /model ... --runtime ... command. For native Codex execution, the selected model is still openai/gpt-5.5; the codex runtime selects the harness and uses Codex auth separately.

For local/GGUF models, store the full provider-prefixed ref in the allowlist, for example ollama/gemma4:26b, lmstudio/Gemma4-26b-a4-it-gguf, or the exact provider/model shown by openclaw models list --provider <provider>. Bare local filenames or display names are not enough when the allowlist is active.

Example allowlist config:

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

# Switching models in chat (/model)

You can switch models for the current session without restarting:

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

Full command behavior/config: Slash commands.

# CLI commands

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

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

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

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

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

# models list

Shows configured/auth-available models by default. Useful flags:

--allboolean

Full catalog. Includes bundled provider-owned static catalog rows before auth is configured, so discovery-only views can show models that are unavailable until you add matching provider credentials.

--localboolean

Local providers only.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> Filter by provider id, for example moonshot. Display labels from interactive pickers are not accepted.

--plainboolean

One model per line.

--jsonboolean

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.

Example (Claude CLI):

claude auth login
openclaw models status

# Scanning (OpenRouter free models)

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

--no-probeboolean

Skip live probes (metadata only).

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

Set agents.defaults.model.primary to the first selection.

--set-imageboolean

Set agents.defaults.imageModel.primary to the first image selection.

Scan results are ranked by:

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

Input:

• OpenRouter /models list (filter :free)
• Live probes require OpenRouter API key from auth profiles or OPENROUTER_API_KEY (see Environment variables)
• Optional filters: --max-age-days, --min-params, --provider, --max-candidates
• Request/probe controls: --timeout, --concurrency

When live probes run in a TTY, you can select fallbacks interactively. In non-interactive mode, pass --yes to accept defaults. Metadata-only results are informational; --set-default and --set-image require live probes so OpenClaw does not configure an unusable keyless OpenRouter model.

# Models registry (models.json)

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

# Related

• Agent runtimes — PI, 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
• Music generation — music model configuration
• Video generation — video model configuration