ClawRouter

Save 78% on LLM costs. Automatically.

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

Docs · Models · Configuration · Architecture · 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?

100% local routing — 15-dimension weighted scoring runs on your machine in <1ms
Zero external calls — no API calls for routing decisions, ever
30+ models — OpenAI, Anthropic, Google, DeepSeek, xAI, Moonshot through one wallet
x402 micropayments — pay per request with USDC on Base, no API keys
Open source — MIT licensed, fully inspectable routing logic

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

Done! Smart routing (blockrun/auto) is now your default model.

Tips

Use /model blockrun/auto in any conversation to switch on the fly
Want a specific model? Use blockrun/openai/gpt-4o or blockrun/anthropic/claude-sonnet-4
Already have a funded wallet? export BLOCKRUN_WALLET_KEY=0x...

See It In Action

The flow:

Wallet auto-generated on Base (L2) — saved securely at ~/.openclaw/blockrun/wallet.key
Fund with $1 USDC — enough for hundreds of requests
Request any model — "help me call Grok to check @hosseeb's opinion on AI agents"
ClawRouter routes it — spawns a Grok sub-agent via xai/grok-3, pays per-request

No API keys. No accounts. Just fund and go.

How Routing Works

100% local, <1ms, zero API calls.

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

No external classifier calls. Ambiguous queries default to the MEDIUM tier (DeepSeek/GPT-4o-mini) — fast, cheap, and good enough for most tasks.

15-Dimension Weighted Scoring

Dimension	Weight	What It Detects
Reasoning markers	0.18	"prove", "theorem", "step by step"
Code presence	0.15	"function", "async", "import", "```"
Multi-step patterns	0.12	"first...then", "step 1", numbered lists
Agentic task	0.10	"run", "test", "fix", "deploy", "edit"
Technical terms	0.10	"algorithm", "kubernetes", "distributed"
Token count	0.08	short (<50) vs long (>500) prompts
Creative markers	0.05	"story", "poem", "brainstorm"
Question complexity	0.05	Multiple question marks
Constraint count	0.04	"at most", "O(n)", "maximum"
Imperative verbs	0.03	"build", "create", "implement"
Output format	0.03	"json", "yaml", "schema"
Simple indicators	0.02	"what is", "define", "translate"
Domain specificity	0.02	"quantum", "fpga", "genomics"
Reference complexity	0.02	"the docs", "the api", "above"
Negation complexity	0.01	"don't", "avoid", "without"

Weighted sum → sigmoid confidence calibration → tier selection.

Supported Languages

ClawRouter's keyword-based routing works with prompts in:

Language	Script	Examples
English	Latin	Full support (default)
Chinese (中文)	Han/CJK	证明, 定理, 你好, 什么是
Japanese (日本語)	Kanji + Kana	証明, こんにちは, アルゴリズム
Russian (Русский)	Cyrillic	доказать, привет, алгоритм
German (Deutsch)	Latin	beweisen, hallo, algorithmus

Mixed-language prompts are supported — keywords from all languages are checked simultaneously.

Tier → Model Mapping

Tier	Primary Model	Cost/M	Savings vs Opus
SIMPLE	gemini-2.5-flash	$0.60	99.2%
MEDIUM	grok-code-fast-1	$1.50	98.0%
COMPLEX	gemini-2.5-pro	$10.00	86.7%
REASONING	grok-4-fast-reasoning	$0.50	99.3%

Special rule: 2+ reasoning markers → REASONING at 0.97 confidence.

Agentic Auto-Detection

ClawRouter automatically detects multi-step agentic tasks and routes to models optimized for autonomous execution:

"what is 2+2"                    → gemini-flash (standard)
"build the project then run tests" → kimi-k2.5 (auto-agentic)
"fix the bug and make sure it works" → kimi-k2.5 (auto-agentic)

How it works:

Detects agentic keywords: file ops ("read", "edit"), execution ("run", "test", "deploy"), iteration ("fix", "debug", "verify")
Threshold: 2+ signals triggers auto-switch to agentic tiers
No config needed — works automatically

