Introduction
One of OpenClaw's key strengths is its ability to connect to multiple AI model providers at once — Claude, OpenAI, Ollama, Gemini, OpenRouter, and more. Through flexible routing rules, you can assign models by channel, match models by keywords, set up automatic failover, and more. This article provides a detailed guide to multi-model switching and routing configuration.
Configuring Multiple Model Providers
Configure multiple providers in the models.providers section of openclaw.json5:
{
models: {
// Default provider
default: "claude",
providers: {
// Anthropic Claude
claude: {
apiKey: "$env:OPENCLAW_CLAUDE_API_KEY",
model: "claude-sonnet-4-20250514",
maxTokens: 4096,
temperature: 0.7,
},
// Advanced Claude model (for complex tasks)
"claude-opus": {
apiKey: "$env:OPENCLAW_CLAUDE_API_KEY",
model: "claude-opus-4-20250514",
maxTokens: 4096,
temperature: 0.5,
},
// OpenAI
openai: {
apiKey: "$env:OPENCLAW_OPENAI_API_KEY",
model: "gpt-4o",
maxTokens: 4096,
temperature: 0.7,
},
// Local Ollama (free, no API key needed)
ollama: {
baseUrl: "http://localhost:11434",
model: "llama3.1:70b",
maxTokens: 2048,
temperature: 0.8,
},
// Google Gemini
gemini: {
apiKey: "$env:OPENCLAW_GEMINI_API_KEY",
model: "gemini-2.0-flash",
maxTokens: 4096,
},
// OpenRouter (multi-provider aggregator)
openrouter: {
apiKey: "$env:OPENCLAW_OPENROUTER_API_KEY",
model: "anthropic/claude-sonnet-4-20250514",
baseUrl: "https://openrouter.ai/api/v1",
},
},
},
}
You can configure multiple instances of the same provider (like claude and claude-opus above), using different model names.
Manual Model Switching
Once configured, users can switch models in chat using commands:
/model claude → Switch to Claude Sonnet
/model claude-opus → Switch to Claude Opus
/model openai → Switch to GPT-4o
/model ollama → Switch to local Ollama
/model list → View all available models
/model reset → Restore the default model
Model Routing Rules
Routing rules allow OpenClaw to automatically select the most appropriate model based on conditions.
Basic Routing Configuration
{
models: {
default: "claude",
providers: { /* ... */ },
routing: {
// Routing rules (listed from highest to lowest priority)
rules: [
{
name: "Use Claude Opus for coding tasks",
match: {
keywords: ["写代码", "编程", "debug", "代码审查", "code"],
},
provider: "claude-opus",
},
{
name: "Use Gemini for translation tasks",
match: {
keywords: ["翻译", "translate", "英译中", "中译英"],
},
provider: "gemini",
},
{
name: "Use local model for casual chat",
match: {
keywords: ["聊天", "闲聊", "你好", "哈哈"],
},
provider: "ollama",
},
],
// Default provider when no rules match
fallback: "claude",
},
},
}
Route by Channel
Assign different models to different messaging channels:
{
models: {
routing: {
rules: [
{
name: "Use Claude for Telegram",
match: {
channel: "telegram",
},
provider: "claude",
},
{
name: "Use GPT-4o for Discord",
match: {
channel: "discord",
},
provider: "openai",
},
{
name: "Use Claude Opus for Slack workspace",
match: {
channel: "slack",
},
provider: "claude-opus",
},
{
name: "Use Gemini for WhatsApp (cost-effective)",
match: {
channel: "whatsapp",
},
provider: "gemini",
},
],
fallback: "claude",
},
},
}
Route by User
Assign specific models to specific users:
{
models: {
routing: {
rules: [
{
name: "VIP users get Opus",
match: {
users: ["user_001", "user_002"],
},
provider: "claude-opus",
},
{
name: "Regular users get Sonnet",
match: {
users: ["*"], // Wildcard matches all users
},
provider: "claude",
},
],
},
},
}
Route by Time
Use different models at different times of day (e.g., cheaper models during off-hours):
{
models: {
routing: {
rules: [
{
name: "Premium model during business hours",
match: {
timeRange: {
start: "09:00",
end: "18:00",
timezone: "Asia/Shanghai",
weekdays: [1, 2, 3, 4, 5], // Monday through Friday
},
},
provider: "claude-opus",
},
{
name: "Economy model during off-hours",
match: {
timeRange: {
start: "18:00",
end: "09:00",
timezone: "Asia/Shanghai",
},
},
provider: "gemini",
},
],
},
},
}
Combined Conditions
You can combine multiple conditions with an AND relationship:
{
name: "Use Opus for coding tasks in Slack",
match: {
channel: "slack",
keywords: ["代码", "code", "debug"],
},
provider: "claude-opus",
},
Failover Chain
When the primary model is unavailable, OpenClaw can automatically switch to a backup model.
{
models: {
default: "claude",
providers: { /* ... */ },
// Failover chain
fallbackChain: [
"claude", // Primary
"openai", // First fallback
"gemini", // Second fallback
"ollama", // Last resort (local model, always available)
],
// Failover trigger policy
fallbackPolicy: {
// Number of consecutive failures before triggering failover
maxFailures: 3,
// How long to wait before attempting recovery
recoveryInterval: 300, // seconds
// Timeout duration (exceeding this counts as a failure)
timeout: 30000, // milliseconds
// Notification when failover is triggered
notification: {
enabled: true,
message: "Model {provider} is unavailable, automatically switched to {fallback}",
},
},
},
}
Failover Flow
User sends a message
├─ Try Claude → Success → Return response
│ Failure ↓
├─ Try OpenAI → Success → Return response
│ Failure ↓
├─ Try Gemini → Success → Return response
│ Failure ↓
└─ Try Ollama → Success → Return response (local model)
Failure → Return error message
Load Balancing
When you have multiple API keys for the same model, you can configure load balancing:
{
models: {
providers: {
"claude-pool": {
type: "pool",
strategy: "round-robin", // round-robin, random, least-used
instances: [
{
apiKey: "sk-ant-key-1",
model: "claude-sonnet-4-20250514",
weight: 1,
},
{
apiKey: "sk-ant-key-2",
model: "claude-sonnet-4-20250514",
weight: 1,
},
{
apiKey: "sk-ant-key-3",
model: "claude-sonnet-4-20250514",
weight: 2, // Higher weight, receives more requests
},
],
},
},
},
}
Load balancing strategy descriptions:
| Strategy | Description |
|---|---|
round-robin |
Cycles through each instance in order |
random |
Random selection (weighted) |
least-used |
Selects the instance with the lowest current usage |
Cost Control
When using multiple paid models, you can configure cost alerts and limits:
{
models: {
costControl: {
// Daily budget (USD)
dailyBudget: 10.0,
// Monthly budget
monthlyBudget: 200.0,
// Action when budget is reached
onBudgetReached: "switch-to-free", // switch-to-free, warn, block
// Free/low-cost model
freeProvider: "ollama",
// Warning threshold (sends notification at this percentage of budget)
warningThreshold: 0.8,
},
},
}
Viewing Model Usage Statistics
You can view each model's usage in the Dashboard. You can also check via command line:
# Open the Dashboard
openclaw dashboard
# View all configured models
openclaw skill list
Dashboard URL: http://localhost:18789/dashboard. On the statistics page you can see:
- Call count per model
- Average response time per model
- Token usage
- Cost estimates
- Failover event history
Complete Configuration Example
Here is a complete configuration with multi-model routing, failover, and cost control:
{
gateway: {
port: 18789,
host: "0.0.0.0",
},
models: {
default: "claude",
providers: {
claude: {
apiKey: "$env:OPENCLAW_CLAUDE_API_KEY",
model: "claude-sonnet-4-20250514",
maxTokens: 4096,
},
openai: {
apiKey: "$env:OPENCLAW_OPENAI_API_KEY",
model: "gpt-4o",
maxTokens: 4096,
},
ollama: {
baseUrl: "http://localhost:11434",
model: "llama3.1",
},
},
routing: {
rules: [
{
name: "Use Claude for Slack",
match: { channel: "slack" },
provider: "claude",
},
{
name: "Use local model for casual chat",
match: { keywords: ["聊天", "闲聊"] },
provider: "ollama",
},
],
fallback: "claude",
},
fallbackChain: ["claude", "openai", "ollama"],
costControl: {
dailyBudget: 5.0,
monthlyBudget: 100.0,
onBudgetReached: "switch-to-free",
freeProvider: "ollama",
},
},
}
Summary
OpenClaw's multi-model architecture frees you from being locked into a single AI provider. Through flexible routing rules, you can intelligently assign models based on task type, messaging channel, user identity, and even time of day. Combined with the failover chain, your AI assistant can continue serving users even if one provider goes down. We recommend starting with a simple configuration and gradually adding routing rules and failover strategies based on real-world usage.