---
name: clawrouter
description: Install, configure, and manage ClawRouter as a local LLM proxy for Hermes Agent. Routes AI requests across 55+ models via USDC payments on Base/Solana. Use when setting up ClawRouter, checking wallet status, updating versions, or configuring Hermes to use blockrun provider.
version: 1.0.0
---

# ClawRouter Local LLM Proxy

Agent-native LLM router that runs as a local proxy on port 8402. Analyzes requests across 15 dimensions and routes to the most cost-effective model. Uses USDC on Base or Solana via x402 protocol.

## Installation

### Fresh Install
```bash
npm install -g @blockrun/clawrouter
```

### Update (DO NOT use the curl script — it hangs/timeout prone)
```bash
npm install -g @blockrun/clawrouter
```

**IMPORTANT:** The `curl -fsSL https://blockrun.ai/ClawRouter-update | bash` script frequently times out and BLOCKS. Always use `npm install -g` instead.

### Version Conflict Resolution
- Old OpenClaw install lives at `/usr/bin/clawrouter` (symlinked from `/usr/lib/node_modules/`)
- New npm global installs go to `~/.local/lib/node_modules/@blockrun/clawrouter/`
- Binary at `~/.local/bin/clawrouter` (in PATH)
- Check which version you're running with `/usr/bin/clawrouter --version` vs `~/.local/bin/clawrouter --version`
- If `/usr/bin/clawrouter` is stale, update the symlink:
  ```bash
  rm /usr/bin/clawrouter
  ln -s ~/.local/lib/node_modules/@blockrun/clawrouter/dist/cli.js /usr/bin/clawrouter
  ```

## Starting the Proxy

```bash
mkdir -p ~/.hermes/logs
nohup ~/.local/lib/node_modules/@blockrun/clawrouter/dist/cli.js </dev/null > ~/.hermes/logs/clawrouter.log 2>&1 &
```

**CRITICAL:** Use `</dev/null` to prevent the process from blocking on stdin. Without it, the process hangs.

## Checking Status

```bash
# Health check (returns wallet address and payment chain)
curl -s http://127.0.0.1:8402/health

# Get all available models
curl -s http://127.0.0.1:8402/v1/models | head -c 200

# Via CLI (only works when proxy is running)
npx @blockrun/clawrouter status
npx @blockrun/clawrouter wallet
```

## Stopping

```bash
pkill -f clawrouter
```

## Wallet

Wallet key stored at: `~/.openclaw/blockrun/wallet.key` (legacy OpenClaw path, still used by ClawRouter)

Address is printed on startup in logs or via health endpoint.

## Hermes Integration

Hermes has two supported custom-provider shapes. Prefer the newer keyed `providers` shape when present in the user's config; older installs may still use `custom_providers`.

### Newer Hermes config shape (`providers`)

Add or fix this entry in `~/.hermes/config.yaml`:
```yaml
providers:
  blockrun:
    name: blockrun
    api: http://127.0.0.1:8402/v1
    transport: chat_completions
    default_model: blockrun/auto
    models:
      blockrun/auto: {}
      blockrun/eco: {}
      blockrun/premium: {}
```

The `models` map matters for the `hermes model` picker: if `blockrun` exists but has no model list, the provider may be configured but not visibly useful in the picker. If you find `default_model: gpt-5.5` under `providers.blockrun`, replace it with `blockrun/auto`.

### Legacy config shape (`custom_providers`)

Use this only if the config already uses `custom_providers` or the newer `providers` key is absent:
```yaml
custom_providers:
- api_key: ''
  api_mode: chat_completions
  base_url: http://127.0.0.1:8402/v1
  name: blockrun
  model: blockrun/auto
  models:
    blockrun/auto: {}
    blockrun/eco: {}
    blockrun/premium: {}
```

To make ClawRouter the default model:
```yaml
model:
  default: blockrun/auto    # auto-routes based on task complexity
  provider: blockrun
```

