Save 78% on LLM costs. Automatically.

Route every request to the cheapest model that can handle it. One wallet, 30+ models, zero API keys.

npm License: MIT TypeScript Node

Docs · Models · Telegram · X

"What is 2+2?" → DeepSeek 0ドル.27/M saved 99%
"Summarize this article" → GPT-4o-mini 0ドル.60/M saved 99%
"Build a React component" → Claude Sonnet 15ドル.00/M best balance
"Prove this theorem" → DeepSeek-R 0ドル.42/M reasoning
"Run 50 parallel searches"→ Kimi K2.5 2ドル.40/M agentic swarm

Why ClawRouter?

Ask Your OpenClaw How ClawRouter Saves You Money

Quick Start (2 mins)

# 1. Install with smart routing enabled by default
curl -fsSL https://raw.githubusercontent.com/BlockRunAI/ClawRouter/main/scripts/reinstall.sh | bash
# 2. Fund your wallet with USDC on Base (address printed on install)
# 5ドル is enough for thousands of requests
# 3. Restart OpenClaw gateway
openclaw gateway restart

Tips

See It In Action

How Routing Works

Request → Weighted Scorer (14 dimensions)
 │
 ├── High confidence → Pick model from tier → Done
 │
 └── Low confidence → Default to MEDIUM tier → Done

14-Dimension Weighted Scoring

Supported Languages

Tier → Model Mapping

Cost Savings (Real Numbers)

Models

Kimi K2.5: Agentic Workflows

Payment

Request → 402 (price: 0ドル.003) → wallet signs USDC → retry → response

Wallet Configuration

Resolution Order

Common Scenarios

# Check if a saved wallet exists
ls -la ~/.openclaw/blockrun/wallet.key
# Use your own wallet (only works if no saved file exists)
export BLOCKRUN_WALLET_KEY=0x...
# Force use of a different wallet
rm ~/.openclaw/blockrun/wallet.key
export BLOCKRUN_WALLET_KEY=0x...
openclaw restart
# See which wallet is active
curl http://localhost:8402/health | jq .wallet

Why This Order?

Architecture

┌─────────────────────────────────────────────────────────────┐
│ Your Application │
└─────────────────────────────────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────────┐
│ ClawRouter (localhost) │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
│ │ Weighted Scorer │→ │ Model Selector │→ │ x402 Signer │ │
│ │ (14 dimensions)│ │ (cheapest tier) │ │ (USDC) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────────┐
│ BlockRun API │
│ → OpenAI | Anthropic | Google | DeepSeek | xAI | Moonshot│
└─────────────────────────────────────────────────────────────┘

Source Structure

src/
├── index.ts # Plugin entry point
├── provider.ts # OpenClaw provider registration
├── proxy.ts # Local HTTP proxy + x402 payment
├── models.ts # 30+ model definitions with pricing
├── auth.ts # Wallet key resolution
├── logger.ts # JSON usage logging
├── dedup.ts # Response deduplication (prevents double-charge)
├── payment-cache.ts # Pre-auth optimization (skips 402 round trip)
├── x402.ts # EIP-712 USDC payment signing
└── router/
 ├── index.ts # route() entry point
 ├── rules.ts # 14-dimension weighted scoring
 ├── selector.ts # Tier → model selection
 ├── config.ts # Default routing config
 └── types.ts # TypeScript types

Configuration

Override Tier Models

# openclaw.yaml
plugins:
 - id: "@blockrun/clawrouter"
 config:
 routing:
 tiers:
 COMPLEX:
 primary: "openai/gpt-4o"
 SIMPLE:
 primary: "google/gemini-2.5-flash"

Override Scoring Weights

routing:
 scoring:
 reasoningKeywords: ["proof", "theorem", "formal verification"]
 codeKeywords: ["function", "class", "async", "await"]

Programmatic Usage

import { startProxy } from "@blockrun/clawrouter";
const proxy = await startProxy({
 walletKey: process.env.BLOCKRUN_WALLET_KEY!,
 onReady: (port) => console.log(`Proxy on port ${port}`),
 onRouted: (d) => console.log(`${d.model} saved ${(d.savings * 100).toFixed(0)}%`),
});
// Any OpenAI-compatible client works
const res = await fetch(`${proxy.baseUrl}/v1/chat/completions`, {
 method: "POST",
 headers: { "Content-Type": "application/json" },
 body: JSON.stringify({
 model: "blockrun/auto",
 messages: [{ role: "user", content: "What is 2+2?" }],
 }),
});
await proxy.close();

import { route, DEFAULT_ROUTING_CONFIG, BLOCKRUN_MODELS } from "@blockrun/clawrouter";
// Build pricing map
const modelPricing = new Map();
for (const m of BLOCKRUN_MODELS) {
 modelPricing.set(m.id, { inputPrice: m.inputPrice, outputPrice: m.outputPrice });
}
const decision = route("Prove sqrt(2) is irrational", undefined, 4096, {
 config: DEFAULT_ROUTING_CONFIG,
 modelPricing,
});
console.log(decision);
// {
// model: "deepseek/deepseek-reasoner",
// tier: "REASONING",
// confidence: 0.97,
// method: "rules",
// savings: 0.994,
// costEstimate: 0.002,
// }

Performance Optimizations (v0.3)

Why Not OpenRouter / LiteLLM?

Troubleshooting

Quick Checklist

# 1. Check your version (should be 0.3.21+)
cat ~/.openclaw/extensions/clawrouter/package.json | grep version
# 2. Check proxy is running
curl http://localhost:8402/health
# 3. Watch routing in action
openclaw logs --follow
# Should see: gemini-2.5-flash 0ドル.0012 (saved 99%)

"Unknown model: blockrun/auto" or "Unknown model: auto"

"No API key found for provider blockrun"

"Config validation failed: plugin not found: clawrouter"

"No USDC balance" / "Insufficient funds"

Security Scanner Warning: "env-harvesting"

[env-harvesting] Environment variable access combined with network send

Port 8402 already in use

lsof -i :8402
# Kill the process or restart OpenClaw

How to Update ClawRouter

curl -fsSL https://raw.githubusercontent.com/BlockRunAI/ClawRouter/main/scripts/reinstall.sh | bash
openclaw gateway restart

Verify Routing is Working

openclaw logs --follow

[plugins] [SIMPLE] google/gemini-2.5-flash 0ドル.0012 (saved 99%)
[plugins] [MEDIUM] deepseek/deepseek-chat 0ドル.0003 (saved 99%)
[plugins] [REASONING] deepseek/deepseek-reasoner 0ドル.0005 (saved 99%)

Development

git clone https://github.com/BlockRunAI/ClawRouter.git
cd ClawRouter
npm install
npm run build
npm run typecheck
# End-to-end tests (requires funded wallet)
BLOCKRUN_WALLET_KEY=0x... npx tsx test-e2e.ts

Roadmap

License

BlockRun — Pay-per-request AI infrastructure

If ClawRouter saves you money, consider starring the repo.