DOCSEARCHbyAlgolia
Submit Docs

ClawRouter Documentation

repository·main·Indexed 27 days ago

https://github.com/blockrunai/clawrouter

An open-source, agent-native LLM router providing access to 66+ models via wallet signatures and USDC micropayments using the x402 protocol. It features smart local routing to reduce inference costs by up to 87%, supports OpenAI-compatible clients (Cursor, continue.dev), and includes integrated capabilities for AI image/video generation, outbound voice calls via Bland.ai, and crypto data queries via the Surf API.

Tokens
64.1K
Snippets
137
Records
309
Agent score
91%

What's inside ClawRouter

  1. Understand ClawRouter Routing Profiles

    main

    ClawRouter uses four distinct routing profiles to map classified request tiers to specific models. Depending on your needs, you can choose between default performance, ultra-low cost, or maximum quality.

    • Auto Profile (Default): Balanced for speed, cost, and user retention.
    • Eco Profile: Optimized for minimum cost using free or near-free models.
    • Premium Profile: Prioritizes highest quality regardless of cost.
    • Fallback Chains: Every tier includes an ordered list of models used if the primary model returns a 402 (payment failed), 429 (rate limited), or 5xx error. The chain descends by quality and then by speed.

  2. Reduce AI costs with ClawRouter

    main

    ClawRouter is an open-source local proxy that sits between your application (using the OpenAI SDK) and over 41 AI models. It reduces costs by automatically routing requests to the most cost-effective model, compressing tokens, and caching responses.

    Instead of routing all requests to expensive frontier models like Claude Sonnet or Opus, you can set your model to "auto" in your application code to leverage ClawRouter's smart routing.

  3. Use the blockrun_polymarket tool for trading

    main

    The blockrun_polymarket tool is used for real-money trading on Polymarket's CLOB V2 (Polygon). It handles setup, funding, buying/selling, managing positions, and redeeming winnings.

    Important distinction: This tool is for trading only. For market data discovery (finding market IDs, token IDs, etc.), use the blockrun_predexon_* data tools instead.

    Key Concepts:

    • Signer: The ClawRouter wallet key (~/.openclaw/blockrun/wallet.key or BLOCKRUN_WALLET_KEY). This key signs transactions locally and never leaves the machine.
    • Deposit Wallet: A Polygon vault contract (POLY_1271) derived from your signer. It holds betting funds in pUSD. All operations (deploy, approve, redeem) are gasless via a relayer.
    • Money Separation: Bets use pUSD on Polygon. API fees use USDC on Base. Both are funded from your single ClawRouter wallet.

  4. Implement the ClawRouter Worker Network

    main

    The Worker Network allows ClawRouter users to opt-in as worker nodes that execute HTTP health checks and earn USDC micropayments via x402.

    Architecture Overview:

    • Polling: ClawRouter polls the BlockRun API every 30 seconds for tasks.
    • Execution: Workers execute HTTP GET requests and verify the status code.
    • Verification: Results are signed using the worker's existing wallet key (EIP-191 signature) to prove identity.
    • Payment: BlockRun accumulates credits and pays out via x402 (TransferWithAuthorization) once a worker reaches a $0.01 threshold to ensure gas efficiency.

  5. Understand ClawRouter Project Structure

    main

    The ClawRouter repository is organized into the following core modules:

    • src/index.ts: Plugin entry point using register() and activate().
    • src/provider.ts: Registers the blockrun provider in OpenClaw.
    • src/proxy.ts: Local HTTP proxy handling routing and x402 payments.
    • src/models.ts: Definitions for 30+ models including pricing data.
    • src/auth.ts: Wallet key resolution via environment variables, config, or prompts.
    • src/logger.ts: JSON lines usage logger.
    • src/types.ts: OpenClaw plugin type definitions.
    • src/router/index.ts: The main route() entry point.
    • src/router/rules.ts: Weighted classifier using 14 dimensions and sigmoid confidence.
    • src/router/llm-classifier.ts: LLM fallback mechanism (using gemini-flash with caching).
    • src/router/selector.ts: Maps Tiers to models and calculates costs.
    • src/router/config.ts: Default routing configuration.
    • src/router/types.ts: Defines RoutingDecision, Tier, and ScoringResult types.

  6. Understand the Smart LLM Router architecture

    main

    The ClawRouter uses a rule-based classifier to route requests based on a 14-dimension scoring system. This allows the system to select the optimal model by balancing speed, quality, and cost rather than optimizing for a single metric like latency.

    Routing Workflow:

    1. Preprocessing: User prompt is lowercased and tokenized.
    2. Scoring: 14 dimensions (e.g., reasoningMarkers, codePresence, agenticTask) are scored between -1 and 1.
    3. Aggregation: Scores are combined using a weighted sum (weights sum to 1.0).
    4. Tier Classification: The weighted score is mapped to tiers: SIMPLE < 0.0 < MEDIUM < 0.3 < COMPLEX < 0.5 < REASONING.
    5. Confidence Calibration: A sigmoid function calculates confidence based on the distance from tier boundaries. If confidence < 0.7, the request is marked AMBIGUOUS and defaults to the MEDIUM tier.
    6. Model Selection: The determined tier and profile are used to select the final model.

  7. Understand ClawRouter System Architecture

    main

    ClawRouter acts as a local proxy between an OpenAI-compatible client (like Cursor, VS Code, or a custom app) and AI providers (OpenAI, Anthropic, Google). It provides smart routing, deduplication, and a non-custodial payment system using USDC.

    Key Principles:

    • 100% local routing: Model selection logic runs on your machine without external API calls.
    • Client-side only: Your wallet private keys never leave your local machine.
    • Non-custodial: USDC remains in your wallet until the moment it is spent.
    • Dual-chain support: Supports USDC on Base (EVM) or Solana. Note that SOL or ETH tokens are not accepted; only USDC can be used for payments.

  8. Understand ClawRouter's Fallback and Retry Mechanism

    main

    ClawRouter provides robust error handling through 8-deep fallback chains per routing tier. Unlike traditional aggregators that may surface raw HTTP 429 (Rate Limit) or 529 (Overloaded) errors to the agent, ClawRouter automates recovery:

    1. 200ms Retry: Performs a short-burst retry for transient rate limits.
    2. Model Cascading: If the retry fails, it automatically moves to the next model in the fallback chain.
    3. Per-model Isolation: Failures in one provider do not affect the availability of others.
    4. Structured Error Reporting: If the entire chain fails, it provides a summary of all attempts and specific failure reasons.
    [ClawRouter] Trying model 1/6: google/gemini-2.5-flash
