OpenClaw API Key Configuration: From Claude to GPT (Complete Guide)

An API key is the “password” that connects OpenClaw to an AI model (Claude, GPT, Gemini, etc.). Without one, OpenClaw can’t process any task. This guide covers how to get an API key from each major provider, configure it correctly in openclaw.json, use the openclaw configure command, set up multi-model routing, and troubleshoot auth errors.

Haven’t installed OpenClaw yet? Start with the How to Install OpenClaw: Complete A-Z Guide first.

---

Which model should you choose for OpenClaw?

Before getting an API key, decide which model you want to use. OpenClaw supports 50+ LLM providers — from major cloud providers (Anthropic, OpenAI, Google) to local models (Ollama) and aggregators (OpenRouter, Groq).

Model	Provider	Strengths	Best for	Approx. cost
Claude Sonnet	Anthropic	Best speed/quality balance	Most everyday tasks	~$3/1M tokens
Claude Opus	Anthropic	Highest quality output	Complex reasoning, deep analysis	~$15/1M tokens
Claude Haiku	Anthropic	Fast, affordable	Simple tasks, chatbots	~$0.25/1M tokens
GPT-4o	OpenAI	Versatile, vision support	Image processing, multimodal	~$5/1M tokens
GPT-4o mini	OpenAI	Cheap, fast	Basic tasks	~$0.15/1M tokens
Gemini Pro	Google	Generous free tier	Testing, low budget	Free tier available
DeepSeek V3	DeepSeek	Very affordable, good quality	Budget-conscious, coding	~$0.27/1M tokens
Grok	xAI	Fast, real-time data	News, trending topics	~$5/1M tokens
Local (Ollama)	Self-hosted	Free, fully private	Privacy-focused users	Hardware cost only

Recommendation: Start with Claude Sonnet for good quality at reasonable cost. Use Gemini if you want a free tier to experiment with first. Use GPT-4o when you need image processing.

---

Method 1: Quick configuration with openclaw configure

The simplest approach — OpenClaw asks you step by step and writes the config file automatically.

openclaw configure

The wizard asks you to: choose a provider → enter your API key → select a model → test the connection. Done.

Configure specific sections:

openclaw configure --section models     # Models / API keys only
openclaw configure --section gateway    # Gateway settings only
openclaw configure --section channels   # Channel connections only

Check and change your current model:

openclaw models list          # List all available models
openclaw models set <model>   # Switch model quickly

Or in an OpenClaw chat session, type /model to switch models without leaving your messaging app.

---

Method 2: Manual configuration in openclaw.json

The config file lives at ~/.openclaw/openclaw.json (JSON5 format — supports comments and trailing commas). Use this for precise control over every setting.

Basic structure

{
  // Primary AI model
  "agents": {
    "defaults": {
      "model": {
        "primary": "claude-sonnet-4-20250514",      // Default model
        "fallbacks": ["gpt-4o-mini", "gemini-pro"]  // Backup when primary fails
      },
      "models": [                                    // Allowlist — only these models can be used
        "claude-sonnet-4-20250514",
        "claude-haiku-4-5-20251001",
        "gpt-4o",
        "gpt-4o-mini",
        "gemini-pro"
      ]
    }
  }
}

Key fields explained:

• model.primary — the default model for all tasks
• model.fallbacks — if primary hits rate limits or times out, OpenClaw automatically switches to the next model in the list. Auto-cooldown before retrying primary
• models — allowlist: only models in this list can be used. If someone types /model gpt-4-turbo and it’s not on the list, it’s blocked

Set API keys via environment variables

OpenClaw reads API keys from environment variables using standard convention:

# Anthropic (Claude)
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx..."

# OpenAI (GPT)
export OPENAI_API_KEY="sk-proj-xxxxx..."

# Google (Gemini)
export GOOGLE_API_KEY="AIzaSy..."

# xAI (Grok)
export XAI_API_KEY="xai-xxxxx..."

# DeepSeek
export DEEPSEEK_API_KEY="sk-xxxxx..."

# OpenRouter (50+ models via one key)
export OPENROUTER_API_KEY="sk-or-xxxxx..."

