OpenClaw Model Setup: Providers and Authentication

OpenClaw is the body, and the AI model is the brain. This guide shows how to connect a model provider such as Anthropic, OpenAI, Google, OpenRouter or a local model, which sign-in method to use, how to set a default with automatic fallbacks, and how to keep your API keys safe.

Quick answer

Put your key in ~/.openclaw/.env (for example ANTHROPIC_API_KEY=…), pick a model with openclaw models set <provider/model>, add a backup with openclaw models fallbacks add, and confirm with openclaw models status --probe.

The basics

How models work in OpenClaw

provider/model

Every model has a reference like ollama/gemma4: the provider, a slash, then the model ID.

Default + fallbacks

One primary model, plus backups OpenClaw tries if the primary fails or is rate limited.

Per agent

Each agent can use its own model, such as a cheap one for chat and a strong one for research.

Text and image

Separate defaults for text and for image generation.

Thinking levels

Ask for deeper reasoning on hard problems, if the model supports it.

Swap any time

Change models without touching your channels, skills or memory.

Two different keys

Your model provider key, covered on this page, lets OpenClaw talk to an AI. Your gateway token lets your own apps talk to OpenClaw. See the API guide for that one.

Providers

Choose a model provider

OpenClaw bundles the major providers and supports more than 40 others. The most common choices:

ANTHROPIC_API_KEYAnthropic

Claude models. Popular with OpenClaw users for tool use and long tasks.

Claude guide →
OPENAI_API_KEYOpenAI

GPT models, by API key or ChatGPT/Codex sign-in.

OpenAI guide →
GEMINI_API_KEYGoogle Gemini

Gemini models by API key, Vertex, or the Gemini CLI runtime.

Gemini guide →
OPENROUTER_API_KEYOpenRouter

One key for many models from different labs. Handy for experimenting.

OLLAMA_API_KEYOllama

Run open models on your own machine, or use Ollama Cloud.

Local models →
custom base URLLM Studio, vLLM

Local inference servers, connected through a custom provider base URL.

Local models →

The variable names follow one pattern: <PROVIDER>_API_KEY. Run openclaw models list to see every model you can use, with exact IDs.

Authentication

Ways to sign in to a model provider

MethodHow it worksBest for
API key recommendedPaste a key into ~/.openclaw/.env. You pay per use.Always-on gateways and servers
Claude CLI reuseRoute Anthropic models through an existing local Claude Code sign-inMachines that already use Claude Code
Setup tokenA long-lived Anthropic token from claude setup-tokenHeadless servers without a browser
ChatGPT / Codex OAuthSign in with your OpenAI account in the browserPeople who use ChatGPT
Gemini CLI runtimeUse Google's Gemini CLI sign-inGemini CLI users
Secret storeReference keys from an external secret manager (keyRef)Teams and production
Local, no keyOllama, LM Studio or vLLM on your networkPrivacy and zero per-message cost

Using a consumer subscription instead of an API key? Check your provider's current terms for use with third-party tools, and its usage limits. For an assistant that runs 24/7, the official docs recommend API keys as the simplest option.

Setup helper

Get the exact commands for your provider

Provider
Sign-in method
Anthropic · API key
    1
    Step 1

    Add your provider API key

    Create a key in your provider's dashboard and set a monthly spending limit there. Then add it to OpenClaw's environment file so the background service can read it:

    ~/.openclaw/.env
    ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...
# GEMINI_API_KEY=...
# OPENROUTER_API_KEY=...

    The onboarding wizard (openclaw onboard) can do this for you. Settings › Models in the Control UI works too.

    2
    Step 2

    Pick your default model

    List what's available, then set the default:

    Terminal
    openclaw models list
openclaw models set <provider/model>

    Or set it in your config file:

    ~/.openclaw/openclaw.json (JSON5)
    {
  agents: {
    defaults: {
      model: { primary: "ollama/gemma4" },
    },
  },
}

    Image generation has its own default: openclaw models set-image <model>. Add --agent <id> to any models command to change one agent only.

    3
    Step 3

    Add fallback models

    If your primary model is down, rate limited or out of credit, OpenClaw moves down the fallback chain so your assistant keeps working.

    Terminal
    openclaw models fallbacks add <provider/model>
