# OpenClaw API Keys: Connect OpenAI, Claude, Gemini, and More

Connect multiple AI models safely, avoid auth errors, control costs, and keep workflows running without provider failures breaking your agent.

## Why API Keys Matter in OpenClaw

API keys let OpenClaw connect with AI model providers such as OpenAI, Claude, Gemini, OpenRouter, Groq, and other compatible APIs.

In simple words, API keys decide:

- Which AI models OpenClaw can use
- Whether your workflows can run
- How much each request costs
- Which provider handles coding, research, chat, or automation
- Whether fallback models are available when one provider fails

A wrong API key does not only break chat replies. It can break browser actions, scheduled workflows, coding agents, research tasks, and tool-based automation.

That is why setting up API keys properly matters before running serious OpenClaw workflows.

## API Key Setup Is Different for Every Provider

Not every provider uses the same setup. Some only need an API key. Others need a base URL, model name, billing access, or project-level permission.

| Provider Type | What You Usually Need |
|---|---|
| OpenAI-compatible APIs | API key, base URL, model name |
| Claude / Anthropic | API key, billing, model access |
| Gemini | API key, project access, model name |
| OpenRouter | API key, model slug, route access |
| Groq | API key and supported model |
| Local models | Local host URL, port, installed model |

This is where many users make mistakes. They add a key, forget the model name or base URL, then wonder why OpenClaw behaves like a haunted calculator.

## Before You Add API Keys

Before connecting any provider, check these basics:

- Create an account with the provider
- Generate a fresh API key
- Confirm billing or free credits are active
- Check that your selected model is available
- Copy the key without extra spaces
- Keep the key private
- Never commit API keys to GitHub
- Use `.env` or environment variables where possible

Add your `.env` file to `.gitignore`:

```bash
echo ".env" >> .gitignore
```

This prevents your API keys from being pushed to a public repository. Simple, boring, and it protects paid credentials from strangers on the internet.

## Recommended API Key Format for OpenClaw

A clean `.env` file keeps provider setup easier to manage.

Example:

```bash
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GEMINI_API_KEY=your_gemini_key
OPENROUTER_API_KEY=your_openrouter_key
GROQ_API_KEY=your_groq_key
```

For OpenAI-compatible providers, you may also need a base URL and model name:

```bash
CUSTOM_PROVIDER_API_KEY=your_provider_key
CUSTOM_PROVIDER_BASE_URL=https://api.provider.com/v1
CUSTOM_PROVIDER_MODEL=model-name
```

| Value | Purpose |
|---|---|
| API key | Proves your account has access |
| Base URL | Tells OpenClaw where to send requests |
| Model name | Tells OpenClaw which model to use |

If any one of these is wrong, OpenClaw may return no output, model errors, or authentication failures.

## How to Add API Keys in OpenClaw

You can add API keys through the OpenClaw dashboard or through environment variables, depending on your setup.

### Option 1: Add API Keys Through OpenClaw Settings

Use this method if your OpenClaw setup has a dashboard or provider settings page.

Steps:

1. Open the OpenClaw dashboard
2. Go to model or provider settings
3. Select your provider
4. Paste the API key
5. Add the base URL if required
6. Select the model
7. Save the configuration
8. Test the provider before running workflows

### Option 2: Add API Keys Through Environment Variables

Use this method if you are running OpenClaw on a VPS, local machine, or server setup.

Open your `.env` file:

```bash
nano ~/.openclaw/.env
```

Add your provider keys:

```bash
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GEMINI_API_KEY=your_gemini_key
OPENROUTER_API_KEY=your_openrouter_key
GROQ_API_KEY=your_groq_key
```

Save the file, then restart the OpenClaw gateway so it picks up the new values:

```bash
openclaw gateway restart
```

If your setup runs OpenClaw as a systemd service, restart the service instead:

```bash
sudo systemctl restart openclaw
```

After restart, OpenClaw should load the new provider keys.

## Set the Default Provider and Model

Adding API keys is not enough. You also need to make sure OpenClaw knows which model to use by default.

List available models:

```bash
openclaw models list
```

Set your default model with `openclaw config set`:

```bash
openclaw config set agents.defaults.model.primary <provider>/<model-name>
```

Example:

```bash
openclaw config set agents.defaults.model.primary anthropic/claude-opus-4-6
```

