iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Antihost offers VPS plans with one-click OpenClaw, NVMe storage and a 14-day free trial.
The fastest way to change models in OpenClaw is to type /model <provider/model> in the chat. That changes the current conversation without rewriting your configuration. To change the default used by future sessions, run openclaw models set <provider/model> or update agents.defaults.model.primary in ~/.openclaw/openclaw.json. Always authenticate the provider first, use the full provider/model identifier, and edit only the model field rather than replacing the entire configuration.
Choose the right kind of model change
OpenClaw can apply a model selection at several scopes. The scope determines how long the choice lasts, who can make it, and whether other conversations inherit it.
| Scope | Command | What changes | Typical authority | Persistence |
|---|---|---|---|---|
| Session | /model <provider/model> -s |
The current conversation | Normal session user, subject to policy | Temporary |
| Agent | /model <provider/model> -a |
The current session and a request to update that agent’s default | Owner or administrator | Agent default |
| Global | /model <provider/model> -g |
The current session and a request to update the shared default | Owner or administrator | Shared default |
| Persistent CLI | openclaw models set <provider/model> |
The configured primary model | Anyone with the required CLI access | Persistent configuration |
A bare /model <provider/model> is normally a session override. Use -s or --session when you want that scope to be unmistakable. Being an owner or administrator does not automatically make an unscoped selection global; use the explicit -a or -g flag.
How to decide which scope you need
Use session scope when you are experimenting, handling one specialized task, or comparing responses. Use agent scope when a particular agent should consistently use another model while unrelated agents retain their defaults. Use global scope only when the shared fallback for the installation should change. The CLI command is the clearest choice for a deliberate persistent change that should survive new sessions and can be documented in an operations runbook.
#1 Best Overall
Before switching: verify the model name and provider access
Use OpenClaw’s exact model identifier
Model references use the form provider/model. For example, documentation examples include openai/gpt-5.5 and anthropic/claude-sonnet-4-6. These are identifiers, not interchangeable display names. Select the exact ID exposed by the provider configured in your OpenClaw installation.
List models OpenClaw can see
From the CLI, run:
openclaw models listInside a chat, the equivalent discovery commands are:
Recommended Free Tools
/model list
/models
/models <provider>The provider-specific form is useful when several providers expose similarly named models. If a model does not appear in the list, selecting it will not work until the provider is configured and the model is available to that account. Copy the identifier exactly rather than typing a shortened marketing name.
Authenticate before selecting
OpenClaw’s provider workflow is authenticate first, then set a provider/model default. Depending on the provider and installation, authentication is started with openclaw onboard or openclaw configure. Complete the provider’s login or API-key steps, then repeat the model listing command.
Authentication and model selection are separate operations. Adding credentials does not automatically replace an existing agents.defaults.model.primary. If you intentionally want a login operation to set the default, the documented form is:
openclaw models auth login --provider <id> --set-defaultThat option is useful during a first-time setup. During reauthentication, omit --set-default when you want to refresh credentials without changing the model already chosen for the installation.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsChange the model for one chat only
Use the chat command
- Open the OpenClaw conversation you want to change.
- Enter the full model reference, for example:
/model openai/gpt-5.5To make the intended scope explicit, use:
/model openai/gpt-5.5 -s
/model openai/gpt-5.5 --sessionThe new model applies to that conversation without changing the configured default for new sessions. This is the safest option for testing a model, handling a task that needs different capabilities, or avoiding a configuration change.
Confirm the effective model
Run:
/model statusUse the status information to confirm both the selected model and the scope in which it is active. If your deployment exposes documented model or session status tools, those provide the same verification path outside the chat command. Check status after switching, after changing policy, and after opening a new session; each check answers a different question about what is actually being used.
Return to the configured default
To remove a temporary override, enter:
/model defaultFor integrations that manage sessions programmatically, the model concepts documentation also supports clearing an override with a session patch whose model value is null:
sessions.patch {"model": null}Clearing a session override does not undo an agent or global default. It simply lets that session resolve the model again from the next applicable level.
Change the default model for future sessions
Use the CLI (recommended for a deliberate persistent change)
Run:
openclaw models set anthropic/claude-sonnet-4-6Replace the example with the exact model ID returned by openclaw models list. This updates the configured primary model rather than only the conversation in which the command is run. A later session will use that model unless a session, agent, policy, or other more specific selection overrides it.
Record the old and new identifiers when making a production change. Keeping the previous value gives you an immediate rollback command:
openclaw models set <previous-provider/previous-model>Change the setting in the configuration file
The primary model is stored at:
~/.openclaw/openclaw.jsonThe relevant path is agents.defaults.model.primary. A minimal configuration fragment looks like this:
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-sonnet-4-6"
}
}
}
}Preserve every unrelated key in the existing file. If you edit through an RPC or configuration interface, inspect the schema for the model path and use a partial config.patch object. Do not submit a newly constructed full configuration unless you have deliberately reproduced every required setting and made a backup.
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 matchWhen the CLI is preferable
- It changes only the intended model setting through OpenClaw’s own configuration path.
- It avoids JSON syntax errors caused by manual editing.
- It gives you a single, repeatable command that can be recorded in an operations runbook.
- It makes reverting to the previous provider/model a one-line operation.
Safe file-edit checklist
- Save a known-good copy of
openclaw.jsonbefore editing. - Inspect the schema or current value of
agents.defaults.model.primary. - Change only that string, keeping indentation and all unrelated keys intact.
- Validate the configuration through OpenClaw, then start a fresh session.
- Run
/model statusand retain the backup until the new model has been tested.
Set an agent or shared global model from chat
Agent default
An owner or administrator can request an agent-default update with:
/model openai/gpt-5.5 -a
/model openai/gpt-5.5 --agentThis also changes the current session, so verify the result with /model status. The agent scope is useful when one agent should consistently use a different model while the rest of the installation keeps its existing global default.
Shared global default
An owner or administrator can request a shared default update with:
/model openai/gpt-5.5 -g
/model openai/gpt-5.5 --globalThe global command affects the current session and requests the shared default change. Use it only when you intend to change the fallback for other sessions as well. If you lack the required authority, OpenClaw should reject the scoped request rather than silently applying a broader change.
Why the flags matter
OpenClaw distinguishes session, agent, and global changes. A user with owner or administrator status still needs the explicit scope flag; an unscoped model command does not become global merely because of that account’s role. Treat the flag as part of the change request, not as optional decoration.
Understand which setting wins
When several selections exist, the most specific applicable setting normally controls the active conversation. A session override is more specific than an agent default, and an agent or global default is more specific than the installation’s primary configuration. Policy can still reject a candidate model even when the scope and credentials are correct.
| Question | Command or location | What it tells you |
|---|---|---|
| What can this provider offer? | /models <provider> or openclaw models list |
Available identifiers |
| What is this conversation using? | /model status |
Effective model and override state |
| What is the persistent primary? | openclaw models set history or agents.defaults.model.primary |
Configured fallback for future sessions |
| Why is a valid ID rejected? | modelPolicy.allow configuration |
Whether an allowlist excludes it |
This distinction explains why changing the persistent primary may not alter an already-running conversation: that conversation can retain a session or agent override. Clear the override or open a new session before judging the persistent change.
Understand provider prefixes and aliases
Always prefer an explicit reference such as openai/gpt-5.5 instead of an unqualified name such as gpt-5.5. When the provider is omitted, OpenClaw may try aliases and configured-provider matches before a deprecated default-provider fallback. That resolution can select a different model than you intended, especially when multiple providers expose similar names.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →If an alias is part of your local setup, verify what it resolves to before making it a persistent default. The model list and status commands are the authoritative checks for what OpenClaw will actually use. An alias that worked for a temporary test can later become ambiguous if another provider is added, so explicit provider/model strings are safer in scripts and runbooks.
Fix common model-switching problems
“Model not found” or an empty model list
- Run
openclaw models listand copy the identifier exactly, including capitalization, punctuation, and the provider prefix. - Authenticate the provider with
openclaw onboardoropenclaw configure, then list models again. - Check that the account or API credential has access to the requested model.
- If the provider was recently added, remember that authentication alone does not replace the existing primary model; set it explicitly.
Authentication succeeds but the old model remains active
This is expected when an existing primary model is preserved. Run openclaw models set <provider/model>, or use openclaw models auth login --provider <id> --set-default when you want the authentication flow to set the default intentionally. Then verify with /model status.
The requested model is valid but policy blocks it
An explicit allowlist can reject a model even when the provider is authenticated and the model ID is correct. The commands for setting a model, authenticating a provider, and creating aliases do not change modelPolicy.allow. If an allowlist is enabled in your configuration, update that policy separately according to your deployment’s configuration reference, then retry the selection. Do not disable the policy merely to test a typo; first compare the requested ID with the provider’s model list.
The command appears to work, but another session uses the old model
Check the scope first. A session override affects only one conversation. An agent change affects that agent’s default, while a global or persistent CLI change is needed for a shared fallback. Run /model status in the affected conversation and compare it with the configured primary model. Also check for a more specific session or agent override that takes precedence.
A configuration edit broke OpenClaw
The most common cause is replacing the entire configuration with a fragment that omitted unrelated required settings. Restore a known-good backup if one exists. If not, run openclaw doctor and follow its repair guidance. For future edits, inspect the relevant schema path and apply a partial patch that changes only agents.defaults.model.primary.
You receive a permission error
Use the session scope for a personal, temporary change. Agent and global requests require the corresponding owner or administrator authority. CLI changes require access to the OpenClaw installation and its configuration. Permission to authenticate a provider does not necessarily grant permission to alter shared defaults.
A model change works in one channel but not another
Verify that both channels point to the same agent and session context. A command entered in one conversation does not automatically propagate to another conversation. Apply the appropriate agent or global scope if the intention is to standardize behavior, then check status separately in each affected session.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Safe workflows for common situations
Testing a model before committing to it
- Run
openclaw models listand confirm the exact model ID. - Authenticate the provider if necessary.
- Use
/model <provider/model> -sin a test conversation. - Check
/model statusand evaluate the task in that session. - Use
/model defaultwhen the test is finished.
Making a deliberate installation-wide change
- Confirm the target provider credentials are valid.
- Check the model ID and any allowlist policy.
- Note the current primary model for rollback.
- Run
openclaw models set <provider/model>. - Start or select a fresh session and run
/model status. - Keep the previous model reference available so you can revert quickly with another
openclaw models setcommand.
Changing one agent without changing everyone else
- Confirm you are using an owner or administrator account.
- Enter
/model <provider/model> -a. - Verify the current session and the agent’s subsequent default behavior.
- Use the global flag only if the shared default is also meant to change.
Refreshing credentials without changing models
- Run the provider’s authentication flow without a default-setting option.
- Confirm that the existing primary value is still present.
- Run
/model statusin a current session. - Only use
--set-defaultif changing the primary model is intentional.
Key distinctions to remember
- Fastest one-off switch:
/model <provider/model>. - Explicit session scope: add
-sor--session. - Persistent primary model:
openclaw models set <provider/model>or editagents.defaults.model.primary. - Authentication: required before selection, but it does not normally change the primary model.
- Reliable naming: include the provider prefix.
- Shared changes: use
-aor-gdeliberately and only with the required authority. - Configuration safety: patch the single model field; never replace the whole OpenClaw configuration just to change a model.
- Verification: use
/model statusafter every scope or policy change.
Frequently Asked Questions
How do I switch models without wiping my OpenClaw config?
Use /model <provider/model> -s for a session-only change, or run openclaw models set <provider/model> for the persistent primary. If editing JSON, change only agents.defaults.model.primary with a partial patch and preserve every other key.
Free tools Windows power users keep installed
One-click scans. No signup required.
How do I change the default LLM for future sessions?
Authenticate the provider, confirm the exact identifier with openclaw models list, then run openclaw models set <provider/model>. The equivalent configuration path is agents.defaults.model.primary in ~/.openclaw/openclaw.json.
How do I pick a model in OpenClaw chat?
Enter /model <provider/model>. Add -s or --session to make the temporary scope explicit. Use /models or /model list first if you need to discover available IDs.
Why did adding provider authentication leave my old model active?
OpenClaw preserves an existing primary model when credentials are added or refreshed. Set the model explicitly with openclaw models set <provider/model>, or use openclaw models auth login --provider <id> --set-default when the login should also select the default.
What is the difference between -s, -a, and -g?
-s applies to the current session, -a requests an agent-default change, and -g requests a shared global-default change. Agent and global requests require owner or administrator authority; an unscoped command does not become global automatically.
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 →Scan for outdated or missing drivers - takes under a minuteDriver Scan →How do I undo a temporary model override?
Run /model default in the conversation. Integrations that patch sessions can clear the override with sessions.patch {"model": null}. This restores normal resolution without changing the configured primary.
Why does a valid model get rejected?
Check the provider prefix, credentials, and the exact ID shown by openclaw models list. An enabled modelPolicy.allow allowlist can still block a valid model; model-setting and authentication commands do not modify that policy, so update it separately.
What should I do if a full config replacement broke OpenClaw?
Restore a known-good backup if available. Otherwise run openclaw doctor and follow its repair guidance. Future model changes should use the CLI or a partial configuration patch rather than replacing the complete file.
The Bottom Line
Authenticate first, choose an exact provider/model ID, and match the command to the scope you intend. Use /model ... -s for one conversation, -a or -g for authorized agent or global changes, and openclaw models set ... for the persistent default. Verify with /model status, and change only the model field in configuration.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
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.
