How to Set Up Your OpenClaw Model Provider (Step-by-Step)

Key takeaways

• OpenClaw doesn't include an AI model. It routes your requests to whichever provider you configure.
• You need at least one API key from Anthropic, OpenAI, or Google before the agent will respond.
• Keys go in openclaw.json under env, or in ~/.openclaw/.env for daemon setups.
• openclaw onboard is the fast path. One command and you're done.
• Run openclaw doctor after setup to confirm the connection is working.

Why OpenClaw needs a model provider configured before it can respond

OpenClaw is a routing layer, not a model. When you send it a message, it forwards that message to whichever AI provider you've configured, gets back a response, and relays it to you. Without a provider key, there's nowhere to route the request, so it either errors or hangs silently. (docs.openclaw.ai)

This is intentional. Separating the agent infrastructure from the model means you control which model runs, what it costs, and how it behaves. You can switch providers, run failover chains, or mix models per task. But only after you've given OpenClaw at least one set of credentials.

Installation doesn't include this step. If you followed the install guide and stopped there, adding a model provider is what's missing.

How to get an Anthropic API key for OpenClaw

Go to console.anthropic.com/settings/keys and create a new key. Your key will start with sk-ant- and will be shown exactly once. Copy it to a safe place before closing that page.

A few things to know before you start:

• New Anthropic accounts receive $5 in free credits, but billing must be added to your account before the key actually works. (Anthropic pricing) Skip this and requests will fail even with a valid key.
• Free credits expire, so don't wait weeks before testing.
• The key is visible only at creation time. If you lose it, you'll need to revoke it and create a new one.

Once you have the key, you can paste it into openclaw.json manually or pass it to openclaw onboard --anthropic-api-key "sk-ant-..." for automated setup. (docs.openclaw.ai)

How to get an OpenAI API key for OpenClaw

Go to platform.openai.com/api-keys and create a new secret key. OpenAI keys start with sk- and are also shown only once.

A couple of things worth noting:

• Billing is managed at platform.openai.com/settings/organization/billing. You need a funded account or payment method attached before API calls succeed.
• OpenAI's free tier is limited. Budget a small amount (a few dollars) before starting, especially if you plan to test with GPT-4o.
• Like Anthropic, you won't see the key again after creation. Copy it immediately.

How to get a Google AI Studio API key for OpenClaw

Go to aistudio.google.com, sign in with a Google account, and generate an API key from the left sidebar. Google AI Studio has a free tier that covers a reasonable number of requests per day, which makes it useful for testing.

One common issue: if you get a 403 Forbidden error when using your Google key with OpenClaw, it usually means the Gemini API isn't enabled in your Google Cloud Console. Go to the APIs & Services section, find the Generative Language API, and enable it. (getopenclaw.ai)

Google keys start with AIza. Same rule applies: copy it as soon as you create it.

How to add your API key to openclaw.json

Fast path: openclaw onboard

The recommended way to add your first provider key is openclaw onboard. It walks you through provider selection and key entry interactively: (docs.openclaw.ai)

openclaw onboard

For non-interactive setups (scripts, CI, server provisioning):

openclaw onboard --anthropic-api-key "sk-ant-..."

Manual path: edit openclaw.json

If you prefer direct config edits, open your openclaw.json. On most systems the config lives at ~/.openclaw/openclaw.json. Some systems may use ~/.config/openclaw/openclaw.json5 instead.

Add your key under the env block:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-..."
  }
}

For OpenAI:

{
  "env": {
    "OPENAI_API_KEY": "sk-..."
  }
}

For Google:

{
  "env": {
    "GOOGLE_API_KEY": "AIza..."
  }
}

You can have all three set at the same time. OpenClaw uses whichever one matches the model you've set as your default.

Daemon setup: use the .env file

For always-on gateway hosts (systemd, launchd, Docker), environment variables are often better managed outside the JSON config. Put your keys in ~/.openclaw/.env: (docs.openclaw.ai)

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=AIza...

Common mistake

Keys must go inside the env block. Placing them at the top level or inside agents is the most frequent config error. The key won't be picked up and you'll get auth failures with no clear error message. (getopenclaw.ai)

After editing the config, restart the gateway for changes to take effect.

How to set your default OpenClaw model

The default model is controlled by agents.defaults.model.primary in your openclaw.json: (docs.openclaw.ai)

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6"
      }
    }
  }
}

Provider prefix format for each provider:

To see all available models from your configured providers, run:

openclaw models list

How to configure OpenClaw model failover

Failover lets OpenClaw automatically switch to a backup model when the primary isn't available. It's configured in agents.defaults.model.fallbacks: (docs.openclaw.ai)

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

OpenClaw uses a two-stage failover process. First, if you have multiple API keys for the same provider (via auth profile rotation), it tries those in round-robin order. Oldest-used first, OAuth keys before API keys. Only if all auth profiles for the primary provider fail does it move on to the next model in the fallbacks list. (docs.openclaw.ai)