Add these to ~/.bashrc (or ~/.zshrc) to make them permanent. On Windows, set them in System Properties → Environment Variables.

Prefer not to use env vars? Run openclaw configure — the wizard stores keys securely without exposing them in plaintext.

---

Get an API key from Anthropic (Claude)

1. Go to console.anthropic.com
2. Create an account with your email
3. Go to Settings → Billing → add a credit/debit card → add credits (minimum $5)
4. Go to Settings → API Keys → click Create Key
5. Name it (e.g. “OpenClaw Production”) → copy the key immediately

Key format: sk-ant-api03-xxxxx... — the key is only shown once. If you lose it, you’ll need to create a new one.

export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx..."
openclaw models set claude-sonnet-4-20250514

Or use OAuth (no copy-pasting needed):

openclaw models auth login --provider anthropic

This opens your browser → you log in to Anthropic → grant access → done. The token is stored automatically and refreshes on its own.

---

Get an API key from OpenAI (GPT)

1. Go to platform.openai.com
2. Sign up / log in → verify your phone number
3. Go to Settings → Billing → add credits (recommend $10 to start)
4. Go to API Keys → click Create new secret key → copy it

Key format: sk-proj-xxxxx...

export OPENAI_API_KEY="sk-proj-xxxxx..."
openclaw models set gpt-4o

Note: Some models (GPT-4o, o1) require Tier 2+ on OpenAI. If you get a “model not found” error, check your tier in the OpenAI dashboard.

---

Get an API key from Google (Gemini)

1. Go to aistudio.google.com → sign in with your Google account
2. Click Get API Key → select a project (or create a new one) → copy the key

Key format: AIzaSy...

export GOOGLE_API_KEY="AIzaSy..."
openclaw models set gemini-pro

Advantage: Google offers a generous free tier — good for experimenting before committing to Claude or GPT.

---

Use local models with Ollama (no API key needed)

If you want OpenClaw without any external API dependency:

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Download a model
ollama pull llama3.1

# Configure OpenClaw to use it
openclaw configure --section models
# Choose provider: ollama → model: llama3.1 → base URL: http://localhost:11434

Or configure manually in openclaw.json:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/llama3.1"
      }
    }
  }
}

Note: Local models require decent hardware (minimum 16 GB RAM, GPU recommended). Output quality is generally lower than Claude/GPT for complex tasks, but cost is zero and your data never leaves your machine.

---

Use OpenRouter (50+ models via 1 API key)

If you want access to many models from different providers without managing multiple API keys, OpenRouter is the best aggregator:

1. Go to openrouter.ai → sign up → add credits
2. Go to API Keys → create a key

export OPENROUTER_API_KEY="sk-or-xxxxx..."

In openclaw.json:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4",
        "fallbacks": ["openai/gpt-4o-mini", "google/gemini-pro"]
      }
    }
  }
}

Advantage: 1 key, 50+ models, 1 billing dashboard. Tradeoff: One extra hop adds a small amount of latency.

---

Multi-model routing: using multiple LLMs intelligently

OpenClaw supports automatic multi-model routing with failover:

Strategy 1: Primary + Fallback

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "claude-sonnet-4-20250514",
        "fallbacks": ["gpt-4o-mini", "gemini-pro"]
      }
    }
  }
}

When Claude hits a rate limit (429) or times out → OpenClaw automatically switches to GPT-4o mini → if that fails too → Gemini. Automatic cooldown before retrying the primary.

Strategy 2: Model by task type

Use a powerful model for complex tasks, a cheaper model for simple ones — saves 60–70% on API costs:

• Main tasks (writing, analysis, code): Claude Sonnet
• Simple tasks (summarization, classification, basic chat): GPT-4o mini or Claude Haiku
• Image processing: GPT-4o (vision)

Switch models quickly in chat by typing /model claude-haiku-4-5-20251001 or /model gpt-4o-mini.

Track your costs

/status         # See current model, token count
/usage full     # Detailed cost report by model and by day

---

OAuth: authenticate without copying keys

Instead of copy-pasting API keys, OpenClaw supports OAuth (browser-based authentication) for major providers:

openclaw models auth login --provider anthropic
openclaw models auth login --provider openai
openclaw models auth login --provider google

