You changed the primary model in openclaw.json, restarted the gateway, and your agent is still answering with the old one. Or /status shows deepseek-v4-flash while the config clearly says deepseek-v4-pro, and every new chat keeps picking the cheap model. Nothing is broken. OpenClaw resolves a model on every single turn, and the value in your config file is only one input into that decision.
Three things explain most mismatches: the session is pinned to a model you picked earlier, an automatic fallback is still holding the session, or the model you asked for is not in the allowlist and the selection was rejected. A fourth case looks identical but is not: you are watching a sub-agent, a cron job, or a different agent that has its own model line.
This guide shows the exact resolution order, the commands that reveal which layer is winning, and the fix for each layer. It assumes OpenClaw 2026.x and a standard ~/.openclaw install.
How OpenClaw picks a model (config is only the floor)
Model selection is per run, not per install. At the start of every turn OpenClaw resolves session state first, then walks a fixed precedence list. The first match wins.
- 1. User session selection. A model you picked with
/model, the model picker,session_status(model=...), orsessions.patch. It is stored withmodelOverrideSource: "user"and treated as an exact choice. - 2. Auto fallback override. Written by the runtime when the primary failed and a fallback answered. Stored as
modelOverrideSource: "auto". - 3. Agent primary.
agents.list[].modelfor the agent handling the message. - 4. Global default.
agents.defaults.model.primary, which is whatopenclaw models setwrites.
Then, if the chosen model cannot produce a reply, OpenClaw walks agents.defaults.model.fallbacks in order. Before it leaves a provider, it rotates through that provider’s auth profiles, so a rate limit on one key often never becomes a visible fallback at all.
Two details cause most of the confusion. A user selection is strict: if that model is unreachable, the run fails visibly instead of quietly borrowing a fallback. An agent primary is also strict unless that agent’s model block declares its own fallbacks. So an agent can look correctly configured and still never fail over.

Find the layer that is overriding you
Start with the config view. The first command reads openclaw.json, the auth store, and the model catalog. It does not read session pins, which is exactly why it can disagree with what your agent is doing. The second command shows the resolved model per session, which is where a pin shows up.
Four rows, three different models, one config file. That is normal. Cron jobs, direct chats, sub-agents, and group channels are separate sessions with separate histories and separate overrides. Look at the Model column, not the config default, when you are debugging one specific conversation.
In chat, /status gives you the same answer for the current session on one compact line. When a session is pinned, OpenClaw spells it out: This session is pinned to X; config primary Y will apply to new/unpinned sessions. If you see that sentence, stop editing config. The config is fine. The session is not listening to it.
Fix 1: clear a pinned session model
A user pin survives gateway restarts, config edits, and model catalog refreshes, because it lives in the session store rather than in openclaw.json. It also survives /new and /reset, which clear auto fallback overrides only.
Inside the chat that shows the wrong model, run /model status to confirm the pin, then /model default to clear it. The next run resolves from the agent primary and then the global default. If a run is already active, the switch is marked pending and applied at the next clean retry point, so give it a turn before you assume it failed.
If you only want a different model for this one conversation, leave the pin in place. If you want the new config default everywhere, clear every pinned session you care about, then verify with openclaw sessions list.
Fix 2: handle the “Model is not allowed” rejection
If agents.defaults.models is set, it becomes the allowlist for /model, model pickers, and session overrides. Selecting anything outside it fails before a reply is generated, with an error that starts Model "provider/model" is not allowed and ends with a suggested config set command.
The suggested fix is correct, and the --merge flag matters. Without it, you risk replacing the whole allowlist with a single entry and locking yourself out of everything else.
openclaw config set agents.defaults.models \
'{"deepseek/deepseek-v4-pro":{}}' --strict-json --merge
If you do not want to maintain a list, allow a whole provider with a wildcard entry such as "openai/*": {} or "ollama/*": {}. New models from that provider then appear without another edit.
Local models need the full provider-prefixed reference. ollama/qwen2.5:14b works. A bare filename or display name does not, once the allowlist is active. Run openclaw models list --provider ollama to copy the exact string instead of typing it from memory.
Fix 3: release a fallback that will not let go
Here is the part that surprises people. When OpenClaw falls back, it does not just answer one message with a different model. It writes a temporary override to the session, marked modelOverrideSource: "auto", so the next turns keep using the working model instead of hammering a dead primary every single time.
That override is cleared automatically when the original primary recovers. OpenClaw probes the origin every 5 minutes, and that interval is not configurable. While the session is on fallback you get one notice, and one more when it clears: Model Fallback: deepseek/deepseek-v4-flash (selected deepseek/deepseek-v4-pro; 429 rate limit), followed later by Model Fallback cleared.
If the notices are buried in a long channel, the session can sit on a fallback for days and look like a config bug. Check the provider first. If the primary is still rate limited, out of credit, or returning auth errors, the fallback is doing its job. Fix the billing or the key, and the next probe will restore the primary.
If you want to force the session back immediately, run /new in that chat. That clears the auto override and starts a clean session. Note that /new does not clear a user pin, which is why the two fixes are separate.
One more edge: heartbeat runs without an explicit heartbeat.model clear a direct auto override when its origin no longer matches the configured default. If you changed the default and a background heartbeat is still using the old fallback, that is the reason. For the full failover sequence, including auth profile rotation and cooldowns, see our guide to OpenClaw model fallbacks when your provider goes down.