Billing failures get special treatment. If a provider returns a billing error, OpenClaw starts a backoff: it won't retry that provider for 5 hours, then 10, then 20, capping at 24 hours. This prevents a billing issue from hammering the provider and running up error counts. (docs.openclaw.ai)

Auth profiles also maintain session stickiness. Once a session is assigned to a particular profile, it stays on that profile for cache warmth. Failover only breaks stickiness when all profiles for that model fail.

Which OpenClaw model provider should you start with?

Start with Anthropic and Claude Sonnet 4.6. It handles the widest range of tasks well (coding, writing, multi-step reasoning, tool use) and it's what most OpenClaw configurations are tested against. (docs.openclaw.ai) The cost-to-quality ratio is solid for everyday use.

That said, the right choice depends on what you're doing:

• Claude Sonnet 4.6 is the best default for most users. Strong reasoning, good with tools, reliable with long context.
• GPT-4o-mini is a good fit when you're running high volumes of simple tasks and want to keep costs down.
• Gemini 3 Pro has a 1M-token context window, which makes it useful for document analysis, large codebases, or anything that would overflow other models.

Monthly cost estimates (light / moderate / heavy usage). Based on current published API rates from Anthropic and OpenAI:

These are rough ranges. Your actual costs depend heavily on message volume and context length. Check Anthropic pricing and OpenAI pricing for current per-token rates. For tighter spending control, see the OpenClaw cost control guide.

If you're still deciding on your setup, the OpenClaw Starter Kit includes recommended config templates for each provider, including pre-tuned failover chains.

How to verify your OpenClaw model provider is working

Once you've added your key and set a default model, run two commands to confirm everything is connected:

openclaw models status

This shows which providers are configured, whether their keys are valid, and the current reachability of each. (docs.openclaw.ai)

openclaw doctor

openclaw doctor runs a broader health check across your full OpenClaw config. It flags missing keys, misconfigured sections, unreachable providers, and other common issues. It's the fastest way to confirm the gateway is ready. See the OpenClaw doctor command guide for full output details.

openclaw models list

Lists all models available from your configured providers. If a provider's key is invalid or the API isn't reachable, its models won't appear here. That's a quick way to spot which provider isn't working.

How to check OpenClaw model usage and API costs

OpenClaw doesn't track spend directly, but each provider has usage dashboards:

• Anthropic: console.anthropic.com shows token usage and billing per period.
• OpenAI: platform.openai.com/usage has a detailed per-model breakdown.
• Google: usage is visible under APIs & Services in console.cloud.google.com.

For agent-level tracking (which OpenClaw task used what), check the OpenClaw cost control guide. It covers budget limits, per-task model routing, and how to avoid surprise bills when leaving an agent running overnight.

Key terms

Model provider is an external AI service (Anthropic, OpenAI, or Google) that supplies the language model OpenClaw routes requests to.

API key is a credential string that authenticates your requests to a provider's API. In OpenClaw, it goes in the env block of openclaw.json.

Model primary is the first-choice model OpenClaw uses for a given request, set in agents.defaults.model.primary.

Failover is the process of switching to a backup model or auth profile when the primary is unavailable, configured in agents.defaults.model.fallbacks.

Auth profile rotation is OpenClaw's behavior of cycling through multiple API keys for the same provider before falling back to a different model.

Billing backoff is a hold period OpenClaw applies when a provider returns a billing error, starting at 5 hours and doubling up to a 24-hour cap.

FAQ

Does OpenClaw work without any API key?

No, OpenClaw requires at least one provider API key before it can respond to messages. The gateway can start and run without a key configured, but any agent request will fail. You'll need to add a key from Anthropic, OpenAI, or Google and restart the gateway before the agent becomes functional.

Can I use more than one model provider at the same time in OpenClaw?

Yes. OpenClaw supports multiple providers simultaneously. You can set a primary model from one provider and fallback models from others. Keys for all three providers (Anthropic, OpenAI, Google) can coexist in your env block. Different workflows or tasks can be routed to different providers using OpenClaw's model routing config.

Why is my Anthropic key valid but OpenClaw still won't respond?

The most common cause is a missing billing method on your Anthropic account. New accounts receive $5 in free credits, but billing must be enabled before the key works. (Anthropic pricing) Go to console.anthropic.com, add a payment method, and try again. The second most common cause is the key being placed in the wrong section of openclaw.json.

What does a Google 403 Forbidden error mean in OpenClaw?

A 403 error from Google means the Gemini API isn't enabled in your Google Cloud Console. Your key is valid, but the API isn't active for your project. Go to console.cloud.google.com, open APIs & Services, search for "Generative Language API," and enable it. The error clears immediately once you enable it.

Where exactly does OpenClaw's openclaw.json live?

On most systems it's at ~/.openclaw/openclaw.json. Some configurations use ~/.config/openclaw/openclaw.json5 instead. Run openclaw doctor to see which config file OpenClaw is reading. The output includes the resolved config path.

Related resources

• OpenClaw cost control: manage API spending without killing your agent
• OpenClaw CLI commands reference
• OpenClaw doctor command guide
• OpenClaw troubleshooting guide
• OpenClaw Telegram setup guide

Changelog