How to Add Models to OpenClaw: Complete Configuration Guide

Adding new AI models to OpenClaw gives you the flexibility to work with different providers, optimize costs, and build resilient applications with automatic fallbacks. Whether you're connecting to cloud providers like OpenAI and Anthropic or running local models with Ollama, the process follows a clear structure once you understand the core commands and configuration options.

Quick Answer: The openclaw models add command adds new provider configurations to OpenClaw, while openclaw models set changes your active model. You'll configure providers in your openclaw.json file with authentication details, then reference models using the provider/model-id format throughout your workflows.

What is the openclaw add model command and how does it work?

OpenClaw doesn't have a single "add model" command in the traditional sense. Instead, you add models through a two-step process: first configuring the provider, then setting which model to use.

The command structure breaks down into several operations:

Provider configuration happens through openclaw models add <provider> for built-in providers like Anthropic, OpenAI, and OpenRouter. This launches an interactive wizard that guides you through entering API keys and selecting default models.

Model selection uses openclaw models set <provider/model> to change your active model immediately. For example, openclaw models set anthropic/claude-3-5-sonnet switches to Claude Sonnet as your primary model.

Model discovery relies on openclaw models list to show all configured models, with the --all flag displaying the full catalog and --provider <name> filtering to specific providers.

The model reference format always follows provider/model-id patterns. You might use openai/gpt-4, ollama/llama3.3, or openrouter/anthropic/claude-3-opus depending on your provider setup.

Here's why this matters: OpenClaw treats models as combinations of provider authentication and model identifiers. You can't just add a model without first configuring how to authenticate with the provider that hosts it.

How do you add a new AI model provider to OpenClaw?

Adding a provider depends on whether it's a built-in option or a custom service. Built-in providers like Anthropic, OpenAI, and Google have streamlined setup processes, while custom providers require manual configuration.

Built-in Provider Setup

For major providers, use the interactive wizard:

openclaw models add anthropic

This command prompts you for:

Your API key
Default model selection
Optional configuration preferences

The wizard validates your credentials and updates both openclaw.json and auth-profiles.json automatically. Your API key gets stored securely in the auth profiles file, separate from your model configuration.

If you're just getting started with OpenClaw, check out our step-by-step setup guide for complete installation instructions.

Custom Provider Configuration

Custom providers require editing openclaw.json directly. You'll add an entry to the models.providers section:

{
  "models": {
    "providers": {
      "myapi": {
        "type": "openai-compatible",
        "baseUrl": "https://api.example.com/v1",
        "apiKey": "${MY_API_KEY}"
      }
    }
  }
}

The configuration includes:

type: Either openai-compatible or anthropic-compatible depending on the API format
baseUrl: The endpoint URL for API requests
apiKey: Your authentication token (use environment variables for security)

For local model servers like LM Studio or vLLM, you'll point to localhost:

{
  "models": {
    "providers": {
      "lmstudio": {
        "type": "openai-compatible",
        "baseUrl": "http://127.0.0.1:1234/v1",
        "apiKey": "not-needed"
      }
    }
  }
}

Most local servers don't require authentication, so you can use a placeholder API key value.

What's the difference between openclaw models add and openclaw models set?

These commands serve distinct purposes in your model management workflow.

openclaw models add configures a provider's authentication and connection details. Think of it as adding a new service to your available options. You run this once per provider, entering API keys and base URLs.

openclaw models set changes which model you're actively using. This is what you'll run regularly as you switch between different models for different tasks. It doesn't modify authentication—just tells OpenClaw which model to send requests to.

Here's a practical example:

# Add OpenAI as a provider (once)
openclaw models add openai

# Switch between OpenAI models (anytime)
openclaw models set openai/gpt-4
openclaw models set openai/gpt-4-turbo
openclaw models set openai/o1

The distinction matters because you can set models without re-entering credentials. Once OpenAI is configured, you can freely switch between any OpenAI model using the set command.

There's also openclaw models set-image for configuring which model handles vision tasks. This lets you use a cheaper text model for most work while automatically routing image inputs to a vision-capable model.

How do you configure authentication for different model providers?

Authentication configuration varies by provider type, but OpenClaw standardizes the approach through environment variables and the auth profiles system.

API Key Storage

Store credentials as environment variables rather than hardcoding them:

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GROQ_API_KEY="gsk_..."

In your openclaw.json, reference these variables:

{
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}"
      }
    }
  }
}

