@blockrun/clawrouter 0.12.66 → 0.12.68

package/docs/clawrouter-vs-openrouter-llm-routing-comparison.md

@@ -2,6 +2,8 @@
 
 > _OpenRouter is the most popular LLM aggregator. It's also the source of the most frustration in OpenClaw's issue tracker._
 
+![Reading 100 OpenClaw Issues Built a Better Router — We searched OpenClaw's GitHub for "openrouter" and read every result. 100 issues. We didn't find edge cases — we found structural failures.](./assets/clawrouter-100-openclaw-issues-intro.png)
+
 ---
 
 ## The Data
@@ -21,6 +23,10 @@ We searched OpenClaw's GitHub issues for "openrouter" and read every result. 100
 
 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.
 
+![The Anatomy of Middleman Failure — Treemap showing issue distribution: Broken Fallback (~20), Model ID Mangling (~15), Missing Feature Parity (~10), Authentication/401s (~8), Cost Opacity (~6), Routing Opacity (~5), Model Staleness (~5), Rate Limits (~4). These are the inevitable consequences of a custodial middleman architecture.](./assets/clawrouter-anatomy-of-middleman-failure.png)
+
+![The Architectural Shift: Middleman vs. Local Router — OpenRouter adds latency, translation errors, and hidden limits as a middleman aggregator. ClawRouter moves routing logic locally, eliminating the black box. One hop, not two. Zero translation errors. Total control.](./assets/clawrouter-architectural-shift-middleman-vs-local.png)
+
 ---
 
 ## 1. Broken Fallback — The #1 Pain Point
@@ -53,6 +59,8 @@ ClawRouter maintains 8-deep fallback chains per routing tier. When a model fails
 
 No silent failures. No raw 429s surfaced to the agent.
 
+![Surviving the 429: Cascading Fallback Chains — OpenRouter surfaces raw HTTP 429 errors and the agent stops. ClawRouter maintains 8-deep isolated fallback chains per tier with 200ms retry, per-model isolation, and seamless cascading. No silent failures.](./assets/clawrouter-cascading-fallback-chains-429.png)
+
 ---
 
 ## 2. Model ID Mangling — Death by Prefix
