The quickest way to change OpenClaw’s model is to enter /model <provider/model> in the current chat. That override affects only the conversation. To change the default used by future sessions, run openclaw models set <provider/model> or update agents.defaults.model.primary in ~/.openclaw/openclaw.json. Authenticate the provider first, use the exact provider/model identifier, and edit only the model field rather than replacing the entire configuration.
Antihost offers VPS plans with one-click OpenClaw, NVMe storage and a 14-day free trial.
Choose the kind of model change you need
OpenClaw supports several scopes. Selecting the right one prevents the common mistake of changing a single conversation when you intended to change every new session, or attempting an administrator-level change as a normal user.
As an Amazon Associate I earn from qualifying purchases.
| Scope | Command or setting | What changes | Who can use it |
|---|---|---|---|
| Session | /model <provider/model> -s or --session |
Only the current conversation; temporary | Normal session user, subject to policy |
| Agent | /model <provider/model> -a or --agent |
Current conversation and a requested agent-default update | Owner or administrator |
| Global | /model <provider/model> -g or --global |
Current conversation and a shared global-default request | Owner or administrator |
| Persistent CLI | openclaw models set <provider/model> |
Updates the configured default for later sessions | Anyone with the required CLI access and configuration permission |
| Configuration file | agents.defaults.model.primary in ~/.openclaw/openclaw.json |
Sets the primary model value directly | Administrator or account with file/configuration access |
A bare /model <provider/model> is normally a session override. Add -s when you want the scope to be unambiguous in scripts, documentation, or team procedures. An administrator’s role does not automatically broaden an unscoped selection; the explicit -a or -g flag is what requests those wider scopes.
How to switch models in the current OpenClaw chat
1. Find the exact model identifier
List models that OpenClaw can currently resolve:
openclaw models listInside chat, you can use:
/model listThe shorter /models form is also supported. To narrow the result to one provider, use /models <provider>. Copy the identifier exactly as OpenClaw displays it; model references use the form provider/model, not just a model nickname.
2. Authenticate before selecting a model
If the provider is not authenticated, complete its setup first. Depending on the provider and your installation, the normal entry points are openclaw onboard and openclaw configure. The provider workflow is intentionally ordered as authenticate first, then choose a provider/model default. Authentication alone does not select a new primary model.
3. Apply the conversation-only override
In the OpenClaw chat where you want the change, enter:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →/model <provider/model>For example:
/model openai/gpt-5.5To state explicitly that the selection is limited to this session, use:
/model openai/gpt-5.5 -sThe conversation continues with the selected model, while the configured default for future sessions remains unchanged. This is the safest choice for testing a model, handling one unusually complex task, or comparing responses without altering shared settings.
How to change OpenClaw’s default model for future sessions
Use the model-management command
The supported persistent shortcut is:
openclaw models set <provider/model>For example:
openclaw models set anthropic/claude-sonnet-4-6This changes the configured primary model used by later sessions. It is different from a chat-only /model override: the command writes the model selection to OpenClaw’s configuration rather than attaching it only to the current conversation.
Set the primary model in the JSON configuration
The corresponding configuration field is:
agents.defaults.model.primaryIn the standard per-user configuration file, the path is:
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →~/.openclaw/openclaw.jsonSet that field to the complete provider-qualified value, such as anthropic/claude-sonnet-4-6 or openai/gpt-5.5. Preserve the rest of the JSON and make a backup before editing. OpenClaw’s documented guidance is to change only model fields and avoid replacing the full configuration object.
Safer RPC-based edits
If you are changing configuration through OpenClaw’s RPC tools, inspect the target field with config.schema.lookup and then submit a partial object with config.patch. A partial patch limits the change to the model property and avoids deleting unrelated provider credentials, routing rules, or agent settings. A full overwrite can silently remove values that are not present in the replacement payload.
How the session, agent and global flags differ
Use scope flags when the desired persistence or authority matters:
Session scope: -s or --session
This is the temporary option. It affects the current conversation only and is appropriate for a trial, a one-off fallback, or a task whose context should not influence other chats.
Agent scope: -a or --agent
An owner or administrator can request an agent-default update with:
/model <provider/model> -aThe current session uses the selected model, and OpenClaw also processes the request to update the agent’s default. If your account lacks owner or administrator authority, the broader update may be rejected even though a session-only selection is allowed.
Global scope: -g or --global
For a shared default, an owner or administrator can enter:
/model <provider/model> -gThis applies the model to the current session and requests a shared global-default change. Use it only when all users or agents that inherit the global setting should move to the new model.
The CLI command openclaw models set <provider/model> is the straightforward persistent route when you have command-line configuration access. Scope flags are especially useful when the change originates in chat and must be explicit.
Compare the choices before you switch
The practical differences are scope, persistence, authority, and risk. A session override is temporary and generally available to the person using that chat. An agent change affects the agent’s later behavior and requires owner or administrator authority. A global change is broader still and can alter the experience for multiple users or agents. The CLI command changes the configured default without requiring a chat command, while a direct file edit gives you the most control but also the greatest chance of damaging unrelated settings.
For a reversible experiment, choose -s. For a deliberate default change on one agent, choose -a. For a shared environment, choose -g only after checking policy and notifying affected users. Use the CLI or a narrow configuration patch when the change should be repeatable and auditable.
Verify which model OpenClaw is actually using
Do not infer success solely from the command returning without an error. Check the effective selection with:
Recommended Free Tools
/model statusOpenClaw’s documented model and session status tools can provide the same information when you are operating outside an interactive chat. Verification should confirm both the provider prefix and the model name, because an alias can resolve to a different configured provider than you expected.
When diagnosing a persistent change, verify twice: once in the session where you changed it, and again by opening a new session. The first check confirms the active override; the second confirms that the default was written successfully. If the two checks disagree, clear the old session override with /model default before concluding that the persistent setting failed.
Reset a temporary model override
To return the current conversation to its configured default, enter:
/model defaultThe model concepts documentation also supports clearing a session override through the session patch operation:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
sessions.patch {model: null}Resetting the session does not undo a deliberate persistent change made with openclaw models set, an agent-scope request, a global-scope request, or a configuration-file edit. It only removes the temporary model value attached to that session.
Why adding provider authentication may not change the model
OpenClaw preserves an existing agents.defaults.model.primary when you add or reauthenticate a provider. This behavior prevents an authentication step from unexpectedly moving all sessions to a different model. Therefore, completing provider login and seeing new credentials in the configuration is not proof that the default model changed.
To intentionally combine authentication with a default-model change, use the provider login flow’s explicit default option where supported:
openclaw models auth login --provider <id> --set-defaultAlternatively, authenticate first and then run openclaw models set <provider/model>. Keeping those actions conceptually separate makes it easier to tell whether a failure is an authentication problem or a model-selection problem.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsAlways include the provider prefix
Use a fully qualified reference such as openai/gpt-5.5, not simply gpt-5.5. When the provider is omitted, OpenClaw may try aliases and matches from configured providers before falling back to a deprecated default-provider behavior. That resolution chain can select a model from an unintended provider or fail after a provider is renamed.
The exact spelling is also significant. Copy the identifier from openclaw models list or /model list, including punctuation and version suffixes. The examples below illustrate the format; they are not a promise that every installation exposes those models:
openai/gpt-5.5anthropic/claude-sonnet-4-6
Handle allowlists and model policy restrictions
A model can be valid, authenticated and visible in the model list yet still be blocked by policy. The model-management commands, provider setup, and alias commands do not modify modelPolicy.allow. If your installation uses an explicit allowlist, update that policy separately through the configuration reference or the administrator’s approved configuration process.
When an allowlist is active, check these items in order:
- Confirm the exact
provider/modelspelling in the allowlist. - Confirm that the provider credentials belong to the account or workspace allowed to use that model.
- Check whether the policy applies at session, agent or global scope.
- Retry the model selection only after the policy change has been saved and reloaded.
Do not work around an allowlist by using an unqualified alias. That makes resolution less predictable and can violate the intent of the policy.
Common failures and their fixes
“Model not found” or an empty model list
Run openclaw models list and copy an identifier exactly. If the provider is absent, complete openclaw onboard or openclaw configure and authenticate it. A model name copied from a provider’s website may not match the identifier exposed by your OpenClaw provider configuration.
The command succeeds but the old model remains
Run /model status in the affected chat. A session override can mask a newly changed persistent default, while an old session can retain its own model value. Use /model default to clear that override, then open a new session and check the status again.
Authentication completed, but the primary model did not move
This is expected when an existing primary model is already configured. Run openclaw models set <provider/model> or use openclaw models auth login --provider <id> --set-default when that option is available.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchAn administrator cannot make an unscoped chat selection global
Use the explicit -a or -g flag. Owner or administrator authority does not automatically expand the scope of a bare /model command.
A valid model is rejected by policy
Inspect modelPolicy.allow. Model selection commands do not add entries to that allowlist, so an administrator must update it separately.
The configuration broke after a manual edit
Restore a known-good backup or run openclaw doctor. If the edit was made through RPC, use the schema lookup and a partial config.patch next time instead of submitting a complete replacement object. This preserves settings unrelated to model selection.
A model works in one chat but not another
Compare /model status in both sessions. One may have a session-specific override, while the other is inheriting the agent or global default. Reset the exceptional session with /model default or apply the intended model explicitly at the correct scope.
Free tools Windows power users keep installed
One-click scans. No signup required.
The provider is listed but the requested ID still fails
Use /models <provider> to see the identifiers that provider exposes to OpenClaw. Do not substitute a similarly named ID from another provider or remove a version suffix. A visible provider does not guarantee that every model sold by that provider is configured for your account.
Practical workflows
Test a cheaper or faster model for one task
- Run
/model listand choose an available, authenticated identifier. - Enter
/model <provider/model> -s. - Complete the task and run
/model statusif you need to record the exact model used. - Enter
/model defaultbefore continuing with the conversation’s normal model.
Move all new sessions to a newly authenticated provider
- Authenticate the provider with
openclaw onboardoropenclaw configure. - Run
openclaw models listand copy the provider-qualified model ID. - Set it with
openclaw models set <provider/model>. - Open a new session and confirm the result with
/model status.
Change a shared default as an administrator
- Confirm that the target model is authenticated and permitted by policy.
- In the relevant chat, run
/model <provider/model> -g, or use the CLI persistent command if the change should be managed from the host. - Verify the current session, then verify a newly created session.
- Tell other users that existing sessions may retain their own temporary overrides.
Move only one agent to another provider
- Authenticate the provider and confirm its model appears in
openclaw models list. - Check the allowlist if policy restrictions are enabled.
- Run
/model <provider/model> -aas an owner or administrator. - Use
/model statusin the current chat and a fresh chat for that agent.
Configuration-safety checklist
- Back up
~/.openclaw/openclaw.jsonbefore manual changes. - Change only
agents.defaults.model.primarywhen that is the intended setting. - Prefer
config.patchwith a partial object for RPC changes. - Keep the provider prefix in every model reference.
- Authenticate before selecting a provider model.
- Check
modelPolicy.allowwhen a valid model is refused. - Use
/model statusand a fresh session to verify persistence. - If a full replacement damaged the configuration, restore a backup or run
openclaw doctor.
The shortest reliable decision rule
Use /model <provider/model> -s when you want a temporary conversation change. Use openclaw models set <provider/model> when future sessions should use a new default. Use -a or -g only when you have the required authority and genuinely intend to update an agent or shared setting. In every case, authenticate first, qualify the model with its provider, verify the effective model, and avoid replacing the full OpenClaw configuration.
Frequently Asked Questions
How do I change the AI model in OpenClaw for only one chat?
Run /model <provider/model> -s, using the exact identifier from /model list or openclaw models list. The change remains limited to that conversation.
How do I change OpenClaw’s default model?
Run openclaw models set <provider/model>, or set agents.defaults.model.primary in ~/.openclaw/openclaw.json. Verify with /model status in a new session.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallDoes adding a provider API key automatically switch OpenClaw to that provider?
No. OpenClaw preserves an existing primary model. Authenticate first, then run openclaw models set <provider/model> or use openclaw models auth login --provider <id> --set-default when supported.
What is the difference between -s, -a, and -g?
-s requests session scope, -a requests an agent-default update, and -g requests a shared global-default update. Agent and global changes require owner or administrator authority.
Why should I write the provider name in the model reference?
OpenClaw resolves unqualified names through aliases and configured providers, which can select an unintended match. Use a fully qualified value such as openai/gpt-5.5.
How do I reset a temporary model choice?
Enter /model default. Through the session API, clearing the value with sessions.patch {model: null} also removes the session override.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Why is a model listed but rejected when I select it?
An explicit modelPolicy.allow allowlist may block it. Update that policy separately; model-selection and provider-authentication commands do not add allowlist entries.
What should I do if editing the configuration removes other settings?
Restore a known-good backup or run openclaw doctor. For future RPC changes, inspect the schema and use a narrow config.patch instead of replacing the complete configuration.
The Bottom Line
For a one-off switch, use /model <provider/model> -s. For a persistent default, use openclaw models set <provider/model>. Authenticate first, include the provider prefix, respect session/agent/global permissions, check allowlists, verify with /model status, and make only partial configuration edits.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
