OpenClaw Models Command: What Top Builders Always Configure

Picking the wrong model for a task costs real money and kills response quality. A research agent using a fast, cheap model produces shallow results. A simple routing agent using GPT-4o burns budget on tokens it doesn't need. The openclaw models command gives you surgical control over which model each agent uses — and lets you switch providers without touching a single agent config file.

What the openclaw models Command Does

The openclaw models command is your CLI interface to the model registry inside the OpenClaw gateway. Every model you've configured across all providers — OpenAI, Anthropic, Groq, local Ollama instances — appears here. The command handles four operations: listing available models, setting defaults, assigning models to specific agents, and managing model aliases.

This matters because OpenClaw separates model configuration from agent configuration by design. Your agent definition describes what an agent does. The model setting describes how it thinks. Keeping these separate means you can upgrade models across your entire fleet with one command rather than editing every agent config file individually.

As of early 2025, the models command works with all major providers that OpenClaw supports natively — no plugin installation required for the big four providers.

Listing Available Models

The list subcommand queries every configured provider and returns a unified view of available models.

# List all models across all providers
openclaw models list

# Filter to a specific provider
openclaw models list --provider anthropic

# Show only currently active models (excludes deprecated)
openclaw models list --active

# Get JSON output for scripting
openclaw models list --output json

The default output shows model ID, provider, context window (in tokens), per-million-token cost where available, and current status. Status can be active, unavailable (API key issue or provider outage), or deprecated (still works but scheduled for removal).

Here's what a typical output looks like for a multi-provider setup:

MODEL                        PROVIDER    CONTEXT    STATUS
gpt-4o                       openai      128k       active
gpt-4o-mini                  openai      128k       active
gpt-4-turbo                  openai      128k       deprecated
claude-3-5-sonnet-20241022   anthropic   200k       active
claude-3-haiku-20240307      anthropic   200k       active
llama3.1:70b                 ollama      128k       active

The JSON output is what you want for automation scripts that need to validate model availability before deploying agents.

Setting the Global Default Model

The global default is the fallback model for any agent that doesn't have a specific model assigned. Setting it correctly is the first thing you should do after adding provider API keys.

# Set global default to GPT-4o
openclaw models set-default --model gpt-4o

# Confirm the change
openclaw models get-default

# Reset to no default (agents will fail to start without a per-agent model)
openclaw models set-default --reset

The change takes effect immediately for new conversations. Agents currently in a session continue using whatever model they started with — this is intentional, to avoid mid-conversation model switches that can break context handling.

Choose your global default based on your most common workload. For teams running mixed research and automation pipelines, a mid-tier model like GPT-4o-mini or claude-3-haiku-20240307 makes sense as the default — capable enough for most tasks, cheap enough to run continuously.

Per-Agent Model Configuration

Per-agent model assignment is where the real optimization happens. Assign your best model to agents that need deep reasoning, and a fast model to agents that handle routing, triage, or simple data extraction.

# Assign a specific model to one agent
openclaw models set --agent researcher-001 --model claude-3-5-sonnet-20241022

# Assign a model to multiple agents at once
openclaw models set --agent "researcher-001,researcher-002" --model claude-3-5-sonnet-20241022

# Remove a per-agent override (reverts to global default)
openclaw models unset --agent router-001

# List which model each agent is currently using
openclaw models list --agents

The --agents flag on list gives you a combined view: each agent, their assigned model (or "default" if using the global), and whether that model is currently available. This is the fastest way to audit your entire fleet's model config in one command.

Sound familiar? You've probably done this manually by editing agent YAML files. The CLI approach is faster and less error-prone — no risk of typos in model IDs that only surface when the agent tries to start.

Switching Providers Without Breaking Agent Configs

Here's the workflow most teams get wrong. They add Anthropic keys, want to switch their research agents from GPT-4o to Claude Sonnet, and start editing agent YAML files one by one. That's unnecessary manual work.

# Step 1: Verify Anthropic models are available
openclaw models list --provider anthropic

# Step 2: Set per-agent model for affected agents
openclaw models set --agent researcher-001 --model claude-3-5-sonnet-20241022
openclaw models set --agent researcher-002 --model claude-3-5-sonnet-20241022

# Step 3: Confirm the changes
openclaw models list --agents | grep researcher

Model aliases take this further. Define an alias in your openclaw config — for example, research-model → current best model — and assign agents to the alias rather than the model ID directly. When you upgrade models, you update one alias definition and all agents pointing to that alias switch automatically.

# Define an alias (in openclaw config)
openclaw config set --key model_aliases.research-model --value claude-3-5-sonnet-20241022

# Assign agents to the alias
openclaw models set --agent researcher-001 --model research-model

# Upgrade the alias later — all agents update automatically
openclaw config set --key model_aliases.research-model --value claude-3-7-sonnet-20250201

This is the pattern production teams use. It decouples agent configuration from provider-side model ID changes entirely.

Common Mistakes With the Models Command

• Using full model IDs that change with provider updates — providers silently rename or deprecate model IDs. Use aliases or monitor the deprecated status flag in openclaw models list regularly.
• Not setting a global default before starting agents — agents without a model assigned and no global default will fail to initialize with an unhelpful error. Set a default immediately after configuring provider API keys.
• Ignoring context window mismatches — assigning a model with an 8k context window to a research agent that regularly handles 50k-token documents causes silent truncation. Always check context window sizes in openclaw models list against your actual workload.
• Changing the global default during active sessions — agents currently running keep their session-start model. The default change only affects new sessions. Plan model migrations during low-traffic windows to avoid inconsistent behavior across your fleet.
• Not auditing after provider API key changes — if you rotate provider keys, run openclaw models list to confirm all models still show "active" before assuming agents are working correctly.

Frequently Asked Questions

How do I list all available models in OpenClaw?

Run openclaw models list to see every model across all configured providers. The output includes model IDs, provider names, context window sizes, and current status. Use --provider to filter by provider and --output json for scripting.

How do I set the default model for all agents?

Run openclaw models set-default --model gpt-4o to set a global default. All agents without a specific model override use this model. The change takes effect immediately for new conversations — running sessions are unaffected.

Can I assign different models to different agents?

Yes. Use openclaw models set --agent researcher-001 --model claude-3-5-sonnet-20241022 to assign a model to a specific agent. Per-agent settings override the global default. This lets you run expensive models for complex reasoning and fast models for simple routing.

What happens if a model I've configured is no longer available?

OpenClaw logs an error on agent startup and falls back to the global default model if set. If no default is configured, the agent fails to initialize. Run openclaw models list to verify availability after provider updates or version upgrades.

How do I switch from OpenAI to Anthropic using the CLI?

First add your Anthropic API key with openclaw config set --key anthropic_api_key --value sk-ant-xxx. Then run openclaw models set-default --model claude-3-5-sonnet-20241022. Agents using the old default switch on their next session start.

Does the openclaw models command support model aliases?

Model aliases let you reference models by a short name instead of full provider IDs. Define aliases in your openclaw config and assign agents to alias names. When providers update model IDs, you update one alias definition — all agents pointing to that alias switch automatically.