Use this file to discover all available pages before exploring further.

Models CLI

Model failover

Auth profile rotation, cooldowns, and how that interacts with fallbacks.

Model providers

Quick provider overview and examples.

Agent runtimes

PI, Codex, and other agent loop runtimes.

Configuration reference

Model config keys.

Model refs choose a provider and model. They do not usually choose the low-level agent runtime. For example,

text

openai/gpt-5.5

can run through the normal OpenAI provider path or through the Codex app-server runtime, depending on

text

agents.defaults.agentRuntime.id

. See Agent runtimes.

How model selection works

OpenClaw selects models in this order:

Primary model

`agents.defaults.model.primary` (or `agents.defaults.model`).

Fallbacks

`agents.defaults.model.fallbacks` (in order).

Provider auth failover

Auth failover happens inside a provider before moving to the next model.

Selection source and fallback behavior

The same

text

provider/model

can mean different things depending on where it came from:

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


bash
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)

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

note

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

Provider configuration examples (including OpenCode) live in OpenCode.

Safe allowlist edits

Use additive writes when updating

text

agents.defaults.models

by hand:


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

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

text

agents.defaults.models

is set, it becomes the allowlist for

text

/model

and for session overrides. When a user selects a model that isn't in that allowlist, OpenClaw returns:


text
Model "provider/model" is not allowed. Use /model to list available models.

warning

This happens **before** a normal reply is generated, so the message can feel like it "didn't respond." The fix is to either:

Add the model to
text
agents.defaults.models
, or
Clear the allowlist (remove
text
agents.defaults.models
), or
Pick a model from
text
/model list
.

For local/GGUF models, store the full provider-prefixed ref in the allowlist, for example

text

ollama/gemma4:26b

text

lmstudio/Gemma4-26b-a4-it-gguf

, or the exact provider/model shown by

text

openclaw models list --provider <provider>

. Bare local filenames or display names are not enough when the allowlist is active.

Example allowlist config:


json5
{
  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 (
text
`/model`
)

You can switch models for the current session without restarting:


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

Full command behavior/config: Slash commands.

CLI commands


bash
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

text

openclaw models

(no subcommand) is a shortcut for

text

models status

text
`models list`

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

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. Local providers only. Filter by provider id, for example `moonshot`. Display labels from interactive pickers are not accepted. One model per line. Machine-readable output.

text
`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).

text

--plain

prints only the resolved primary model.

note

Auth choice is provider/account dependent. For always-on gateway hosts, API keys are usually the most predictable; Claude CLI reuse and existing Anthropic OAuth/token profiles are also supported.

Example (Claude CLI):


bash
claude auth login
openclaw models status

Scanning (OpenRouter free models)

text

openclaw models scan

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

Skip live probes (metadata only). Minimum parameter size (billions). Skip older models. Provider prefix filter. Fallback list size. Set `agents.defaults.model.primary` to the first selection. Set `agents.defaults.imageModel.primary` to the first image selection.

note

The OpenRouter `/models` catalog is public, so metadata-only scans can list free candidates without a key. Probing and inference still require an OpenRouter API key (from auth profiles or `OPENROUTER_API_KEY`). If no key is available, `openclaw models scan` falls back to metadata-only output and leaves config unchanged. Use `--no-probe` to request metadata-only mode explicitly.

Scan results are ranked by:

Image support
Tool latency
Context size
Parameter count

Input:

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

When live probes run in a TTY, you can select fallbacks interactively. In non-interactive mode, pass

text

--yes

to accept defaults. Metadata-only results are informational;

text

--set-default

and

text

--set-image

require live probes so OpenClaw does not configure an unusable keyless OpenRouter model.

Models registry (
text
`models.json`
)

Custom providers in

text

models.providers

are written into

text

models.json

under the agent directory (default

text

~/.openclaw/agents/<agentId>/agent/models.json

). This file is merged by default unless

text

models.mode

is set to

text

replace

note

Marker persistence is source-authoritative: OpenClaw writes markers from the active source config snapshot (pre-resolution), not from resolved runtime secret values. This applies whenever OpenClaw regenerates `models.json`, including command-driven paths like `openclaw agent`.

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

OpenClaw Docs

Models CLI

Model failover

Model providers

Agent runtimes

Configuration reference

How model selection works

Primary model

Fallbacks

Provider auth failover

Selection source and fallback behavior

Quick model policy

Onboarding (recommended)

Config keys (overview)

note

Safe allowlist edits

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

warning

Switching models in chat (
text
`/model`
)

CLI commands

text
`models list`

text
`models status`

note

Scanning (OpenRouter free models)

note

Models registry (
text
`models.json`
)

note

Related

OpenClaw Docs

Models CLI

Model failover

Model providers

Agent runtimes

Configuration reference

How model selection works

Primary model

Fallbacks

Provider auth failover

Selection source and fallback behavior

Quick model policy

Onboarding (recommended)

Config keys (overview)

note

Safe allowlist edits

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

warning

Switching models in chat (textCopy/model)

CLI commands

textCopymodels list

textCopymodels status

note

Scanning (OpenRouter free models)

note

Models registry (textCopymodels.json)

note

Related

Switching models in chat (
text
`/model`
)

text
`models list`

text
`models status`

Models registry (
text
`models.json`
)