Agentic tier models (optimized for multi-step autonomy):

Tier	Agentic Model	Why
SIMPLE	claude-haiku-4.5	Fast + reliable tool use
MEDIUM	kimi-k2.5	200+ tool chains, 76% cheaper
COMPLEX	claude-sonnet-4	Best balance for complex tasks
REASONING	kimi-k2.5	Extended reasoning + execution

You can also force agentic mode via config:

# openclaw.yaml
plugins:
  - id: "@blockrun/clawrouter"
    config:
      routing:
        overrides:
          agenticMode: true  # Always use agentic tiers

Tool Detection (v0.5)

When your request includes a tools array (function calling), ClawRouter automatically switches to agentic tiers:

// Request with tools → auto-agentic mode
{
  model: "blockrun/auto",
  messages: [{ role: "user", content: "Check the weather" }],
  tools: [{ type: "function", function: { name: "get_weather", ... } }]
}
// → Routes to claude-haiku-4.5 (excellent tool use)
// → Instead of gemini-flash (may produce malformed tool calls)

Why this matters: Some models (like deepseek-reasoner) are optimized for chain-of-thought reasoning but can generate malformed tool calls. Tool detection ensures requests with functions go to models proven to handle tool use correctly.

Context-Length-Aware Routing (v0.5)

ClawRouter automatically filters out models that can't handle your context size:

150K token request:
  Full chain: [grok-4-fast (131K), deepseek (128K), kimi (262K), gemini (1M)]
  Filtered:   [kimi (262K), gemini (1M)]
  → Skips models that would fail with "context too long" errors

This prevents wasted API calls and faster fallback to capable models.

Session Persistence (v0.5)

For multi-turn conversations, ClawRouter pins the model to prevent mid-task switching:

Turn 1: "Build a React component" → claude-sonnet-4
Turn 2: "Add dark mode support"   → claude-sonnet-4 (pinned)
Turn 3: "Now add tests"           → claude-sonnet-4 (pinned)

Sessions are identified by conversation ID and persist for 1 hour of inactivity.

Cost Savings (Real Numbers)

Tier	% of Traffic	Cost/M
SIMPLE	~45%	$0.27
MEDIUM	~35%	$0.60
COMPLEX	~15%	$15.00
REASONING	~5%	$10.00
Blended average		$3.17/M

Compared to $75/M for Claude Opus = 96% savings on a typical workload.

Models

30+ models across 6 providers, one wallet:

Model	Input $/M	Output $/M	Context	Reasoning
OpenAI
gpt-5.2	$1.75	$14.00	400K	*
gpt-4o	$2.50	$10.00	128K
gpt-4o-mini	$0.15	$0.60	128K
o3	$2.00	$8.00	200K	*
o3-mini	$1.10	$4.40	128K	*
Anthropic
claude-opus-4.5	$5.00	$25.00	200K	*
claude-sonnet-4	$3.00	$15.00	200K	*
claude-haiku-4.5	$1.00	$5.00	200K
Google
gemini-2.5-pro	$1.25	$10.00	1M	*
gemini-2.5-flash	$0.15	$0.60	1M
DeepSeek
deepseek-chat	$0.14	$0.28	128K
deepseek-reasoner	$0.55	$2.19	128K	*
xAI
grok-3	$3.00	$15.00	131K	*
grok-3-mini	$0.30	$0.50	131K
grok-4-fast-reasoning	$0.20	$0.50	131K	*
grok-4-fast	$0.20	$0.50	131K
grok-code-fast-1	$0.20	$1.50	131K
Moonshot
kimi-k2.5	$0.50	$2.40	262K	*
NVIDIA
gpt-oss-120b	FREE	FREE	128K

Full list: src/models.ts

Kimi K2.5: Agentic Workflows

Kimi K2.5 from Moonshot AI is optimized for agent swarm and multi-step workflows:

Agent Swarm — Coordinates up to 100 parallel agents, 4.5x faster execution
Extended Tool Chains — Stable across 200-300 sequential tool calls without drift
Vision-to-Code — Generates production React from UI mockups and videos
Cost Efficient — 76% cheaper than Claude Opus on agentic benchmarks