openclaw models fallbacks list
    PrimaryYour best model
    Fallback 1Another provider
    Fallback 2Local or low-cost

    Use a different provider for your first fallback, so one company's outage doesn't take your assistant offline.

    4
    Step 4

    Verify everything works

    Terminal
    openclaw models status          # default, fallbacks and auth overview
openclaw models status --probe  # live test against each provider
openclaw models status --check  # exit code: 0 ok, 1 missing/expired, 2 expiring

    --check is handy in scripts or monitoring to catch expiring credentials before your assistant stops answering.

    Anthropic options

    Claude CLI reuse and setup tokens

    If Claude Code is installed on the same machine, route Anthropic models through its sign-in:

    Terminal
    claude auth login
openclaw models auth login --provider anthropic --method cli --set-default
    Local AI

    Use a local model with Ollama

    1. Install Ollama and pull a model:
      Terminal
      ollama pull gemma4
    2. Set a placeholder key for a local Ollama. Use a real key only for Ollama Cloud.
      ~/.openclaw/.env
      OLLAMA_API_KEY=ollama-local
    3. Make it the default:
      Terminal
      openclaw models set ollama/gemma4
    Use Ollama's native address

    Point OpenClaw at http://127.0.0.1:11434, not the OpenAI-compatible /v1 endpoint, which breaks tool calling. Onboarding offers Local only, Cloud only, or Cloud + Local.

    LM Studio and vLLM connect as custom providers with a base URL under models.providers. Hardware advice: local models guide and system requirements.

    Heavy use

    API key rotation for rate limits

    Give OpenClaw several keys for the same provider. It switches to the next one only on rate-limit errors: 429, quota exceeded or resource exhausted. Keys are picked in this order:

    1. OPENCLAW_LIVE_<PROVIDER>_KEYA single override
    2. <PROVIDER>_API_KEYSSeveral keys, separated by commas, spaces or semicolons
    3. <PROVIDER>_API_KEYThe standard single key
    4. <PROVIDER>_API_KEY_*Any variable with this prefix
    ~/.openclaw/.env
    ANTHROPIC_API_KEYS=sk-ant-key-one,sk-ant-key-two
    Keep keys safe

    Protect your API keys and your wallet

    A leaked key can run up a large bill in hours. A few habits prevent most problems.

    More: what OpenClaw costs to run · security guide

    Troubleshooting

    Fix common model and key problems

    401 / invalid API key

    The key is wrong, revoked or for another provider. Check it with openclaw models status --probe.

    Works in terminal, not in background

    The service doesn't see your shell's variables. Put keys in ~/.openclaw/.env and restart the gateway.

    429 / quota exceeded

    You hit a rate or spending limit. Add a fallback model or extra keys for rotation, or raise your limit.

    Unknown model

    Use the exact reference from openclaw models list, or run openclaw models refresh to update the catalog.

    Ollama ignores tools

    You're using the /v1 endpoint. Switch to the native http://127.0.0.1:11434 address, and use a model that supports tool calling.

    Credentials expiring

    OAuth and CLI sign-ins expire. openclaw models status --check returns 2 when they're about to, so log in again.

    More fixes: troubleshooting guide.

    FAQ

    OpenClaw model setup questions

    Which AI models does OpenClaw support?

    OpenClaw is model-agnostic. It bundles Anthropic, OpenAI, Google Gemini and OpenRouter, supports more than 40 other providers, and runs local models through Ollama, LM Studio and vLLM.

    How do I add an API key to OpenClaw?

    Add it to ~/.openclaw/.env as PROVIDER_API_KEY, for example ANTHROPIC_API_KEY, or enter it during openclaw onboard or in Settings, Models. Then check it with openclaw models status --probe.

    How do I change the default model?

    Run openclaw models list to see available models, then openclaw models set followed by the provider/model reference. You can also set agents.defaults.model.primary in your config.

    What are fallback models?

    Backup models OpenClaw tries when the primary model fails or is rate limited. Add them with openclaw models fallbacks add, ideally from a different provider.

    Can I use OpenClaw without paying for an API?

    Yes, by running a local model with Ollama, LM Studio or vLLM. You need capable hardware, and local models are usually less reliable at complex multi-step tasks than top hosted models.

    Can different agents use different models?

    Yes. Add --agent with the agent ID to openclaw models commands to give each agent its own default and fallbacks.

    Model guides

    ClaudeAnthropic models OpenAIGPT models GeminiGoogle models Local modelsPrivate and offline