OpenRouter is the most popular LLM aggregator. It's also the source of the most frustration in OpenClaw's issue tracker.
The Data
We searched OpenClaw's GitHub issues for "openrouter" and read every result. 100 issues. Open and closed. Filed by users who ran into the same structural problems over and over.
| Category | Issues | Examples |
|---|---|---|
| Broken fallback / failover | ~20 | #22136, #45663, #50389, #49079 |
| Model ID mangling | ~15 | #49379, #50711, #25665, #2373 |
| Authentication / 401 errors | ~8 | #51056, #34830, #26960 |
| Cost / billing opacity | ~6 | #25371, #50738, #38248 |
| Routing opacity | ~5 | #7006, #35842 |
| Missing feature parity | ~10 | #46255, #50485, #30850 |
| Rate limit / key exhaustion | ~4 | #8615, #48729 |
| Model catalog staleness | ~5 | #10687, #30152 |
These aren't edge cases. They're structural consequences of how OpenRouter works: a middleman that adds latency, mangles model IDs, obscures routing decisions, and introduces its own failure modes on top of the providers it aggregates.
1. Broken Fallback — The #1 Pain Point
From #45663:
"Provider returned error from OpenRouter does not trigger model failover."
From #50389:
"Rate limit errors surfaced to user instead of auto-failover."
When OpenRouter returns a 429 or provider error, OpenClaw's failover logic often doesn't recognize it as retriable. The user sees a raw error. The agent stops. ~20 issues document variations of this: HTTP 529 (Anthropic overloaded) not triggering fallback (#49079), invalid model IDs causing 400 instead of failover (#50017), timeouts in cron sessions with no recovery (#49597).
How ClawRouter Solves This
ClawRouter maintains 8-deep fallback chains per routing tier. When a model fails:
- 200ms retry — short-burst rate limits often recover in milliseconds
- Next model — if retry fails, move to the next model in the chain
- Per-model isolation — one provider's failure doesn't poison the others
- All-failed summary — if every model in the chain fails, you get a structured error listing every attempt and failure reason
[ClawRouter] Trying model 1/6: google/gemini-2.5-flash
[ClawRouter] Model google/gemini-2.5-flash returned 429, retrying in 200ms...
[ClawRouter] Retry failed, trying model 2/6: deepseek/deepseek-chat
[ClawRouter] Success with model: deepseek/deepseek-chat
No silent failures. No raw 429s surfaced to the agent.
2. Model ID Mangling — Death by Prefix
From #25665:
"Model config defaults to
openrouter/openrouter/auto(double prefix)."
From #50711:
"Control UI model picker strips
openrouter/prefix."
OpenRouter uses nested model IDs: openrouter/deepseek/deepseek-v3.2. OpenClaw's UI, Discord bot, and web gateway all handle these differently. Some add the prefix. Some strip it. Some double it. 15 issues trace back to model ID confusion.
How ClawRouter Solves This
Clean aliases. You say sonnet and get anthropic/claude-sonnet-4-6. You say flash and get google/gemini-2.5-flash. No nested prefixes. No double-prefix bugs.
// resolveModelAlias() handles all normalization
"sonnet" → "anthropic/claude-sonnet-4-6"
"opus" → "anthropic/claude-opus-4-6"
"flash" → "google/gemini-2.5-flash"
"grok" → "xai/grok-4-0314"
"deepseek" → "deepseek/deepseek-chat"
One canonical format. No mangling. No UI inconsistency.
3. API Key Hell — 401s, Leakage, and Rotation
From #51056:
"OpenRouter fails with '401 Missing Authentication header' despite valid key."
From #8615:
"Feature request: native multi-API-key support with load balancing and fallback."
API keys are the root cause of an entire category of failures. Keys expire. Keys leak into LLM context — every provider sees every other provider's keys in the serialized request. Keys hit rate limits that can't be load-balanced. 8 issues document auth failures alone.
How ClawRouter Solves This
ClawRouter has no API keys. Zero.
Payment happens via x402 — a cryptographic micropayment protocol. Your agent generates a wallet on first run (BIP-44 derivation, both EVM and Solana). Each request is signed with the wallet's private key. USDC moves per-request.
No keys to leak. No keys to rotate. No keys to rate-limit. No keys to expire.
The wallet is the identity. The signature is the authentication. Nothing to configure, nothing to paste into a config file, nothing for the LLM to accidentally serialize.
4. Cost and Billing Opacity — Surprise Bills
From #25371:
"OpenRouter 402 billing error misclassified as 'Context overflow', triggering auto-compaction that drains remaining credits faster."
From #7006:
"
openrouter/autodoesn't expose which model was actually used or its cost."
When OpenRouter runs out of credits, it returns a 402 that OpenClaw misreads as a context overflow. OpenClaw then auto-compacts the context and retries — on the same empty balance. Each retry charges the compaction cost. Credits drain faster. The agent burns money trying to fix a billing error it doesn't understand.
How ClawRouter Solves This
Per-request cost visibility. Every response includes cost headers:
x-clawrouter-cost: 0.003400
x-clawrouter-savings: 82%
x-clawrouter-model: google/gemini-2.5-flash
Per-request USDC payments. No prepaid balance to drain. Each request shows its price before you pay. When the wallet is empty, requests don't fail — they fall back to the free tier (NVIDIA GPT-OSS-120B).
Budget guard. maxCostPerRun caps per-session spending. Two modes: graceful (downgrade to cheaper models) or strict (hard stop). The $248/day heartbeat scenario is structurally impossible.
Usage logging. Every request logs to ~/.openclaw/blockrun/logs/usage-YYYY-MM-DD.jsonl with model, tier, cost, baseline cost, savings, and latency. /stats shows the breakdown.
5. Routing Opacity — "Which Model Did I Just Pay For?"
From #7006:
"No visibility into which model
openrouter/autoactually uses."
From #35842:
"Need explicit Claude Sonnet default instead of auto-routing."
When you use openrouter/auto, you don't know what model served your request. You can't debug quality regressions. You can't understand cost spikes. You're paying for a black box.
How ClawRouter Solves This
ClawRouter's routing is 100% local, open-source, and transparent.
A 14-dimension weighted classifier runs locally in <1ms. It scores every request across: token count, code presence, reasoning markers, technical terms, multi-step patterns, question complexity, tool signals, and more.
Debug headers on every response:
x-clawrouter-profile: auto
x-clawrouter-tier: MEDIUM
x-clawrouter-model: moonshot/kimi-k2.5
x-clawrouter-confidence: 0.87
x-clawrouter-reasoning: "Code task with moderate complexity"
SSE debug comments in streaming responses show the routing decision inline. You always know which model, why it was selected, and how confident the classifier was.
Four routing profiles give you explicit control:
| Profile | Behavior | Savings |
|---|---|---|
auto |
Balanced quality + cost | 74–100% |
eco |
Cheapest possible | 95–100% |
premium |
Best quality always | 0% |
free |
NVIDIA GPT-OSS only | 100% |
No black box. No mystery routing. Full visibility, full control.
6. Missing Feature Parity — Images, Tools, Caching
From #46255:
"Images not passed to OpenRouter models."
From #47707:
"Mistral models fail with strict tool call ID requirements."
OpenRouter doesn't always pass through provider-specific features correctly. Image payloads get dropped. Cache retention headers get ignored. Tool call ID formats cause silent failures with strict providers.
How ClawRouter Solves This
Vision auto-detection. When image_url content parts are detected, ClawRouter automatically filters the fallback chain to vision-capable models only. No images dropped.
Tool calling validation. Every model has a toolCalling flag. When tools are present in the request, ClawRouter forces agentic routing tiers and excludes models without tool support. No silent tool call failures.
Direct provider routing. ClawRouter routes through BlockRun's API directly to providers — not through a second aggregator. One hop, not two. Provider-specific features work because there's no middleman translating them.
7. Model Catalog Staleness — "Where's the New Model?"
From #10687:
"Need fully dynamic model discovery."
From #30152:
"Allowlist silently drops models not in catalog."
When new models launch, OpenRouter's catalog lags. Users configure a model that exists at the provider but isn't in the catalog. The request fails silently or gets rerouted.
How ClawRouter Solves This
ClawRouter maintains a curated catalog of 46+ models across 8 providers, updated with each release. Delisted models have automatic redirect aliases:
// Delisted models redirect automatically
"xai/grok-code-fast-1" → "deepseek/deepseek-chat"
"google/gemini-2.0-pro" → "google/gemini-3.1-pro"
No silent drops. No stale catalog. Models are benchmarked for speed, quality, and tool support before inclusion.
The Full Comparison
| OpenRouter | ClawRouter | |
|---|---|---|
| Authentication | API key (leak risk) | Wallet signature (no keys) |
| Payment | Prepaid balance (custodial) | Per-request USDC (non-custodial) |
| Routing | Server-side black box | Local 14-dim classifier, <1ms |
| Fallback | Often broken (20+ issues) | 8-deep chains, per-model isolation |
| Model IDs | Nested prefixes, mangling bugs | Clean aliases, single format |
| Cost visibility | None per-request | Headers + JSONL logs + /stats
|
| Empty wallet | Request fails | Auto-fallback to free tier |
| Rate limits | Per-key, shared | Per-wallet, independent |
| Vision support | Images sometimes dropped | Auto-detected, vision-only fallback |
| Tool calling | Silent failures with some models | Flag-based filtering, guaranteed support |
| Model catalog | Laggy, silent drops | Curated 46+ models, redirect aliases |
| Budget control | Monthly invoice | Per-session cap (maxCostPerRun) |
| Setup | Create account, paste key | Agent generates wallet, auto-configured |
| Average cost | $25/M tokens (Opus direct) | $2.05/M tokens (auto-routed) = 92% savings |
Getting Started
# Install
npm install -g @blockrun/clawrouter
# Start (auto-configures OpenClaw)
clawrouter
# Check your wallet
# /wallet
# View routing stats
# /stats
ClawRouter auto-injects itself into ~/.openclaw/openclaw.json as a provider on startup. Your existing tools, sessions, and extensions are unchanged.
Load a wallet with USDC on Base or Solana, pick a routing profile, and run.
GitHub · blockrun.ai · npm install -g @blockrun/clawrouter
Top comments (0)