OpenClaw OpenRouter: Base URL, Model Routing and Fallback Checks

Who this is for

Developers using OpenClaw as a coding agent and routing requests through OpenRouter for access to multiple models. If you are comparing routes, choosing a fallback model or checking why one provider path fails while another works, this guide is for you.

What OpenClaw and OpenRouter do together

OpenClaw is an open-source AI agent platform that connects to messaging channels and executes tasks. OpenRouter is an aggregator that routes model requests to underlying providers through a single OpenAI-compatible API. OpenClaw has built-in OpenRouter support - you do not need to manually configure a models.providers entry.

The key configuration points are your OpenRouter API key, the openrouter/ model ID format, and the openclaw gateway run command to apply changes. Credits, model availability and token usage are tracked in the OpenRouter Activity dashboard.

Recommended setup with openclaw onboard

The easiest way to configure OpenClaw with OpenRouter is the built-in setup wizard. Run this command and follow the prompts:

openclaw onboard

The wizard guides you through choosing OpenRouter as the provider, entering your API key, selecting a primary model, and configuring messaging channels.

If you already have your OpenRouter API key and want to skip the wizard, use the one-line command:

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

After configuration, start or restart the gateway:

openclaw gateway run

Let openclaw onboard select the current recommended model, then inspect the generated configuration. OpenRouter and OpenClaw documentation may reference different Auto model IDs across versions - for example openrouter/auto versus openrouter/openrouter/auto. Verify the value in your ~/.openclaw/openclaw.json against the OpenClaw version you have installed.

Manual configuration

For advanced users who prefer to edit the config file directly, OpenClaw stores its configuration at ~/.openclaw/openclaw.json. A minimal working configuration with OpenRouter looks like this:

{
  "env": {
    "OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/auto"
      },
      "models": {
        "openrouter/auto": {}
      }
    }
  }
}

Example only - verify the current model ID for your installed OpenClaw version. OpenRouter and OpenClaw documentation may reference different Auto model IDs across versions.

Set the API key as an environment variable in your shell profile instead of committing it to the config file:

export OPENROUTER_API_KEY="<YOUR_OPENROUTER_API_KEY>"

After any configuration change, restart the gateway:

openclaw gateway run

OpenClaw has built-in OpenRouter support. You do not need to add a models.providers section for OpenRouter. Just set the API key and reference models using the openrouter/ prefix.

Using auth profiles for key security

Instead of storing the key directly in openclaw.json, use OpenClaw auth profiles to store the key in your system keychain. Add this to openclaw.json:

{
  "auth": {
    "profiles": {
      "openrouter:default": {
        "provider": "openrouter",
        "mode": "api_key"
      }
    }
  }
}

Then set the key using the CLI:

openclaw auth set openrouter:default --key "$OPENROUTER_API_KEY"

This keeps your API key out of any config file. Do not commit API keys to shared repositories or paste them into public screenshots.

Model ID format in OpenClaw

OpenClaw uses the format openrouter/<author>/<slug> for all OpenRouter models. The OpenRouter model catalog shows IDs differently - OpenClaw requires the openrouter/ prefix. This is a common source of model not found errors.

Key rules:

• Always prefix OpenRouter model IDs with openrouter/ in OpenClaw config.
• Use ~author for latest-family aliases, e.g. openrouter/~anthropic/claude-sonnet-latest.
• The catalog ID shown on openrouter.ai/models without the openrouter/ prefix will cause model not found in OpenClaw.
• Model availability and IDs can change - verify the current ID at openrouter.ai/models before every significant run.

Example model IDs in OpenClaw format (verify before use):

• openrouter/auto - OpenRouter Auto model, picks the most cost-effective model per request.
• openrouter/~anthropic/claude-sonnet-latest - Latest Claude Sonnet in the Anthropic family.
• openrouter/deepseek/deepseek-chat - DeepSeek Chat model.

Example only - verify the current model ID before publishing or deploying.

Primary and fallback models

Set a primary model and add fallbacks as an ordered list. OpenClaw tries them in sequence. Both the primary and every fallback must also be listed in agents.defaults.models:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/auto",
        "fallbacks": [
          "openrouter/deepseek/deepseek-chat"
        ]
      },
      "models": {
        "openrouter/auto": {},
        "openrouter/deepseek/deepseek-chat": {}
      }
    }
  }
}

Example only - verify the current model IDs for your installed OpenClaw version. OpenRouter and OpenClaw documentation may reference different Auto model IDs across versions.