The command opens your browser → you log in to the provider → grant access → token is stored automatically. Tokens refresh on their own when they expire.

When to use OAuth instead of an API key:

• You don’t want to handle raw keys (reduced risk of key exposure)
• Your organization requires OAuth for security policy compliance
• Multiple team members sharing a config but each authenticating individually

Check auth status:

openclaw models auth status

---

Configuring on TryOpenClaw.io

If you’re using TryOpenClaw.io, configuring the API key is simpler — no config files or terminal commands:

1. Dashboard → Settings → Model
2. Choose your model (Claude / GPT / Gemini)
3. Paste your API key into the corresponding field
4. Click Save — no restart needed, no config file editing

TryOpenClaw also supports a built-in credit system — you can purchase credits directly and use them for LLM calls without creating an API key with any individual provider. More convenient if you’d rather not manage API keys yourself.

More details: Run OpenClaw on Cloud — No Installation Needed

---

API key security best practices

Your API key = access to your LLM provider account. If exposed, others can use your credits.

Never commit API keys to Git. OpenClaw’s config file (openclaw.json) doesn’t store keys in plaintext — they live in environment variables or are encrypted by openclaw configure.

Rotate keys regularly. Create a new key every 3–6 months and revoke the old one on the provider dashboard.

Set spending limits. Both Anthropic and OpenAI let you set monthly spending caps — configure these to avoid surprise charges.

Use separate keys per project. Don’t share an API key between OpenClaw and other applications. If one key gets exposed, only one project is affected.

Config file permissions. OpenClaw checks file permissions automatically. If ~/.openclaw/openclaw.json is world-readable, OpenClaw will warn you:

chmod 600 ~/.openclaw/openclaw.json

---

Common API key configuration errors

“Invalid API key” or “401 Unauthorized”: Key was copied with extra characters, has leading/trailing whitespace, or was revoked. Fix: create a new key, copy it carefully, run openclaw configure --section models again.

“Insufficient quota” or “402 Payment Required”: No credits remaining. Top up your account with the provider. Check if your spending limit is set too low.

“Model not found”: Incorrect model name, or your account doesn’t have access to that model tier. Run openclaw models list to see available models. Some models require higher tiers (GPT-4o requires Tier 2+ on OpenAI).

Responses very slow: Switch to a lighter model: /model claude-haiku-4-5-20251001 or /model gpt-4o-mini. You may also be hitting rate limits on a lower tier.

OAuth token expired:

openclaw models auth login --provider <provider-name>

Full debug guide: OpenClaw Troubleshooting Guide

---

Frequently Asked Questions

Are API keys free? Most providers charge based on usage (pay-as-you-go). Google Gemini has a fairly generous free tier. OpenAI and Anthropic typically give $5–$10 in free credits to new accounts.

How much credit do I need to start? $5–$10 is enough for 1–2 weeks of basic personal use (a few hundred simple tasks). Using Haiku or GPT-4o mini for lightweight tasks can stretch this 10x further.

Do API keys expire? Anthropic and OpenAI keys don’t expire unless you revoke them. Google keys are similar. However, your credits can run out — at which point the key returns a 402 error.

Can I use multiple providers at the same time? Yes. Configure a primary + fallbacks in openclaw.json. OpenClaw switches automatically when a provider fails or rate-limits.

OpenRouter or individual provider keys? Individual keys: faster (one less hop), provider pricing. OpenRouter: convenient (1 key, 1 billing), flexible model switching. If you only use 1–2 providers → individual keys. If you frequently switch models or experiment → OpenRouter.

---

Summary

Configuring OpenClaw to use an AI model takes 3 steps:

1. Get an API key from your chosen provider (Anthropic, OpenAI, Google, or use Ollama for free local models)
2. Configure OpenClaw via openclaw configure (simplest) or by editing ~/.openclaw/openclaw.json directly
3. Verify with openclaw doctor and test a task

For multi-model setups, configure a primary model + fallbacks in your JSON config — OpenClaw handles switching automatically when rate limits or outages occur.

---

Ready to go? Run openclaw configure and follow the prompts. Or if you use TryOpenClaw.io, configure everything from the Dashboard — no terminal needed.