@blockrun/clawrouter 0.9.33 โ 0.9.34
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 +157 -369
- package/dist/cli.js +2 -2
- package/dist/cli.js.map +1 -1
- package/dist/index.js +3 -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,108 @@ 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
|
|
80
|
+
## โก How It Works
|
|
98
81
|
|
|
99
|
-
**100% local
|
|
82
|
+
**100% local routing. <1ms latency. Zero external API calls.**
|
|
100
83
|
|
|
101
84
|
```
|
|
102
|
-
Request โ Weighted Scorer (15 dimensions)
|
|
103
|
-
โ
|
|
104
|
-
โโโ High confidence โ Pick model from tier โ Done
|
|
105
|
-
โ
|
|
106
|
-
โโโ Low confidence โ Default to MEDIUM tier โ Done
|
|
85
|
+
Request โ Weighted Scorer (15 dimensions) โ Tier โ Cheapest Model โ Response
|
|
107
86
|
```
|
|
108
87
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
ClawRouter now offers 4 routing profiles to match different priorities:
|
|
116
|
-
|
|
117
|
-
| Profile | Strategy | Savings vs Opus 4.5 | When to Use |
|
|
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:**
|
|
127
|
-
|
|
128
|
-
```
|
|
129
|
-
/model eco # Switch to cost-optimized routing
|
|
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
|
|
133
|
-
```
|
|
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) |
|
|
134
94
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
| Tier | Primary Model | Cost/M | Savings vs Opus |
|
|
138
|
-
| --------- | ----------------------- | ------ | --------------- |
|
|
139
|
-
| SIMPLE | nvidia/kimi-k2.5 | $0.001 | **~100%** |
|
|
140
|
-
| MEDIUM | grok-code-fast-1 | $1.50 | **94.0%** |
|
|
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)
|
|
159
|
-
|
|
160
|
-
### Cost Savings
|
|
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
|
|
211
|
-
|
|
212
|
-
[Kimi K2.5](https://kimi.ai) from Moonshot AI is optimized for agent swarm and multi-step workflows:
|
|
139
|
+
---
|
|
213
140
|
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
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>
|
|
218
155
|
|
|
219
|
-
|
|
156
|
+
**The flow:**
|
|
157
|
+
1. **Wallet auto-generated** on Base (L2) โ saved at `~/.openclaw/blockrun/wallet.key`
|
|
158
|
+
2. **Fund with $1 USDC** โ enough for hundreds of requests
|
|
159
|
+
3. **Request any model** โ ClawRouter picks the cheapest capable one
|
|
160
|
+
4. **Pay per request** โ non-custodial, you hold your keys
|
|
220
161
|
|
|
221
162
|
---
|
|
222
163
|
|
|
223
|
-
## Payment
|
|
164
|
+
## ๐ณ Payment
|
|
224
165
|
|
|
225
166
|
No account. No API key. **Payment IS authentication** via [x402](https://x402.org).
|
|
226
167
|
|
|
@@ -230,243 +171,90 @@ Request โ 402 (price: $0.003) โ wallet signs USDC โ retry โ response
|
|
|
230
171
|
|
|
231
172
|
USDC stays in your wallet until spent โ non-custodial. Price is visible in the 402 header before signing.
|
|
232
173
|
|
|
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
174
|
```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
|
-
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
175
|
+
/wallet # Check balance and address
|
|
176
|
+
/stats # View usage and savings
|
|
278
177
|
```
|
|
279
178
|
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
**
|
|
179
|
+
**Fund your wallet:**
|
|
180
|
+
- **Coinbase:** Buy USDC, send to Base
|
|
181
|
+
- **Bridge:** Move USDC from any chain to Base
|
|
182
|
+
- **CEX:** Withdraw USDC to Base network
|
|
283
183
|
|
|
284
184
|
---
|
|
285
185
|
|
|
286
|
-
## Configuration
|
|
186
|
+
## โ๏ธ Configuration
|
|
287
187
|
|
|
288
188
|
For basic usage, no configuration needed. For advanced options:
|
|
289
189
|
|
|
290
|
-
|
|
|
291
|
-
|
|
190
|
+
| Variable | Default | Description |
|
|
191
|
+
|----------|---------|-------------|
|
|
192
|
+
| `BLOCKRUN_WALLET_KEY` | auto-generated | Your wallet private key |
|
|
193
|
+
| `BLOCKRUN_PROXY_PORT` | `8402` | Local proxy port |
|
|
292
194
|
| `CLAWROUTER_DISABLED` | `false` | Disable smart routing |
|
|
293
|
-
| `BLOCKRUN_PROXY_PORT` | `8402` | Proxy port |
|
|
294
|
-
| `BLOCKRUN_WALLET_KEY` | auto | Wallet private key |
|
|
295
195
|
|
|
296
196
|
**Full reference:** [docs/configuration.md](docs/configuration.md)
|
|
297
197
|
|
|
298
198
|
---
|
|
299
199
|
|
|
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
|
|
200
|
+
## ๐ฅ vs OpenRouter
|
|
328
201
|
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
**
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
They're built for developers. ClawRouter is built for **agents**.
|
|
338
|
-
|
|
339
|
-
| | OpenRouter / LiteLLM | ClawRouter |
|
|
340
|
-
| --------------- | --------------------------- | -------------------------------- |
|
|
341
|
-
| **Setup** | Human creates account | Agent generates wallet |
|
|
342
|
-
| **Auth** | API key (shared secret) | Wallet signature (cryptographic) |
|
|
343
|
-
| **Payment** | Prepaid balance (custodial) | Per-request (non-custodial) |
|
|
344
|
-
| **Routing** | Proprietary / closed | Open source, client-side |
|
|
345
|
-
| **Rate limits** | Per-key quotas | None (your wallet, your limits) |
|
|
346
|
-
| **Cost** | $25/M (Opus equivalent) | $2.05/M blended average |
|
|
347
|
-
|
|
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 |
|
|
202
|
+
| | OpenRouter / LiteLLM | ClawRouter |
|
|
203
|
+
|--|---------------------|------------|
|
|
204
|
+
| **Setup** | Human creates account | Agent generates wallet |
|
|
205
|
+
| **Auth** | API key (shared secret) | Wallet signature (cryptographic) |
|
|
206
|
+
| **Payment** | Prepaid balance (custodial) | Per-request (non-custodial) |
|
|
207
|
+
| **Routing** | Proprietary / closed | Open source, client-side |
|
|
208
|
+
| **Rate limits** | Per-key quotas | None (your wallet, your limits) |
|
|
209
|
+
| **Cost** | $25/M (Opus equivalent) | $2.05/M blended average |
|
|
361
210
|
|
|
362
211
|
**[Full comparison โ](docs/vs-openrouter.md)**
|
|
363
212
|
|
|
364
213
|
---
|
|
365
214
|
|
|
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
|
|
215
|
+
## ๐ Development
|
|
403
216
|
|
|
404
217
|
```bash
|
|
405
218
|
git clone https://github.com/BlockRunAI/ClawRouter.git
|
|
406
219
|
cd ClawRouter
|
|
407
220
|
npm install
|
|
408
221
|
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
|
|
222
|
+
npm test
|
|
422
223
|
```
|
|
423
224
|
|
|
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
225
|
---
|
|
449
226
|
|
|
450
|
-
## Support
|
|
227
|
+
## ๐ Support
|
|
451
228
|
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
229
|
+
| Channel | Link |
|
|
230
|
+
|---------|------|
|
|
231
|
+
| ๐
Schedule Demo | [calendly.com/vickyfu9/30min](https://calendly.com/vickyfu9/30min) |
|
|
232
|
+
| ๐ฌ Community Telegram | [t.me/blockrunAI](https://t.me/blockrunAI) |
|
|
233
|
+
| ๐ฆ X / Twitter | [x.com/BlockRunAI](https://x.com/BlockRunAI) |
|
|
234
|
+
| ๐ฑ Founder Telegram | [@bc1max](https://t.me/bc1max) |
|
|
235
|
+
| โ๏ธ Email | vicky@blockrun.ai |
|
|
457
236
|
|
|
458
237
|
---
|
|
459
238
|
|
|
460
|
-
##
|
|
239
|
+
## ๐ More Resources
|
|
461
240
|
|
|
462
|
-
|
|
241
|
+
| Resource | Description |
|
|
242
|
+
|----------|-------------|
|
|
243
|
+
| [Documentation](https://blockrun.ai/docs) | Full docs |
|
|
244
|
+
| [Model Pricing](https://blockrun.ai/models) | All models & prices |
|
|
245
|
+
| [Routing Profiles](docs/routing-profiles.md) | ECO/AUTO/PREMIUM details |
|
|
246
|
+
| [Architecture](docs/architecture.md) | Technical deep dive |
|
|
247
|
+
| [Configuration](docs/configuration.md) | Environment variables |
|
|
248
|
+
| [vs OpenRouter](docs/vs-openrouter.md) | Why ClawRouter wins |
|
|
249
|
+
| [Features](docs/features.md) | All features |
|
|
250
|
+
| [Troubleshooting](docs/troubleshooting.md) | Common issues |
|
|
463
251
|
|
|
464
252
|
---
|
|
465
253
|
|
|
466
254
|
<div align="center">
|
|
467
255
|
|
|
468
|
-
**[BlockRun](https://blockrun.ai)
|
|
256
|
+
**MIT License** ยท [BlockRun](https://blockrun.ai) โ Pay-per-request AI infrastructure
|
|
469
257
|
|
|
470
|
-
If ClawRouter saves you money, consider starring the repo
|
|
258
|
+
โญ If ClawRouter saves you money, consider starring the repo!
|
|
471
259
|
|
|
472
260
|
</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" };
|