@blockrun/clawrouter 0.12.257 → 0.12.259
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +34 -30
- package/dist/cli.js +538 -142
- package/dist/index.js +538 -142
- package/dist/router/index.js +43 -30
- package/docs/9-free-ai-models-zero-cost-blockrun.md +79 -86
- package/docs/anthropic-cost-savings.md +4 -4
- package/docs/anthropic-third-party-harness-changes.md +4 -4
- package/docs/clawrouter-cuts-llm-api-costs-500x.md +1 -1
- package/docs/clawrouter-vs-openrouter-llm-routing-comparison.md +4 -4
- package/docs/features.md +9 -8
- package/docs/routing-profiles.md +27 -23
- package/docs/subscription-failover.md +1 -1
- package/package.json +3 -3
- package/scripts/benchmark.py +2 -2
- package/scripts/reinstall.sh +7 -5
- package/skills/clawrouter/SKILL.md +4 -4
- package/src/top-models.json +11 -4
package/README.md
CHANGED
|
@@ -7,11 +7,11 @@
|
|
|
7
7
|
<p>Agents can't sign up for accounts. Agents can't enter credit cards.<br>
|
|
8
8
|
Agents can only sign transactions.<br><br>
|
|
9
9
|
<strong>ClawRouter is the only LLM router that lets agents operate independently.</strong><br><br>
|
|
10
|
-
<em><!-- br:models.free -->
|
|
10
|
+
<em><!-- br:models.free -->7<!-- /br:models.free --> models free, no crypto required. No signup. No API key. No credit card.</em></p>
|
|
11
11
|
|
|
12
12
|
<br>
|
|
13
13
|
|
|
14
|
-
<img src="https://img.shields.io/badge/🆓
|
|
14
|
+
<img src="https://img.shields.io/badge/🆓_7_Free_Models-success?style=for-the-badge" alt="7 free models">
|
|
15
15
|
<img src="https://img.shields.io/badge/🤖_Agent--Native-black?style=for-the-badge" alt="Agent native">
|
|
16
16
|
<img src="https://img.shields.io/badge/🔑_Zero_API_Keys-blue?style=for-the-badge" alt="No API keys">
|
|
17
17
|
<img src="https://img.shields.io/badge/⚡_Local_Routing-yellow?style=for-the-badge" alt="Local routing">
|
|
@@ -34,7 +34,7 @@ Agents can only sign transactions.<br><br>
|
|
|
34
34
|
|
|
35
35
|
</div>
|
|
36
36
|
|
|
37
|
-
> **ClawRouter** is an open-source smart LLM router that reduces AI API costs by up to <!-- br:savings.autoVsBaselinePct -->
|
|
37
|
+
> **ClawRouter** is an open-source smart LLM router that reduces AI API costs by up to <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->%. It analyzes each request across <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions and routes to the cheapest capable model in under 1ms, entirely locally. ClawRouter is the only LLM router built for autonomous AI agents — it uses wallet signatures for authentication (no API keys) and USDC micropayments via the x402 protocol (no credit cards). <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models from OpenAI, Anthropic, Google, xAI, DeepSeek, and more. MIT licensed.
|
|
38
38
|
|
|
39
39
|
---
|
|
40
40
|
|
|
@@ -46,7 +46,7 @@ Every other LLM router was built for **human developers** — create an account,
|
|
|
46
46
|
|
|
47
47
|
ClawRouter is built for the agent-first world:
|
|
48
48
|
|
|
49
|
-
- **Starts at $0** — <!-- br:models.free -->
|
|
49
|
+
- **Starts at $0** — <!-- br:models.free -->7<!-- /br:models.free --> open-weight models are free forever (incl. a 1M-context reasoner and two sub-second coders). Image turns route to paid models — see the free-tier note below.
|
|
50
50
|
- **No accounts** — a wallet is generated locally, no signup
|
|
51
51
|
- **No API keys** — your wallet signature IS authentication
|
|
52
52
|
- **No model selection** — <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions -->-dimension scoring + constraint-first ranking ([router-core](https://github.com/BlockRunAI/router-core)) picks the right model automatically
|
|
@@ -61,8 +61,8 @@ This is the stack that lets agents operate autonomously: **x402 + USDC + local r
|
|
|
61
61
|
|
|
62
62
|
| | OpenRouter | LiteLLM | Martian | Portkey | **ClawRouter** |
|
|
63
63
|
| ---------------- | ----------------- | ---------------- | ----------------- | ----------------- | ---------------------------------------------------------------------- |
|
|
64
|
-
| **Models** | 200+ | 100+ | Smart routing | Gateway | **<!-- br:models.chatVisible -->
|
|
65
|
-
| **Free tier** | Rate-limited | BYO keys | No | No | **<!-- br:models.free -->
|
|
64
|
+
| **Models** | 200+ | 100+ | Smart routing | Gateway | **<!-- br:models.chatVisible -->76<!-- /br:models.chatVisible -->** |
|
|
65
|
+
| **Free tier** | Rate-limited | BYO keys | No | No | **<!-- br:models.free -->7<!-- /br:models.free --> models, no signup** |
|
|
66
66
|
| **Routing** | Manual selection | Manual selection | Smart (closed) | Observability | **Smart (open source)** |
|
|
67
67
|
| **Auth** | Account + API key | Your API keys | Account + API key | Account + API key | **Wallet signature** |
|
|
68
68
|
| **Payment** | Credit card | BYO keys | Credit card | $49-499/mo | **USDC per-request** |
|
|
@@ -78,7 +78,7 @@ This is the stack that lets agents operate autonomously: **x402 + USDC + local r
|
|
|
78
78
|
|
|
79
79
|
## Quick Start
|
|
80
80
|
|
|
81
|
-
> **No wallet? <!-- br:models.free -->
|
|
81
|
+
> **No wallet? <!-- br:models.free -->7<!-- /br:models.free --> models work free out of the box.** Install, run, and pin `free/nemotron-3.5-lightning` (or any of the <!-- br:models.free -->7<!-- /br:models.free -->) — no crypto, no signup, no balance required. Add USDC later when you want paid models.
|
|
82
82
|
|
|
83
83
|
### Option A — OpenClaw Agent
|
|
84
84
|
|
|
@@ -107,7 +107,7 @@ openclaw gateway restart
|
|
|
107
107
|
|
|
108
108
|
> **Using Claude Code?** Check out [BRCC](https://github.com/BlockRunAI/brcc) — it's purpose-built for Claude Code with the same smart routing and x402 payments.
|
|
109
109
|
>
|
|
110
|
-
> **Using NousResearch Hermes?** See [ClawRouter-Hermes](https://github.com/BlockRunAI/ClawRouter-Hermes) — a Python plugin that wires Hermes into the ClawRouter proxy. Same wallet, same <!-- br:models.chatVisible -->
|
|
110
|
+
> **Using NousResearch Hermes?** See [ClawRouter-Hermes](https://github.com/BlockRunAI/ClawRouter-Hermes) — a Python plugin that wires Hermes into the ClawRouter proxy. Same wallet, same <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models, same x402 USDC settlement on Base & Solana.
|
|
111
111
|
|
|
112
112
|
No OpenClaw required. ClawRouter runs as a local proxy on port 8402.
|
|
113
113
|
|
|
@@ -118,7 +118,7 @@ npx @blockrun/clawrouter
|
|
|
118
118
|
```
|
|
119
119
|
|
|
120
120
|
**2. Fund your wallet** — optional, skip for free tier
|
|
121
|
-
Your wallet address is printed on first run. For paid models, send a few USDC on Base or Solana — $5 covers thousands of requests. To stay at $0, pin any of the <!-- br:models.free -->
|
|
121
|
+
Your wallet address is printed on first run. For paid models, send a few USDC on Base or Solana — $5 covers thousands of requests. To stay at $0, pin any of the <!-- br:models.free -->7<!-- /br:models.free --> free models (e.g. `free/nemotron-3.5-lightning`) or use `/model free` inside OpenClaw.
|
|
122
122
|
|
|
123
123
|
**3. Point your client at `http://localhost:8402`**
|
|
124
124
|
|
|
@@ -191,7 +191,7 @@ Choose your routing strategy with `/model <profile>`:
|
|
|
191
191
|
| Profile | Strategy | Savings | Best For |
|
|
192
192
|
| ---------------- | ------------------ | ---------------------------------------------------------------------------------- | -------------------- |
|
|
193
193
|
| `/model free` | Free NVIDIA models | **100%** | $0 balance, learning |
|
|
194
|
-
| `/model auto` | Balanced (default) | **<!-- br:savings.autoVsBaselinePct -->
|
|
194
|
+
| `/model auto` | Balanced (default) | **<!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->%** | General use |
|
|
195
195
|
| `/model eco` | Cheapest possible | **<!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->%** | Maximum savings |
|
|
196
196
|
| `/model premium` | Best quality | 0% | Mission-critical |
|
|
197
197
|
|
|
@@ -217,19 +217,19 @@ Request → 15-dimension scorer → tier + task shape
|
|
|
217
217
|
3. **Rank** — survivors are scored on task quality, capability, estimated cost, speed and reliability, with per-profile weights (`eco` leans on cost, `premium` on quality and reliability).
|
|
218
218
|
4. **Recover** — the whole ranked list rides along as the fallback chain, so a provider timeout or 5xx costs a retry, not the task.
|
|
219
219
|
|
|
220
|
-
| Tier | ECO Model
|
|
221
|
-
| --------- |
|
|
222
|
-
| SIMPLE |
|
|
223
|
-
| MEDIUM | glm-5.3-flash ($0.15/$0.50)
|
|
224
|
-
| COMPLEX | glm-5.3-flash ($0.15/$0.50)
|
|
225
|
-
| REASONING | deepseek-reasoner ($0.14/$0.28)
|
|
220
|
+
| Tier | ECO Model | AUTO Model | PREMIUM Model | AGENTIC Model ‡ |
|
|
221
|
+
| --------- | --------------------------------- | ------------------------------- | ---------------------------- | ------------------------- |
|
|
222
|
+
| SIMPLE | nemotron-3.5-lightning (**FREE**) | gemini-2.5-flash ($0.30/$2.50) | gemini-3.5-flash ($1.50/$9) | gpt-4o-mini ($0.15/$0.60) |
|
|
223
|
+
| MEDIUM | glm-5.3-flash ($0.15/$0.50) | gemini-3.5-flash ($1.50/$9) | gpt-5.3-codex ($1.75/$14.00) | gpt-5-mini ($0.25/$2) |
|
|
224
|
+
| COMPLEX | glm-5.3-flash ($0.15/$0.50) | gemini-3.1-pro ($2/$12) | claude-fable-5 ($10/$50) | claude-sonnet-5 ($3/$15) |
|
|
225
|
+
| REASONING | deepseek-reasoner ($0.14/$0.28) | deepseek-reasoner ($0.14/$0.28) | claude-sonnet-5 ($3/$15) | claude-sonnet-5 ($3/$15) |
|
|
226
226
|
|
|
227
227
|
† Withheld from `/v1/models` — since Router Core V3.5 no chain names such a model: every primary and every fallback rung above is a model you can find on the public pricing page. [savings-mix.json](https://github.com/BlockRunAI/blockrun/blob/main/src/brand/savings-mix.json) prices the published savings claim on the same visible models.
|
|
228
228
|
‡ Auto-selected in any profile when the turn actually needs its attached tools; prefers models that keep going instead of stopping to ask.
|
|
229
229
|
|
|
230
230
|
These are the curated primaries; every tier carries a benchmark-ordered fallback chain — full chains and per-profile ranking weights in [docs/routing-profiles.md](docs/routing-profiles.md). On router-core's frozen three-arm agent benchmark (τ-bench, BrowseComp, Terminal-Bench) the V3.4 policy (the last one benchmarked; V3.5 is a catalog refresh on the same scorer and weights) completed **57%** of tasks vs **49%** for the previous rules router, at **6.4%** lower cost per successful task — and spent **8.9%** of the tokens a pinned flagship would have.
|
|
231
231
|
|
|
232
|
-
**<!-- br:savings.autoVsBaselinePct -->
|
|
232
|
+
**<!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% cheaper than pinning Claude Opus 5** for the same traffic, on `auto`; **<!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->%** on `eco`.
|
|
233
233
|
|
|
234
234
|
Not an "up to" figure. The baseline, the workload mix and the token ratio are
|
|
235
235
|
published in [`savings-mix.json`](https://github.com/BlockRunAI/blockrun/blob/main/src/brand/savings-mix.json),
|
|
@@ -407,7 +407,7 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
|
|
|
407
407
|
|
|
408
408
|
## Models & Pricing
|
|
409
409
|
|
|
410
|
-
<!-- br:models.chatVisible -->
|
|
410
|
+
<!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models across 9 providers, one wallet. **<!-- br:models.free -->7<!-- /br:models.free --> models are $0 — paid models start at fractions of a cent.**
|
|
411
411
|
|
|
412
412
|
> **💡 "Cost per request"** = estimated cost for a typical chat message (~500 input + 500 output tokens). Paid requests also carry a flat **$0.001/tx settlement fee** (covers on-chain gas; already included in the price the gateway quotes). Free models never pay it.
|
|
413
413
|
|
|
@@ -415,11 +415,13 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
|
|
|
415
415
|
|
|
416
416
|
| Model | Input $/M | Output $/M | ~$/request | Context | Features |
|
|
417
417
|
| ------------------------------------------- | --------: | ---------: | ---------: | ------- | -------------------------------------------- |
|
|
418
|
-
| free/nemotron-3-
|
|
419
|
-
| free/
|
|
420
|
-
| free/
|
|
421
|
-
| free/
|
|
422
|
-
| free/nemotron-nano-
|
|
418
|
+
| free/nemotron-3.5-lightning | **FREE** | **FREE** | **$0** | 1M | reasoning (thinking mode) — the free default |
|
|
419
|
+
| free/nemotron-3-nano-30b | **FREE** | **FREE** | **$0** | 131K | fastest free model (~121 tok/s) |
|
|
420
|
+
| free/laguna-xs-2.1 | **FREE** | **FREE** | **$0** | 131K | coding (Poolside, ~161 tok/s) |
|
|
421
|
+
| free/north-mini-code | **FREE** | **FREE** | **$0** | 256K | coding (Cohere, sub-second) |
|
|
422
|
+
| free/nemotron-3-nano-omni-30b-a3b-reasoning | **FREE** | **FREE** | **$0** | 256K | reasoning (text only — see note) |
|
|
423
|
+
| free/nemotron-3-ultra-550b | **FREE** | **FREE** | **$0** | 1M | largest free model (550B/55B MoE) |
|
|
424
|
+
| free/llama-3.2-11b-vision | **FREE** | **FREE** | **$0** | 128K | Meta Llama (text only — see note) |
|
|
423
425
|
| qwen/qwen3.7-flash | $0.03 | $0.13 | $0.0001 | 1M | reasoning, tools (fastest Qwen tier) |
|
|
424
426
|
| openai/gpt-5-nano | $0.05 | $0.40 | $0.0002 | 128K | tools |
|
|
425
427
|
| openai/gpt-5.6-luna-pro | $0.10 | $0.60 | $0.0004 | 1M | reasoning, vision, agentic, tools |
|
|
@@ -497,7 +499,9 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
|
|
|
497
499
|
| openai/gpt-5.4-pro | $30.00 | $180.00 | $0.1050 | 400K | reasoning, tools |
|
|
498
500
|
| openai/gpt-5.5-pro | $30.00 | $180.00 | $0.1050 | 1M | reasoning, vision, tools |
|
|
499
501
|
|
|
500
|
-
> **Free tier:** <!-- br:models.free -->
|
|
502
|
+
> **Free tier:** <!-- br:models.free -->7<!-- /br:models.free --> open-weight models cost nothing — `/model free` pins the free default (`nemotron-3.5-lightning`, with the other six as fallbacks), `/model eco` opens on it, or pick one directly (e.g., `/model lightning` for 1M-context reasoning, `/model north-mini` or `/model laguna` for fast coding, `/model nano-30b` for the fastest).
|
|
503
|
+
>
|
|
504
|
+
> **No free vision.** Two free models are catalogued as vision-capable and neither reliably is: on a 64×64 solid-colour probe `nemotron-3-nano-omni` was right 1 of 4 times on Base and answered "white" for red on Solana, and `llama-3.2-11b-vision` replied "I'm unable to see the image" 3 of 3 while answering text fine. Both return HTTP 200, so a wrong answer arrives with no error to branch on. ClawRouter therefore does not flag them for vision, and requests carrying an `image_url` route to a paid vision model instead.
|
|
501
505
|
> **Best value:** `gpt-5-nano` and `gemini-2.5-flash-lite` deliver strong results at ~$0.0003/request.
|
|
502
506
|
|
|
503
507
|
---
|
|
@@ -573,7 +577,7 @@ For basic usage, no configuration needed. For advanced options:
|
|
|
573
577
|
Block specific models from being routed to. Useful if a model doesn't follow your agent instructions or you want to control costs.
|
|
574
578
|
|
|
575
579
|
```bash
|
|
576
|
-
/exclude add free/
|
|
580
|
+
/exclude add free/nemotron-3.5-lightning # Block a free model (e.g. not for your workload)
|
|
577
581
|
/exclude add grok-4 # Aliases work — blocks all grok-4 variants
|
|
578
582
|
/exclude add gpt-5.4 # Skip expensive models
|
|
579
583
|
/exclude # Show current exclusions
|
|
@@ -667,7 +671,7 @@ npm test
|
|
|
667
671
|
|
|
668
672
|
**The LLM router built for autonomous agents**
|
|
669
673
|
|
|
670
|
-
You're here. <!-- br:models.chatVisible -->
|
|
674
|
+
You're here. <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models, local smart routing, x402 USDC payments — the only stack that lets agents operate independently.
|
|
671
675
|
|
|
672
676
|
`curl -fsSL https://blockrun.ai/ClawRouter-update | bash`
|
|
673
677
|
|
|
@@ -678,7 +682,7 @@ You're here. <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> mod
|
|
|
678
682
|
|
|
679
683
|
**BlockRun for Claude Code**
|
|
680
684
|
|
|
681
|
-
Run Claude Code with <!-- br:models.chatVisible -->
|
|
685
|
+
Run Claude Code with <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models, no rate limits, no Anthropic account, no phone verification. Pay per request with USDC — your wallet is your identity.
|
|
682
686
|
|
|
683
687
|
`curl -fsSL https://blockrun.ai/brcc-install | bash`
|
|
684
688
|
|
|
@@ -691,7 +695,7 @@ Run Claude Code with <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible
|
|
|
691
695
|
|
|
692
696
|
**ClawRouter for NousResearch Hermes**
|
|
693
697
|
|
|
694
|
-
Python plugin that wraps the ClawRouter proxy for `hermes-agent`. Same <!-- br:models.chatVisible -->
|
|
698
|
+
Python plugin that wraps the ClawRouter proxy for `hermes-agent`. Same <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models, same x402 USDC payments on Base & Solana, native Hermes ergonomics.
|
|
695
699
|
|
|
696
700
|
`pip install hermes-plugin-clawrouter`
|
|
697
701
|
|
|
@@ -739,7 +743,7 @@ ClawRouter is an open-source (MIT licensed) smart LLM router built for autonomou
|
|
|
739
743
|
|
|
740
744
|
### How much can ClawRouter save on LLM costs?
|
|
741
745
|
|
|
742
|
-
On the `auto` profile ClawRouter costs <!-- br:savings.autoVsBaselinePct -->
|
|
746
|
+
On the `auto` profile ClawRouter costs <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% less than pinning Claude Opus 5 for every request, and <!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->% less on `eco`. That is computed from a published workload mix rather than estimated — see [savings-mix.json](https://github.com/BlockRunAI/blockrun/blob/main/src/brand/savings-mix.json) for the baseline and assumptions. Actual savings depend on your workload — simple queries are routed to free models ($0/request), while complex tasks get premium models.
|
|
743
747
|
|
|
744
748
|
### How does ClawRouter compare to OpenRouter?
|
|
745
749
|
|
|
@@ -755,7 +759,7 @@ ClawRouter works with any tool that makes OpenAI-compatible API calls — point
|
|
|
755
759
|
|
|
756
760
|
### Is ClawRouter free?
|
|
757
761
|
|
|
758
|
-
ClawRouter itself is free and MIT licensed. You pay only for the LLM API calls routed through it — and several
|
|
762
|
+
ClawRouter itself is free and MIT licensed. You pay only for the LLM API calls routed through it — and several open-weight models (`nemotron-3.5-lightning`, `nemotron-3-nano-30b`, `laguna-xs-2.1`, `north-mini-code`, `nemotron-3-nano-omni-30b-a3b-reasoning`, `nemotron-3-ultra-550b`, `llama-3.2-11b-vision`) are completely free (text only). Use `/model free` to smart-route across them, or pick any by name.
|
|
759
763
|
|
|
760
764
|
---
|
|
761
765
|
|