ClawRouter

What it is

ClawRouter is an open-source (MIT), agent-native smart LLM router designed for autonomous workflows. It provides a local proxy that analyzes requests across 15 dimensions (cost, latency, reasoning depth, etc.) and routes them to the optimal model in under 1ms.

What problem it solves

It solves the "autonomous agent payment gap" by using the x402 protocol for USDC micropayments and wallet signatures for authentication. This allows agents to operate independently without human-managed API keys, accounts, or credit cards. It also reduces LLM costs by up to 92% through aggressive model routing across frontier models (Claude 5.6, GPT-5.6, Gemini 4.0 Ultra, DeepSeek-V4) and local open-weights servers (vLLM, TGI, Ollama).

Where it fits in the stack

Infrastructure / Routing Layer. ClawRouter sits between the AI agent (Claude 5.6, GPT-5.6) and model providers (Anthropic, OpenAI, Google, NVIDIA, etc.), acting as a smart, payment-integrated proxy.

Typical use cases

• Autonomous Agent Ops: Powering agents that need to pay for their own inference via on-chain USDC.
• Cost-Optimized Coding: Routing simple code edits to free or low-cost models while using Claude 5.1 for complex architecture.
• Multi-Modal Orchestration: Seamlessly switching between specialized models for text, vision, image generation, and voice calls.
• Agentic Infrastructure: Providing a local, <1ms routing layer for high-volume agent fleets and FastMCP 3.1 workflows.

Strengths

• Agent-First Auth: Uses wallet signatures instead of API keys, making it truly native to autonomous entities.
• Cost Efficiency: Access to 6+ free models (NVIDIA-hosted) and smart routing that targets 90%+ savings.
• Local & Fast: Routing logic runs entirely locally with sub-1ms latency and no external routing dependencies.
• Rich Ecosystem: Supports 55+ models and integrates features like image generation, video generation, and AI-powered voice calls.
• Non-Custodial Payments: Agents pay per-request using USDC via x402 directly from their own local wallets.

Limitations

• Ecosystem Focus: While standalone, its primary integrations are centered around OpenClaw and agent-native environments.
• Payment Learning Curve: Requires understanding of USDC micropayments and the x402 protocol for paid tiers.
• Model Bias: Routing logic is optimized for agentic workloads, which may differ from general chat requirements.
• Local Resource Usage: Running the routing engine and local wallet adds a small memory footprint to the host machine.

When to use it

• When building autonomous agents that need to manage their own inference costs and payments.
• When model routing is a first-class operational concern for reducing agentic overhead.
• In OpenClaw-heavy stacks where plugin integration provides advanced UI features.

When not to use it

• When a simpler, provider-agnostic router like LiteLLM is sufficient and payments aren't a priority.
• When you prefer centralized billing and account management over per-request USDC settlement.
• For purely human-driven chat applications where standard API key management is preferred.

Getting started

To set up ClawRouter in January 2027:

1. Installation:

   npx @blockrun/clawrouter
   

2. Wallet Setup: On first run, a BIP-39 mnemonic and wallet (Base/Solana) are generated. Your address is printed to the console.
3. Funding: Optional. Skip for the free tier (6 models). For paid models, send USDC on the Base or Solana network to your address.
4. Integration: Point your client (Cursor, Continue, or OpenAI SDK) to http://localhost:8402/v1/.

CLI examples

Diagnostic Check

Run the "doctor" to verify system, wallet, and network status with AI-powered analysis:

npx @blockrun/clawrouter doctor

Managing Models

Manually exclude or include models from the smart routing logic:

# Block expensive models
clawrouter exclude add gpt-5.5-pro
# Verify current exclusions
clawrouter exclude

Phone & Voice Ops

Manage wallet-owned phone numbers for AI voice calls:

# Buy a US number for agentic calls
clawrouter phone numbers buy US --area-code 415
# List active numbers and expiry
clawrouter phone numbers list

API examples

Smart Routing Call

The default blockrun/auto model automatically selects the best model for each request:

from openai import OpenAI

# ClawRouter local proxy
client = OpenAI(base_url="http://localhost:8402/v1", api_key="x402")

