How to Set Up OpenClaw with OpenRouter Multi-Provider Routing

OpenClaw supports multiple LLM providers directly, including Anthropic, OpenAI, and Google. Each provider requires its own API key, billing account, and configuration. OpenRouter consolidates all of them behind a single endpoint and API key.

That consolidation matters for three reasons.

First, you get access to models from every major provider without managing separate accounts. One API key routes to Claude, GPT, Gemini, DeepSeek, Llama, and hundreds of other models.

Second, OpenRouter handles provider-level failover automatically. If one provider's endpoint goes down or hits capacity, OpenRouter routes to another provider hosting the same model. Your agent keeps working without manual intervention.

Third, you can mix models by task type. A coding agent doesn't need a $30-per-million-token frontier model for every heartbeat check or classification task. OpenRouter lets you route expensive reasoning requests to Claude Opus while sending simple tasks to Gemini Flash-Lite at $0.50 per million tokens. The VelvetShark multi-model routing guide documents savings of 62-65% for teams that implement task-based routing.

OpenClaw's OpenRouter integration is a first-class provider. You don't need custom API adapters or proxy configurations. Set the API key, pick your models, and the agent handles the rest.

Start by creating an API key at openrouter.ai/keys. Name it something you'll recognize later, like "OpenClaw Production," and copy the key immediately.

OpenClaw's onboarding flow walks you through provider selection. Choose OpenRouter as your provider and paste the API key when prompted. The setup writes your key to the local configuration and defaults to openrouter/auto for model selection. For headless environments like CI pipelines or Docker containers, you can export the key as an environment variable instead. Check the official OpenClaw OpenRouter docs for the exact variable name and non-interactive setup steps.

After onboarding, verify the connection by checking your model status in the CLI. You should see your OpenRouter key recognized and a default model assigned. If both appear, you're ready to go.

Switching models after onboarding

The openrouter/auto default works immediately, but you can change the primary model at any time. Model references follow the openrouter/<provider>/<model> format, such as openrouter/anthropic/claude-sonnet-4 or openrouter/google/gemini-3-flash. OpenClaw normalizes them to lowercase automatically, so capitalization doesn't matter. You can also browse available models or scan OpenRouter's free catalog directly from the CLI. See the official docs for the full list of configuration options.

OpenClaw's default openrouter/auto setting delegates model selection to OpenRouter's Auto Router. The Auto Router analyzes each prompt's complexity and picks a model that balances cost and capability. Simple prompts go to cheaper models. Complex multi-step reasoning goes to frontier models.

This works well as a starting point, especially if you don't know which models perform best for your workload. But it trades control for convenience. You can't predict which model will handle a given request, which makes debugging harder and cost forecasting less precise.

When auto routing makes sense

• Early exploration, before you know your agent's workload patterns
• Mixed workloads where prompt complexity varies widely
• Teams that want reasonable defaults without configuration overhead

When explicit models make sense

• Production agents with predictable workloads
• Tasks where you've benchmarked specific models and know which performs best
• Cost-sensitive deployments where you need per-request pricing visibility
• Compliance or audit requirements that need deterministic model selection

Auto Exacto for tool calling

OpenRouter's Auto Exacto feature, introduced in March 2026, optimizes provider ordering specifically for requests that include tool definitions. Instead of routing by price alone, Auto Exacto reorders providers based on tool-calling reliability, throughput, and benchmark scores. It re-evaluates providers roughly every five minutes using live telemetry.

Auto Exacto runs by default on every tool-calling request. Since OpenClaw agents make heavy use of tool calling for file operations, code execution, and MCP interactions, this feature directly improves reliability without any configuration changes. OpenRouter reported that tool call error rates dropped by 80-88% on certain models after Auto Exacto launched.

If you want the same quality-weighted routing on non-tool-calling requests, append :exacto to any model slug:

openclaw models set openrouter/deepseek/deepseek-reasoner:exacto

To opt out of Auto Exacto and route strictly by price, you can append :floor to the model slug or set provider.sort to "price" in your OpenRouter account settings.

Persist your OpenClaw agent output across sessions

Free 50GB workspace with Intelligence Mode for semantic search, MCP server access, and branded share links. No credit card required.

Sign Up Free

Fallback chains protect your agent from provider outages. If the primary model is unavailable or rate-limited, OpenClaw tries each fallback in order until one responds.

Adding fallbacks via CLI

openclaw models fallbacks add openrouter/openai/gpt-5.2
openclaw models fallbacks add openrouter/deepseek/deepseek-reasoner
openclaw models fallbacks add openrouter/google/gemini-3-flash

Check your current chain:

openclaw models fallbacks list

Configuration file approach

