hermes-plugin-clawrouter

ClawRouter for Hermes — 66 LLMs from 9 providers, x402 USDC micropayments, smart routing. One local proxy, one wallet, no API keys.

Current catalog headliners: Claude Fable 5 / Opus 4.8 / Sonnet 5, GPT-5.6 (Terra / Sol / Luna), Gemini 3.1 Pro / 3.5 Flash, Grok 4.5, DeepSeek V4 Pro, GLM-5.2, Kimi K2.7, MiniMax M3 — plus 8 free NVIDIA-hosted models that cost nothing to run. Image, video, and web-search tools bill through the same wallet.

Wraps the existing ClawRouter TypeScript proxy as a Hermes plugin. Wallet (BIP-39, Base + Solana), routing (15-dimension scorer), and x402 payment all stay in the canonical TS implementation — this is a thin Python adapter.

Install

Recommended one-command installer:

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. On common Linux/macOS package managers it installs missing basics, avoids Debian/Ubuntu's externally-managed-environment / PEP 668 trap by installing the plugin into Hermes' own Python environment, then enables the plugin, runs setup, and prints doctor checks.

Manual install is still fine if you already know where Hermes' Python environment 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 doctor

If pip install hermes-plugin-clawrouter shows externally-managed-environment, do not use --break-system-packages. Use the installer above, or run pip from Hermes' venv as shown. If hermes says ~/.hermes/hermes-agent/venv/bin/hermes: No such file or directory, reinstall/repair Hermes first, then rerun the ClawRouter installer.

setup 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 can show the provider and curated BlockRun chat models.

Upgrading is just pip install -U. The materialized plugin is stamped with the version that wrote it, so the next Hermes start notices an older stamp and rewrites the plugin in place — no setup --force needed to pick up newly added models. (Before 0.3.16 that refresh never happened, which is why a plain upgrade could leave you on an old model list.)

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

hermes-clawrouter is provided because some Hermes releases do not add plugin-defined top-level CLI commands before the plugin is enabled. Once the plugin is loaded, hermes clawrouter <setup|wallet|doctor|route|stats> may also be available.

If hermes-clawrouter --version shows an older version after updating, your shell may be finding an old ~/.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.

Usage

In a Hermes chat:

• Set model to blockrun/auto to use ClawRouter's smart routing.
• /clawrouter wallet — address + USDC balance
• /clawrouter stats — proxy usage stats
• /clawrouter status — proxy health
• /clawrouter route <eco|auto|premium> — switch routing profile

Tools (callable from chat):

• clawrouter_image_generate — 8 image models incl. GPT Image 2, Nano Banana / Pro, Seedream 5 Pro, Grok Imagine, CogView-4
• clawrouter_video_generate — Seedance 1.5/2.0, Grok Imagine, Sora 2
• clawrouter_web_search — Exa-powered

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). To create one:

npx @blockrun/clawrouter setup

Then fund USDC on Base or Solana — $5 covers thousands of requests, non-custodial. The plugin never writes to the wallet.

Headless / CI

Set BLOCKRUN_WALLET_KEY=<0x raw EVM hex> to bypass the mnemonic file (EVM-only — Solana derivation unavailable).

Environment variables

Guides

Troubleshooting and how-to articles for common Hermes provider/vision setups. Each is a standalone problem→solution walkthrough:

How it works

1. hermes starts → the entry-point plugin is loaded → 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 Hermes config/env hints needed by current Hermes provider and gateway model-picker paths.
3. Hermes' providers/__init__.py discovers the materialized directory and registers the 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).

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.

This 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

pip install -e ".[dev]"
pytest

License

MIT. © BlockRun.