We Read 100 OpenClaw Issues About OpenRouter. Here's What We Built Instead.

[1bcMax]

We Read 100 OpenClaw Issues About OpenRouter. Here's What We Built Instead.

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	Issue Count	Representative Issues
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:

1. 200ms retry — short-burst rate limits often recover in milliseconds
2. Next model — if retry fails, move to the next model in the chain
3. Per-model isolation — one provider's failure doesn't poison the others
4. 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

ClawRouter uses 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/auto doesn'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.0034
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 (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/auto actually 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.

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	Free models 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 55+ models across 9 providers (including 11 free models), 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 55+ 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.com/BlockRunAI/ClawRouter · blockrun.ai · npm install -g @blockrun/clawrouter