clawrouter

# ClawRouter Hosted-gateway LLM router that saves <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% on inference costs by forwarding each request to the blockrun.ai gateway, which picks the cheapest model capable of handling it across <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models from 9 providers (<!-- br:models.free -->6<!-- /br:models.free --> free open-weight models). All billing flows through one BlockRun credential — either a USDC wallet paying x402 per call, or a BlockRun API key drawing on card-funded account credit. Either way you do not hold provider API keys. **This is not a local-inference tool.** ClawRouter is a thin local proxy. Your prompts are sent over HTTPS to the blockrun.ai gateway for model execution. If your workload requires inference that never leaves your machine, use a local runtime like Ollama — ClawRouter is not the right tool for that use case. Source: https://github.com/BlockRunAI/ClawRouter · npm: https://www.npmjs.com/package/@blockrun/clawrouter · License: MIT. ## Data Flow ``` Your app → localhost proxy (ClawRouter) → https://blockrun.ai/api (or sol.blockrun.ai/api) ↓ OpenAI / Anthropic / Google / etc. ↓ Response → back through proxy → your app ``` **Sent to blockrun.ai on every request:** the model name, the full prompt/messages body, sampling params (temperature, max_tokens, tools, etc.), and a payment credential — an `X-PAYMENT` header containing a signed x402 USDC micropayment in wallet mode, or an `Authorization: Bearer brk_live_…` header in API-key mode. **Not sent:** your wallet private key (only the detached payment signature is sent), any other local files, environment variables, or OpenClaw config beyond what's needed for this request. **Blockrun's privacy stance:** https://blockrun.ai/privacy. Treat prompts the same way you'd treat prompts sent to any hosted LLM API (OpenAI, Anthropic, etc.) — do not send data you would not share with a third-party API provider. ## Credentials & Local Key Storage ClawRouter does **not** collect or forward third-party provider API keys. You do not supply OpenAI, Anthropic, Google, DeepSeek, xAI, or NVIDIA credentials — the blockrun.ai gateway owns those relationships. **What `models.providers.blockrun` stores (fully enumerated):** | Field | Sensitive | Purpose | | ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `walletKey` | Only in wallet mode | EVM private key used to sign USDC micropayments via x402. **Auto-generated locally on first run** — no user input required. Never transmitted over the network; only detached payment signatures are sent. Not used, read, or generated at all when a BlockRun API key is configured. | | `solanaKey` | Yes | Solana keypair (BIP-44 `m/44'/501'/0'/0'`). Auto-derived from the same local mnemonic via `@scure/bip32` + `@scure/bip39`. | | `gateway` | No | Gateway URL. Defaults: `https://sol.blockrun.ai/api` (Solana, default chain for new installs) · `https://blockrun.ai/api` (Base, default for pre-existing installs). | | `routing` | No | Optional override of the router-core config (tier chains, `strategy: "rules"` rollback, `shadow` comparison, scorer keywords). | **How and where keys are stored:** - Keys live in the OpenClaw user config file — typically `~/.config/openclaw/config.json` on Linux, `~/Library/Application Support/openclaw/config.json` on macOS, `%APPDATA%\openclaw\config.json` on Windows — under the `models.providers.blockrun` path. - Written by OpenClaw's standard config writer with `0600` permissions on POSIX systems (owner read/write only). - **Stored in plaintext**, the same way every OpenClaw provider's API key is stored. ClawRouter does not add an extra encryption layer; your filesystem permissions are the security boundary. If you require an encrypted keystore, run OpenClaw on an encrypted volume (FileVault, LUKS, BitLocker) or use a dedicated burner wallet funded only with what you intend to spend. - Auto-generation uses `@scure/bip39` to produce a 24-word mnemonic, then BIP-44 derivation for both chains. Source: [`src/wallet.ts`](https://github.com/BlockRunAI/ClawRouter/blob/main/src/wallet.ts). **Operational guidance:** treat the wallet as a spending account with a small top-up, not a long-term store of value. Fund it with what you expect to spend on LLM calls. If the host machine is compromised, the wallet key is compromised — rotate and refund. ## Supply-Chain Integrity - Every release is tagged on GitHub: https://github.com/BlockRunAI/ClawRouter/releases - Every release publishes to npm with a matching version: https://www.npmjs.com/package/@blockrun/clawrouter?activeTab=versions - The `skills/release/SKILL.md` mandatory checklist enforces: same version in `package.json`, matching git tag, matching GitHub release, and matching npm publish. - To verify locally: `npm pack @blockrun/clawrouter@<version>` and compare the tarball contents to the tagged commit. ## Install ```bash openclaw plugins install @blockrun/clawrouter ``` The structured `install` block above tells OpenClaw to install the auditable npm package `@blockrun/clawrouter`. Source for every version is on GitHub; every release is tagged. ## Setup ```bash # Enable smart routing (auto-picks cheapest model per request) openclaw models set blockrun/auto # Or pin a specific model openclaw models set openai/gpt-4o ``` ## How Routing Works Routing is done locally by [`@blockrun/router-core`](https://github.com/BlockRunAI/router-core) (Router Core V3.4, constraint-first), inlined into ClawRouter and pinned by commit. No network call, no second model — about a quarter of a millisecond per request. 1. A 15-dimension weighted scorer classifies each request into one of four tiers, and a task classifier labels the shape of the work (chat, extraction, code_edit, code_agent, tool_agent, reasoning_math, long_context, vision, …). 2. Models that cannot satisfy the request — no tool calling, no vision, too small a context window or max-output, incompatible structured output — are removed before anything is scored. 3. Survivors are ranked on task quality, capability, estimated cost, speed and reliability; the full ranked list is kept as the fallback chain for timeouts and 5xx. Curated primaries on the default `auto` profile: - **SIMPLE** — factual lookups, greetings, translations → gemini-2.5-flash ($0.30/$2.50) - **MEDIUM** — summaries, explanations, data extraction → kimi-k2.7 ($0.95/$4.00) - **COMPLEX** — code generation, multi-step analysis → gemini-3.1-pro ($2/$12) - **REASONING** — proofs, formal logic, multi-step math → grok-4-1-fast-reasoning ($0.20/$0.50) Turns that actually need their attached tools switch to agent-tuned tiers (gpt-4o-mini → kimi-k2.7 → claude-sonnet-4.6). `eco` opens on the free tier (nemotron-3.5-lightning); `premium` climbs to gpt-5.3-codex / claude-fable-5 / claude-sonnet-4.6. Full chains: [docs/routing-profiles.md](../../docs/routing-profiles.md). Prices are per 1M input/output tokens. Per-tier savings percentages are deliberately not quoted here: the published figure is blended across a stated workload mix, and a per-tier number invites comparing it against a baseline nobody wrote down. See [savings-mix.json](https://github.com/BlockRunAI/blockrun/blob/main/src/brand/savings-mix.json). ## Available Models <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models including: gpt-6-astra [GPT-6 flagship, 1M ctx], gpt-6-sol, gpt-6-luna [fast, $0.10/$0.50], gpt-5.6-terra [balanced, stable default], gpt-5.6-sol [flagship], gpt-5.6-luna [cost-efficient], gpt-5.6-sol/terra/luna-pro [pro reasoning tiers], gpt-5.5, gpt-5.5-pro [max compute], chat-latest [ChatGPT Instant], gpt-5.4, gpt-5.1, gpt-4o, o3, claude-fable-5.1, claude-fable-5, claude-opus-5.5 [newest Opus, $4/$20], claude-opus-5 [1M ctx], claude-opus-4.8, claude-opus-4.7, claude-opus-4.5, claude-sonnet-5.5, claude-sonnet-5, claude-sonnet-4.6, gemini-3.1-pro, gemini-3.6-flash, gemini-3.5-flash-lite, gemini-2.5-flash, deepseek-v4-pro, deepseek-chat, grok-4.7, grok-4.6, grok-4.5, grok-4.3, grok-build-0.1, glm-5.3 [Z.AI flagship, 1M ctx], glm-5.3-flash [natively multimodal, 1M ctx — $0.15/$0.50], glm-5.2, minimax-m3, kimi-k3 [1M ctx flagship], kimi-k2.7, qwen3.7-max [Qwen flagship, 1M ctx], qwen3.7-plus, qwen3.7-flash, mimo [Xiaomi MiMo-V2.5 Pro, 1M ctx], and <!-- br:models.free -->6<!-- /br:models.free --> free open-weight models (nemotron-3.5-lightning [1M ctx, thinking mode — the free default], nemotron-3-ultra-550b [550B/55B MoE, 1M ctx — the largest free model], nemotron-3-nano-omni-30b-a3b-reasoning [256K ctx], llama-3.2-11b-vision [Meta Llama], north-mini-code [Cohere, coding, sub-second], laguna-xs-2.1 [Poolside, coding, ~161 tok/s]). The free tier is text-only — image turns route to a paid vision model, because the two free models the catalogs advertise as vision-capable fail a solid-colour probe on both chains and do so with an HTTP 200. ## Built-in Agent Tools In addition to LLM routing, ClawRouter exposes BlockRun's x402-gated data APIs as ready-to-use OpenClaw tools. Every tool is paid from the same USDC wallet — no extra setup, no extra API keys. ### Market Data Realtime prices and historical OHLC across every asset class. The agent should call these directly instead of scraping finance sites. | Tool | Coverage | Price | | -------------------------- | ------------------------------------------------------------------------------- | ------------- | | `blockrun_stock_price` | 12 global markets: US (NYSE/Nasdaq), HK, JP, KR, UK, DE, FR, NL, IE, LU, CN, CA | $0.001 / call | | `blockrun_stock_history` | OHLC bars at 1/5/15/60/240-min or D/W/M resolution | $0.001 / call | | `blockrun_stock_list` | Ticker lookup / company-name search per market | Free | | `blockrun_crypto_price` | BTC-USD, ETH-USD, SOL-USD, and more | Free | | `blockrun_fx_price` | EUR-USD, GBP-USD, JPY-USD, and more | Free | | `blockrun_commodity_price` | XAU-USD (gold), XAG-USD (silver), XPT-USD (platinum) | Free | ### Image & Video Generation | Tool | Purpose | Price |