[ClawRouter] Model google/gemini-2.5-flash returned 429, retrying in 200ms...
[ClawRouter] Retry failed, trying model 2/6: deepseek/deepseek-chat
[ClawRouter] Success with model: deepseek/deepseek-chat

  9. Understand ClawRouter tier classification

    main

    ClawRouter automatically classifies every query into one of four tiers to select the most cost-effective model capable of handling the task:

    • SIMPLE: Basic questions, short responses, and simple lookups.
    • MEDIUM: Code generation and tasks of moderate complexity.
    • COMPLEX: Large context windows, multi-step reasoning, and complex code tasks.
    • REASONING: Logic puzzles, mathematics, and chain-of-thought tasks.

  10. Understand ClawRouter Smart Routing Architecture

    main

    ClawRouter uses a hybrid, client-side approach to route LLM queries to the most cost-effective model based on task complexity. This prevents sending simple queries to expensive models like Claude Opus when cheaper models like Gemini Flash are sufficient.

    The routing process follows four steps:

    1. Weighted Scoring Engine (< 1ms): Analyzes 14 dimensions (e.g., code presence, reasoning markers, token count) to produce a score and confidence level.
    2. LLM Classifier (~200ms): If scoring confidence is below 0.70, a cheap model (gemini-2.5-flash) is used to classify the query.
    3. Tier → Model Selection: Maps the determined tier to the cheapest capable model.
    4. Metadata Generation: Produces a RoutingDecision object containing the selected model, tier, confidence, and cost savings.

  11. Understand ClawRouter routing tiers and limitations

    main

    ClawRouter uses an intelligent routing architecture to classify requests into four complexity tiers. This allows for cost-effective execution via ECO mode (routing to free models) or balanced execution via AUTO mode (routing to premium models).

    Routing Tiers

    TierTypical TasksECO Route (Free)AUTO Route (Premium)
    SIMPLEFormatting, translation, Q&AGPT-OSS 120BGPT-4o Mini
    MEDIUMSummaries, analysis, general codingDeepSeek V3.2DeepSeek V3.2
    COMPLEXArchitecture, complex codeNemotron Ultra 253BClaude Sonnet 4
    REASONINGMathematical proofs, multi-step logicN/ADeepSeek R1 or Claude Opus 4

    Important Limitations

    1. No Verified Tool Calling: None of the free models support structured function calling (tool use). For applications requiring tool use, you must use a paid model (e.g., GPT-4o, Claude Sonnet).
    2. Reasoning Ceiling: While several free models support reasoning, they may not match the performance of top-tier models like Claude Opus 4 or o3 on extremely difficult mathematical or formal logic tasks.
    3. Context Windows: Most free models offer between 128K and 256K context. While generous, they may not accommodate massive datasets (like entire monorepos) as effectively as models with 2M+ context windows.

  12. Understand ClawRouter data flow and privacy

    main

    ClawRouter acts as a thin local proxy. It does not perform local inference. Instead, it forwards requests to the blockrun.ai gateway.

    Data Flow: Your app $\rightarrow$ localhost proxy (ClawRouter) $\rightarrow$ https://blockrun.ai/api (or sol.blockrun.ai/api) $\rightarrow$ Provider (OpenAI, Anthropic, etc.) $

    What is sent to the gateway:

    • Model name
    • Full prompt/messages body
    • Sampling parameters (temperature, max_tokens, tools, etc.)
    • An X-PAYMENT header containing a signed x402 USDC micropayment.

    What is NOT sent:

    • Your wallet private key (only a detached payment signature is sent).
    • Local files, environment variables, or other OpenClaw configurations.

    Privacy Note: Treat prompts sent through ClawRouter the same way you would treat prompts sent to any hosted LLM API (like OpenAI or Anthropic).