@@ -82,6 +90,8 @@ ClawRouter uses clean aliases. You say `sonnet` and get `anthropic/claude-sonnet
 
 One canonical format. No mangling. No UI inconsistency.
 
+![Eliminating Model ID Mangling — OpenRouter's nested prefixes cause double-prefix bugs (openrouter/openrouter/auto) and UI stripping issues. ClawRouter uses one canonical format with clean aliases: "sonnet" → anthropic/claude-sonnet-4-6, "flash" → google/gemini-2.5-flash.](./assets/clawrouter-eliminating-model-id-mangling.png)
+
 ---
 
 ## 3. API Key Hell — 401s, Leakage, and Rotation
@@ -111,6 +121,8 @@ 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.
 
+![Cryptographic Auth: The End of API Key Hell — API keys are exposed in config, serialized into LLM context, share rate limits, and expire. ClawRouter replaces them with BIP-44 EVM/Solana wallets and per-request cryptographic signatures via x402.](./assets/clawrouter-cryptographic-auth-x402-wallet.png)
+
 ---
 
 ## 4. Cost and Billing Opacity — Surprise Bills
@@ -141,6 +153,8 @@ x-clawrouter-model: google/gemini-2.5-flash
 
 **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.
 
+![Absolute Cost Visibility & Session Guardrails — No prepaid balances to drain. Every response includes explicit cost headers. JSONL usage logs track every request. maxCostPerRun caps per-session spending. When your wallet empties, you downgrade to the free tier instead of crashing.](./assets/clawrouter-cost-visibility-session-guardrails.png)
+
 ---
 
 ## 5. Routing Opacity — "Which Model Did I Just Pay For?"
@@ -184,6 +198,8 @@ x-clawrouter-reasoning: "Code task with moderate complexity"
 
 No black box. No mystery routing. Full visibility, full control.
 
+![Transparent Routing via 14-Dimension Classification — Radar chart showing ClawRouter's local classifier scoring across Token Count, Code Presence, Reasoning Markers, Technical Terms, Multi-step Patterns, and Tool Signals. Executes locally in <1ms with SSE debug headers. Four profiles: auto (balanced), eco (cheapest), premium (best), free (GPT-OSS).](./assets/clawrouter-14-dimension-routing-classification.png)
+
 ---
 
 ## 6. Missing Feature Parity — Images, Tools, Caching
@@ -206,6 +222,8 @@ OpenRouter doesn't always pass through provider-specific features correctly. Ima
 
 **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.
 
+![Guaranteed Feature Parity & Direct Connectivity — Three-panel diagram: Vision (image_url auto-detected → vision-capable models only), Tool Calling (toolCalling flag → agentic models only), Catalog (curated 46+ models with automatic legacy-to-modern redirects). Direct provider routing means no dropped payloads.](./assets/clawrouter-feature-parity-direct-connectivity.png)
+
 ---
 
 ## 7. Model Catalog Staleness — "Where's the New Model?"
@@ -232,6 +250,8 @@ ClawRouter maintains a curated catalog of 46+ models across 8 providers, updated
 
 No silent drops. No stale catalog. Models are benchmarked for speed, quality, and tool support before inclusion.
 
+![The Cost/Transparency Nexus — Local routing engine + direct connections + x402 micropayments = 100% transparency = 92% cost savings. Direct Opus routing: $25.00/M tokens. ClawRouter auto-routed: $2.05/M tokens. Transparency and cost savings are two sides of the same architectural coin.](./assets/clawrouter-cost-transparency-nexus-92-savings.png)
+
 ---
 
 ## The Full Comparison
@@ -253,6 +273,8 @@ No silent drops. No stale catalog. Models are benchmarked for speed, quality, an
 | **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** |
 
+![The Engineering Matrix — Side-by-side feature comparison: OpenRouter vs ClawRouter across Routing, Authentication, Payment, Fallback, Model IDs, Empty Wallet, Vision/Tools, and Average Cost. ClawRouter wins on every dimension.](./assets/clawrouter-engineering-matrix-comparison.png)
+
 ---
 
 ## Getting Started
@@ -275,6 +297,8 @@ ClawRouter auto-injects itself into `~/.openclaw/openclaw.json` as a provider on
 
 Load a wallet with USDC on Base or Solana, pick a routing profile, and run.
 
+![Frictionless Integration — npm install -g @blockrun/clawrouter, auto-injected provider into ~/.openclaw/openclaw.json. No code rewrites. Your existing tools, sessions, and extensions remain entirely unchanged.](./assets/clawrouter-frictionless-integration.png)
+
 ---
 
 _[github.com/BlockRunAI/ClawRouter](https://github.com/BlockRunAI/ClawRouter) · [blockrun.ai](https://blockrun.ai) · `npm install -g @blockrun/clawrouter`_

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/clawrouter",
-  "version": "0.12.66",
+  "version": "0.12.68",
   "description": "Smart LLM router — save 85% on inference costs. 46+ models, one wallet, x402 micropayments.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/reinstall.sh

@@ -159,19 +159,6 @@ if (c.plugins?.installs?.clawrouter) delete c.plugins.installs.clawrouter;
 if (Array.isArray(c.plugins?.allow)) {
   c.plugins.allow = c.plugins.allow.filter(p => p !== 'clawrouter' && p !== '@blockrun/clawrouter');
 }
-// Remove deprecated model aliases from picker
-const deprecated = [
-  'blockrun/xai/grok-code-fast-1', // delisted 2026-03-12
-  'blockrun/xai/grok-3-fast',      // removed (too expensive)
-];
-if (c.agents?.defaults?.models) {
-  for (const key of deprecated) {
-    if (c.agents.defaults.models[key]) {
-      delete c.agents.defaults.models[key];
-      console.log('  Removed deprecated alias: ' + key);
-    }
-  }
-}
 atomicWrite(f, JSON.stringify(c, null, 2));
 console.log('  Config cleaned');
 "
@@ -354,18 +341,18 @@ try {
   }
 
   const allowlist = config.agents.defaults.models;
-  const DEPRECATED_MODELS = [
-    'blockrun/xai/grok-code-fast-1',
-    'blockrun/xai/grok-3-fast'
-  ];
+  const currentKeys = new Set(TOP_MODELS.map(id => 'blockrun/' + id));
+
+  // Remove any blockrun/* entries not in the current TOP_MODELS list
   let removed = 0;
-  for (const key of DEPRECATED_MODELS) {
-    if (allowlist[key]) {
+  for (const key of Object.keys(allowlist)) {
+    if (key.startsWith('blockrun/') && !currentKeys.has(key)) {
       delete allowlist[key];
-      changed = true;
       removed++;
     }
   }
+
+  // Add any missing current models
   let added = 0;
   for (const id of TOP_MODELS) {
     const key = 'blockrun/' + id;

package/scripts/update.sh

@@ -51,16 +51,20 @@ restore_previous_install() {
 
 run_dependency_install() {
   local plugin_dir="$1"
-  local log_file
-  log_file="$(mktemp -t clawrouter-update-npm.XXXXXX.log)"
+  local log_file="$HOME/clawrouter-npm-install.log"
 
+  echo "  (log: $log_file)"
   if (cd "$plugin_dir" && npm install --omit=dev >"$log_file" 2>&1); then
     tail -1 "$log_file"
-    rm -f "$log_file"
   else
-    echo "  npm install failed. Last 20 log lines:" >&2
-    tail -20 "$log_file" >&2 || true
-    echo "  Full log: $log_file" >&2
+    echo ""
+    echo "  ✗ npm install failed. Error log:"
+    echo "  ─────────────────────────────────"
+    tail -30 "$log_file" >&2 || true
+    echo "  ─────────────────────────────────"
+    echo ""
+    echo "  Full log saved: $log_file"
+    echo "  Send this file to @bc1max on Telegram for help."
     return 1
   fi
 }
@@ -286,17 +290,18 @@ try {
   }
 
   const allowlist = config.agents.defaults.models;
-  const DEPRECATED_MODELS = [
-    'blockrun/xai/grok-code-fast-1',
-    'blockrun/xai/grok-3-fast'
-  ];
+  const currentKeys = new Set(TOP_MODELS.map(id => 'blockrun/' + id));
+
+  // Remove any blockrun/* entries not in the current TOP_MODELS list
   let removed = 0;
-  for (const key of DEPRECATED_MODELS) {
-    if (allowlist[key]) {
+  for (const key of Object.keys(allowlist)) {
+    if (key.startsWith('blockrun/') && !currentKeys.has(key)) {
       delete allowlist[key];
       removed++;
     }
   }
+
+  // Add any missing current models
   let added = 0;
   for (const id of TOP_MODELS) {
     const key = 'blockrun/' + id;