You can also edit ~/.openclaw/openclaw.json directly:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4",
        "fallbacks": [
          "openrouter/openai/gpt-5.2",
          "openrouter/deepseek/deepseek-reasoner",
          "openrouter/google/gemini-3-flash"
        ]
      }
    }
  }
}

Fallback chain best practices

Spread your fallbacks across different underlying providers. If your primary is an Anthropic model and your first fallback is also Anthropic, a provider-level outage takes both down simultaneously. A chain like Anthropic, then OpenAI, then DeepSeek gives you genuine redundancy.

Keep your fallback list short. Three to four models is enough. Each model in the chain adds latency on failure because OpenClaw tries them sequentially. A long chain means longer waits when multiple providers are down.

Match capability levels across your chain. If your primary model handles 200K context windows, don't fall back to a model with 8K context. The agent might fail mid-task when the fallback can't process the full conversation history.

Fallback chains work alongside OpenRouter's own provider-level failover. OpenRouter already routes around unhealthy providers for the same model. Your fallback chain adds a second layer by switching to entirely different models when the first model is genuinely unavailable across all providers.

The biggest cost savings come from routing different task types to appropriately sized models. Not every agent request needs a frontier model. Heartbeat checks, status pings, and simple classification tasks run fine on models that cost 60x less than Claude Opus.

Three-tier routing strategy

The VelvetShark routing guide documents a three-tier approach that maps well to most OpenClaw workloads:

• Tier 1, complex reasoning: Architecture decisions, multi-file refactoring, and debugging hard problems. Use Claude Opus, GPT-5.2, or DeepSeek Reasoner. These models cost $2.74 to $30 per million tokens but handle the work that cheaper models get wrong.

• Tier 2, daily coding work: Code generation, test writing, documentation, and research tasks. Claude Sonnet or DeepSeek R1 handle these well at $2-5 per million tokens.

• Tier 3, lightweight tasks: Heartbeat checks, simple classification, commit message generation, and status queries. Gemini Flash-Lite ($0.50/M tokens) or DeepSeek V3.2 ($0.53/M tokens) are fast and cheap enough that cost is negligible.

Configuring subagent routing

OpenClaw lets you assign different models to subagent tasks separately from the primary agent:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-opus-4-5"
      },
      "subagents": {
        "model": "openrouter/deepseek/deepseek-reasoner"
      },
      "heartbeat": {
        "every": "30m",
        "model": "openrouter/google/gemini-2.5-flash-lite"
      }
    }
  }
}

This configuration sends primary agent reasoning to Opus, subagent work to DeepSeek, and periodic heartbeats to Gemini Flash-Lite.

Real cost impact

The VelvetShark guide documents concrete savings across usage levels: light users ($200/month baseline) dropped to around $70/month, a 65% reduction. Power users ($943/month baseline) dropped to roughly $347/month. Heavy users at $2,750/month reduced spend to about $1,000/month. The consistent 62-65% savings come from moving the majority of requests, which are lightweight, to the cheapest capable model.

Session model switching

You don't need to restart your agent to change models. Use the /model command in an active OpenClaw chat session:

/model openrouter/deepseek/deepseek-reasoner

This is useful when you're in a session and realize the current task needs a cheaper or more capable model. The /model command also opens a numbered picker if you don't specify a model reference.

Multi-model routing optimizes the AI side of your agent workflow. But the output still needs to go somewhere persistent and shareable, especially when you're handing work off to teammates or clients.

Local file storage works for solo development, but it breaks down when multiple people need to review agent output, when you want audit trails of what was generated, or when the agent needs to read back its own previous work across sessions.

Cloud storage services like S3, Google Drive, or Dropbox can hold files, but they weren't designed for the agent handoff workflow. They lack built-in intelligence features like semantic search across uploaded documents, and they don't offer an MCP interface that agents can call directly.

Fast.io provides workspaces built for this pattern. Your OpenClaw agent connects to a Fast.io workspace through the MCP server, uploads its output, and the workspace automatically indexes everything for semantic search through Intelligence Mode. When you're ready to hand off, you create a branded share link and transfer ownership to the recipient.

The free agent tier includes 50GB of storage, 5,000 credits per month, and 5 workspaces with no credit card required. That's enough to store months of agent-generated content, reports, and artifacts. Agents and humans share the same workspaces and intelligence layer: humans use the web UI, agents use the API or MCP server.

For OpenClaw specifically, the MCP server at /storage-for-agents/ exposes 19 consolidated tools for workspace management, file operations, AI queries, and sharing. Your agent can upload generated files, create share links, query existing documents with citations, and manage permissions, all through standard MCP tool calls.

This approach separates model routing (handled by OpenRouter) from output persistence (handled by Fast.io). Each layer does what it's good at, and you can change your model configuration without touching your storage setup.