The ${VARIABLE_NAME} syntax tells OpenClaw to read from your environment. This keeps secrets out of version control and makes it easy to rotate keys without editing configuration files.

OAuth-Based Authentication

Some providers like Qwen use OAuth device code flows. For these, OpenClaw handles the authentication process:

openclaw models add qwen

This generates a device code and opens your browser for authentication. Once you approve access, OpenClaw stores the OAuth tokens in auth-profiles.json and handles token refresh automatically.

Provider-Specific Requirements

Different providers have different authentication patterns:

OpenRouter requires you to set OPENROUTER_API_KEY and optionally configure HTTP referer headers for request attribution.

Ollama typically needs no authentication for local usage, but you can configure basic auth for remote Ollama servers.

Custom APIs may use bearer tokens, basic auth, or custom headers. For these, you'll add authentication details to the provider configuration:

{
  "models": {
    "providers": {
      "custom": {
        "type": "openai-compatible",
        "baseUrl": "https://api.example.com/v1",
        "headers": {
          "Authorization": "Bearer ${CUSTOM_TOKEN}",
          "X-Custom-Header": "value"
        }
      }
    }
  }
}

When you're planning your deployment strategy, understanding how authentication works across different hosting approaches becomes important. Our guide on OpenClaw as a service covers authentication considerations for both managed and self-hosted setups.

What are model fallbacks and why should you use them?

Model fallbacks create a safety net for your AI applications by automatically trying alternative models when your primary choice fails.

How Fallbacks Work

When a request fails—whether due to rate limits, service outages, or model unavailability—OpenClaw cascades down your fallback list until it finds a working model.

Configure fallbacks with:

openclaw models fallbacks add openai/gpt-4-turbo
openclaw models fallbacks add anthropic/claude-3-5-sonnet
openclaw models fallbacks add openrouter/meta-llama/llama-3.3-70b

Your fallback order matters. OpenClaw tries your primary model first, then each fallback in the order you added them.

Real-World Scenarios

Fallbacks solve several practical problems:

Cost optimization: Set an expensive flagship model as primary, with cheaper alternatives as fallbacks. Most requests succeed with the premium option, but you avoid complete failure when budgets tighten.

Rate limit handling: When you hit API limits on one provider, requests automatically route to another provider with available capacity.

Regional availability: Some models or providers work better in certain geographic regions. Fallbacks ensure you have coverage regardless of where your users connect from.

Service reliability: Even major providers experience occasional outages. A multi-provider fallback strategy keeps your application running during provider downtime.

Performance Considerations

Fallbacks introduce some latency when they trigger. Each failed attempt adds network round-trip time before trying the next option. In practice, this rarely matters—a failed request is nearly instant, and the fallback attempt happens within milliseconds.

The bigger consideration is model capability consistency. If your primary model supports tool calling but your fallback doesn't, features might break during failover. Choose fallbacks with compatible capabilities when possible.

How do you add local models using Ollama or LM Studio?

Local models give you complete control over your AI infrastructure, eliminate API costs, and keep sensitive data on your hardware. Both Ollama and LM Studio integrate smoothly with OpenClaw.

Ollama Setup

Ollama is the most straightforward path to local models. After installing Ollama, you'll need to pull models and configure OpenClaw to use them.

Pull a model:

ollama pull llama3.3
ollama pull deepseek-coder
ollama pull qwen2.5

Configure OpenClaw:

OpenClaw auto-detects local Ollama installations at http://127.0.0.1:11434/v1. You typically don't need manual configuration—just reference models directly:

openclaw models set ollama/llama3.3

If your Ollama server runs on a different port or host, add it to openclaw.json:

{
  "models": {
    "providers": {
      "ollama": {
        "type": "openai-compatible",
        "baseUrl": "http://localhost:11434/v1"
      }
    }
  }
}

Hardware requirements: An 8GB model like Llama 3.3 needs about 10GB of RAM for inference. For faster performance, you'll want a GPU with at least 8GB VRAM (something like an RTX 3060 or better).

LM Studio Configuration

LM Studio provides a graphical interface for running local models and exposes an OpenAI-compatible API.

Start the server in LM Studio:

Load your preferred model
Enable the "Local Server" option
Note the port (typically 1234)

Add to OpenClaw:

{
  "models": {
    "providers": {
      "lmstudio": {
        "type": "openai-compatible",
        "baseUrl": "http://127.0.0.1:1234/v1",
        "apiKey": "not-required"
      }
    }
  }
}

Then reference it:

openclaw models set lmstudio/your-model-name

Local vs Hosted Decision Framework