Or use specific profiles:
- `blockrun/auto` — balanced routing (default)
- `blockrun/eco` — cheapest possible models
- `blockrun/premium` — highest quality models

### Verification checklist

1. Read `~/.hermes/config.yaml` and confirm `providers.blockrun.models` contains `blockrun/auto`, `blockrun/eco`, and `blockrun/premium`.
2. Confirm the proxy is reachable: `curl -s http://127.0.0.1:8402/health`.
3. Confirm model discovery: `curl -s http://127.0.0.1:8402/v1/models`.
4. Run `hermes model` and verify the `blockrun` provider shows usable model entries.

If a safety approval blocks proxy/status commands, stop and report the already-discovered config issue rather than trying alternate ways to reach the same blocked outcome.

## Available Models

- `blockrun/auto`, `blockrun/eco`, `blockrun/premium` — smart routing
- `free/*` — 11 free models (GPT-OSS, Nemotron, DeepSeek V3.2, Mistral, Qwen Coder, GLM, Llama, Devstral)
- `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-6`, etc.
- `openai/gpt-5.3-codex`, `openai/gpt-5.4`, `openai/o3`, etc.
- `google/gemini-2.5-pro`, `google/gemini-3.1-pro`, etc.
- `xai/grok-4`, `deepseek/deepseek-chat`, `moonshot/kimi-k2.5`

## systemd Service (Recommended for persistent ClawRouter)

For long-lived ClawRouter on Ignacio's Ubuntu server, prefer a systemd service over shell-level `nohup`/`&` wrappers. Hermes terminal sessions reject or poorly track shell-managed daemons; systemd gives restart and logs.

```ini
[Unit]
Description=ClawRouter LLM Proxy
After=network.target

[Service]
Type=simple
User=ubuntu
Environment=HOME=/home/ubuntu
WorkingDirectory=/home/ubuntu
ExecStart=/home/ubuntu/.local/lib/node_modules/@blockrun/clawrouter/dist/cli.js
Restart=always
RestartSec=5
StandardInput=null
StandardOutput=append:/home/ubuntu/.hermes/logs/clawrouter.log
StandardError=append:/home/ubuntu/.hermes/logs/clawrouter.log

[Install]
WantedBy=multi-user.target
```

Note: StandardInput=null is equivalent to </dev/null — prevents stdin blocking. If `systemctl --user` fails with `No medium found`, install a system service with `User=ubuntu` instead.

## Delegateable UI/design specialist profile

For recurring UI work, create a dedicated Hermes profile and wrapper that use ClawRouter's `anthropic/claude-sonnet-4.6` without changing the default assistant. See `references/ui-designer-profile.md` for exact config, systemd service, wrapper script, and smoke test.

## Pitfalls

- **curl update script hangs**: Use `npm install -g` always
- **Process blocks on stdin**: Must redirect with `</dev/null` or set `StandardInput=null`
- **Hermes terminal daemon tracking**: Do not start persistent ClawRouter via shell-level `nohup ... &` inside a foreground terminal command. Use systemd for persistence or `terminal(background=true)` for a temporary process.
- **Version mismatch**: `/usr/bin/clawrouter` may be from old OpenClaw install — check `~/.local/bin/clawrouter` for the updated version
- **Model picker missing Blockrun models**: `providers.blockrun.default_model` alone may not make `hermes model` useful. Add `discover_models: true` plus a `models:` map containing `auto`, `eco`, `premium`, and important vendor models such as `anthropic/claude-sonnet-4.6`.
- **Router profile IDs**: The live ClawRouter endpoint may expose router profiles as `auto`, `eco`, and `premium` rather than `blockrun/auto`, `blockrun/eco`, `blockrun/premium`. Check `/v1/models` before writing model IDs.
- **Wallet shows $0**: May be stale data from old process. Kill and restart the proxy. If still $0, verify on-chain balance at basescan.org for the wallet address.
- **Log permission errors**: Don't log to `/var/log/` as non-root user — use `~/.hermes/logs/`