Best for: parallel web research, multi-agent orchestration, long-running automation tasks.

Payment

No account. No API key. Payment IS authentication via x402.

Request → 402 (price: $0.003) → wallet signs USDC → retry → response

USDC stays in your wallet until spent — non-custodial. Price is visible in the 402 header before signing.

Fund your wallet:

Coinbase: Buy USDC, send to Base
Bridge: Move USDC from any chain to Base
CEX: Withdraw USDC to Base network

Wallet Configuration

ClawRouter uses one environment variable: BLOCKRUN_WALLET_KEY

Resolution Order

Priority	Source	Behavior
1st	Saved file (`~/.openclaw/blockrun/wallet.key`)	Used if exists
2nd	`BLOCKRUN_WALLET_KEY` env var	Used if no saved file
3rd	Auto-generate	Creates new wallet, saves to file

Important: The saved file takes priority over the environment variable. If you have both, the env var is ignored.

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?

The saved file is checked first to ensure wallet persistence across sessions. Once a wallet is generated and funded, you don't want an accidentally-set env var to switch wallets and leave your funds inaccessible.

If you explicitly want to use a different wallet:

Delete ~/.openclaw/blockrun/wallet.key
Set BLOCKRUN_WALLET_KEY=0x...
Restart OpenClaw

Wallet Backup & Recovery

Your wallet private key is stored at ~/.openclaw/blockrun/wallet.key. Back up this file before terminating any VPS or machine!

Using the `/wallet` Command

ClawRouter provides a built-in command for wallet management:

# Check wallet status (address, balance, file location)
/wallet

# Export private key for backup (shows the actual key)
/wallet export

The /wallet export command displays your private key so you can copy it before terminating a machine.

Manual Backup

# Option 1: Copy the key file
cp ~/.openclaw/blockrun/wallet.key ~/backup-wallet.key

# Option 2: View and copy the key
cat ~/.openclaw/blockrun/wallet.key

Restore on a New Machine

# Option 1: Set environment variable (before installing ClawRouter)
export BLOCKRUN_WALLET_KEY=0x...your_key_here...
openclaw plugins install @blockrun/clawrouter

# Option 2: Create the key file directly
mkdir -p ~/.openclaw/blockrun
echo "0x...your_key_here..." > ~/.openclaw/blockrun/wallet.key
chmod 600 ~/.openclaw/blockrun/wallet.key
openclaw plugins install @blockrun/clawrouter

Important: If a saved wallet file exists, it takes priority over the environment variable. To use a different wallet, delete the existing file first.

Lost Key Recovery

If you lose your wallet key, there is no way to recover it. The wallet is self-custodial, meaning only you have the private key. We do not store keys or have any way to restore access.

Prevention tips:

Run /wallet export before terminating any VPS
Keep a secure backup of ~/.openclaw/blockrun/wallet.key
For production use, consider using a hardware wallet or key management system

Architecture

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

Routing is client-side — open source and inspectable.

Deep dive: docs/architecture.md — request flow, payment system, optimizations

Configuration

For basic usage, no configuration is needed. For advanced options:

Setting	Default	Description
`CLAWROUTER_DISABLED`	`false`	Disable plugin (use default routing)
`BLOCKRUN_PROXY_PORT`	`8402`	Proxy port (env var)
`BLOCKRUN_WALLET_KEY`	auto	Wallet private key (env var)
`routing.tiers`	see docs	Override tier→model mappings
`routing.scoring`	see docs	Custom keyword weights

Quick examples:

# Temporarily disable ClawRouter (use OpenClaw's default routing)
CLAWROUTER_DISABLED=true openclaw gateway restart

# Re-enable ClawRouter
openclaw gateway restart

# Use different port
export BLOCKRUN_PROXY_PORT=8403
openclaw gateway restart

# openclaw.yaml — override models
plugins:
  - id: "@blockrun/clawrouter"
    config:
      routing:
        tiers:
          COMPLEX:
            primary: "openai/gpt-4o"