Fix 4: agents, cron jobs, and sub-agents have their own model
If the main chat behaves and a background job does not, you are probably looking at a different agent or a different run type. Each of these has its own model surface:
- Per-agent:
agents.list[].modeloverridesagents.defaults.model. Give that block afallbacksarray if you want it to fail over. - Sub-agents: set
agents.defaults.subagents.modelto a cheaper model, or passmodelon a singlesessions_spawncall. This is the easiest way to keep heavy research on a budget model while your main agent stays on the strong one. - Cron jobs:
payload.modelis a per-job primary. It still uses the configured fallbacks unless the job setspayload.fallbacks. An empty array,[], makes that job strict. - Heartbeat:
heartbeat.modelpins the background check to a specific model without touching interactive chats.
Confirm the agent’s own model before you touch anything global. Run openclaw config get agents.list --json and read the model block for the agent id you are debugging. On this Mac, for example, the main agent has one fallback while several site agents have a different primary and three fallbacks. Same config file, different resolved behavior. If you edit the default and wonder why one agent ignores it, this is the line to read.
Verify the fix actually stuck
Do not trust the config file after an edit. Check the resolved state in three places:
- Config view:
openclaw models statusshould show the primary and fallbacks you intended. - Session view:
openclaw sessions listshould show the target model for the session key you fixed, with no unexpected extra sessions still pinned. - Chat view:
/statusshould show the model and, ideally, no pinned-session sentence.
Then send one normal message in that chat. A clean turn with no fallback notice means the resolution order landed where you wanted. If you still see a fallback notice, the primary is failing, not misconfigured. Read the reason in the notice before you change more settings. If you recently updated OpenClaw and these commands behave differently than expected, our OpenClaw upgrade playbook covers the version-specific changes worth checking.
Common mistakes
- Editing the default and expecting old chats to change. Sessions pin their own model. The new default applies to new and unpinned sessions only.
- Using
/newto clear a user pin. It clears auto fallbacks, not explicit selections. Use/model default. - Adding a fallback but not a primary. The allowlist gates what you can select in chat. The primary still has to be a valid, authenticated model reference.
- Assuming every agent inherits fallbacks. An agent primary without a
fallbacksarray is strict. The global fallback list does not rescue it. - Typing local model names from memory. Copy the exact
provider/modelstring fromopenclaw models list --provider ollama. - Debugging in a sub-agent. Children can run a different model by design. Test the session you actually care about.
Check out our guide to OpenClaw token costs. It shows where the spend actually goes and the settings that bring a runaway agent back under control without downgrading everything.
See the Cost GuideBecause the session has its own model state. A user pin from /model, or an automatic fallback override, takes priority over agents.defaults.model.primary. Run /model default to clear a pin, or /new to clear an auto fallback.
No. Session model overrides live in the session store, so they survive a restart. A restart reloads config, which helps after a config edit, but it will not clear a pinned session or a persisted fallback override.
Use /model in that chat for an interactive session, pass model on sessions_spawn for a sub-agent one-off, or set payload.model on a cron job. Each of those is scoped to that session or run and does not rewrite your global default.
An explicit user selection is strict, and an agent primary is strict unless agents.list[].model includes its own fallbacks array. Add fallbacks to that agent block if you want automatic failover on that agent.
No. It sets the model for the current session only. Other sessions, agents, and cron jobs keep their own resolved model until you change them separately.
Final thoughts
The config file is a starting point, not a command. Once you know the order, which is user pin, auto fallback, agent primary, global default, the strange model names in /status stop being mysterious. Most of the time the fix is one command in the right chat, not a config rewrite.
Work top down and verify at each layer: fix the session, then the allowlist, then the fallback state, then the per-agent or per-job model. If you change one layer and the model still looks wrong, the next layer is telling you something.

