Setting Up API Keys for All Providers — Complete Guide

⚠️ The Problem

You need to set up API keys for AI providers (Anthropic, OpenAI, Google, OpenRouter) or OAuth for services like Gmail, but you're getting authentication errors, token refresh failures, or don't know where to put the credentials in the config file.

🔍 Why This Happens

Authentication issues typically stem from: (1) Credentials placed in wrong section of config file (e.g., inside skills.entries instead of root level), (2) OAuth tokens expired and refresh failing, (3) Missing required OAuth scopes, (4) Incorrect redirect URI in OAuth app settings, (5) Environment variables not being read, or (6) Multi-auth configuration syntax errors.

✅ The Fix

## Config File Structure

Understanding where credentials go is critical. Your config file (~/.config/openclaw/openclaw.json5) has a specific structure:

json5

{  // Root-level sections  "meta": { ... },  "models": {    "providers": { ... },  // AI provider API keys go here    "defaults": { ... }  },  "gmail": { ... },         // Gmail OAuth goes at ROOT level  "channels": { ... },  "skills": {    "entries": { ... }     // NOT here - this is for skills only  }}

Common mistake: Putting gmail config inside skills.entries. It must be at the root level alongside models and channels.

## Anthropic (Claude) API Key

bash

# Set via environment variable (recommended)export ANTHROPIC_API_KEY="sk-ant-..."# Or use the configure wizardopenclaw configure

Config file:

json5

{  "models": {    "providers": {      "anthropic": {        "apiKey": "$ANTHROPIC_API_KEY"  // References env var        // Or hardcode: "apiKey": "sk-ant-..."      }    },    "defaults": {      "provider": "anthropic",      "model": "claude-sonnet-4-20250514"    }  }}

## OpenAI API Key

bash

export OPENAI_API_KEY="sk-..."

Config file:

json5

{  "models": {    "providers": {      "openai": {        "apiKey": "$OPENAI_API_KEY"      }    },    "defaults": {      "provider": "openai",      "model": "gpt-4o"    }  }}

## Google (Gemini) API Key

bash

# Get key from https://makersuite.google.com/app/apikeyexport GOOGLE_API_KEY="AIza..."

Config file:

json5

{  "models": {    "providers": {      "google": {        "apiKey": "$GOOGLE_API_KEY"      }    },    "defaults": {      "provider": "google",      "model": "gemini-2.0-flash"    }  }}

Common error: 403 Forbidden - Enable the Gemini API in Google Cloud Console for your project.

## OpenRouter API Key

OpenRouter gives you access to many models through one API:

bash

# Get key from https://openrouter.ai/keysexport OPENROUTER_API_KEY="sk-or-..."# Onboardopenclaw onboard --auth-choice apiKey --token-provider openrouter --token "sk-or-..."

## Gmail OAuth Setup (Step-by-Step)

Gmail requires OAuth, not just an API key. Here's the complete setup:

### Step 1: Create Google Cloud OAuth Credentials

1. Go to https://console.cloud.google.com/

2. Create a new project or select existing

3. Enable the Gmail API: APIs & Services → Library → Search "Gmail API" → Enable

4. Create OAuth credentials: APIs & Services → Credentials → Create Credentials → OAuth client ID

5. Select Desktop app as application type

6. Add authorized redirect URI: http://127.0.0.1:5316

7. Download or copy your Client ID and Client Secret

### Step 2: Configure OpenClaw

Add Gmail config at the ROOT LEVEL of your config file (not inside skills.entries):

json5

{  "meta": { ... },  "models": { ... },    // Gmail config goes HERE at root level  "gmail": {    "clientId": "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",    "clientSecret": "YOUR_GOOGLE_CLIENT_SECRET"  },    "channels": { ... }}

### Step 3: Authenticate

bash

# Start the OAuth flowopenclaw gmail login

This opens a browser window. Sign in with your Google account and grant permissions.

### Common Gmail OAuth Errors

Error: error: too many arguments for 'setup'. Expected 0 arguments but got 1.

Cause: Old command syntax. Use gmail login not webhooks gmail setup --account.

Error: OAuth token refresh failed for google-antigravity

Cause: Refresh token expired or revoked. Re-authenticate:

bash

openclaw gmail login

Error: redirect_uri_mismatch

Cause: The redirect URI in Google Cloud Console doesn't match. Must be exactly: http://127.0.0.1:5316

## Multi-Auth (Multiple Accounts)

You can configure multiple accounts for the same provider for fallback or rate limit handling:

json5

{  "auth": {    "order": {      "google-antigravity": [        "google-antigravity:primary@gmail.com",        "google-antigravity:backup@gmail.com"      ]    },    "profiles": {      "google-antigravity:primary@gmail.com": {        "provider": "google-antigravity",        "mode": "oauth",        "email": "primary@gmail.com"      },      "google-antigravity:backup@gmail.com": {        "provider": "google-antigravity",        "mode": "oauth",        "email": "backup@gmail.com"      }    }  }}

### Multi-Auth Troubleshooting

Error:

bash

Profile google-antigravity:primary@gmail.com timed out (possible rate limit). Trying next account...FailoverError: LLM request timed out.

Cause: All accounts in the failover chain are rate-limited or have invalid tokens.

Fix:

bash

# Re-authenticate each accountopenclaw auth login google-antigravity --email primary@gmail.comopenclaw auth login google-antigravity --email backup@gmail.com# Verify tokens are validopenclaw auth status

## Environment Variables vs Config File

You can use either method. Environment variables are more secure for CI/CD:

### Environment Variables

bash

# Add to ~/.bashrc or ~/.zshrcexport ANTHROPIC_API_KEY="sk-ant-..."export OPENAI_API_KEY="sk-..."export GOOGLE_API_KEY="AIza..."export OPENROUTER_API_KEY="sk-or-..."

Then reference in config with $VAR_NAME:

json5

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

### Config File (Direct)

json5

{  "models": {    "providers": {      "anthropic": { "apiKey": "sk-ant-api03-..." }    }  }}

Warning: Don't commit config files with hardcoded keys to git.

## Using the env Block

For cleaner organization, use the env block in your config:

json5

{  "env": {    "ANTHROPIC_API_KEY": "sk-ant-...",    "OPENAI_API_KEY": "sk-...",    "DEEPSEEK_API_KEY": "sk-..."  },  "models": {    "providers": {      "anthropic": { "apiKey": "$ANTHROPIC_API_KEY" },      "openai": { "apiKey": "$OPENAI_API_KEY" }    }  }}

## Verifying Your Setup

bash

# Check all providers and auth statusopenclaw doctor# List configured providersopenclaw models list# Check auth profilesopenclaw auth status# Test a quick promptopenclaw chat "Hello, test message"

## All Scopes Reference (Google OAuth)

If you need access to multiple Google services, request these scopes in Google Cloud Console:

bash

https://www.googleapis.com/auth/gmail.modify    # Gmail read/writehttps://www.googleapis.com/auth/calendar        # Calendar accesshttps://www.googleapis.com/auth/drive           # Drive accesshttps://www.googleapis.com/auth/spreadsheets    # Sheets access

Note: More scopes require OAuth app verification for non-test users.

🔥 Your AI should run your business, not just answer questions.

We'll show you how.$97/mo (going to $197 soon)

Join Vibe Combinator →

📋 Quick Commands

Command	Description
openclaw configure	Interactive wizard for API key setup
openclaw onboard --auth-choice apiKey --token-provider <provider> --token <key>	Onboard with a specific provider API key
openclaw gmail login	Start Gmail OAuth authentication flow
openclaw auth status	Show status of all configured auth profiles
openclaw auth login <provider> --email <email>	Re-authenticate a specific OAuth account
openclaw doctor	Diagnose configuration and auth issues
openclaw models list	List all available models from configured providers

Related Issues

How to Switch Models & Configure Providers in OpenClaw

Setting Up API Keys for All Providers — Complete Guide

⚠️ The Problem

🔍 Why This Happens

✅ The Fix

📋 Quick Commands

Related Issues

📚 You Might Also Like

How to Use Claude API: Complete Beginner's Guide

1Password

How to Run AI Locally: Complete Step-by-Step Guide

OpenClaw vs Claude

Still stuck?