ClawRouter for Hermes

Hermes gives your agent a body. ClawRouter gives it a wallet.
No provider accounts. No API keys. No credit card.

One Hermes provider, 71 models from 12 labs, paid per request in USDC.

5 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 install gives Hermes 71 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 88% versus pinning Claude Opus 5. Authentication is a wallet signature, billing is USDC over x402 on Base or Solana, and 5 models cost nothing at all. MIT licensed.

Why this plugin exists

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.

Your agent can't do any of that. Agents can't open accounts or type in credit cards — they can only sign transactions.

ClawRouter collapses the whole thing into one provider:

• Starts at $0 — 5 free models, usable before you ever touch crypto
• One provider, every lab — Hermes' /model picker shows the full curated catalog, grouped by provider
• No API keys — the local wallet signature is authentication; you never hold a lab's key
• No model babysitting — blockrun/auto scores each request across 15 dimensions and picks the cheapest model that can actually do the job
• Pay per request — USDC via x402 on Base or Solana; $5 covers thousands of calls, non-custodial
• Same wallet for everything — image, video and web-search tools bill through it too
• Fixes Hermes' auxiliary-vision breakage — a single api_key provider on 127.0.0.1 sidesteps #38679 and #38685 (how)

How it compares

Quick Start

No wallet? Free models work out of the box. Install, pick any blockrun/free/... model in /model, and you're running — no crypto, no balance. Add USDC later when you want frontier models.

1. Install

curl -fsSL https://raw.githubusercontent.com/BlockRunAI/ClawRouter-Hermes/main/scripts/install.sh | bash

The 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.

~/.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 doctor

2. Pick a model

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/deepseek-v4-flash.

3. Fund the wallet (optional)

Free models need nothing. For paid models, create and fund the shared wallet:

npx @blockrun/clawrouter setup     # creates ~/.openclaw/blockrun/mnemonic

Send a few USDC on Base or Solana — $5 covers thousands of requests, fully non-custodial. Check it any time with /clawrouter wallet.

What you get

Models

The /model picker carries a curated, provider-grouped slice of the catalog (small inline keyboards can't render 71 entries); every other model stays routable by full ID.

Routing profiles

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.

Slash commands

Tools

All three bill from the same wallet — no extra keys, no extra setup.

CLI

hermes-clawrouter <setup|update|wallet|doctor|route|stats>

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.

Auxiliary vision

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: 120

setup 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.

Wallet

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 setup

Fund USDC on Base or Solana — $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.

Headless / CI: set BLOCKRUN_WALLET_KEY=<0x raw EVM hex> to bypass the mnemonic file (EVM-only — Solana derivation unavailable).

Environment variables

CLAWROUTER_API_KEY is intentionally a non-secret placeholder (clawrouter-local). ClawRouter payments use the local wallet and proxy, but Hermes hides API-key-style providers from /model unless the configured key env var exists.

Upgrading

hermes-clawrouter update      # pip upgrade + refresh the materialized integration

A 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.)

Troubleshooting

Guides

Standalone problem→solution walkthroughs for common Hermes provider/vision setups:

How it works

Hermes chat  →  ClawRouter provider (127.0.0.1:8402)  →  blockrun.ai gateway  →  OpenAI / Anthropic / Google / …
                        ↑ spawned + supervised                ↑ x402 USDC micropayment, signed locally

1. hermes starts → the entry-point plugin loads → register(ctx) wires tools, slash commands, CLI, and the skill.
2. hermes-clawrouter setup materializes ~/.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.
3. Hermes' providers/__init__.py discovers the materialized directory and registers ClawRouterProfile, pointing base_url at http://127.0.0.1:<port>/v1.
4. First tool call or chat turn → the supervisor probes :8402, spawns npx -y @blockrun/clawrouter --port <port> if needed, waits ≤30s for /v1/models, then forwards the request.
5. A heartbeat thread restarts the subprocess on death (max 3 restarts/min).

Wallet (BIP-39, Base + Solana), 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 the blockrun.ai gateway for execution. If you need inference that never leaves your machine, use Ollama.

Distribution

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/ by hermes-clawrouter setup): ProviderProfile registration.

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.

Development

git clone https://github.com/BlockRunAI/ClawRouter-Hermes.git
cd ClawRouter-Hermes
pip install -e ".[dev]"
pytest

Support

From the BlockRun ecosystem

FAQ

Does this replace Hermes' own providers?

No. It adds one more provider. Existing OpenAI/Anthropic/OAuth blocks in config.yaml keep working; you can move to ClawRouter model by model.

Do I need crypto to try it?

No. 5 models are free with no wallet, no balance and no signup. Fund USDC only when you want frontier models.

Where do my keys live?

You have no lab API keys. The only secret is a local BIP-39 mnemonic at ~/.openclaw/blockrun/mnemonic (mode 0o600), which never leaves the machine — only detached x402 payment signatures are sent. Treat it as a spending account with a small top-up, not a store of value.

What does it cost to run?

The plugin is MIT and free. You pay per request in USDC, at gateway prices — on blockrun/auto that's 88% less than pinning Claude Opus 5 for the same traffic, and 98% less on eco.

Can I point it at my own proxy?

Yes — set CLAWROUTER_PROXY_URL and the plugin skips the local spawn entirely.