The Complete Guide to openclaw.json Configuration
Quick Answer: openclaw.json is the main configuration file for OpenClaw's LLM providers. It tells the internal Gateway which providers to use (Anthropic, OpenAI, Google, DeepSeek, Moonshot, Ollama), how to rotate auth profiles across multiple API keys, and how to build fallback chains with exponential backoff so your agents never go down when a single provider fails.
OpenClaw's model-agnostic design means you can switch between any supported provider — or chain several together — by editing this single file. No code changes required.
How Does the Gateway Architecture Work?
The Gateway is OpenClaw's internal request router. It sits between your agent and the LLM providers, handling auth rotation, fallback logic, and exponential backoff — all configured through openclaw.json.
Automatic Fallback Chains
Define an ordered list of providers. If the primary fails, the Gateway seamlessly falls back to the next in line — no code changes, no downtime. Exponential backoff prevents request storms.
Auth Profile Rotation
Supply multiple API keys per provider. The Gateway round-robins across them, distributing requests to avoid per-key rate limits and maximise throughput for production workloads.
Request Isolation
Each provider connection is isolated. A timeout or error from one provider does not block or corrupt requests to others. The Gateway manages connection pools and timeouts independently.
Model-Agnostic Routing
Anthropic, OpenAI, Google, DeepSeek, Moonshot, Ollama — the Gateway normalises requests across all of them. Switch providers by changing a single line in openclaw.json.
How the Gateway Routes a Request
How Do You Configure Providers in openclaw.json?
OpenClaw is model-agnostic. Every provider below is configured as an entry in the providers array inside openclaw.json.
Anthropic (Claude)
Claude Sonnet 4.5, Claude Opus 4, Claude Haiku 4.5
ANTHROPIC_API_KEYStrongest reasoning and instruction-following. Recommended as primary provider for complex agent tasks.
OpenAI (GPT-4o)
GPT-4o, GPT-4o Mini, GPT-4 Turbo
OPENAI_API_KEYBroadest ecosystem support. Excellent for structured output, function calling, and multi-modal tasks.
Google (Gemini)
Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 1.5 Flash
GOOGLE_API_KEYVery long context windows (up to 1M tokens). Ideal for document analysis and large-context automation.
DeepSeek
DeepSeek V3, DeepSeek Coder V2
DEEPSEEK_API_KEYHighly cost-effective. Strong coding capabilities. Good fallback provider for budget-conscious setups.
Moonshot (Kimi K2.5)
Kimi K2.5, Moonshot V1
MOONSHOT_API_KEYCompetitive pricing with strong multilingual support. Growing provider with long-context capabilities.
Ollama (Local)
Qwen 2.5, Llama 3.3, Gemma 3, DeepSeek R1, any GGUF model
None (local)Zero API cost, full privacy. Requires local hardware. Configure base URL to point at your Ollama server.
What Does an Example openclaw.json Configuration Look Like?
A production-ready openclaw.json with a three-provider fallback chain, auth rotation, and exponential backoff.
openclaw.json
{
"gateway": {
"enabled": true,
"fallbackChain": ["anthropic", "openai", "ollama"],
"retryPolicy": {
"maxRetries": 3,
"backoff": "exponential",
"initialDelayMs": 1000,
"maxDelayMs": 16000
}
},
"providers": [
{
"name": "anthropic",
"models": ["claude-3-5-sonnet-20241022"],
"authProfiles": [
{ "apiKey": "${ANTHROPIC_API_KEY_1}" },
{ "apiKey": "${ANTHROPIC_API_KEY_2}" }
],
"timeout": 30000
},
{
"name": "openai",
"models": ["gpt-4o"],
"authProfiles": [
{ "apiKey": "${OPENAI_API_KEY}" }
],
"timeout": 30000
},
{
"name": "ollama",
"models": ["qwen2.5:7b"],
"baseUrl": "http://localhost:11434",
"authProfiles": [],
"timeout": 60000
}
]
}How Does Auth Profile Rotation Work?
Spread API usage across multiple keys for a single provider. The Gateway round-robins through your authProfiles array on every request.
Why Rotate Keys?
- Avoid per-key rate limits on high-throughput deployments
- Distribute cost across multiple billing accounts or teams
- Graceful degradation — if one key is revoked, others keep working
- Test different key tiers (free vs. paid) without code changes
Auth Rotation Config
{
"name": "anthropic",
"models": ["claude-3-5-sonnet-20241022"],
"authProfiles": [
{ "apiKey": "${ANTHROPIC_KEY_TEAM_A}" },
{ "apiKey": "${ANTHROPIC_KEY_TEAM_B}" },
{ "apiKey": "${ANTHROPIC_KEY_TEAM_C}" }
],
"rotation": "round-robin"
}How Do Fallback Chains with Exponential Backoff Work?
The Gateway tries providers in order. If one fails, it backs off exponentially before retrying, then falls to the next provider. Your agents stay online even during provider outages.
Fallback Chain Example
{
"gateway": {
"enabled": true,
"fallbackChain": ["anthropic", "openai", "deepseek", "ollama"],
"retryPolicy": {
"maxRetries": 3,
"backoff": "exponential",
"initialDelayMs": 1000,
"maxDelayMs": 16000
},
"healthCheck": {
"enabled": true,
"intervalMs": 60000
}
}
}1. Request sent to Anthropic (primary)
If Claude responds successfully, the result is returned immediately. No fallback needed.
2. Anthropic fails -- retry with backoff
Gateway waits 1s, retries. If it fails again, waits 2s, retries. After maxRetries (3), moves to the next provider.
3. Fallback to OpenAI
The same request is sent to GPT-4o. If it succeeds, the result is returned. If it fails, backoff and retry again.
4. Fallback to DeepSeek, then Ollama
The chain continues through every provider. Ollama (local) is the final safety net — it never has rate limits or outages.
What Are the Recommended Starter Configurations?
Copy-paste templates for common setups. Start simple and add providers as your needs grow.
Single Provider (Simplest)
{
"providers": [
{
"name": "anthropic",
"models": ["claude-3-5-sonnet-20241022"],
"authProfiles": [
{ "apiKey": "${ANTHROPIC_API_KEY}" }
]
}
]
}Local-Only with Ollama (Free)
{
"providers": [
{
"name": "ollama",
"models": ["qwen2.5:7b", "gemma3:4b"],
"baseUrl": "http://localhost:11434",
"authProfiles": [],
"timeout": 60000
}
]
}Hybrid: Cloud Primary + Local Fallback
{
"gateway": {
"enabled": true,
"fallbackChain": ["anthropic", "ollama"],
"retryPolicy": {
"maxRetries": 2,
"backoff": "exponential",
"initialDelayMs": 500,
"maxDelayMs": 4000
}
},
"providers": [
{
"name": "anthropic",
"models": ["claude-3-5-sonnet-20241022"],
"authProfiles": [
{ "apiKey": "${ANTHROPIC_API_KEY}" }
],
"timeout": 30000
},
{
"name": "ollama",
"models": ["qwen2.5:7b"],
"baseUrl": "http://localhost:11434",
"authProfiles": [],
"timeout": 60000
}
]
}What Are the Most Common openclaw.json Questions?
Stop Wasting 40-60% of Your AI Budget
Download the free '6 Token Drains' guide — identify the hidden patterns burning through your tokens and get copy-paste fixes for each one.
Read the Free GuideYour Competitors Are Already Automating. Are You?
Every week we send one automation that saves 10+ hours of manual work — the same playbooks our clients use to run their businesses on autopilot. Miss a week, miss the edge.
Get the Automation Playbook (Free)
One deploy-ready automation every week. Same strategies our clients pay thousands for. 400+ business owners already inside.
Need it done for you?
Book a Free Strategy Call See what we've built for real businesses →