How to change the model in OpenClaw (and why a switch might not stick)
/model with -s, -a, or -g scopes since 2.0, the modelPolicy.allow allowlist that replaced the old models map, and the traps: pending runs, wrong scope, and 7.x's stale-channel capture.
Type /model in any chat to see the current model, and /model <name> to change it. An alias, a provider/model ref, or just a provider name (fuzzy-matched) all work. Since OpenClaw 2.0 the command has explicit scopes: -s changes only the current session, -a the selected agent’s default, -g the shared global default. A bare /model <name> from the owner updates the configured default, not just the session. If a pick is refused with “not allowed by” agents.defaults.modelPolicy.allow, that config key is the allowlist to edit. And after any switch, trust what the next reply actually reports, not the acknowledgement.
The /model command, scope by scope
The full shape is /model [name|default|list|status] [-s|-a|-g], sent as a chat message to your agent on any channel. What each scope does:
-s / --session changes only the conversation you are in. Other sessions and the configured defaults are untouched. /model default -s clears the session’s selection and drops it back to the configured default.
-a / --agent changes this session and requests an update to the selected agent’s configured model (agents.entries.<agent>.model).
-g / --global changes this session and requests an update to the shared default (agents.defaults.model) that every agent without its own setting inherits.
The subtlety worth knowing: without a flag, what happens depends on who is asking. From the owner or an admin, a bare /model <name> also updates the agent’s existing explicit primary (or the global default if the agent has none), so an owner’s casual switch is persistent by default. From anyone else, bare commands stay session-only, and explicit -a or -g requests are rejected. If you want bare commands to default to a different scope, set agents.defaults.modelSelectionScope to "session", "agent" or "global".
Two neighbours do related jobs: /new <model> starts a fresh session already on that model, and /think <level> sets the reasoning-effort override for the session, a separate lever from which model is answering.
Where restrictions live in 2.0
OpenClaw 2.0 split two things older versions kept in one map. agents.defaults.models now holds aliases and per-model settings only. Adding an entry there no longer limits anything. Restrictions live in agents.defaults.modelPolicy.allow: empty or absent means you can select any provider/model you can authenticate, even one not in the picker’s catalog; non-empty means it is an allowlist enforced across /model, session overrides, and --model flags, with exact refs or trailing wildcards like openrouter/*. Per-agent policies (agents.entries.*.modelPolicy.allow) override the default.
Which allowlist you have depends on how your install got to 2.0. A fresh install has none. A migrated install keeps whatever its old models map restricted, because the migration deliberately avoids silently opening access. So if your upgraded agent refuses a model with “not allowed by agents.defaults.modelPolicy.allow”, that is July’s restriction wearing its new name, and the fix is to extend or remove the list.
Changing the default outside chat
The CLI equivalent is openclaw models set <provider/model> for the default and openclaw models status to read the current state. The 2.0 Control UI also grew a model picker in the chat composer and guided provider setup, and model lists are now discovered live from providers rather than shipped as a built-in snapshot, so a model released yesterday appears without an OpenClaw update.
Why a switch might not stick
A run was in progress. If the agent is mid-task when you switch, the change is marked pending and “applied at the next clean retry point”, so the reply you are watching may finish on the old model and the next one arrive on the new.
The scope was not the one you meant. A session-scoped switch changes one conversation and nothing else, so if you wanted the default to move for every other session, the change belonged in -a or -g. It cuts the other way too: a session pick lasts until you clear it with /model default -s, and on a Telegram chat /new starts a fresh conversation and keeps the pick (watched on a 2026.9.1 install in September 2026). A conversation carrying its own pick also ignores any later change to the default, whoever made it, until that pick is cleared.
The allowlist refused it. The refusal is explicit in 2.0, and a failed user-selected model now fails visibly rather than silently falling through to a fallback, a deliberate change from older behavior.
On 2026.7.x: the config was live, but the channel wasn’t reading it. If you are still on a 7.x install, there is a trap we have watched cost real afternoons on our own machines: a running channel serves the configuration it captured when it started, so a config-file change, hand-edited or CLI-written, can be verifiably in place while your live Telegram conversation keeps answering on the old model until the channel restarts. The in-chat /model override is the lever that works immediately there, landing on the next message with no restart.
Trust the run, not the acknowledgement
Whatever path you use, verify from the model’s side. Ask the agent what model produced its last reply, run /model status, or check /status, which reports the runtime actually serving the session. An agent can say “switched!” a turn before the switch applies; the run record is the fact. Which models are worth switching to is its own question. Our model-choice guide covers that side.