docs/concepts/models.md
A model ref (provider/model) chooses a provider and model. It does not usually choose the low-level agent runtime. OpenAI is the main exception: official openai/gpt-* agent refs run through the Codex app-server runtime by default. Subscription Copilot refs (github-copilot/*) can be opted into the external GitHub Copilot agent runtime plugin, but that path is always explicit (never selected by auto). Runtime overrides belong on provider/model policy, not on the whole agent or session. In Codex runtime mode, openai/gpt-* does not imply API-key billing; auth can come from a Codex account or an openai OAuth profile. See Agent runtimes and GitHub Copilot agent runtime.
Related model-config surfaces:
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.agents.list[].model (plus bindings) overrides agents.defaults.model — see Multi-agent routing.Full key reference, defaults, and JSON5 examples: Configuration reference.
The same provider/model behaves differently depending on where it came from:
| Source | Behavior |
|---|---|
Configured default (agents.defaults.model.primary, per-agent primary) | Normal starting point; uses agents.defaults.model.fallbacks. |
| Auto fallback | Temporary recovery state, stored as modelOverrideSource: "auto". OpenClaw periodically reprobes the original primary, clears the auto selection on recovery, and announces fallback/recovery transitions once per state change. |
| User session selection | Exact and strict. /model, the model picker, session_status(model=...), and sessions.patch store modelOverrideSource: "user". If that provider/model becomes unreachable, the run fails visibly instead of falling through to another configured model. |
Cron --model / payload model | Per-job primary. Still uses configured fallbacks unless the job supplies its own payload fallbacks (fallbacks: [] forces a strict run). |
Other selection rules:
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.models.mode: "replace" by listing only models.providers.*.models instead of the full built-in catalog.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).Full mechanics: Model failover.
openclaw onboard
Sets up model and auth for common providers without hand-editing config, including OpenAI Codex subscription OAuth and Anthropic (API key or Claude CLI reuse).
With no primary model configured, fresh OpenAI API-key setup selects
openai/gpt-5.6; the bare direct-API id resolves to the Sol tier. Fresh
ChatGPT/Codex OAuth setup selects the exact openai/gpt-5.6-sol catalog ref.
Reauthentication preserves an existing explicit primary model, including
openai/gpt-5.5. If GPT-5.6 is unavailable to the account, select
openai/gpt-5.5 explicitly; OpenClaw does not silently downgrade it.
If agents.defaults.models is set, it becomes the allowlist for /model and session overrides. Selecting a model outside that allowlist returns, before any normal reply is generated:
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
Fix it by adding the model to agents.defaults.models, clearing the allowlist entirely (remove the key), or picking a model from /model list. If 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 local/GGUF models, the allowlist needs the full provider-prefixed ref, for example ollama/gemma4:26b or lmstudio/Gemma4-26b-a4-it-gguf — check openclaw models list --provider <provider> for the exact string. Bare filenames or display names are not enough once the allowlist is active.
To limit providers without listing every model, use provider/* wildcard entries:
{
agents: {
defaults: {
models: {
"openai/*": {},
"vllm/*": {},
},
},
},
}
/model, /models, and model pickers then show the discovered catalog for those providers only, and new models can appear without editing the allowlist. Mix exact provider/model entries with provider/* entries to pull in one specific model from another provider.
Example allowlist with aliases:
{
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
openclaw config set refuses plain-object assignments to agents.defaults.models, models.providers, or models.providers.<id>.models when they would drop existing entries; use --replace only when the new value should become the complete target value. Interactive provider setup and openclaw configure --section model already merge provider-scoped selections into the allowlist, so adding a provider does not drop unrelated entries; configure preserves an existing agents.defaults.model.primary. Explicit commands like openclaw models auth login --provider <id> --set-default and openclaw models set <model> still replace the primary.
</Accordion>
/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./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./; 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.Full command behavior and config: Slash commands.
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
openclaw models with no subcommand is a shortcut for models status, which also surfaces OAuth expiry for auth-store profiles (warns within 24h by default). Full flags, JSON shapes, and auth-profile subcommands: Models CLI reference.
Results rank by: image support, then tool latency, then context size, then parameter count. In a TTY, probed results prompt an interactive fallback selection; non-interactive mode needs `--yes` to accept defaults.
models.json)Custom providers configured under models.providers are written into models.json under the agent directory (default ~/.openclaw/agents/<agentId>/agent/models.json). Provider-plugin catalogs are stored separately as generated plugin-owned catalog shards and load automatically. This file is merged with config by default; set models.mode: "replace" to use only your configured providers.
- A non-empty `baseUrl` already present in the agent `models.json` wins.
- A non-empty `apiKey` in `models.json` wins only when that provider is not SecretRef-managed in the current config/auth-profile context.
- SecretRef-managed `apiKey` values refresh from source markers instead of persisting resolved secrets: the env variable name for env refs, `secretref-managed` for file/exec refs.
- SecretRef-managed header values refresh the same way, using `secretref-env:ENV_VAR_NAME` for env refs.
- Empty or missing `apiKey`/`baseUrl` in `models.json` fall back to config `models.providers`.
- Other provider fields refresh from config and normalized catalog data.
Marker persistence is source-authoritative: OpenClaw writes markers from the active source config snapshot (pre-resolution), not from resolved runtime secret values, whenever it regenerates models.json — including command-driven paths like openclaw agent.