Verify the change:

```bash
openclaw config get agents.defaults.model
```

The default model is used when a workflow does not specify a model manually.

For better results, use different models for different tasks:

| Task | Recommended Model Type |
|---|---|
| Simple chat | Fast, low-cost model |
| Summaries | Mid-range model |
| Coding | Strong reasoning model |
| Research | Large-context model |
| Browser automation | Reliable tool-calling model |

This helps reduce cost and improves workflow quality.

## Set Provider Fallbacks

A fallback provider helps OpenClaw continue working when the primary provider fails.

Provider failures can happen because of:

- Rate limits
- Billing problems
- Expired API keys
- Temporary provider outage
- Wrong model name
- Region restrictions
- Permission errors

Example fallback strategy:

| Workflow Type | Primary Provider | Fallback Provider |
|---|---|---|
| Coding agent | Claude or OpenAI | OpenRouter |
| Fast chat tasks | Groq | OpenAI-compatible provider |
| Research workflows | Gemini or OpenAI | Claude |
| Low-cost automation | Small model | Larger model only when needed |

A fallback provider prevents one failed key from killing the full workflow. It is a small setup step that saves you from very stupid debugging sessions later.

## How to Test Every API Key

Do not assume a provider works just because you pasted a key. Test it.

### Test 1: Check Available Models

```bash
openclaw models list
```

This checks whether OpenClaw can detect your provider and available models.

### Test 2: Confirm Provider Auth

```bash
openclaw models status
```

This shows which providers are authenticated and where each key is loaded from (env, config, or profile).

### Test 3: Run a Simple Reply Test

Send a one-line prompt to OpenClaw:

```
Reply with the active provider name and model name in one sentence.
```

This confirms the API key and model are working end to end.

### Test 4: Run a Tool-Calling Test

Use this prompt:

```
Create a short task plan with 3 steps and ask for approval before taking action.
```

This checks whether the selected model can follow agent-style instructions.

### Test 5: Run a Long Context Test

Use this prompt:

```
Summarize this long input into 5 bullets and keep the original meaning.
```

This helps test whether the model handles longer inputs correctly.

| Test | What It Checks |
|---|---|
| Model list | Provider connection |
| Models status | Auth source and validity |
| Simple reply | API key validity |
| Tool-calling test | Agent reliability |
| Long context test | Context handling |

## Common API Key Problems and Fixes

| Problem | What It Means | Fix |
|---|---|---|
| Invalid API key | Key is wrong, expired, or copied badly | Regenerate the key and paste it again |
| No output | Provider is connected but model failed | Check model name and logs |
| Model not found | Wrong model ID | Use the exact provider model name |
| 401 error | Authentication failed | Check API key and account access |
| 403 error | Key exists but lacks permission | Enable API access or billing |
| 429 rate limit | Too many requests | Use fallback or upgrade limits |
| Billing required | Provider requires payment method | Add billing or use another provider |
| Empty tool output | Model is weak at tool use | Switch to a better tool-capable model |

If OpenClaw still fails after fixing the key, check logs:

```bash
openclaw logs --follow
```

Or, if OpenClaw runs as a systemd service:

```bash
journalctl -u openclaw -f
```

Logs usually show whether the issue is authentication, billing, rate limit, or wrong model name.

## Provider-Specific Notes

### OpenAI

OpenAI-compatible setup usually needs:

- API key
- Correct model name
- Billing enabled
- Supported endpoint

Use OpenAI for general tasks, tool workflows, coding, and automation.

### Claude / Anthropic

Claude is useful for reasoning, coding, writing, and agent workflows.

Check:

- API key is active
- Billing is enabled
- Your account has access to the selected model
- Model name is correct

Claude may fail if your key is valid but model access is not enabled.

### Gemini

Gemini is useful for research, long-context work, and multimodal tasks.

Check:

- API key is active
- API access is enabled
- Project permissions are correct
- Model name matches the provider documentation

Wrong project setup can cause errors even when the key looks valid.

### OpenRouter

OpenRouter is useful when you want access to many models through one API key.

Check:

- OpenRouter API key is valid
- Model slug is correct
- Selected model is available
- Credits or billing are active

OpenRouter is good for fallback routing, but model quality can vary depending on the selected provider.

