@blockrun/clawrouter 0.3.1 → 0.3.3

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.
Files changed (5) hide show
  1. package/README.md +291 -217
  2. package/dist/index.d.ts +215 -3
  3. package/dist/index.js +668 -86
  4. package/dist/index.js.map +1 -1
  5. package/package.json +10 -3
package/README.md CHANGED
@@ -19,160 +19,237 @@ One wallet, 30+ models, zero API keys.
19
19
  ---
20
20
 
21
21
  ```
22
- "What is 2+2?" → Gemini Flash $0.60/M saved 99%
23
- "Summarize this article" → DeepSeek Chat $0.42/M saved 99%
24
- "Build a React component" → Claude Opus $75.00/M best quality
25
- "Prove this theorem" → o3 $8.00/M saved 89%
22
+ "What is 2+2?" → DeepSeek $0.27/M saved 99%
23
+ "Summarize this article" → GPT-4o-mini $0.60/M saved 99%
24
+ "Build a React component" → Claude Sonnet $15.00/M best balance
25
+ "Prove this theorem" → o3 $10.00/M reasoning
26
+ "Run 50 parallel searches"→ Kimi K2.5 $2.40/M agentic swarm
26
27
  ```
27
28
 
28
- ClawRouter is a smart LLM router for [OpenClaw](https://github.com/openclaw/openclaw). It classifies each request, picks the cheapest model that can handle it, and pays per-request via [x402](https://x402.org) USDC micropayments on Base. No account, no API key — your wallet signs each payment.
29
+ ## Why ClawRouter?
29
30
 
30
- ## Quick Start
31
+ - **100% local routing** — 14-dimension weighted scoring runs on your machine in <1ms
32
+ - **Zero external calls** — no API calls for routing decisions, ever
33
+ - **30+ models** — OpenAI, Anthropic, Google, DeepSeek, xAI, Moonshot through one wallet
34
+ - **x402 micropayments** — pay per request with USDC on Base, no API keys
35
+ - **Open source** — MIT licensed, fully inspectable routing logic
36
+
37
+ ### Ask Your OpenClaw How ClawRouter Saves You Money
38
+
39
+ <img src="docs/clawrouter-savings.png" alt="ClawRouter savings explanation" width="600">
40
+
41
+ ---
42
+
43
+ ## Quick Start (2 mins)
31
44
 
32
45
  ```bash
33
46
  # 1. Install — auto-generates a wallet on Base
34
- openclaw plugin install @blockrun/clawrouter
47
+ openclaw plugins install @blockrun/clawrouter
35
48
 
36
49
  # 2. Fund your wallet with USDC on Base (address printed on install)
37
- # A few dollars is enough to start — each request costs fractions of a cent
50
+ $5 is enough for thousands of requests
38
51
 
39
52
  # 3. Enable smart routing
40
- openclaw config set model blockrun/auto
53
+ openclaw models set blockrun/auto
41
54
  ```
42
55
 
43
56
  Every request now routes to the cheapest capable model.
44
57
 
45
- Already have a funded wallet? Bring your own: `export BLOCKRUN_WALLET_KEY=0x...`
58
+ Already have a funded wallet? `export BLOCKRUN_WALLET_KEY=0x...`
59
+
60
+ Want a specific model? `openclaw models set openai/gpt-4o` — still get x402 payments and usage logging.
61
+
62
+ ---
63
+
64
+ ## See It In Action
65
+
66
+ <div align="center">
67
+ <img src="assets/telegram-demo.png" alt="ClawRouter in action via Telegram" width="500"/>
68
+ </div>
69
+
70
+ **The flow:**
71
+
72
+ 1. **Wallet auto-generated** on Base (L2) — saved securely at `~/.openclaw/blockrun/wallet.key`
73
+ 2. **Fund with $1 USDC** — enough for hundreds of requests
74
+ 3. **Request any model** — "help me call Grok to check @hosseeb's opinion on AI agents"
75
+ 4. **ClawRouter routes it** — spawns a Grok sub-agent via `xai/grok-3`, pays per-request
76
+
77
+ No API keys. No accounts. Just fund and go.
46
78
 
47
- Want a specific model instead? `openclaw config set model openai/gpt-4o` — you still get x402 payments and usage logging.
79
+ ---
48
80
 
49
81
  ## How Routing Works
50
82
 
51
- Hybrid rules-first approach. 14 weighted scoring dimensions classify ~80% of requests in <1ms at zero cost. Only low-confidence queries hit the LLM classifier.
83
+ **100% local, <1ms, zero API calls.**
52
84
 
53
85
  ```
54
- Request → Weighted scorer (14 dimensions, < 1ms, free)
55
- ├── Confident → pick model → done
56
- └── Low confidence → LLM classifier (~200ms, ~$0.00003)
57
- └── classify → pick model → done
86
+ Request → Weighted Scorer (14 dimensions)
87
+ │
88
+ ├── High confidence → Pick model from tier → Done
89
+ │
90
+ └── Low confidence → Default to MEDIUM tier → Done
58
91
  ```
59
92
 
60
- ### Weighted Scoring Engine
61
-
62
- 14 dimensions, each scored in [-1, 1] and multiplied by a learned weight:
93
+ No external classifier calls. Ambiguous queries default to the MEDIUM tier (DeepSeek/GPT-4o-mini) — fast, cheap, and good enough for most tasks.
63
94
 
64
- | Dimension | Weight | Signal |
65
- |-----------|--------|--------|
66
- | Reasoning markers | 0.18 | "prove", "theorem", "step by step" |
67
- | Code presence | 0.15 | "function", "async", "import", "```" |
68
- | Simple indicators | 0.12 | "what is", "define", "translate" |
69
- | Multi-step patterns | 0.12 | "first...then", "step 1", numbered lists |
70
- | Technical terms | 0.10 | "algorithm", "kubernetes", "distributed" |
71
- | Token count | 0.08 | short (<50) vs long (>500) |
72
- | Creative markers | 0.05 | "story", "poem", "brainstorm" |
73
- | Question complexity | 0.05 | 4+ question marks |
74
- | Constraint count | 0.04 | "at most", "O(n)", "maximum" |
75
- | Imperative verbs | 0.03 | "build", "create", "implement" |
76
- | Output format | 0.03 | "json", "yaml", "schema" |
77
- | Domain specificity | 0.02 | "quantum", "fpga", "genomics" |
78
- | Reference complexity | 0.02 | "the docs", "the api", "above" |
79
- | Negation complexity | 0.01 | "don't", "avoid", "without" |
95
+ ### 14-Dimension Weighted Scoring
80
96
 
81
- Weighted score maps to a tier via configurable boundaries. Confidence is calibrated using a sigmoid function — distance from the nearest tier boundary determines how sure the classifier is.
97
+ | Dimension | Weight | What It Detects |
98
+ | -------------------- | ------ | ---------------------------------------- |
99
+ | Reasoning markers | 0.18 | "prove", "theorem", "step by step" |
100
+ | Code presence | 0.15 | "function", "async", "import", "```" |
101
+ | Simple indicators | 0.12 | "what is", "define", "translate" |
102
+ | Multi-step patterns | 0.12 | "first...then", "step 1", numbered lists |
103
+ | Technical terms | 0.10 | "algorithm", "kubernetes", "distributed" |
104
+ | Token count | 0.08 | short (<50) vs long (>500) prompts |
105
+ | Creative markers | 0.05 | "story", "poem", "brainstorm" |
106
+ | Question complexity | 0.05 | Multiple question marks |
107
+ | Constraint count | 0.04 | "at most", "O(n)", "maximum" |
108
+ | Imperative verbs | 0.03 | "build", "create", "implement" |
109
+ | Output format | 0.03 | "json", "yaml", "schema" |
110
+ | Domain specificity | 0.02 | "quantum", "fpga", "genomics" |
111
+ | Reference complexity | 0.02 | "the docs", "the api", "above" |
112
+ | Negation complexity | 0.01 | "don't", "avoid", "without" |
82
113
 
83
- | Tier | Primary Model | Output $/M | vs Opus |
84
- |------|--------------|-----------|-----------|
85
- | SIMPLE | gemini-2.5-flash | $0.60 | **99% cheaper** |
86
- | MEDIUM | deepseek-chat | $0.42 | **99% cheaper** |
87
- | COMPLEX | claude-opus-4 | $75.00 | best quality |
88
- | REASONING | o3 | $8.00 | **89% cheaper** |
114
+ Weighted sum → sigmoid confidence calibration → tier selection.
89
115
 
90
- Special override: 2+ reasoning markers → REASONING at 0.97 confidence, regardless of other dimensions.
116
+ ### Tier → Model Mapping
91
117
 
92
- ### LLM Classifier Fallback
118
+ | Tier | Primary Model | Cost/M | Savings vs Opus |
119
+ | --------- | --------------- | ------ | --------------- |
120
+ | SIMPLE | deepseek-chat | $0.27 | **99.6%** |
121
+ | MEDIUM | gpt-4o-mini | $0.60 | **99.2%** |
122
+ | COMPLEX | claude-sonnet-4 | $15.00 | **80%** |
123
+ | REASONING | o3 | $10.00 | **87%** |
93
124
 
94
- When confidence is below the threshold (0.70), ClawRouter sends the first 500 characters to `gemini-2.5-flash` with `max_tokens: 10` and asks for one word: SIMPLE, MEDIUM, COMPLEX, or REASONING. Cost per classification: ~$0.00003. Results cached for 1 hour.
125
+ Special rule: 2+ reasoning markers → REASONING at 0.97 confidence.
95
126
 
96
- ### Estimated Savings
127
+ ### Cost Savings (Real Numbers)
97
128
 
98
- | Tier | % of Traffic | Output $/M |
99
- |------|-------------|-----------|
100
- | SIMPLE | 40% | $0.60 |
101
- | MEDIUM | 30% | $0.42 |
102
- | COMPLEX | 20% | $75.00 |
103
- | REASONING | 10% | $8.00 |
104
- | **Weighted avg** | | **$16.17/M — 78% savings vs Claude Opus** |
129
+ | Tier | % of Traffic | Cost/M |
130
+ | ------------------- | ------------ | ----------- |
131
+ | SIMPLE | ~45% | $0.27 |
132
+ | MEDIUM | ~35% | $0.60 |
133
+ | COMPLEX | ~15% | $15.00 |
134
+ | REASONING | ~5% | $10.00 |
135
+ | **Blended average** | | **$3.17/M** |
105
136
 
106
- Every routed request logs its decision:
137
+ Compared to **$75/M** for Claude Opus = **96% savings** on a typical workload.
107
138
 
108
- ```
109
- [ClawRouter] deepseek-chat (MEDIUM, rules, confidence=0.82)
110
- Cost: $0.0004 | Baseline: $0.0713 | Saved: 99.4%
111
- ```
139
+ ---
112
140
 
113
141
  ## Models
114
142
 
115
- 30+ models across 5 providers, all through one wallet:
116
-
117
- | Model | Input $/M | Output $/M | Context | Reasoning |
118
- |-------|----------|-----------|---------|:---------:|
119
- | **OpenAI** | | | | |
120
- | gpt-5.2 | $1.75 | $14.00 | 400K | * |
121
- | gpt-5-mini | $0.25 | $2.00 | 200K | |
122
- | gpt-5-nano | $0.05 | $0.40 | 128K | |
123
- | gpt-4o | $2.50 | $10.00 | 128K | |
124
- | gpt-4o-mini | $0.15 | $0.60 | 128K | |
125
- | o3 | $2.00 | $8.00 | 200K | * |
126
- | o3-mini | $1.10 | $4.40 | 128K | * |
127
- | o4-mini | $1.10 | $4.40 | 128K | * |
128
- | **Anthropic** | | | | |
129
- | claude-opus-4.5 | $15.00 | $75.00 | 200K | * |
130
- | claude-sonnet-4 | $3.00 | $15.00 | 200K | * |
131
- | claude-haiku-4.5 | $1.00 | $5.00 | 200K | |
132
- | **Google** | | | | |
133
- | gemini-3-pro-preview | $2.00 | $12.00 | 1M | * |
134
- | gemini-2.5-pro | $1.25 | $10.00 | 1M | * |
135
- | gemini-2.5-flash | $0.15 | $0.60 | 1M | |
136
- | **DeepSeek** | | | | |
137
- | deepseek-chat | $0.28 | $0.42 | 128K | |
138
- | deepseek-reasoner | $0.28 | $0.42 | 128K | * |
139
- | **xAI** | | | | |
140
- | grok-3 | $3.00 | $15.00 | 131K | * |
141
- | grok-3-fast | $5.00 | $25.00 | 131K | * |
142
- | grok-3-mini | $0.30 | $0.50 | 131K | |
143
-
144
- Full list in [`src/models.ts`](src/models.ts).
143
+ 30+ models across 6 providers, one wallet:
144
+
145
+ | Model | Input $/M | Output $/M | Context | Reasoning |
146
+ | ----------------- | --------- | ---------- | ------- | :-------: |
147
+ | **OpenAI** | | | | |
148
+ | gpt-5.2 | $1.75 | $14.00 | 400K | \* |
149
+ | gpt-4o | $2.50 | $10.00 | 128K | |
150
+ | gpt-4o-mini | $0.15 | $0.60 | 128K | |
151
+ | o3 | $2.00 | $8.00 | 200K | \* |
152
+ | o3-mini | $1.10 | $4.40 | 128K | \* |
153
+ | **Anthropic** | | | | |
154
+ | claude-opus-4.5 | $5.00 | $25.00 | 200K | \* |
155
+ | claude-sonnet-4 | $3.00 | $15.00 | 200K | \* |
156
+ | claude-haiku-4.5 | $1.00 | $5.00 | 200K | |
157
+ | **Google** | | | | |
158
+ | gemini-2.5-pro | $1.25 | $10.00 | 1M | \* |
159
+ | gemini-2.5-flash | $0.15 | $0.60 | 1M | |
160
+ | **DeepSeek** | | | | |
161
+ | deepseek-chat | $0.14 | $0.28 | 128K | |
162
+ | deepseek-reasoner | $0.55 | $2.19 | 128K | \* |
163
+ | **xAI** | | | | |
164
+ | grok-3 | $3.00 | $15.00 | 131K | \* |
165
+ | grok-3-mini | $0.30 | $0.50 | 131K | |
166
+ | **Moonshot** | | | | |
167
+ | kimi-k2.5 | $0.50 | $2.40 | 128K | \* |
168
+
169
+ Full list: [`src/models.ts`](src/models.ts)
170
+
171
+ ### Kimi K2.5: Agentic Workflows
172
+
173
+ [Kimi K2.5](https://kimi.ai) from Moonshot AI is optimized for agent swarm and multi-step workflows:
174
+
175
+ - **Agent Swarm** — Coordinates up to 100 parallel agents, 4.5x faster execution
176
+ - **Extended Tool Chains** — Stable across 200-300 sequential tool calls without drift
177
+ - **Vision-to-Code** — Generates production React from UI mockups and videos
178
+ - **Cost Efficient** — 76% cheaper than Claude Opus on agentic benchmarks
179
+
180
+ Best for: parallel web research, multi-agent orchestration, long-running automation tasks.
181
+
182
+ ---
145
183
 
146
184
  ## Payment
147
185
 
148
- No account. No API key. Payment IS authentication via [x402](https://x402.org).
186
+ No account. No API key. **Payment IS authentication** via [x402](https://x402.org).
149
187
 
150
188
  ```
151
189
  Request → 402 (price: $0.003) → wallet signs USDC → retry → response
152
190
  ```
153
191
 
154
- USDC stays in your wallet until the moment each request is paid — non-custodial. The price is visible in the 402 response before your wallet signs.
192
+ USDC stays in your wallet until spent — non-custodial. Price is visible in the 402 header before signing.
155
193
 
156
- **Funding your wallet** — send USDC on Base to your wallet address:
157
- - Coinbase — buy USDC, send to Base
158
- - Any CEX — withdraw USDC to Base
159
- - Bridge — move USDC from any chain to Base
194
+ **Fund your wallet:**
160
195
 
161
- ## Usage Logging
196
+ - Coinbase: Buy USDC, send to Base
197
+ - Bridge: Move USDC from any chain to Base
198
+ - CEX: Withdraw USDC to Base network
162
199
 
163
- Every routed request is logged as a JSON line:
200
+ ---
201
+
202
+ ## Architecture
164
203
 
165
204
  ```
166
- ~/.openclaw/blockrun/logs/usage-2026-02-03.jsonl
205
+ ┌─────────────────────────────────────────────────────────────┐
206
+ │ Your Application │
207
+ └─────────────────────────────────────────────────────────────┘
208
+ │
209
+ ▼
210
+ ┌─────────────────────────────────────────────────────────────┐
211
+ │ ClawRouter (localhost) │
212
+ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
213
+ │ │ Weighted Scorer │→ │ Model Selector │→ │ x402 Signer │ │
214
+ │ │ (14 dimensions)│ │ (cheapest tier) │ │ (USDC) │ │
215
+ │ └─────────────────┘ └─────────────────┘ └─────────────┘ │
216
+ └─────────────────────────────────────────────────────────────┘
217
+ │
218
+ ▼
219
+ ┌─────────────────────────────────────────────────────────────┐
220
+ │ BlockRun API │
221
+ │ → OpenAI | Anthropic | Google | DeepSeek | xAI | Moonshot│
222
+ └─────────────────────────────────────────────────────────────┘
167
223
  ```
168
224
 
169
- ```json
170
- {"timestamp":"2026-02-03T20:15:30.123Z","model":"google/gemini-2.5-flash","cost":0.000246,"latencyMs":1250}
225
+ Routing is **client-side** — open source and inspectable.
226
+
227
+ ### Source Structure
228
+
229
+ ```
230
+ src/
231
+ ├── index.ts # Plugin entry point
232
+ ├── provider.ts # OpenClaw provider registration
233
+ ├── proxy.ts # Local HTTP proxy + x402 payment
234
+ ├── models.ts # 30+ model definitions with pricing
235
+ ├── auth.ts # Wallet key resolution
236
+ ├── logger.ts # JSON usage logging
237
+ ├── dedup.ts # Response deduplication (prevents double-charge)
238
+ ├── payment-cache.ts # Pre-auth optimization (skips 402 round trip)
239
+ ├── x402.ts # EIP-712 USDC payment signing
240
+ └── router/
241
+ ├── index.ts # route() entry point
242
+ ├── rules.ts # 14-dimension weighted scoring
243
+ ├── selector.ts # Tier → model selection
244
+ ├── config.ts # Default routing config
245
+ └── types.ts # TypeScript types
171
246
  ```
172
247
 
248
+ ---
249
+
173
250
  ## Configuration
174
251
 
175
- ### Override Routing
252
+ ### Override Tier Models
176
253
 
177
254
  ```yaml
178
255
  # openclaw.yaml
@@ -184,59 +261,23 @@ plugins:
184
261
  COMPLEX:
185
262
  primary: "openai/gpt-4o"
186
263
  SIMPLE:
187
- primary: "openai/gpt-4o-mini"
188
- scoring:
189
- reasoningKeywords: ["proof", "theorem", "formal verification"]
264
+ primary: "google/gemini-2.5-flash"
190
265
  ```
191
266
 
192
- ### Pin a Model
193
-
194
- Skip routing. Use one model for everything:
195
-
196
- ```bash
197
- openclaw config set model openai/gpt-4o
198
- ```
267
+ ### Override Scoring Weights
199
268
 
200
- You still get x402 payments and usage logging.
201
-
202
- ## Architecture
203
-
204
- ```
205
- src/
206
- ├── index.ts # Plugin entry — register() + activate()
207
- ├── provider.ts # Registers "blockrun" provider in OpenClaw
208
- ├── proxy.ts # Local HTTP proxy — routing + x402 payment
209
- ├── models.ts # 30+ model definitions with pricing
210
- ├── auth.ts # Wallet key resolution (env, config, prompt)
211
- ├── logger.ts # JSON lines usage logger
212
- ├── types.ts # OpenClaw plugin type definitions
213
- └── router/
214
- ├── index.ts # route() entry point
215
- ├── rules.ts # Weighted classifier (14 dimensions, sigmoid confidence)
216
- ├── llm-classifier.ts # LLM fallback (gemini-flash, cached)
217
- ├── selector.ts # Tier → model selection + cost calculation
218
- ├── config.ts # Default routing configuration
219
- └── types.ts # RoutingDecision, Tier, ScoringResult
269
+ ```yaml
270
+ routing:
271
+ scoring:
272
+ reasoningKeywords: ["proof", "theorem", "formal verification"]
273
+ codeKeywords: ["function", "class", "async", "await"]
220
274
  ```
221
275
 
222
- The plugin runs a local HTTP proxy between OpenClaw and BlockRun's API. OpenClaw sees a standard OpenAI-compatible endpoint at `localhost`. Routing is **client-side** — open source and inspectable.
223
-
224
- ```
225
- OpenClaw Agent
226
- │
227
- ▼
228
- ClawRouter (localhost proxy)
229
- │ ① Classify query (rules → LLM fallback)
230
- │ ② Pick cheapest capable model
231
- │ ③ Sign x402 USDC payment
232
- │
233
- ▼
234
- BlockRun API → Provider (OpenAI, Anthropic, Google, DeepSeek, xAI)
235
- ```
276
+ ---
236
277
 
237
278
  ## Programmatic Usage
238
279
 
239
- Use ClawRouter as a library without OpenClaw:
280
+ Use without OpenClaw:
240
281
 
241
282
  ```typescript
242
283
  import { startProxy } from "@blockrun/clawrouter";
@@ -244,13 +285,10 @@ import { startProxy } from "@blockrun/clawrouter";
244
285
  const proxy = await startProxy({
245
286
  walletKey: process.env.BLOCKRUN_WALLET_KEY!,
246
287
  onReady: (port) => console.log(`Proxy on port ${port}`),
247
- onRouted: (d) => {
248
- const saved = (d.savings * 100).toFixed(0);
249
- console.log(`${d.model} (${d.tier}) saved ${saved}%`);
250
- },
288
+ onRouted: (d) => console.log(`${d.model} saved ${(d.savings * 100).toFixed(0)}%`),
251
289
  });
252
290
 
253
- // Use with any OpenAI-compatible client
291
+ // Any OpenAI-compatible client works
254
292
  const res = await fetch(`${proxy.baseUrl}/v1/chat/completions`, {
255
293
  method: "POST",
256
294
  headers: { "Content-Type": "application/json" },
@@ -266,109 +304,145 @@ await proxy.close();
266
304
  Or use the router directly:
267
305
 
268
306
  ```typescript
269
- import { route, DEFAULT_ROUTING_CONFIG } from "@blockrun/clawrouter";
307
+ import { route, DEFAULT_ROUTING_CONFIG, BLOCKRUN_MODELS } from "@blockrun/clawrouter";
270
308
 
271
- const decision = await route("Prove sqrt(2) is irrational", undefined, 4096, {
309
+ // Build pricing map
310
+ const modelPricing = new Map();
311
+ for (const m of BLOCKRUN_MODELS) {
312
+ modelPricing.set(m.id, { inputPrice: m.inputPrice, outputPrice: m.outputPrice });
313
+ }
314
+
315
+ const decision = route("Prove sqrt(2) is irrational", undefined, 4096, {
272
316
  config: DEFAULT_ROUTING_CONFIG,
273
317
  modelPricing,
274
- payFetch,
275
- apiBase: "https://blockrun.ai/api",
276
318
  });
277
319
 
278
320
  console.log(decision);
279
321
  // {
280
322
  // model: "openai/o3",
281
323
  // tier: "REASONING",
282
- // confidence: 0.973,
324
+ // confidence: 0.97,
283
325
  // method: "rules",
284
- // savings: 0.893,
285
- // costEstimate: 0.032776,
286
- // baselineCost: 0.307500,
326
+ // savings: 0.87,
327
+ // costEstimate: 0.041,
287
328
  // }
288
329
  ```
289
330
 
290
- ## Development
331
+ ---
291
332
 
292
- ```bash
293
- git clone https://github.com/BlockRunAI/ClawRouter.git
294
- cd ClawRouter
295
- npm install
296
- npm run build # Build with tsup
297
- npm run dev # Watch mode
298
- npm run typecheck # Type check
333
+ ## Performance Optimizations (v0.3)
299
334
 
300
- # Run tests
301
- npx tsup test/e2e.ts --format esm --outDir test/dist --no-dts
302
- node test/dist/e2e.js
335
+ - **SSE heartbeat**: Sends headers + heartbeat immediately, preventing upstream timeouts
336
+ - **Response dedup**: SHA-256 hash → 30s cache, prevents double-charge on retries
337
+ - **Payment pre-auth**: Caches 402 params, pre-signs USDC, skips 402 round trip (~200ms saved)
303
338
 
304
- # Run with live proxy (requires funded wallet)
305
- BLOCKRUN_WALLET_KEY=0x... node test/dist/e2e.js
306
- ```
339
+ ---
307
340
 
308
- ## Roadmap
341
+ ## Why Not OpenRouter / LiteLLM?
309
342
 
310
- - [x] Provider plugin — one wallet, 30+ models, x402 payment proxy
311
- - [x] Smart routing — hybrid rules + LLM classifier, 4-tier model selection
312
- - [x] Usage logging — JSON lines to disk, per-request cost tracking
313
- - [x] Weighted scoring engine — 14 dimensions, sigmoid confidence, configurable tier boundaries
314
- - [ ] KNN fallback — embedding-based classifier to replace LLM fallback (<5ms vs ~200ms)
315
- - [ ] Cascade routing — try cheaper model first, escalate on low quality (AutoMix-inspired)
316
- - [ ] Graceful fallback — auto-switch on rate limit or provider error
317
- - [ ] Spend controls — daily/monthly budgets, server-side enforcement
318
- - [ ] Cost dashboard — analytics at blockrun.ai
343
+ They're built for developers. ClawRouter is built for **agents**.
319
344
 
320
- ## Why Not OpenRouter / LiteLLM?
345
+ | | OpenRouter / LiteLLM | ClawRouter |
346
+ | ----------- | --------------------------- | -------------------------------- |
347
+ | **Setup** | Human creates account | Agent generates wallet |
348
+ | **Auth** | API key (shared secret) | Wallet signature (cryptographic) |
349
+ | **Payment** | Prepaid balance (custodial) | Per-request (non-custodial) |
350
+ | **Routing** | Proprietary / closed | Open source, client-side |
321
351
 
322
- They're built for developers — create an account, get an API key, prepay a balance, manage it through a dashboard.
352
+ Agents shouldn't need a human to paste API keys. They should generate a wallet, receive funds, and pay per request — programmatically.
323
353
 
324
- ClawRouter is built for **agents**. The difference:
354
+ ---
355
+
356
+ ## Troubleshooting
357
+
358
+ ### "Unknown model: blockrun/auto"
325
359
 
326
- | | OpenRouter / LiteLLM | ClawRouter |
327
- |---|---|---|
328
- | **Setup** | Human creates account, gets API key | Agent generates wallet, pays per request |
329
- | **Payment** | Prepaid balance (custodial) | Per-request micropayment (non-custodial) |
330
- | **Auth** | API key (shared secret) | Wallet signature (cryptographic proof) |
331
- | **Custody** | Provider holds your money | USDC stays in YOUR wallet until spent |
332
- | **Routing** | Proprietary / closed | Open source, client-side, inspectable |
360
+ This error means the ClawRouter plugin isn't loaded. **Don't change the model name** — `blockrun/auto` is correct.
333
361
 
334
- As agents become autonomous, they need financial infrastructure designed for machines. An agent shouldn't need a human to sign up for a service and paste an API key. It should generate a wallet, receive funds, and pay per request — programmatically.
362
+ **Fix:**
335
363
 
336
- ## Test Results
364
+ ```bash
365
+ # 1. Verify plugin is installed
366
+ openclaw plugins list
367
+ # Should show @blockrun/clawrouter
368
+
369
+ # 2. If not installed
370
+ openclaw plugins install @blockrun/clawrouter
337
371
 
338
- Real output from `node test/dist/e2e.js` — weighted scoring with sigmoid confidence:
372
+ # 3. Restart OpenClaw after installing
339
373
 
374
+ # 4. Verify proxy is running
375
+ curl http://localhost:8402/health
376
+ # Should return {"status":"ok","wallet":"0x..."}
340
377
  ```
341
- ═══ Rule-Based Classifier ═══
342
378
 
343
- Simple queries:
344
- ✓ "What is the capital of France?" → SIMPLE (score=-0.200)
345
- ✓ "Hello" → SIMPLE (score=-0.200)
346
- ✓ "Define photosynthesis" → SIMPLE (score=-0.125)
347
- ✓ "Translate hello to Spanish" → SIMPLE (score=-0.200)
348
- ✓ "Yes or no: is the sky blue?" → SIMPLE (score=-0.200)
379
+ ### Proxy won't start / Health check fails
380
+
381
+ **Cause:** Wallet has no USDC balance.
349
382
 
350
- Complex queries (correctly deferred to classifier):
351
- ✓ Kanban board → AMBIGUOUS (score=0.090, conf=0.673)
352
- ✓ Distributed trading → AMBIGUOUS (score=0.127, conf=0.569)
383
+ **Fix:**
384
+ 1. Find your wallet address (printed during install, or check `~/.openclaw/blockrun/wallet.key`)
385
+ 2. Send USDC on **Base network** to that address
386
+ 3. $1-5 is enough for hundreds of requests
387
+ 4. Restart OpenClaw
353
388
 
354
- Reasoning queries:
355
- ✓ "Prove sqrt(2) irrational" → REASONING (score=0.180, conf=0.973)
356
- ✓ "Derive time complexity" → REASONING (score=0.186, conf=0.973)
357
- ✓ "Chain of thought proof" → REASONING (score=0.180, conf=0.973)
389
+ ### Port 8402 already in use
358
390
 
359
- ═══ Full Router ═══
391
+ **Fix:**
360
392
 
361
- ✓ Simple factual → google/gemini-2.5-flash (SIMPLE, rules) saved=99.2%
362
- ✓ Greeting → google/gemini-2.5-flash (SIMPLE, rules) saved=99.2%
363
- ✓ Math proof → openai/o3 (REASONING, rules) saved=89.3%
393
+ ```bash
394
+ # Find what's using the port
395
+ lsof -i :8402
364
396
 
365
- ═══════════════════════════════════
366
- 19 passed, 0 failed
367
- ═══════════════════════════════════
397
+ # Kill it or restart OpenClaw
368
398
  ```
369
399
 
370
- **Bottom line:** A simple "What is 2+2?" costs **$0.002** instead of **$0.308** on Opus — that's **99% savings** on every simple query.
400
+ ### "RPC error" / Balance check failed
401
+
402
+ **Cause:** Can't reach Base RPC to check wallet balance.
403
+
404
+ **Fix:** Check internet connection. If persistent, the public RPC may be rate-limited — try again in a few minutes.
405
+
406
+ ---
407
+
408
+ ## Development
409
+
410
+ ```bash
411
+ git clone https://github.com/BlockRunAI/ClawRouter.git
412
+ cd ClawRouter
413
+ npm install
414
+ npm run build
415
+ npm run typecheck
416
+
417
+ # End-to-end tests (requires funded wallet)
418
+ BLOCKRUN_WALLET_KEY=0x... npx tsx test-e2e.ts
419
+ ```
420
+
421
+ ---
422
+
423
+ ## Roadmap
424
+
425
+ - [x] Smart routing — 14-dimension weighted scoring, 4-tier model selection
426
+ - [x] x402 payments — per-request USDC micropayments, non-custodial
427
+ - [x] Response dedup — prevents double-charge on retries
428
+ - [x] Payment pre-auth — skips 402 round trip
429
+ - [x] SSE heartbeat — prevents upstream timeouts
430
+ - [ ] Cascade routing — try cheap model first, escalate on low quality
431
+ - [ ] Spend controls — daily/monthly budgets
432
+ - [ ] Analytics dashboard — cost tracking at blockrun.ai
433
+
434
+ ---
371
435
 
372
436
  ## License
373
437
 
374
438
  MIT
439
+
440
+ ---
441
+
442
+ <div align="center">
443
+
444
+ **[BlockRun](https://blockrun.ai)** — Pay-per-request AI infrastructure
445
+
446
+ If ClawRouter saves you money, consider starring the repo.
447
+
448
+ </div>