OpenClaw runs AI agents across Telegram, Discord, Slack, Signal, iMessage, and WhatsApp from one place. It’s open source and it needs a model provider behind it. Point it at one provider directly and you own that relationship: one key, one bill, and an agent that stops the moment that provider has a bad minute.

OpenClaw ships with built-in OpenRouter support, so one key reaches 300+ models across 70+ providers, billing lands in one place, and requests fail over to another provider automatically. The connection is a single command. This guide covers that setup, then the model format, failover, cost controls, and the errors that come up most.

Connect OpenClaw to OpenRouter in one command

Run the onboard command with your key:

openclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY"

That writes your credential to ~/.openclaw/openclaw.json and sets the openrouter/auto model. You’re connected.

If you’d rather edit the config by hand, the file lives at ~/.openclaw/openclaw.json under the home directory of the user running OpenClaw. A minimal config needs your key and one model:

{
  "env": {
    "OPENROUTER_API_KEY": "sk-or-..."
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/openrouter/auto"
      },
      "models": {
        "openrouter/openrouter/auto": {}
      }
    }
  }
}

On a server, set the key in the env block rather than a shell profile. A service that runs under a different user or shell won’t pick up an interactive profile, and the env block is injected with the process at start time. To change the key later, edit env.OPENROUTER_API_KEY and restart with openclaw gateway run.

Then confirm your models loaded:

openclaw models list

OpenClaw references OpenRouter models as openrouter/<author>/<slug>. Prefix the author with ~ to track the latest version in a family, or drop it to pin an exact version. Check the current slug on the models page before you commit one, since identifiers change as new versions ship.

Append a variant suffix to change routing on the same model. :free routes to a free endpoint, :nitro sorts providers by throughput, and :thinking asks for extended reasoning. To change an agent’s model later, update agents.defaults.model.primary and restart the gateway.

The Auto Router is referenced as openrouter/openrouter/auto: the author is openrouter and the model is auto. That double openrouter is easy to get wrong, and it’s the fix for the unknown model error below.

Keep agents running when a provider drops

A one-off API call that fails is easy to retry. An OpenClaw agent holding state across a multi-step Telegram conversation is not, since a mid-run failure can leave a message that looks sent but wasn’t, or a tool call that never returned. OpenRouter handles that at two levels.

Provider failover is automatic. Most models are served by more than one provider, and if the first one OpenRouter tries is down or rate-limiting you, it routes the same request to another. You don’t configure it, and you’re billed only for the request that completes.

Model fallbacks cover the case where a model is unavailable everywhere. Add a fallbacks array and OpenRouter tries each model in order:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/~anthropic/claude-sonnet-latest",
        "fallbacks": [
          "openrouter/~google/gemini-flash-latest",
          "openrouter/deepseek/deepseek-chat"
        ]
      }
    }
  }
}

The two stack. Provider failover swaps providers behind one model; the fallback array swaps models entirely. Check the model field in the response to see which one ran. See the model fallbacks docs for the full configuration.

If your prompts carry data-residency or compliance requirements, restrict routing to providers that don’t retain request data using the data_collection and zdr provider-routing controls. The provider selection docs cover the parameters, and provider logging lists which providers qualify.

Match models to agents to control cost

Running one capable model for every agent action wastes money on work that doesn’t need it. A research agent reading long documents needs a frontier model. A summarizer handling short text runs fine on a free Llama. A bot fielding quick questions runs fine on Gemini Flash.

The Auto Router (openrouter/openrouter/auto), powered by NotDiamond, picks a cost-effective model per request and charges that model’s standard rate with no extra routing fee. It’s a good default for agent traffic that’s mostly low-stakes work like heartbeats and status checks.

When you want explicit control, OpenClaw lets you split models by agent. Set a per-agent override under agents.overrides.<name>.model:

{
  "agents": {
    "overrides": {
      "researcher": {
        "model": { "primary": "openrouter/anthropic/claude-opus-4.6" }
      },
      "summarizer": {
        "model": { "primary": "openrouter/meta-llama/llama-3.3-70b-instruct:free" }
      }
    }
  }
}

On cost: OpenRouter doesn’t mark up provider pricing. On pay-as-you-go the platform fee is 5.5%, and that one fee covers unified billing, failover, and one key across every provider. For low-stakes actions, 20+ free models cost nothing per token. If you bring your own provider keys, the BYOK fee is 5%, waived for the first 1M requests each month. Track spend per model on the Activity dashboard.

The unified endpoint earns its keep once you run more than one model, want requests to survive an outage, or want to switch models by editing a string.

Fix the most common connection errors

“No API key found for provider ‘openrouter’” means the key isn’t reaching OpenClaw. Run echo $OPENROUTER_API_KEY to check it, verify your auth config with openclaw auth list, or re-run the onboard command. On a VPS, the usual cause is the variable loading in your interactive shell but not in the service’s shell, so set it in the config env block.

“unknown model: openrouter/auto” means the Auto Router reference is wrong. Use openrouter/openrouter/auto and list it under agents.defaults.models. OpenClaw expects the full openrouter/<author>/<slug> path.

“OpenRouter not responding” means requests are going out with nothing coming back. Work through four checks: confirm your credit balance at openrouter.ai/keys, run openclaw models list to confirm the slug resolves, run openclaw logs --follow to read the actual error, and make sure your host can reach https://openrouter.ai/api/v1. An egress rule blocking that host produces exactly this no-response.

401 or 403 errors are account-side: the key is invalid, revoked, or out of credits. Check it at openrouter.ai/keys, update env.OPENROUTER_API_KEY, and restart the gateway.

Frequently asked questions

How do I connect OpenClaw to OpenRouter?

Run openclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY". It writes your credential and sets the openrouter/auto model. You don’t need a base URL or a models.providers block.

What model-reference format does OpenClaw use?

openrouter/<author>/<slug>, for example openrouter/deepseek/deepseek-chat. Add a ~ before the author to track the latest version in a family (openrouter/~anthropic/claude-sonnet-latest), or append :free, :nitro, or :thinking to change routing behavior.

How do I fix “unknown model: openrouter/auto”?

Use openrouter/openrouter/auto and list it under agents.defaults.models. OpenClaw expects the full openrouter/<author>/<slug> path, and the Auto Router’s author is openrouter.

Can I use free OpenRouter models with OpenClaw?

Yes. Append :free to the reference, such as openrouter/meta-llama/llama-3.3-70b-instruct:free. Pair it with a fallback so the agent keeps running when a free slot is busy.

Do I need to set a base URL for OpenClaw?

No. OpenClaw’s built-in OpenRouter support handles routing internally. Set the API key and reference models with openrouter/<author>/<slug>.