response = client.chat.completions.create(
    model="blockrun/auto",
    messages=[{"role": "user", "content": "Analyze this repo architecture."}]
)

Image Generation (Asynchronous)

Generate high-fidelity images using specialized agent tools:

curl -X POST http://localhost:8402/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux",
    "prompt": "A futuristic city at sunset, cinematic lighting",
    "size": "1024x1024"
  }'

AI-Powered Voice Call

Initiate a real outbound phone call with automated x402 settlement:

curl -X POST http://localhost:8402/v1/voice/call \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "task": "Confirm the 3pm Thursday meeting.",
    "max_duration": 5
  }'

Programmatic Python Routing & Verification (Pydantic v2)

Verify and check metrics programmatically, enforcing budgets and latency SLAs on self-directed agent runs.

import sys
import time
import requests
from pydantic import BaseModel, Field
from typing import Optional

class RoutingMetadata(BaseModel):
    max_cost_limit_usd: float = Field(default=0.05, ge=0.0, description="Max USD budget per request")
    latency_sla_ms: int = Field(default=1500, ge=100, description="Target max latency in milliseconds")

class ChatMessage(BaseModel):
    role: str
    content: str

class ClawRouterRequest(BaseModel):
    model: str = Field(default="blockrun/auto")
    messages: list[ChatMessage]
    metadata: RoutingMetadata = Field(default_factory=RoutingMetadata)

class UsageInfo(BaseModel):
    estimated_cost_usd: float = Field(default=0.0)

class ChoiceMessage(BaseModel):
    content: str

class Choice(BaseModel):
    message: ChoiceMessage

class ClawRouterResponse(BaseModel):
    model: str
    choices: list[Choice]
    usage: Optional[UsageInfo] = None

def check_clawrouter_health(base_url: str = "http://localhost:8402/v1") -> bool:
    try:
        response = requests.get(f"{base_url}/status", timeout=3)
        if response.status_code == 200:
            status_data = response.json()
            balance = status_data.get("wallet", {}).get("usdc_balance", 0.0)
            network = status_data.get("wallet", {}).get("network", "unknown")
            print(f"ClawRouter is LIVE. Network: {network}. Wallet Balance: {balance} USDC.")
            return True
        return False
    except requests.exceptions.RequestException:
        print("ClawRouter offline or unreachable.")
        return False

def route_with_clawrouter(prompt: str, base_url: str = "http://localhost:8402/v1") -> str:
    headers = {
        "Content-Type": "application/json",
        "Authorization": "Bearer x402"
    }

    req = ClawRouterRequest(
        messages=[ChatMessage(role="user", content=prompt)],
        metadata=RoutingMetadata(max_cost_limit_usd=0.05, latency_sla_ms=1500)
    )

    try:
        start_time = time.time()
        res = requests.post(f"{base_url}/chat/completions", json=req.model_dump(), headers=headers, timeout=10)
        elapsed = time.time() - start_time

        if res.status_code == 200:
            data = ClawRouterResponse.model_validate(res.json())
            completion = data.choices[0].message.content
            cost = data.usage.estimated_cost_usd if data.usage else 0.0
            print(f"Routed to '{data.model}' in {elapsed:.3f}s. Cost: {cost} USDC.")
            return completion
        else:
            print(f"Routing failed: {res.status_code} - {res.text}")
            return ""
    except Exception as e:
        print(f"Routing error: {e}")
        return ""

if __name__ == "__main__":
    if check_clawrouter_health():
        completion = route_with_clawrouter("Draft a python script to calculate Fibonacci series.")
        if completion:
            print(f"Response: {completion[:100]}...")
    else:
        print("Running fallback diagnostics. Ensure 'npx @blockrun/clawrouter' is running locally.")

Related tools / concepts

• OpenClaw
• LiteLLM
• OpenRouter
• Claude 5.6
• GPT-5.6
• Llama 4 Maverick
• Model Context Protocol (MCP)
• Aider
• Zed

Sources / References

• GitHub Repository
• x402 Protocol Specification

Contribution Metadata

• Last reviewed: 2027-01-07
• Confidence: high