Full reference: docs/configuration.md

Programmatic Usage

Use without OpenClaw:

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();

Or use the router directly:

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)

SSE heartbeat: Sends headers + heartbeat immediately, preventing upstream timeouts
Response dedup: SHA-256 hash → 30s cache, prevents double-charge on retries
Payment pre-auth: Caches 402 params, pre-signs USDC, skips 402 round trip (~200ms saved)

Cost Tracking with /stats (v0.5)

Track your savings in real-time:

# In any OpenClaw conversation
/stats

Output:

╔════════════════════════════════════════════════════════════╗
║              ClawRouter Usage Statistics                   ║
╠════════════════════════════════════════════════════════════╣
║  Period: last 7 days                                      ║
║  Total Requests: 442                                      ║
║  Total Cost: $1.73                                       ║
║  Baseline Cost (Opus): $20.13                            ║
║  💰 Total Saved: $18.40 (91.4%)                            ║
╠════════════════════════════════════════════════════════════╣
║  Routing by Tier:                                          ║
║    SIMPLE     ███████████           55.0% (243)            ║
║    MEDIUM     ██████                30.8% (136)            ║
║    COMPLEX    █                      7.2% (32)             ║
║    REASONING  █                      7.0% (31)             ║
╚════════════════════════════════════════════════════════════╝

Stats are stored locally at ~/.openclaw/blockrun/logs/ and aggregated on demand.

Why Not OpenRouter / LiteLLM?

They're built for developers. ClawRouter is built for agents.

	OpenRouter / LiteLLM	ClawRouter
Setup	Human creates account	Agent generates wallet
Auth	API key (shared secret)	Wallet signature (cryptographic)
Payment	Prepaid balance (custodial)	Per-request (non-custodial)
Routing	Proprietary / closed	Open source, client-side

Agents shouldn't need a human to paste API keys. They should generate a wallet, receive funds, and pay per request — programmatically.

Troubleshooting

💬 Need help? Open a Discussion or check existing issues.

Quick Checklist

# 1. Check your version (should be 0.5.0+)
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%)

# 4. View cost savings
/stats

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

Plugin isn't loaded or outdated. Don't change the model name — blockrun/auto is correct.

Fix: Update to v0.3.21+ which handles both blockrun/auto and auto (OpenClaw strips provider prefix). See How to Update ClawRouter.

"No API key found for provider blockrun"

Auth profile is missing or wasn't created properly.

Fix: See How to Update ClawRouter — the reinstall script automatically injects the auth profile.

"Config validation failed: plugin not found: clawrouter"

Plugin directory was removed but config still references it. This blocks all OpenClaw commands until fixed.

Fix: See How to Update ClawRouter for complete cleanup steps.

"No USDC balance" / "Insufficient funds"

Wallet needs funding.

Fix:

Find your wallet address (printed during install)
Send USDC on Base network to that address
$1-5 is enough for hundreds of requests
Restart OpenClaw

Security Scanner Warning: "env-harvesting"

OpenClaw's security scanner may flag ClawRouter with:

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

This is a false positive. ClawRouter reads BLOCKRUN_WALLET_KEY to sign x402 payment transactions — this is required and intentional:

The wallet key is used locally for cryptographic signing (EIP-712)
The signature is transmitted, not the private key itself
This is standard x402 payment protocol behavior
Source code is MIT licensed and fully auditable

See openclaw.security.json for detailed security documentation.

Port 8402 already in use

As of v0.4.1, ClawRouter automatically detects and reuses an existing proxy on the configured port instead of failing with EADDRINUSE. You should no longer see this error.

If you need to use a different port:

# Set custom port via environment variable
export BLOCKRUN_PROXY_PORT=8403
openclaw gateway restart

To manually check/kill the process:

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

This removes the old version, installs the latest, and restarts the gateway.

Verify Routing is Working

openclaw logs --follow

You should see model selection for each request:

[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

MIT

BlockRun — Pay-per-request AI infrastructure

If ClawRouter saves you money, consider starring the repo.

FilesExpand file tree

README.md

Latest commit

History