### Groq

Groq is useful for fast responses and low-latency workflows.

Check:

- API key is valid
- Model is supported
- Workflow does not require advanced reasoning beyond the model's strength

Groq is fast, but not every fast model is ideal for complex agent workflows.

### Local Models / Ollama

Local models usually do not need external API keys.

Check:

- Ollama or local runtime is running
- Model is installed
- Host URL and port are correct
- Model can handle OpenClaw workflow requirements

Example Ollama check:

```bash
ollama list
```

Run a model manually:

```bash
ollama run model-name
```

Local models can reduce API cost, but weaker models may fail at tool calling. Free is nice until your agent starts producing nonsense with confidence.

## API Key Security Best Practices

API keys are sensitive. Treat them like passwords.

Follow these rules:

- Never paste keys in public chats
- Never commit `.env` files
- Use separate keys for development and production
- Rotate leaked keys immediately
- Delete unused keys
- Use provider spending limits
- Review usage logs regularly

Before pushing code, check staged files:

```bash
git status
```

Check what will be committed:

```bash
git diff --cached
```

If `.env` appears, stop and remove it from Git tracking:

```bash
git rm --cached .env
```

Then commit again after confirming the key file is not included.

## Cost Control When Using Multiple Providers

Using multiple providers gives OpenClaw more flexibility, but it can also increase cost if you route everything to expensive models.

Use this simple strategy:

| Workflow | Best Model Choice |
|---|---|
| Reminders | Low-cost fast model |
| Short summaries | Mid-range model |
| Coding / debugging | Strong reasoning model |
| Browser automation | Reliable tool-calling model |
| Long research | Large-context model |
| Final review | Stronger model |

Cost control tips:

- Use cheap models for simple tasks
- Use stronger models only when needed
- Set spending limits in provider dashboards
- Avoid sending huge context to expensive models
- Use fallback models carefully
- Review provider usage weekly

The goal is not to use the strongest model for everything. That is how people turn a simple automation into a billing crime scene.

## When Manual API Key Setup Becomes Annoying

Manual setup is fine if you want full control. But it can become painful when you need to manage:

- Multiple `.env` files
- Provider-specific settings
- Server restarts
- Gateway issues
- Expired keys
- Failed workflows
- Rate limits
- Uptime
- Logs and monitoring

This is where many users stop building workflows and start debugging infrastructure instead. Very productive, if your goal is sadness.

## Easier Option: Run OpenClaw on Ampere.sh

If you want OpenClaw running without managing servers, ports, gateway setup, uptime, or manual provider configuration, use Ampere.sh.

With Ampere.sh, you can deploy OpenClaw in a managed environment, connect model providers, and start running workflows without spending hours fixing setup issues.

Use Ampere.sh if you want:

- Managed OpenClaw hosting
- Faster setup
- Easier provider configuration
- Always-on workflows
- Less server maintenance
- Fewer gateway and port issues
- A cleaner path from setup to real automation

Run OpenClaw on Ampere.sh and spend less time fixing keys, configs, and failed provider connections.

## Frequently Asked Questions

**What API keys do I need for OpenClaw?**
You need API keys for the model providers you want to use, such as OpenAI, Claude, Gemini, OpenRouter, Groq, or other OpenAI-compatible providers.

**Can I use multiple API providers in OpenClaw?**
Yes. Using multiple providers can improve reliability, reduce cost, and give OpenClaw fallback options when one provider fails.

**Why is my OpenClaw API key not working?**
Common reasons include a wrong key, expired key, missing billing, wrong model name, missing base URL, or provider permission issues.

**Can I use OpenRouter with OpenClaw?**
Yes. OpenRouter can be useful when you want access to many models through one API key. Make sure you use the correct model slug.

**How do I safely store OpenClaw API keys?**
Store keys in environment variables or a .env file. Never commit keys to GitHub, and rotate keys immediately if they leak.

**Do I need to restart OpenClaw after adding an API key?**
Usually yes. If OpenClaw loads keys from environment variables or the .env file at startup, restart the gateway so it picks up the new value.

**Which provider should I pick first?**
Start with whichever provider you already have credits or an account on. Anthropic Claude and OpenAI are good defaults for agent workflows. Add OpenRouter or Groq later for fallback or low-cost tasks.