Factor	Local Models (Ollama/LM Studio)	Hosted APIs
Cost	Zero per-request cost, upfront hardware investment	Pay per token, no infrastructure
Privacy	Complete data control, nothing leaves your network	Data sent to provider servers
Performance	Depends on your hardware, can be slower	Optimized infrastructure, consistent speed
Maintenance	You manage updates and models	Provider handles everything
Availability	Limited to your hardware uptime	High availability with SLAs
Model Selection	Limited to what runs on your hardware	Access to latest cutting-edge models

Choose local models when privacy matters most, when you have sufficient hardware, or when you need to eliminate ongoing API costs. Choose hosted models when you need the absolute best performance, want zero maintenance, or require models that are too large to run locally.

What are the best practices for managing multiple AI models in OpenClaw?

Effective model management combines configuration organization, strategic fallbacks, and smart alias usage.

Use Meaningful Aliases

Aliases create shortcuts for complex model references:

openclaw models aliases add opus anthropic/claude-3-opus
openclaw models aliases add gpt4 openai/gpt-4
openclaw models aliases add local ollama/llama3.3

Now you can use openclaw models set opus instead of typing the full provider/model path. This is especially helpful for frequently-used models or when working with lengthy OpenRouter model paths like openrouter/anthropic/claude-3-opus:beta.

Implement Multi-Tier Fallbacks

Structure your fallbacks by capability and cost:

Tier 1 (Primary): Your preferred flagship model for quality Tier 2 (Fallback 1): A comparable model from a different provider Tier 3 (Fallback 2): A budget option that still meets minimum requirements Tier 4 (Last Resort): A local model or free-tier option

Example configuration:

openclaw models set anthropic/claude-3-opus
openclaw models fallbacks add openai/gpt-4-turbo
openclaw models fallbacks add openrouter/meta-llama/llama-3.3-70b
openclaw models fallbacks add ollama/llama3.3

This gives you premium quality when available, with progressively more economical options as safety nets.

Organize Configuration with Environment Variables

Keep your openclaw.json portable across environments:

{
  "models": {
    "primary": "${PRIMARY_MODEL}",
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}"
      },
      "openai": {
        "apiKey": "${OPENAI_API_KEY}"
      }
    }
  }
}

Set environment-specific variables:

# Development environment
export PRIMARY_MODEL="ollama/llama3.3"

# Production environment
export PRIMARY_MODEL="anthropic/claude-3-opus"

This pattern lets you use local models for development while keeping production on hosted APIs.

Maintain an Allowlist

The agents.defaults.models configuration acts as an allowlist, restricting which models your OpenClaw instance can access. This prevents accidental usage of expensive models:

{
  "agents": {
    "defaults": {
      "models": [
        "anthropic/claude-3-5-sonnet",
        "anthropic/claude-3-haiku",
        "openai/gpt-4-turbo",
        "ollama/llama3.3"
      ]
    }
  }
}

Only models in this list will be available, even if you have additional providers configured. This is especially useful in team environments where you want to control costs.

For complex multi-agent setups, you might also want to explore how the OpenClaw agent gateway handles model routing across different agent types.

Monitor Model Performance

While OpenClaw doesn't include built-in analytics, you can track model usage through logging:

{
  "logging": {
    "level": "info",
    "includeModelCalls": true
  }
}

This logs each model invocation, letting you analyze which models you use most frequently and where fallbacks trigger. Review these logs periodically to optimize your model selection strategy.

How do you troubleshoot common model configuration errors?

Model configuration issues typically fall into a few categories, each with clear diagnostic steps.

"Model is not allowed" Error

This means your requested model isn't in the allowlist.

Solution: Add the model to agents.defaults.models in openclaw.json:

{
  "agents": {
    "defaults": {
      "models": [
        "your-provider/your-model"
      ]
    }
  }
}

After editing, restart OpenClaw to load the updated configuration.

Authentication Failures

When you see "Invalid API key" or "Unauthorized" errors, check several things:

Verify environment variables are set:

echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

If these return empty, your environment variables aren't loaded. Add them to your shell profile or .env file.

Check auth-profiles.json:

cat ~/.config/openclaw/auth-profiles.json

This file should contain entries for each configured provider. If a provider is missing, re-run the setup wizard:

openclaw models add <provider>

Verify API key permissions: Some providers issue keys with limited scopes. Ensure your key has permission to access the specific model you're requesting.

Provider Connection Issues

When OpenClaw can't reach a provider, you'll see timeout or connection refused errors.

