Hermes gives your agent a body. ClawRouter gives it a way to pay.
No provider accounts. No per-lab keys. Two rails, one provider block.
One Hermes provider, 76 models from 12 labs, paid per request —
USDC from a local wallet, or account credit on one BlockRun key.
7 models free — no crypto, no balance, no signup required.
hermes-plugin-clawrouter wires NousResearch Hermes into ClawRouter, the open-source LLM router built for autonomous agents. One
pip installgives Hermes 76 chat models from OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, Z.ai, MiniMax, Qwen, NVIDIA and more — plus image, video and web-search tools — behind a single local provider. Requests are scored across 15 dimensions and routed to the cheapest capable model in under 1ms, cutting inference cost by 84% versus pinning Claude Opus 5. Pay however suits you: sign a USDC x402 micropayment per call from a local wallet on Solana or Base, or sign up at user.blockrun.ai, top up with a card and use onebrk_…key. 7 models cost nothing on either rail. MIT licensed.
Same catalog, same model ids, same OpenAI-compatible shape. The rails differ only in what authenticates the call and where the money comes from.
| 👛 Wallet (x402) | 🔑 API key (account credit) | |
|---|---|---|
| Who it's for | An agent that can sign but can't open accounts | A person who'd rather pay with a card |
| Set up | npx @blockrun/clawrouter setup — a local BIP-39 wallet |
Sign in at user.blockrun.ai, mint a key |
| Sign-up needed | None, ever | Google sign-in |
| Funding | Send USDC on Solana or Base | Card top-up at /dashboard/credits |
| Gateway | sol.blockrun.ai/api · blockrun.ai/api |
api.blockrun.ai |
| Per-call fee | BlockRun's $0.001 transaction fee, on top of list price |
None — list price, billed at exact usage |
| Top-up fee | None (you just hold USDC) | 5.5% + $0.30 per card top-up |
| Receipts | On-chain, plus /clawrouter stats |
Per-request, at /dashboard/activity |
| Turn it on | The default | hermes-clawrouter login brk_live_… |
A key wins over a wallet whenever both are present. A machine holding a wallet and a key you just added means "bill my account", not "keep spending my USDC". Nothing is deleted — hermes-clawrouter logout puts you straight back on the wallet, same mnemonic, same balance.
- Go to user.blockrun.ai and sign in with Google.
- Mint a key at /dashboard/keys — it looks like
brk_live_…. - Add credit at /dashboard/credits (card; 5.5% + $0.30 per top-up).
- Tell this plugin about it:
hermes-clawrouter login brk_live_...
hermes-clawrouter account # confirms the rail, the gateway and the key (masked)Every call then shows up as its own receipt — model, tokens, exact cost, request id — at /dashboard/activity.
Type the key in a terminal, never in a chat.
/clawrouter logindeliberately refuses: a slash command's arguments live in the transcript, and on Telegram that history is not yours to delete.
Stock Hermes wants a provider block and an API key per lab. Want Claude and GPT and Gemini and Grok? That's four accounts, four billing relationships, four keys to rotate, and a config.yaml that grows every time a new model ships.
ClawRouter collapses the whole thing into one provider:
- Starts at $0 — 7 free models, usable before you pay anyone anything
- One provider, every lab — Hermes'
/modelpicker shows the full curated catalog, grouped by provider - No lab keys, ever — you hold at most one BlockRun credential, never OpenAI's or Anthropic's
- Pay how you like — a wallet signature or one
brk_…key; the plugin follows whichever is configured - No model babysitting —
blockrun/autoscores each request across 15 dimensions and picks the cheapest model that can actually do the job - Same credential for everything — image, video and web-search tools bill through it too
- Fixes Hermes' auxiliary-vision breakage — a single
api_keyprovider on127.0.0.1sidesteps #38679 and #38685 (how)
| Hermes + lab API keys | Hermes + OpenRouter | Local Ollama | ClawRouter for Hermes | |
|---|---|---|---|---|
| Models | One provider block per lab | Many | Whatever you host | 76, one block |
| Free tier | No | Rate-limited | Free but local GPU | 7 models, no signup |
| Auth | An API key per lab | Account + API key | None | Wallet signature, or one BlockRun key |
| Payment | Per-lab invoices | Credit card | Your electricity | USDC per request, or account credit |
| Model selection | Manual | Manual | Manual | Automatic (15-dim scoring, <1ms) |
| Image / video | Another key, another block | No | No | Built-in tools, same credential |
| Frontier models | Yes | Yes | No | Yes |
Not sure you want to pay yet? Free models work out of the box. Install, pick any
blockrun/free/...model in/model, and you're running — no crypto, no account, no balance.
curl -fsSL https://raw.githubusercontent.com/BlockRunAI/ClawRouter-Hermes/main/scripts/install.sh | bashThe installer checks for Python, pip/venv support, pipx, and Node/npm/npx, installs missing basics through common Linux/macOS package managers, avoids Debian/Ubuntu's externally-managed-environment (PEP 668) trap by installing into Hermes' own Python environment, enables the plugin, runs setup, and prints doctor checks.
Manual install — if you already know where Hermes' venv lives
~/.hermes/hermes-agent/venv/bin/python -m pip install -U hermes-plugin-clawrouter
hermes plugins enable clawrouter
~/.hermes/hermes-agent/venv/bin/hermes-clawrouter setup
~/.hermes/hermes-agent/venv/bin/hermes-clawrouter doctorsetup writes the model-provider plugin to ~/.hermes/plugins/model-providers/clawrouter/, seeds CLAWROUTER_API_KEY=clawrouter-local in ~/.hermes/.env, and registers ClawRouter in ~/.hermes/config.yaml so Hermes' /model picker shows the provider and its curated chat models.
In a Hermes chat, open /model and choose ClawRouter → blockrun/auto for smart routing — or pin anything from the catalog, e.g. blockrun/anthropic/claude-opus-5, blockrun/openai/gpt-5.6-terra, blockrun/free/nemotron-3.5-lightning.
Free models need neither. For paid models, pick one:
|
🔑 Pay by card # 1. Sign in + mint a key at user.blockrun.ai
# 2. Add credit at /dashboard/credits
hermes-clawrouter login brk_live_...Verifies the key against |
👛 Pay from a wallet npx @blockrun/clawrouter setup
# creates ~/.openclaw/blockrun/mnemonicSend a few USDC on Solana or Base — $5 covers thousands of requests, fully non-custodial. |
Check either with /clawrouter account in chat, or hermes-clawrouter account in a terminal.
The /model picker carries a curated, provider-grouped slice of the catalog (small inline keyboards can't render 76 entries); every other model stays routable by full ID.
| Provider | In the picker |
|---|---|
| Routing | blockrun/auto · blockrun/premium · blockrun/eco · blockrun/free |
| Anthropic | claude-fable-5 · opus-5 · opus-4.8 · opus-4.7 · sonnet-5 · sonnet-4.6 · haiku-4.5 |
| OpenAI | gpt-5.6-terra / sol / luna · gpt-5.5 · gpt-5.5-pro · gpt-5.4-pro / 5.4 / mini / nano · gpt-5.3-codex |
| gemini-3.1-pro · gemini-3.8-flash · gemini-3.6-flash · gemini-3.5-flash · gemini-3.5-flash-lite · gemini-3.1-flash-lite · gemini-3-flash-preview | |
| xAI | grok-4.5 · grok-4.3 · grok-build-0.1 |
| DeepSeek | deepseek-v4-flash-vision-exp (vision) · deepseek-v4-pro · deepseek-chat · deepseek-reasoner |
| Z.ai | glm-5.3 · glm-5.3-flash · glm-5.2 · glm-5.1 · glm-5-turbo · glm-5 |
| Xiaomi / Tencent | mimo-v2.5 (vision) · mimo-v2.5-pro · hy3 |
| Moonshot / Qwen / MiniMax | kimi-k3 · qwen3.7-max · qwen3.8-flash · minimax-m3 · minimax-m2.7 |
| Free | nemotron-3.5-lightning · nemotron-3-nano-30b · laguna-xs-2.1 · north-mini-code · nemotron-3-nano-omni (vision) · nemotron-3-ultra-550b (1M ctx) · llama-3.2-11b-vision (vision) |
| Model ID | Strategy | Cost vs. pinning Opus 5 | Best for |
|---|---|---|---|
blockrun/free |
Free models only | 100% cheaper | $0 balance, learning |
blockrun/eco |
Cheapest capable | 98% cheaper | Maximum savings |
blockrun/auto |
Balanced (recommended) | 84% cheaper | General use |
blockrun/premium |
Best model per tier | Baseline | Mission-critical |
Savings are computed from a published workload mix, not estimated — see savings-mix.json. /clawrouter route <eco|auto|premium> sets the profile the proxy itself runs with, applied on its next spawn.
| Command | What it does |
|---|---|
/clawrouter account |
Which rail you're paying on, and where to change it |
/clawrouter wallet |
Address + USDC balance (Solana and Base) |
/clawrouter wallet <solana|base> |
Switch payment chain (machine-wide), restarts the proxy |
/clawrouter stats |
Proxy usage stats |
/clawrouter status |
Proxy health, port, active profile, auth mode |
/clawrouter route <eco|auto|premium> |
Set the routing profile |
/clawrouter logout |
Drop the API key, go back to the wallet |
/clawrouter help |
The list above |
There is no /clawrouter login — it refuses on purpose, and points you at the terminal. See Where to sign up.
| Tool | Coverage |
|---|---|
clawrouter_image_generate |
9 image models — GPT Image 2, Nano Banana / Pro, Seedream 5 Pro, Grok Imagine, CogView-4 |
clawrouter_video_generate |
8 video models — Seedance 1.5 / 2.0, Grok Imagine, Sora 2 |
clawrouter_web_search |
Exa-powered web search |
All three bill from whichever rail you're on — wallet or account credit — with no extra keys and no extra setup. On the API-key rail they go to api.blockrun.ai, which serves the media and search endpoints alongside chat.
hermes-clawrouter <setup|update|login|logout|account|wallet|doctor|route|stats>| Subcommand | What it does |
|---|---|
login <brk_…> |
Verify a BlockRun key, store it 0600, switch this machine to account credit |
logout |
Remove stored keys and go back to the x402 wallet |
account |
Which rail is live, which gateway, the key masked (--json for scripts) |
wallet |
Solana + Base addresses and USDC balances (--json) |
doctor |
Health check — the credential checks follow whichever rail is configured |
hermes-clawrouter ships as its own entry point because some Hermes releases don't register plugin-defined top-level CLI commands until the plugin is enabled. Once it's loaded, hermes clawrouter <sub> usually works too.
Hermes' vision_analyze builds a separate OpenAI client for the configured auxiliary.vision provider. That path is fragile for remote custom endpoints (hermes-agent#38679: Connection error) and for OAuth providers (#38685: silent fallback to auto). Routing vision through ClawRouter sidesteps both — it's a single api_key provider on 127.0.0.1, so there's no OAuth branch to miss and no remote TLS handshake to mishandle. Add to ~/.hermes/config.yaml:
auxiliary:
vision:
provider: clawrouter
model: blockrun/auto # or google/gemini-2.5-pro, anthropic/claude-sonnet-4.6
base_url: http://127.0.0.1:8402/v1
api_key: clawrouter-local
timeout: 120setup does not write this automatically — it would overwrite an existing vision config — so add it by hand if you want vision through ClawRouter, then hermes gateway restart.
That api_key: clawrouter-local is the placeholder, not a credential. See the env-var note.
hermes-clawrouter login brk_live_... # bill account credit via api.blockrun.ai
hermes-clawrouter account # what's live right now
hermes-clawrouter logout # back to signing x402 payments from the walletlogin verifies the key against api.blockrun.ai/v1/models before storing it, writes it 0600 to ~/.blockrun/.api-key (shared with every BlockRun product on the machine), and stops any proxy it supervises so the new credential actually takes effect. An unreachable gateway is not treated as a rejected key — it saves anyway and tells you to re-run doctor.
Resolution order, highest first — identical to the upstream TS CLI, because that is the code the proxy itself runs:
BLOCKRUN_API_KEYenvironment variable — for CI and containers~/.blockrun/.api-key— BlockRun Core, shared across products~/.openclaw/blockrun/api-key— legacy ClawRouter location
A file that exists but holds something that isn't a brk_… key is logged and skipped rather than sent upstream: a malformed credential is a 401 per request, and an unexplained 401 is the hardest failure mode there is to diagnose.
What changes inside the proxy is narrower than it sounds. In API-key mode ClawRouter builds no x402 client, registers no signer, and attaches a bearer token instead of settling a 402. Everything downstream is untouched: the same model ids, the same 15-dimension classifier, the same fallback chains, the same routing profiles, the same OpenAI-compatible surface. The three plugin tools keep working unchanged.
Requires @blockrun/clawrouter ≥ 0.12.268. Older proxies ignore BLOCKRUN_API_KEY silently and sign x402 payments from the wallet instead — a configured key would spend USDC you thought was parked. When this plugin sees a stale pre-install alongside a configured key it refuses the fast path and launches @latest through npx instead; hermes-clawrouter doctor reports the version, and setup refreshes the pre-install.
Two proxies never share a port across rails. They bill different accounts from different hosts, so a wallet proxy already listening on :8402 is left alone and a matching one is started on the next free port. doctor cross-checks the running proxy's /health against what you configured, because that is the only thing that proves which account is actually being billed.
The plugin reads the canonical wallet at ~/.openclaw/blockrun/mnemonic (24-word BIP-39 phrase, mode 0o600) and never writes to it. Create one with:
npx @blockrun/clawrouter setupFund USDC on Solana or Base — $5 covers thousands of requests, non-custodial. The same wallet is shared with the upstream TS CLI and every other ClawRouter client on the machine: fund once, use everywhere. Switch chains with /clawrouter wallet solana or /clawrouter wallet base (machine-wide, and it restarts the proxy).
Which chain by default? Solana. When nothing is recorded, a fresh machine prefers Solana — but a machine that already had a wallet before that preference existed stays on Base, because its USDC is sitting in the Base wallet and pointing it at a Solana gateway would fail every request against an empty balance. CLAWROUTER_PAYMENT_CHAIN overrides both. The plugin mirrors the upstream resolution order exactly (env → ~/.blockrun/.chain → ~/.openclaw/blockrun/payment-chain → that default) rather than guessing, because the proxy is what actually signs and the plugin only reports what it will do.
Headless / CI: set BLOCKRUN_WALLET_KEY=<0x raw EVM hex> to bypass the mnemonic file (EVM-only — Solana derivation unavailable).
Configuring an API key does not touch any of this. The mnemonic stays where it is, the balance stays where it is, and logout returns you to it.
| Variable | Effect |
|---|---|
BLOCKRUN_API_KEY |
A real credential. A brk_… key; makes the proxy bill account credit through api.blockrun.ai instead of signing x402 payments. Wins over a wallet. |
BLOCKRUN_API_BASE_URL |
Override the API-key gateway (staging deploys). Default https://api.blockrun.ai. |
CLAWROUTER_PROXY_URL |
Point at an externally-managed proxy (e.g. https://my-host/v1). Skips local spawn entirely. |
HERMES_CLAWROUTER_AUTOSPAWN=0 |
Disable lazy spawn; require npx @blockrun/clawrouter to be running already. |
BLOCKRUN_WALLET_KEY |
Raw EVM hex private key — overrides the mnemonic file. |
CLAWROUTER_PAYMENT_CHAIN |
solana / base. Wins over both chain files. Wallet rail only — an API key has no chain to sign on. |
CLAWROUTER_ROUTING_PROFILE |
eco / auto / premium. Forwarded to the proxy on spawn. |
CLAWROUTER_API_KEYis notBLOCKRUN_API_KEY. The names sit one word apart and mean opposite things.CLAWROUTER_API_KEYis a non-secret placeholder (clawrouter-local) that exists only because Hermes hides API-key-style providers from/modelunless their key env var is set — putting abrk_…key there does nothing, since the local proxy replaces the client'sauthorizationheader on the way upstream.BLOCKRUN_API_KEYis the one that spends money.
hermes-clawrouter update # pip upgrade + refresh the materialized integrationA plain pip install -U works too: the materialized provider plugin is stamped with the version that wrote it, so the next Hermes start notices an older stamp and rewrites it in place — no setup --force needed to pick up newly added models. (Before 0.3.16 that refresh never happened, which is why a bare upgrade could strand you on an old model list.)
update also re-runs setup, which reinstalls @blockrun/clawrouter@latest — the fastest way to clear the "pre-installed proxy is too old for API-key mode" warning.
| Symptom | Fix |
|---|---|
error: externally-managed-environment on pip install |
Do not use --break-system-packages. Use the one-command installer, or run pip from Hermes' venv (~/.hermes/hermes-agent/venv/bin/python -m pip install -U hermes-plugin-clawrouter). |
~/.hermes/hermes-agent/venv/bin/hermes: No such file or directory |
Reinstall or repair Hermes first, then re-run the ClawRouter installer. |
hermes-clawrouter --version still shows the old version |
Your shell is finding a stale ~/.local/bin/hermes-clawrouter from a previous pip --user install. Re-run the one-command installer; it refreshes that launcher to delegate to Hermes' current venv. |
ClawRouter (0 models) in the picker |
Run hermes-clawrouter setup, then restart Hermes. |
| Set a key but the wallet is still being spent | Your pre-installed proxy predates 0.12.268 and ignores the key. Run hermes-clawrouter setup (installs @latest), then doctor. |
401 on every call after login |
The key is revoked or mistyped. hermes-clawrouter doctor says so explicitly; mint a new one at /dashboard/keys. |
402 insufficient_quota on the key rail |
Account credit is exhausted — top up at /dashboard/credits. There is no local balance gate, by design: the gateway's books are server-side, and guessing zero would silently downgrade a paying customer. |
logout didn't switch me back |
BLOCKRUN_API_KEY is still set in your shell — only you can unset that one. logout says so when it happens. |
| Anything else | hermes-clawrouter doctor |
Standalone problem→solution walkthroughs for common Hermes provider/vision setups:
| Guide | When you need it |
|---|---|
vision_analyze "Connection error" on a custom provider |
Chat works but vision_analyze returns Connection error on a custom OpenAI-compatible endpoint (hermes-agent#38679) |
| Auxiliary vision falls back to "auto" with an OAuth provider | auxiliary.vision.provider (e.g. minimax-oauth) logs unhandled auth_type and silently degrades (#38685) |
| Run GPT-5, Claude, Gemini & DeepSeek from one endpoint | You want many models in Hermes without a separate provider/key block per model |
| Pay-per-call LLM access — no API keys | You'd rather pay per request with USDC than manage and rotate provider API keys |
Behind an HTTP proxy/VPN: timeouts, 500s, Premature close |
Small requests work but large agentic requests 500 or time out after payment — your proxy (mihomo/clash/corporate) isn't being used by ClawRouter's upstream traffic |
Retry-and-repay loop: Invalid character in header content |
Non-English prompts (Cyrillic/CJK) on ClawRouter ≤ 0.12.207 crash response delivery after payment settles; Hermes retries and re-pays the same request |
┌─ x402 USDC signed locally ─→ sol.blockrun.ai/api
Hermes chat → ClawRouter provider (127.0.0.1:8402) ─┤ blockrun.ai/api
↑ spawned + supervised └─ Bearer brk_… ─→ api.blockrun.ai
↓
OpenAI / Anthropic / Google / xAI / …
hermesstarts → the entry-point plugin loads →register(ctx)wires tools, slash commands, CLI, and the skill.hermes-clawrouter setupmaterializes~/.hermes/plugins/model-providers/clawrouter/{plugin.yaml,__init__.py}from bundled package data and writes the Hermes config/env hints that current provider and gateway model-picker paths need.- Hermes'
providers/__init__.pydiscovers the materialized directory and registersClawRouterProfile, pointingbase_urlathttp://127.0.0.1:<port>/v1. - First tool call or chat turn → the supervisor probes
:8402, checks the running proxy's/healthis on the rail you configured, spawns one if not, waits ≤30s for/v1/models, then forwards the request. - A heartbeat thread restarts the subprocess on death (max 3 restarts/min).
Wallet (BIP-39, Solana + Base), API-key resolution, routing (the 15-dimension scorer) and x402 payment all live in the canonical TypeScript implementation — this package is a thin Python adapter, not a fork.
Not a local-inference tool. Prompts are sent over HTTPS to a BlockRun gateway for execution. If you need inference that never leaves your machine, use Ollama.
The Python package ships both logical plugins:
- Standalone plugin (this PyPI entry point): tools, slash commands, CLI, skill.
- Model-provider plugin (materialized into
~/.hermes/plugins/model-providers/clawrouter/byhermes-clawrouter setup):ProviderProfileregistration.
The split is required because Hermes' PluginManager (hermes_cli/plugins.py) skips register(ctx) for kind: model-provider, and entry-point plugins always load as kind: standalone.
git clone https://github.com/BlockRunAI/ClawRouter-Hermes.git
cd ClawRouter-Hermes
pip install -e ".[dev]"
pytest| Channel | Link |
|---|---|
| 🔑 Sign up / API keys | user.blockrun.ai |
| 💬 Community Telegram | t.me/blockrunAI |
| 🐦 X / Twitter | x.com/blockrunai |
| 📅 Schedule a demo | calendly.com/vickyfu9/30min |
| vicky@blockrun.ai |
|
ClawRouter for NousResearch Hermes You're here. 76 models, smart routing, wallet or API key.
|
The LLM router built for autonomous agents The canonical TypeScript proxy this plugin wraps. Works with any OpenAI-compatible client.
|
🤖 BRCCBlockRun for Claude Code Claude Code on 76 models — no Anthropic account, no rate limits, pay per request.
|
The live catalog Every model, every price, updated as the gateway changes. |
No. It adds one more provider. Existing OpenAI/Anthropic/OAuth blocks in config.yaml keep working; you can move to ClawRouter model by model.
No. 7 models are free with no wallet, no balance and no signup. Beyond that you can pay with a card at user.blockrun.ai and never touch a wallet at all.
Nothing. The key takes precedence while it's configured, and the wallet sits idle — same mnemonic, same USDC balance, same addresses. hermes-clawrouter logout removes the stored key and the very next call signs x402 again. /clawrouter wallet still shows the balance either way, and still switches the chain the wallet would use.
Yes. api.blockrun.ai serves /v1/images/generations, /v1/videos/generations and /v1/exa/search alongside chat, and the three plugin tools go through the same local proxy on either rail. If a partner endpoint ever isn't published on that host, the proxy rewrites the gateway's Unsupported endpoint 404 into an explanation instead of a bare error.
On the wallet rail: a local BIP-39 mnemonic at ~/.openclaw/blockrun/mnemonic (mode 0o600), which never leaves the machine — only detached x402 payment signatures are sent. On the key rail: ~/.blockrun/.api-key (mode 0o600), sent as a bearer token to exactly one host, api.blockrun.ai. Either way you hold no lab API keys — BlockRun owns those relationships.
The plugin is MIT and free. You pay per request at gateway prices — on blockrun/auto that's 84% less than pinning Claude Opus 5 for the same traffic, and 98% less on eco. The wallet rail adds BlockRun's $0.001 per-call transaction fee; the key rail has no per-call fee and charges 5.5% + $0.30 once, when you top up.
On the key rail, yes — user.blockrun.ai/dashboard/activity lists every request with its model, token counts, exact cost and request id. On the wallet rail, /clawrouter stats plus the on-chain record.
Yes — set CLAWROUTER_PROXY_URL and the plugin skips the local spawn entirely.
MIT License · © BlockRun — agent-native AI infrastructure
⭐ If ClawRouter powers your Hermes agent, consider starring the repo!