This provides an additional layer of reliability on top of OpenRouter provider-level failover. A successful fallback run is billed at that model rate. OpenRouter states that failed routing or fallback attempts are not billed, and zero-completion error responses may be protected by Zero Completion Insurance. Check the Activity dashboard for the final billing record. Do not configure fallback models that are unavailable in your account tier.

Built-in OpenRouter provider vs other gateways

There are two distinct setup paths for OpenClaw model routing:

OpenClaw built-in OpenRouter provider

• Use openclaw onboard and select OpenRouter.
• Provider is OpenRouter; API key is OPENROUTER_API_KEY.
• Model IDs use the openrouter/<author>/<slug> format.
• No models.providers configuration needed.

Third-party OpenAI-compatible gateway

• May require a manual Base URL and a different API key.
• Model aliases are provider-specific and may not use the openrouter/ format.
• Provider-level error handling, routing, credits and model availability differ from OpenRouter.

RutaAPI is an independent alternative gateway. It is not OpenRouter, and the OpenRouter onboarding steps above do not configure RutaAPI. RutaAPI setup and routing rules are separate from OpenClaw OpenRouter integration.

Monitoring and credits

Track OpenClaw usage through the OpenRouter Activity dashboard at openrouter.ai/activity. This shows:

• Token usage and cost per model.
• Request counts and response codes.
• Request counts and response codes, including any routing or fallback attempts.
• Current credits balance.
• Per-model availability status.

OpenClaw token usage can grow quickly because it sends full conversation history on each turn, includes file reads and tool outputs in the prompt, and retries failed requests with the same context. Monitor the Activity dashboard during early test runs and compare token counts against your expectations before scaling.

A successful fallback run is billed at that model rate. OpenRouter states that failed routing or fallback attempts are not billed, and zero-completion error responses may be protected by Zero Completion Insurance. Check the Activity dashboard for the final billing record.

Security checklist

• Store the OpenRouter API key in an environment variable or via openclaw auth set - not in the config file or any committed source.
• Do not paste real API keys into public screenshots or shared documents.
• Use the minimum required permission scope when generating API keys.
• Review file and shell tool permissions in OpenClaw configuration - OpenClaw can execute commands on your machine.
• Conversation history may be logged by model providers; avoid including sensitive credentials or proprietary code in prompts.
• Sanitize untrusted inputs to reduce prompt injection risk.

FAQ

Does OpenClaw support OpenRouter?

Yes. OpenClaw has built-in OpenRouter support. The recommended way to configure it is to run openclaw onboard and select OpenRouter as the provider. OpenClaw does not need manual models.providers configuration for OpenRouter.

What model ID format does OpenClaw use for OpenRouter?

OpenClaw requires the openrouter/ prefix. Format: openrouter/<author>/<slug>. Use tilde-author for latest-family aliases, e.g. openrouter/~anthropic/claude-sonnet-latest. Without the openrouter/ prefix, OpenClaw returns model not found even if the catalog ID is valid on openrouter.ai/models.

Where should I store the OpenRouter API key?

The safest options are: (1) set it as an environment variable in your shell profile, (2) use openclaw auth set to store it in your system keychain via an auth profile. Both keep the key out of your openclaw.json config file and out of any shared or committed files.

Can OpenClaw use fallback models?

Yes. Set a primary model and add fallback models to the fallbacks array. Both the primary and every fallback must also be listed in agents.defaults.models. OpenClaw tries them in order. A successful fallback run is billed at that model rate. OpenRouter states that failed routing or fallback attempts are not billed, and zero-completion error responses may be protected by Zero Completion Insurance.

Why does a model work in OpenRouter but not in OpenClaw?

The most common reason is a missing openrouter/ prefix in the model ID. OpenClaw requires the full openrouter/<author>/<slug> format, which is different from the catalog ID shown on openrouter.ai/models. Verify the exact OpenClaw-format model ID before configuring.

Do I need to configure models.providers for OpenRouter?

No. OpenClaw has built-in OpenRouter support. You do not need to add a models.providers section for OpenRouter. Set OPENROUTER_API_KEY, choose your model IDs in the openrouter/ format, and run openclaw gateway run.

Do failed requests to OpenRouter cost credits?

OpenRouter states that failed routing or fallback attempts are not billed, and zero-completion error responses may be protected by Zero Completion Insurance. A successful request - even if it returns an error from the model - is typically billed. Check the OpenRouter Activity dashboard to see exactly which requests were charged.

Related guides

OpenClaw API Key

Use this for the generic key, Base URL and provider access checks.

Claude Code Token Cost

What drives token cost when using Claude through OpenRouter.

LLM Observability

Trace request IDs, token usage and billing signals.