For local providers (Ollama, LM Studio):

Check the server is running:

curl http://127.0.0.1:11434/v1/models  # Ollama
curl http://127.0.0.1:1234/v1/models   # LM Studio

These should return JSON with available models. If they fail, start your local server.

For hosted providers:

Test connectivity:

curl https://api.anthropic.com/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY"

If this fails, check your internet connection and firewall rules.

For custom providers:

Verify the baseUrl in your configuration:

curl https://your-custom-api.com/v1/models \
  -H "Authorization: Bearer $YOUR_TOKEN"

Ensure your baseUrl exactly matches the provider's documentation, including the version path (/v1).

Rate Limit Handling

When you exceed provider rate limits, requests fail with 429 status codes. OpenClaw should automatically trigger fallbacks, but you can also:

Check your usage:

Most providers offer dashboards showing your request count and limits. Review these to understand your usage patterns.

Implement request delays:

For batch processing, add delays between requests:

# In scripts
sleep 1  # Wait 1 second between requests

Upgrade your plan:

Many providers offer higher rate limits on paid tiers. If you're consistently hitting limits, upgrading may be more reliable than relying on fallbacks.

Model Not Found Errors

If OpenClaw reports a model doesn't exist:

List available models:

openclaw models list --provider <your-provider>

This shows exactly which models the provider supports.

Check model naming:

Model names change. What was gpt-4 might now be gpt-4-0125-preview. Consult provider documentation for current model identifiers.

Verify provider configuration:

For custom providers, ensure the type is correct (openai-compatible vs anthropic-compatible). An incorrect type causes OpenClaw to use the wrong API format, resulting in model not found errors.

Should you use local or hosted AI models with OpenClaw?

The choice between local and hosted models depends on your priorities around cost, privacy, performance, and maintenance.

When to Choose Local Models

Privacy requirements: If you handle sensitive data that can't leave your infrastructure, local models are essential. Medical records, legal documents, and proprietary business data often require on-premises processing.

Cost at scale: Once you're making thousands of API calls per day, the cost of hosted models adds up quickly. A one-time hardware investment might be cheaper than ongoing API fees.

Network constraints: In air-gapped environments or areas with unreliable internet, local models ensure consistent availability.

Experimentation: For research and testing, local models let you iterate rapidly without worrying about API costs or rate limits.

When to Choose Hosted Models

Cutting-edge capabilities: The most powerful models—like GPT-4, Claude Opus, and Gemini Pro—require infrastructure that's impractical to run locally.

Zero maintenance: Hosted providers handle model updates, infrastructure scaling, and performance optimization. You just call the API.

Elastic capacity: During traffic spikes, hosted APIs scale automatically. Local models are limited by your hardware.

Initial exploration: If you're just getting started with OpenClaw, hosted models require minimal setup compared to configuring local inference servers.

Hybrid Approaches

Many production systems use both:

Development: Local models for rapid iteration without costs
Staging: Mid-tier hosted models for realistic testing
Production: Premium hosted models with local models as fallbacks

Or segment by use case:

User-facing features: Hosted models for best quality
Background processing: Local models for bulk operations
Internal tools: Local models for employee use

Configure this with environment-specific settings, so your OpenClaw instance automatically uses the right model for each context.

How do you optimize costs when using multiple model providers?

Strategic model selection can reduce your AI costs by 50-70% without sacrificing quality for most tasks.

Task-Based Model Routing

Not every request needs your most expensive model:

Simple tasks (classification, basic Q&A, formatting):

Use Haiku, GPT-3.5-turbo, or local Llama models
Cost: $0.25-$1.50 per million tokens

Standard tasks (general writing, analysis, coding):

Use Sonnet, GPT-4-turbo, or hosted Llama 70B
Cost: $3-$15 per million tokens

Complex tasks (deep reasoning, expert-level content, multi-step problems):

Use Opus, O1, or Claude 3 Opus
Cost: $15-$75 per million tokens

Manually switch models based on task type:

# Simple daily summary
openclaw models set anthropic/claude-3-haiku

# Complex analysis
openclaw models set anthropic/claude-3-opus

Implement Intelligent Fallbacks for Cost Control

Structure fallbacks from expensive to cheap:

openclaw models set anthropic/claude-3-opus
openclaw models fallbacks add openai/gpt-4-turbo
openclaw models fallbacks add openrouter/meta-llama/llama-3.3-70b:free
openclaw models fallbacks add ollama/llama3.3

