@blockrun/clawrouter 0.9.33 โ 0.9.35
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 +150 -360
- package/dist/cli.js +2 -2
- package/dist/cli.js.map +1 -1
- package/dist/index.js +16 -3
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,54 +1,56 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
1
|
<div align="center">
|
|
4
2
|
|
|
5
|
-
|
|
6
|
-
One wallet, 30+ models, zero API keys.
|
|
3
|
+
<img src="assets/banner.png" alt="ClawRouter Banner" width="600">
|
|
7
4
|
|
|
8
|
-
|
|
9
|
-
[](LICENSE)
|
|
10
|
-
[](https://typescriptlang.org)
|
|
11
|
-
[](https://nodejs.org)
|
|
12
|
-
[](https://x.com/USDC/status/2021625822294216977)
|
|
5
|
+
<h3>The agent-native LLM router for <a href="https://openclaw.ai">OpenClaw</a></h3>
|
|
13
6
|
|
|
14
|
-
|
|
7
|
+
Route every request to the right model at the right price.<br>
|
|
8
|
+
15-dimension scoring, <1ms local routing, optimized for autonomous agents.<br>
|
|
9
|
+
One wallet, 30+ models, zero API keys.
|
|
15
10
|
|
|
16
|
-
|
|
17
|
-
|
|
11
|
+
<img src="https://img.shields.io/badge/๐_92%25_Cost_Savings-success?style=for-the-badge" alt="92% savings">
|
|
12
|
+
<img src="https://img.shields.io/badge/๐_Zero_API_Keys-blue?style=for-the-badge" alt="No API keys">
|
|
13
|
+
<img src="https://img.shields.io/badge/๐ค_30+_Models-purple?style=for-the-badge" alt="30+ models">
|
|
14
|
+
<img src="https://img.shields.io/badge/๐ฐ_Non--Custodial-orange?style=for-the-badge" alt="Non-custodial">
|
|
15
|
+
<img src="https://img.shields.io/badge/โก_<1ms_Routing-yellow?style=for-the-badge" alt="Fast routing">
|
|
16
|
+
|
|
17
|
+
[](https://npmjs.com/package/@blockrun/clawrouter)
|
|
18
|
+
[](https://npmjs.com/package/@blockrun/clawrouter)
|
|
19
|
+
[](https://github.com/BlockRunAI/ClawRouter)
|
|
20
|
+
[](https://github.com/BlockRunAI/ClawRouter/actions)
|
|
21
|
+
[](https://typescriptlang.org)
|
|
22
|
+
[](LICENSE)
|
|
23
|
+
|
|
24
|
+
[](https://x.com/USDC/status/2021625822294216977)
|
|
25
|
+
[](https://x402.org)
|
|
26
|
+
[](https://base.org)
|
|
27
|
+
[](https://openclaw.ai)
|
|
28
|
+
[](https://t.me/blockrunAI)
|
|
18
29
|
|
|
19
30
|
</div>
|
|
20
31
|
|
|
21
32
|
---
|
|
22
33
|
|
|
23
|
-
|
|
24
|
-
"What is 2+2?" โ NVIDIA Kimi $0.001/M saved ~100%
|
|
25
|
-
"Summarize this article" โ Grok Code Fast $1.50/M saved 94%
|
|
26
|
-
"Build a React component" โ Gemini 2.5 Pro $10.00/M best balance
|
|
27
|
-
"Prove this theorem" โ Grok 4.1 Fast $0.50/M reasoning
|
|
28
|
-
"Run 50 parallel searches"โ Kimi K2.5 $2.40/M agentic swarm
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
## Why ClawRouter?
|
|
32
|
-
|
|
33
|
-
- **4 routing profiles** โ auto (balanced), eco (95.9-100% savings), premium (best quality), free (zero cost)
|
|
34
|
-
- **100% local routing** โ 15-dimension weighted scoring runs on your machine in <1ms
|
|
35
|
-
- **Zero external calls** โ no API calls for routing decisions, ever
|
|
36
|
-
- **30+ models** โ OpenAI, Anthropic, Google, DeepSeek, xAI, Moonshot through one wallet
|
|
37
|
-
- **x402 micropayments** โ pay per request with USDC on Base, no API keys
|
|
38
|
-
- **Open source** โ MIT licensed, fully inspectable routing logic
|
|
39
|
-
|
|
40
|
-
### Ask Your OpenClaw How ClawRouter Saves You Money
|
|
34
|
+
## ๐ Quick Navigation
|
|
41
35
|
|
|
42
|
-
|
|
36
|
+
| Section | Description |
|
|
37
|
+
| ----------------------------------------- | --------------------------- |
|
|
38
|
+
| [Quick Start](#-quick-start) | Install in 2 minutes |
|
|
39
|
+
| [Routing Profiles](#-routing-profiles) | eco / auto / premium / free |
|
|
40
|
+
| [How It Works](#-how-it-works) | 15-dimension local routing |
|
|
41
|
+
| [Models & Pricing](#-models--pricing) | 30+ models, full price list |
|
|
42
|
+
| [Screenshots](#-screenshots) | See it in action |
|
|
43
|
+
| [Payment](#-payment) | x402 non-custodial USDC |
|
|
44
|
+
| [Configuration](#%EF%B8%8F-configuration) | Environment variables |
|
|
45
|
+
| [vs OpenRouter](#-vs-openrouter) | Why ClawRouter wins |
|
|
46
|
+
| [Support](#-support) | Telegram, X, founders |
|
|
43
47
|
|
|
44
48
|
---
|
|
45
49
|
|
|
46
|
-
## Quick Start
|
|
47
|
-
|
|
48
|
-
**Inspired by Andreas** โ we've updated our installation script:
|
|
50
|
+
## ๐ Quick Start
|
|
49
51
|
|
|
50
52
|
```bash
|
|
51
|
-
# 1. Install with smart routing enabled
|
|
53
|
+
# 1. Install with smart routing enabled
|
|
52
54
|
curl -fsSL https://blockrun.ai/ClawRouter-update | bash
|
|
53
55
|
openclaw gateway restart
|
|
54
56
|
|
|
@@ -58,169 +60,109 @@ openclaw gateway restart
|
|
|
58
60
|
|
|
59
61
|
Done! Smart routing (`blockrun/auto`) is now your default model.
|
|
60
62
|
|
|
61
|
-
### Routing Profiles
|
|
62
|
-
|
|
63
|
-
Choose your routing strategy with `/model <profile>`:
|
|
64
|
-
|
|
65
|
-
| Profile | Strategy | Savings | Use Case |
|
|
66
|
-
| ---------------- | ------------------ | --------- | ----------------------- |
|
|
67
|
-
| `/model auto` | Balanced (default) | 74-100% | Best overall balance |
|
|
68
|
-
| `/model eco` | Cost optimized | 95.9-100% | Maximum savings |
|
|
69
|
-
| `/model premium` | Quality focused | 0% | Best quality (Opus 4.5) |
|
|
70
|
-
| `/model free` | Free tier only | 100% | Zero cost |
|
|
71
|
-
|
|
72
|
-
**Other shortcuts:**
|
|
73
|
-
|
|
74
|
-
- **Model aliases:** `/model br-sonnet`, `/model grok`, `/model gpt5`, `/model o3`
|
|
75
|
-
- **Specific models:** `blockrun/openai/gpt-4o` or `blockrun/anthropic/claude-sonnet-4.6`
|
|
76
|
-
- **Bring your wallet:** `export BLOCKRUN_WALLET_KEY=0x...`
|
|
77
|
-
|
|
78
63
|
---
|
|
79
64
|
|
|
80
|
-
##
|
|
65
|
+
## ๐ฏ Routing Profiles
|
|
81
66
|
|
|
82
|
-
<
|
|
83
|
-
<img src="assets/telegram-demo.png" alt="ClawRouter in action via Telegram" width="500"/>
|
|
84
|
-
</div>
|
|
85
|
-
|
|
86
|
-
**The flow:**
|
|
67
|
+
Choose your routing strategy with `/model <profile>`:
|
|
87
68
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
69
|
+
| Profile | Strategy | Savings | Best For |
|
|
70
|
+
| ---------------- | ------------------ | ------- | ---------------- |
|
|
71
|
+
| `/model auto` | Balanced (default) | 74-100% | General use |
|
|
72
|
+
| `/model eco` | Cheapest possible | 95-100% | Maximum savings |
|
|
73
|
+
| `/model premium` | Best quality | 0% | Mission-critical |
|
|
74
|
+
| `/model free` | Free tier only | 100% | Zero cost |
|
|
92
75
|
|
|
93
|
-
|
|
76
|
+
**Shortcuts:** `/model grok`, `/model br-sonnet`, `/model gpt5`, `/model o3`
|
|
94
77
|
|
|
95
78
|
---
|
|
96
79
|
|
|
97
|
-
## How
|
|
98
|
-
|
|
99
|
-
**100% local, <1ms, zero API calls.**
|
|
100
|
-
|
|
101
|
-
```
|
|
102
|
-
Request โ Weighted Scorer (15 dimensions)
|
|
103
|
-
โ
|
|
104
|
-
โโโ High confidence โ Pick model from tier โ Done
|
|
105
|
-
โ
|
|
106
|
-
โโโ Low confidence โ Default to MEDIUM tier โ Done
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
No external classifier calls. Ambiguous queries default to the MEDIUM tier (Grok Code Fast) โ fast, cheap, and good enough for most tasks.
|
|
110
|
-
|
|
111
|
-
**Deep dive:** [15-dimension scoring weights](docs/configuration.md#scoring-weights) | [Architecture](docs/architecture.md)
|
|
112
|
-
|
|
113
|
-
### Routing Profiles (NEW in v0.8.21)
|
|
114
|
-
|
|
115
|
-
ClawRouter now offers 4 routing profiles to match different priorities:
|
|
80
|
+
## โก How It Works
|
|
116
81
|
|
|
117
|
-
|
|
118
|
-
| ------------------ | ----------------------- | ------------------- | ----------------------------- |
|
|
119
|
-
| **auto** (default) | Balanced quality + cost | 74-100% | General use, best overall |
|
|
120
|
-
| **eco** | Maximum cost savings | 95.9-100% | Budget-conscious, high volume |
|
|
121
|
-
| **premium** | Best quality only | 0% | Mission-critical tasks |
|
|
122
|
-
| **free** | Free tier only | 100% | Testing, empty wallet |
|
|
123
|
-
|
|
124
|
-
Switch profiles anytime: `/model eco`, `/model premium`, `/model auto`
|
|
125
|
-
|
|
126
|
-
**Example:**
|
|
82
|
+
**100% local routing. <1ms latency. Zero external API calls.**
|
|
127
83
|
|
|
128
84
|
```
|
|
129
|
-
|
|
130
|
-
"Write a React component" # Routes to DeepSeek ($0.28/$0.42)
|
|
131
|
-
# vs Auto โ Grok ($0.20/$1.50)
|
|
132
|
-
# 98.3% savings vs Opus 4.5
|
|
85
|
+
Request โ Weighted Scorer (15 dimensions) โ Tier โ Cheapest Model โ Response
|
|
133
86
|
```
|
|
134
87
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
|
138
|
-
|
|
|
139
|
-
|
|
|
140
|
-
|
|
|
141
|
-
| COMPLEX | gemini-2.5-pro | $10.00 | **60.0%** |
|
|
142
|
-
| REASONING | grok-4-1-fast-reasoning | $0.50 | **98.0%** |
|
|
143
|
-
|
|
144
|
-
Special rule: 2+ reasoning markers โ REASONING at 0.97 confidence.
|
|
145
|
-
|
|
146
|
-
### Advanced Features
|
|
147
|
-
|
|
148
|
-
ClawRouter v0.5+ includes intelligent features that work automatically:
|
|
149
|
-
|
|
150
|
-
- **Agentic auto-detect** โ routes multi-step tasks to Kimi K2.5
|
|
151
|
-
- **Tool detection** โ auto-switches when `tools` array present
|
|
152
|
-
- **Context-aware** โ filters models that can't handle your context size
|
|
153
|
-
- **Model aliases** โ `/model free`, `/model br-sonnet`, `/model grok`
|
|
154
|
-
- **Session persistence** โ pins model for multi-turn conversations
|
|
155
|
-
- **Free tier fallback** โ keeps working when wallet is empty
|
|
156
|
-
- **Auto-update check** โ notifies you when a new version is available
|
|
157
|
-
|
|
158
|
-
**Full details:** [docs/features.md](docs/features.md)
|
|
88
|
+
| Tier | ECO Model | AUTO Model | PREMIUM Model |
|
|
89
|
+
| --------- | ------------------------------ | ---------------------------- | ------------------------- |
|
|
90
|
+
| SIMPLE | nvidia/gpt-oss-120b (FREE) | kimi-k2.5 ($0.50/$2.40) | kimi-k2.5 |
|
|
91
|
+
| MEDIUM | gemini-2.5-flash ($0.15/$0.60) | grok-code-fast ($0.20/$1.50) | gpt-5.2-codex ($2.50/$10) |
|
|
92
|
+
| COMPLEX | gemini-2.5-flash ($0.15/$0.60) | gemini-3-pro ($2/$12) | claude-opus-4 ($15/$75) |
|
|
93
|
+
| REASONING | grok-4-fast ($0.20/$0.50) | grok-4-fast ($0.20/$0.50) | claude-sonnet-4 ($3/$15) |
|
|
159
94
|
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
| Tier | % of Traffic | Cost/M |
|
|
163
|
-
| ------------------- | ------------ | ----------- |
|
|
164
|
-
| SIMPLE | ~45% | $0.001 |
|
|
165
|
-
| MEDIUM | ~35% | $1.50 |
|
|
166
|
-
| COMPLEX | ~15% | $10.00 |
|
|
167
|
-
| REASONING | ~5% | $0.50 |
|
|
168
|
-
| **Blended average** | | **$2.05/M** |
|
|
169
|
-
|
|
170
|
-
Compared to **$25/M** for Claude Opus = **92% savings** on a typical workload.
|
|
95
|
+
**Blended average: $2.05/M** vs $25/M for Claude Opus = **92% savings**
|
|
171
96
|
|
|
172
97
|
---
|
|
173
98
|
|
|
174
|
-
## Models
|
|
175
|
-
|
|
176
|
-
30+ models across
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
|
182
|
-
|
|
|
183
|
-
|
|
|
184
|
-
| gpt-
|
|
185
|
-
|
|
|
186
|
-
|
|
|
187
|
-
| **
|
|
188
|
-
|
|
|
189
|
-
|
|
|
190
|
-
|
|
|
191
|
-
|
|
|
192
|
-
|
|
|
193
|
-
|
|
|
194
|
-
| **
|
|
195
|
-
|
|
|
196
|
-
|
|
|
197
|
-
|
|
|
198
|
-
|
|
|
199
|
-
|
|
|
200
|
-
|
|
|
201
|
-
|
|
|
202
|
-
| grok-
|
|
203
|
-
|
|
|
204
|
-
|
|
|
99
|
+
## ๐ฐ Models & Pricing
|
|
100
|
+
|
|
101
|
+
30+ models across 7 providers, one wallet:
|
|
102
|
+
|
|
103
|
+
<details>
|
|
104
|
+
<summary><strong>Click to expand full model list</strong></summary>
|
|
105
|
+
|
|
106
|
+
| Model | Input $/M | Output $/M | Context | Reasoning |
|
|
107
|
+
| ----------------------- | --------- | ---------- | ------- | :-------: |
|
|
108
|
+
| **OpenAI** | | | | |
|
|
109
|
+
| gpt-5.2 | $1.75 | $14.00 | 400K | \* |
|
|
110
|
+
| gpt-4o | $2.50 | $10.00 | 128K | |
|
|
111
|
+
| gpt-4o-mini | $0.15 | $0.60 | 128K | |
|
|
112
|
+
| gpt-oss-120b | **FREE** | **FREE** | 128K | |
|
|
113
|
+
| o3 | $2.00 | $8.00 | 200K | \* |
|
|
114
|
+
| o4-mini | $1.10 | $4.40 | 128K | \* |
|
|
115
|
+
| **Anthropic** | | | | |
|
|
116
|
+
| claude-opus-4.5 | $5.00 | $25.00 | 200K | \* |
|
|
117
|
+
| claude-sonnet-4.6 | $3.00 | $15.00 | 200K | \* |
|
|
118
|
+
| claude-haiku-4.5 | $1.00 | $5.00 | 200K | |
|
|
119
|
+
| **Google** | | | | |
|
|
120
|
+
| gemini-3-pro-preview | $2.00 | $12.00 | 1M | \* |
|
|
121
|
+
| gemini-2.5-pro | $1.25 | $10.00 | 1M | \* |
|
|
122
|
+
| gemini-2.5-flash | $0.15 | $0.60 | 1M | |
|
|
123
|
+
| **DeepSeek** | | | | |
|
|
124
|
+
| deepseek-chat | $0.14 | $0.28 | 128K | |
|
|
125
|
+
| deepseek-reasoner | $0.55 | $2.19 | 128K | \* |
|
|
126
|
+
| **xAI** | | | | |
|
|
127
|
+
| grok-4-0709 | $0.20 | $1.50 | 131K | \* |
|
|
128
|
+
| grok-4-1-fast-reasoning | $0.20 | $0.50 | 131K | \* |
|
|
129
|
+
| grok-code-fast-1 | $0.20 | $1.50 | 131K | |
|
|
130
|
+
| **Moonshot** | | | | |
|
|
131
|
+
| kimi-k2.5 | $0.50 | $2.40 | 262K | \* |
|
|
132
|
+
| **MiniMax** | | | | |
|
|
133
|
+
| minimax-m2.5 | $0.30 | $1.20 | 205K | \* |
|
|
134
|
+
|
|
135
|
+
</details>
|
|
205
136
|
|
|
206
137
|
> **Free tier:** `gpt-oss-120b` costs nothing and serves as automatic fallback when wallet is empty.
|
|
207
138
|
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
### Kimi K2.5: Agentic Workflows
|
|
139
|
+
---
|
|
211
140
|
|
|
212
|
-
|
|
141
|
+
## ๐ธ Screenshots
|
|
142
|
+
|
|
143
|
+
<table>
|
|
144
|
+
<tr>
|
|
145
|
+
<td width="50%" align="center">
|
|
146
|
+
<strong>Smart Routing in Action</strong><br><br>
|
|
147
|
+
<img src="docs/clawrouter-savings.png" alt="ClawRouter savings" width="400">
|
|
148
|
+
</td>
|
|
149
|
+
<td width="50%" align="center">
|
|
150
|
+
<strong>Telegram Integration</strong><br><br>
|
|
151
|
+
<img src="assets/telegram-demo.png" alt="Telegram demo" width="400">
|
|
152
|
+
</td>
|
|
153
|
+
</tr>
|
|
154
|
+
</table>
|
|
213
155
|
|
|
214
|
-
|
|
215
|
-
- **Extended Tool Chains** โ Stable across 200-300 sequential tool calls without drift
|
|
216
|
-
- **Vision-to-Code** โ Generates production React from UI mockups and videos
|
|
217
|
-
- **Cost Efficient** โ 76% cheaper than Claude Opus on agentic benchmarks
|
|
156
|
+
**The flow:**
|
|
218
157
|
|
|
219
|
-
|
|
158
|
+
1. **Wallet auto-generated** on Base (L2) โ saved at `~/.openclaw/blockrun/wallet.key`
|
|
159
|
+
2. **Fund with $1 USDC** โ enough for hundreds of requests
|
|
160
|
+
3. **Request any model** โ ClawRouter picks the cheapest capable one
|
|
161
|
+
4. **Pay per request** โ non-custodial, you hold your keys
|
|
220
162
|
|
|
221
163
|
---
|
|
222
164
|
|
|
223
|
-
## Payment
|
|
165
|
+
## ๐ณ Payment
|
|
224
166
|
|
|
225
167
|
No account. No API key. **Payment IS authentication** via [x402](https://x402.org).
|
|
226
168
|
|
|
@@ -230,111 +172,34 @@ Request โ 402 (price: $0.003) โ wallet signs USDC โ retry โ response
|
|
|
230
172
|
|
|
231
173
|
USDC stays in your wallet until spent โ non-custodial. Price is visible in the 402 header before signing.
|
|
232
174
|
|
|
233
|
-
**Fund your wallet:**
|
|
234
|
-
|
|
235
|
-
- Coinbase: Buy USDC, send to Base
|
|
236
|
-
- Bridge: Move USDC from any chain to Base
|
|
237
|
-
- CEX: Withdraw USDC to Base network
|
|
238
|
-
|
|
239
|
-
---
|
|
240
|
-
|
|
241
|
-
## Wallet Configuration
|
|
242
|
-
|
|
243
|
-
ClawRouter auto-generates and saves a wallet at `~/.openclaw/blockrun/wallet.key`.
|
|
244
|
-
|
|
245
175
|
```bash
|
|
246
|
-
# Check
|
|
247
|
-
/
|
|
248
|
-
|
|
249
|
-
# Use your own wallet
|
|
250
|
-
export BLOCKRUN_WALLET_KEY=0x...
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
**Full reference:** [Wallet configuration](docs/configuration.md#wallet-configuration) | [Backup & recovery](docs/configuration.md#wallet-backup--recovery)
|
|
254
|
-
|
|
255
|
-
---
|
|
256
|
-
|
|
257
|
-
## Architecture
|
|
258
|
-
|
|
259
|
-
```
|
|
260
|
-
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
261
|
-
โ Your Application โ
|
|
262
|
-
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
263
|
-
โ
|
|
264
|
-
โผ
|
|
265
|
-
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
266
|
-
โ ClawRouter (localhost) โ
|
|
267
|
-
โ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โ
|
|
268
|
-
โ โ Weighted Scorer โโ โ Model Selector โโ โ x402 Signer โ โ
|
|
269
|
-
โ โ (15 dimensions)โ โ (cheapest tier) โ โ (USDC) โ โ
|
|
270
|
-
โ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โ
|
|
271
|
-
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
272
|
-
โ
|
|
273
|
-
โผ
|
|
274
|
-
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
275
|
-
โ BlockRun API โ
|
|
276
|
-
โ โ OpenAI | Anthropic | Google | DeepSeek | xAI | Moonshotโ
|
|
277
|
-
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
176
|
+
/wallet # Check balance and address
|
|
177
|
+
/stats # View usage and savings
|
|
278
178
|
```
|
|
279
179
|
|
|
280
|
-
|
|
180
|
+
**Fund your wallet:**
|
|
281
181
|
|
|
282
|
-
**
|
|
182
|
+
- **Coinbase:** Buy USDC, send to Base
|
|
183
|
+
- **Bridge:** Move USDC from any chain to Base
|
|
184
|
+
- **CEX:** Withdraw USDC to Base network
|
|
283
185
|
|
|
284
186
|
---
|
|
285
187
|
|
|
286
|
-
## Configuration
|
|
188
|
+
## โ๏ธ Configuration
|
|
287
189
|
|
|
288
190
|
For basic usage, no configuration needed. For advanced options:
|
|
289
191
|
|
|
290
|
-
|
|
|
291
|
-
| --------------------- |
|
|
292
|
-
| `
|
|
293
|
-
| `BLOCKRUN_PROXY_PORT` | `8402`
|
|
294
|
-
| `
|
|
192
|
+
| Variable | Default | Description |
|
|
193
|
+
| --------------------- | -------------- | ----------------------- |
|
|
194
|
+
| `BLOCKRUN_WALLET_KEY` | auto-generated | Your wallet private key |
|
|
195
|
+
| `BLOCKRUN_PROXY_PORT` | `8402` | Local proxy port |
|
|
196
|
+
| `CLAWROUTER_DISABLED` | `false` | Disable smart routing |
|
|
295
197
|
|
|
296
198
|
**Full reference:** [docs/configuration.md](docs/configuration.md)
|
|
297
199
|
|
|
298
200
|
---
|
|
299
201
|
|
|
300
|
-
##
|
|
301
|
-
|
|
302
|
-
Use ClawRouter directly in your code:
|
|
303
|
-
|
|
304
|
-
```typescript
|
|
305
|
-
import { startProxy, route } from "@blockrun/clawrouter";
|
|
306
|
-
|
|
307
|
-
// Start proxy server
|
|
308
|
-
const proxy = await startProxy({ walletKey: "0x..." });
|
|
309
|
-
|
|
310
|
-
// Or use router directly (no proxy)
|
|
311
|
-
const decision = route("Prove sqrt(2) is irrational", ...);
|
|
312
|
-
```
|
|
313
|
-
|
|
314
|
-
**Full examples:** [docs/configuration.md#programmatic-usage](docs/configuration.md#programmatic-usage)
|
|
315
|
-
|
|
316
|
-
---
|
|
317
|
-
|
|
318
|
-
## Performance Optimizations (v0.3+)
|
|
319
|
-
|
|
320
|
-
- **SSE heartbeat**: Sends headers + heartbeat immediately, preventing upstream timeouts
|
|
321
|
-
- **Response dedup**: SHA-256 hash โ 30s cache, prevents double-charge on retries
|
|
322
|
-
- **Payment pre-auth**: Caches 402 params, pre-signs USDC, skips 402 round trip (~200ms saved)
|
|
323
|
-
- **Response cache**: LLM response caching with 10-minute TTL, saves cost on repeated queries
|
|
324
|
-
|
|
325
|
-
---
|
|
326
|
-
|
|
327
|
-
## Cost Tracking
|
|
328
|
-
|
|
329
|
-
Track your savings with `/stats` in any OpenClaw conversation.
|
|
330
|
-
|
|
331
|
-
**Full details:** [docs/features.md#cost-tracking-with-stats](docs/features.md#cost-tracking-with-stats)
|
|
332
|
-
|
|
333
|
-
---
|
|
334
|
-
|
|
335
|
-
## Why Not OpenRouter / LiteLLM?
|
|
336
|
-
|
|
337
|
-
They're built for developers. ClawRouter is built for **agents**.
|
|
202
|
+
## ๐ฅ vs OpenRouter
|
|
338
203
|
|
|
339
204
|
| | OpenRouter / LiteLLM | ClawRouter |
|
|
340
205
|
| --------------- | --------------------------- | -------------------------------- |
|
|
@@ -345,128 +210,53 @@ They're built for developers. ClawRouter is built for **agents**.
|
|
|
345
210
|
| **Rate limits** | Per-key quotas | None (your wallet, your limits) |
|
|
346
211
|
| **Cost** | $25/M (Opus equivalent) | $2.05/M blended average |
|
|
347
212
|
|
|
348
|
-
Agents shouldn't need a human to paste API keys. They should generate a wallet, receive funds, and pay per request โ programmatically.
|
|
349
|
-
|
|
350
|
-
### Real Problems with OpenRouter
|
|
351
|
-
|
|
352
|
-
Based on [50+ OpenClaw issues](https://github.com/openclaw/openclaw/issues?q=openrouter):
|
|
353
|
-
|
|
354
|
-
| Issue | Problem | ClawRouter |
|
|
355
|
-
| ----------------------------------------------------------- | ----------------------------------- | -------------------------- |
|
|
356
|
-
| [#11202](https://github.com/openclaw/openclaw/issues/11202) | API keys leaked in every LLM prompt | No API keys to leak |
|
|
357
|
-
| [#2373](https://github.com/openclaw/openclaw/issues/2373) | `openrouter/auto` path broken | `blockrun/auto` just works |
|
|
358
|
-
| [#8615](https://github.com/openclaw/openclaw/issues/8615) | Single API key rate limit hell | Non-custodial, no limits |
|
|
359
|
-
| [#2963](https://github.com/openclaw/openclaw/issues/2963) | Tool calling fails silently | Full tool support |
|
|
360
|
-
| [#10687](https://github.com/openclaw/openclaw/issues/10687) | "Unknown model" errors | 30+ models, auto-update |
|
|
361
|
-
|
|
362
213
|
**[Full comparison โ](docs/vs-openrouter.md)**
|
|
363
214
|
|
|
364
215
|
---
|
|
365
216
|
|
|
366
|
-
##
|
|
367
|
-
|
|
368
|
-
- **Agents need to pay and get paid โ without humans in the loop.** Today's AI infra requires accounts, API keys, manual billing. But an agent spawning 50 sub-agents shouldn't need a human to provision 50 keys. An agent completing a bounty shouldn't wait for someone to invoice and collect.
|
|
369
|
-
|
|
370
|
-
- **Payment IS authentication.** A wallet signature proves you can pay โ no shared secrets that leak into prompts, no accounts to create, no keys to rotate.
|
|
371
|
-
|
|
372
|
-
- **Agents should control their own money.** Non-custodial means the agent holds the keys. No platform can freeze funds or change terms overnight.
|
|
373
|
-
|
|
374
|
-
- **Cost optimization should be automatic.** Agents shouldn't overpay $25/M for "what is 2+2". Smart routing to the cheapest capable model saves 92% on typical workloads.
|
|
375
|
-
|
|
376
|
-
The result: an agent can generate a wallet, receive funds, call any model, pay per-request, and earn money โ all programmatically. **This is agentic commerce.**
|
|
377
|
-
|
|
378
|
-
---
|
|
379
|
-
|
|
380
|
-
## Troubleshooting
|
|
381
|
-
|
|
382
|
-
Quick checklist:
|
|
383
|
-
|
|
384
|
-
```bash
|
|
385
|
-
# Check version (should be 0.8.21+)
|
|
386
|
-
cat ~/.openclaw/extensions/clawrouter/package.json | grep version
|
|
387
|
-
|
|
388
|
-
# Check proxy running
|
|
389
|
-
curl http://localhost:8402/health
|
|
390
|
-
|
|
391
|
-
# Update to latest version
|
|
392
|
-
curl -fsSL https://blockrun.ai/ClawRouter-update | bash
|
|
393
|
-
openclaw gateway restart
|
|
394
|
-
```
|
|
395
|
-
|
|
396
|
-
ClawRouter automatically checks for updates on startup and shows a notification if a newer version is available.
|
|
397
|
-
|
|
398
|
-
**Full guide:** [docs/troubleshooting.md](docs/troubleshooting.md)
|
|
399
|
-
|
|
400
|
-
---
|
|
401
|
-
|
|
402
|
-
## Development
|
|
217
|
+
## ๐ Development
|
|
403
218
|
|
|
404
219
|
```bash
|
|
405
220
|
git clone https://github.com/BlockRunAI/ClawRouter.git
|
|
406
221
|
cd ClawRouter
|
|
407
222
|
npm install
|
|
408
223
|
npm run build
|
|
409
|
-
npm
|
|
410
|
-
|
|
411
|
-
# End-to-end tests (requires funded wallet)
|
|
412
|
-
BLOCKRUN_WALLET_KEY=0x... npx tsx test-e2e.ts
|
|
413
|
-
```
|
|
414
|
-
|
|
415
|
-
---
|
|
416
|
-
|
|
417
|
-
## Uninstall
|
|
418
|
-
|
|
419
|
-
```bash
|
|
420
|
-
openclaw plugins uninstall clawrouter
|
|
421
|
-
openclaw gateway restart
|
|
224
|
+
npm test
|
|
422
225
|
```
|
|
423
226
|
|
|
424
|
-
Your wallet key remains at `~/.openclaw/blockrun/wallet.key` โ back it up before deleting if you have funds.
|
|
425
|
-
|
|
426
|
-
---
|
|
427
|
-
|
|
428
|
-
## Roadmap
|
|
429
|
-
|
|
430
|
-
- [x] Smart routing โ 15-dimension weighted scoring, 4-tier model selection
|
|
431
|
-
- [x] x402 payments โ per-request USDC micropayments, non-custodial
|
|
432
|
-
- [x] Response dedup โ prevents double-charge on retries
|
|
433
|
-
- [x] Payment pre-auth โ skips 402 round trip
|
|
434
|
-
- [x] SSE heartbeat โ prevents upstream timeouts
|
|
435
|
-
- [x] Agentic auto-detect โ auto-switch to agentic models for multi-step tasks
|
|
436
|
-
- [x] Tool detection โ auto-switch to agentic mode when tools array present
|
|
437
|
-
- [x] Context-aware routing โ filter out models that can't handle context size
|
|
438
|
-
- [x] Session persistence โ pin model for multi-turn conversations
|
|
439
|
-
- [x] Cost tracking โ /stats command with savings dashboard
|
|
440
|
-
- [x] Model aliases โ `/model free`, `/model br-sonnet`, `/model grok`, etc.
|
|
441
|
-
- [x] Free tier โ gpt-oss-120b for $0 when wallet is empty
|
|
442
|
-
- [x] Auto-update โ startup version check with one-command update
|
|
443
|
-
- [x] Response cache โ LiteLLM-inspired caching for repeated requests
|
|
444
|
-
- [ ] Cascade routing โ try cheap model first, escalate on low quality
|
|
445
|
-
- [ ] Spend controls โ daily/monthly budgets
|
|
446
|
-
- [ ] Remote analytics โ cost tracking at blockrun.ai
|
|
447
|
-
|
|
448
227
|
---
|
|
449
228
|
|
|
450
|
-
## Support
|
|
229
|
+
## ๐ Support
|
|
451
230
|
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
231
|
+
| Channel | Link |
|
|
232
|
+
| --------------------- | ------------------------------------------------------------------ |
|
|
233
|
+
| ๐
Schedule Demo | [calendly.com/vickyfu9/30min](https://calendly.com/vickyfu9/30min) |
|
|
234
|
+
| ๐ฌ Community Telegram | [t.me/blockrunAI](https://t.me/blockrunAI) |
|
|
235
|
+
| ๐ฆ X / Twitter | [x.com/BlockRunAI](https://x.com/BlockRunAI) |
|
|
236
|
+
| ๐ฑ Founder Telegram | [@bc1max](https://t.me/bc1max) |
|
|
237
|
+
| โ๏ธ Email | vicky@blockrun.ai |
|
|
457
238
|
|
|
458
239
|
---
|
|
459
240
|
|
|
460
|
-
##
|
|
241
|
+
## ๐ More Resources
|
|
461
242
|
|
|
462
|
-
|
|
243
|
+
| Resource | Description |
|
|
244
|
+
| -------------------------------------------- | ------------------------ |
|
|
245
|
+
| [Documentation](https://blockrun.ai/docs) | Full docs |
|
|
246
|
+
| [Model Pricing](https://blockrun.ai/models) | All models & prices |
|
|
247
|
+
| [Routing Profiles](docs/routing-profiles.md) | ECO/AUTO/PREMIUM details |
|
|
248
|
+
| [Architecture](docs/architecture.md) | Technical deep dive |
|
|
249
|
+
| [Configuration](docs/configuration.md) | Environment variables |
|
|
250
|
+
| [vs OpenRouter](docs/vs-openrouter.md) | Why ClawRouter wins |
|
|
251
|
+
| [Features](docs/features.md) | All features |
|
|
252
|
+
| [Troubleshooting](docs/troubleshooting.md) | Common issues |
|
|
463
253
|
|
|
464
254
|
---
|
|
465
255
|
|
|
466
256
|
<div align="center">
|
|
467
257
|
|
|
468
|
-
**[BlockRun](https://blockrun.ai)
|
|
258
|
+
**MIT License** ยท [BlockRun](https://blockrun.ai) โ Pay-per-request AI infrastructure
|
|
469
259
|
|
|
470
|
-
If ClawRouter saves you money, consider starring the repo
|
|
260
|
+
โญ If ClawRouter saves you money, consider starring the repo!
|
|
471
261
|
|
|
472
262
|
</div>
|
package/dist/cli.js
CHANGED
|
@@ -3428,7 +3428,7 @@ async function checkForUpdates() {
|
|
|
3428
3428
|
// src/config.ts
|
|
3429
3429
|
var DEFAULT_PORT = 8402;
|
|
3430
3430
|
var PROXY_PORT = (() => {
|
|
3431
|
-
const envPort = process
|
|
3431
|
+
const envPort = process["env"].BLOCKRUN_PROXY_PORT;
|
|
3432
3432
|
if (envPort) {
|
|
3433
3433
|
const parsed = parseInt(envPort, 10);
|
|
3434
3434
|
if (!isNaN(parsed) && parsed > 0 && parsed < 65536) {
|
|
@@ -5104,7 +5104,7 @@ async function resolveOrGenerateWalletKey() {
|
|
|
5104
5104
|
const account = privateKeyToAccount3(saved);
|
|
5105
5105
|
return { key: saved, address: account.address, source: "saved" };
|
|
5106
5106
|
}
|
|
5107
|
-
const envKey = process
|
|
5107
|
+
const envKey = process["env"].BLOCKRUN_WALLET_KEY;
|
|
5108
5108
|
if (typeof envKey === "string" && envKey.startsWith("0x") && envKey.length === 66) {
|
|
5109
5109
|
const account = privateKeyToAccount3(envKey);
|
|
5110
5110
|
return { key: envKey, address: account.address, source: "env" };
|