Primary requests use premium models. But if you hit rate limits or budget caps, OpenClaw automatically steps down to cheaper alternatives.

Cache Responses

For repeated queries, cache responses to avoid redundant API calls:

# Store response
openclaw chat "Explain quantum computing" > /tmp/quantum-cache.txt

# Reuse for similar queries
cat /tmp/quantum-cache.txt

Some providers offer built-in caching (Anthropic's prompt caching reduces costs for repeated context). Enable this in your API calls when available.

Use Context Windows Efficiently

Longer prompts cost more. Minimize token usage by:

Trimming unnecessary context
Using concise prompts
Splitting large documents into focused chunks
Removing redundant examples

A prompt that's 50% shorter costs 50% less.

Monitor and Set Budgets

Track spending across providers:

# Check usage logs
tail -f ~/.config/openclaw/openclaw.log | grep "model call"

Set up alerts when costs exceed thresholds. Many providers offer spend limits in their dashboard—configure these to avoid surprise bills.

Leverage Free Tiers

Several providers offer free tiers or credits:

OpenRouter: Models with :free suffix cost nothing
Groq: Free tier with rate limits
Ollama: Unlimited local usage
Google Gemini: Generous free tier for development

Use these for non-critical workloads to preserve paid API budgets for production tasks.

Frequently Asked Questions

Can I use multiple providers simultaneously?

Yes. Configure multiple providers in openclaw.json, then switch between them with openclaw models set or set up fallbacks that automatically route to different providers when one fails.

Do I need to restart OpenClaw after changing models?

No. The openclaw models set command changes the active model immediately. You only need to restart when editing openclaw.json configuration files directly.

How do I remove a model provider?

Delete the provider entry from the models.providers section in openclaw.json, then remove its credentials from auth-profiles.json. Alternatively, you can just stop using it—unused providers don't incur any costs or overhead.

Can I use OpenClaw without any API keys?

Yes, if you run local models with Ollama or LM Studio. These require no authentication and cost nothing beyond the hardware to run them.

What happens if all my fallback models fail?

OpenClaw returns an error after exhausting all fallbacks. In this scenario, check your authentication, network connectivity, and provider status pages. Consider adding a local Ollama model as a final fallback to ensure you always have a working option.

How do I test if a model is configured correctly?

Run a simple query:

openclaw chat "Hello, test message" --model provider/model-name

If it returns a response, your configuration works. If you get errors, review the troubleshooting section above for diagnostic steps.

Next Steps

You now have a complete framework for adding and managing AI models in OpenClaw. Start by configuring one or two providers, test them with simple queries, then gradually expand your setup with fallbacks and optimization strategies.

For production deployments, implement monitoring and cost tracking early. Your usage patterns will reveal opportunities to shift workloads between expensive and economical models without impacting quality.

Remember that model capabilities evolve rapidly. Review your configuration every few months to take advantage of new models, improved pricing, or better-performing alternatives. The flexibility OpenClaw provides means you can adapt your model strategy as the AI landscape changes.

How to Add Models to OpenClaw: Complete Configuration Guide

How to Add Models to OpenClaw: Complete Configuration Guide

What is the openclaw add model command and how does it work?

How do you add a new AI model provider to OpenClaw?

Built-in Provider Setup

Custom Provider Configuration

What's the difference between openclaw models add and openclaw models set?

How do you configure authentication for different model providers?

API Key Storage

OAuth-Based Authentication

Provider-Specific Requirements

What are model fallbacks and why should you use them?

How Fallbacks Work

Real-World Scenarios

Performance Considerations

How do you add local models using Ollama or LM Studio?

Ollama Setup

LM Studio Configuration

Local vs Hosted Decision Framework

What are the best practices for managing multiple AI models in OpenClaw?

Use Meaningful Aliases

Implement Multi-Tier Fallbacks

Organize Configuration with Environment Variables

Maintain an Allowlist

Monitor Model Performance

How do you troubleshoot common model configuration errors?

"Model is not allowed" Error

Authentication Failures

Provider Connection Issues

Rate Limit Handling

Model Not Found Errors

Should you use local or hosted AI models with OpenClaw?

When to Choose Local Models

When to Choose Hosted Models

Hybrid Approaches

How do you optimize costs when using multiple model providers?

Task-Based Model Routing

Implement Intelligent Fallbacks for Cost Control

Cache Responses

Use Context Windows Efficiently

Monitor and Set Budgets

Leverage Free Tiers

Frequently Asked Questions

Next Steps

Enjoyed this article?