### Install and Start ClawRouter

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/anthropic-third-party-harness-changes.md

Use this command to install and start the ClawRouter proxy locally. It automatically generates a wallet upon execution.

```bash
npx @blockrun/clawrouter    # Install and start (generates wallet automatically)
```

--------------------------------

### Install and Start ClawRouter

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/clawrouter-vs-openrouter-llm-routing-comparison.md

Install ClawRouter globally using npm and start the service. ClawRouter auto-configures OpenClaw on startup.

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

# Start (auto-configures OpenClaw)
clawrouter

# Check your wallet
# /wallet

# View routing stats
# /stats
```

--------------------------------

### Install and Start ClawRouter

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/9-free-ai-models-zero-cost-blockrun.md

Install the ClawRouter globally using npm and then start the local proxy. This is the recommended first step for using free AI models.

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

# Start the local proxy
clawrouter start
```

--------------------------------

### Install and Start ClawRouter

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/9-free-ai-models-zero-cost-blockrun.md

Install the ClawRouter globally using npm and then start the service. Point your application's base_url to the provided local address.

```bash
npm install -g @blockrun/clawrouter
clawrouter start
```

--------------------------------

### Start ClawRouter with npx

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/anthropic-cost-savings.md

Run this command in your terminal to start the ClawRouter proxy and begin saving on Claude API costs immediately. No additional setup is required.

```bash
# Start saving now:
npx @blockrun/clawrouter
```

--------------------------------

### One-Shot Install Script for OpenClaw

Source: https://github.com/blockrunai/clawrouter/blob/main/README.md

Use this script for a complete installation and setup of ClawRouter as an OpenClaw plugin. It handles registration, model configuration, and wallet setup automatically.

```bash
curl -fsSL https://blockrun.ai/ClawRouter-update | bash
openclaw gateway restart
```

--------------------------------

### Run Docker Install Test

Source: https://github.com/blockrunai/clawrouter/blob/main/CLAUDE.md

Tests the Docker installation process.

```bash
npm run test:docker:install
```

--------------------------------

### Install OpenClaw and ClawRouter Plugin

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/subscription-failover.md

Install the OpenClaw gateway and the ClawRouter plugin globally. This is a prerequisite for configuring subscription failover.

```bash
npm install -g openclaw
openclaw plugins install @blockrun/clawrouter
```

--------------------------------

### Start BlockRun Development Server

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-02-28-worker-network.md

Command to start the BlockRun development server locally.

```bash
cd /Users/vickyfu/Documents/blockrun-web/blockrun
npm run dev
```

--------------------------------

### Run Docker Installation Tests

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-02-13-e2e-docker-deployment.md

This command executes the Docker-based installation test suite for ClawRouter.

```bash
./test/run-docker-test.sh
```

--------------------------------

### Clone and Install Project Dependencies

Source: https://github.com/blockrunai/clawrouter/blob/main/CONTRIBUTING.md

Clone the repository and install project dependencies using npm.

```bash
git clone https://github.com/BlockRunAI/ClawRouter
cd ClawRouter
npm install
npm run build
```

--------------------------------

### Install Dependencies

Source: https://github.com/blockrunai/clawrouter/blob/main/CLAUDE.md

Installs project dependencies using npm.

```bash
npm install
```

--------------------------------

### Install and Run ClawRouter

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/anthropic-third-party-harness-changes.md

Use this command to install and run ClawRouter locally. It helps manage AI workflow costs by routing requests to the cheapest suitable model.

```bash
npx @blockrun/clawrouter
```

--------------------------------

### Create Dockerfile for Installation Testing

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-02-13-e2e-docker-deployment.md

Dockerfile used to set up an environment for testing ClawRouter installation. Installs necessary system dependencies, creates a test user, and configures npm.

```dockerfile
FROM node:22-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    jq \
    && rm -rf /var/lib/apt/lists/*

# Create test user
RUN useradd -m -s /bin/bash testuser

# Set up environment
USER testuser
WORKDIR /home/testuser

# Initialize npm config
RUN npm config set prefix ~/.npm-global
ENV PATH="/home/testuser/.npm-global/bin:$PATH"

CMD ["/bin/bash"]
```

--------------------------------

### Install ClawRouter Skill

Source: https://github.com/blockrunai/clawrouter/blob/main/skills/clawrouter/SKILL.md

Installs the auditable npm package @blockrun/clawrouter using the OpenClaw CLI.

```bash
openclaw plugins install @blockrun/clawrouter
```

--------------------------------

### HTTP Request Example

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/architecture.md

Example of a POST request to the /v1/chat/completions endpoint with streaming enabled.

```http
POST /v1/chat/completions
{
  "model": "blockrun/auto",
  "messages": [{ "role": "user", "content": "What is 2+2?" }],
  "stream": true
}
```

--------------------------------

### End-to-End Test: Starting BlockRun and Verifying Tasks

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/worker-network.md

Instructions for starting the BlockRun application locally and testing the tasks endpoint using curl.

```bash
# 1. Start BlockRun locally
cd /Users/vickyfu/Documents/blockrun-web/blockrun
pnpm dev

# 2. Verify tasks endpoint
curl "http://localhost:3000/api/v1/worker/tasks?address=0x0000000000000000000000000000000000000001"
# → JSON array with 3 tasks
```

--------------------------------

### Clone ClawRouter Repository and Install Dependencies

Source: https://github.com/blockrunai/clawrouter/blob/main/README.md

This snippet shows the basic steps to clone the ClawRouter repository from GitHub, navigate into the directory, install npm dependencies, build the project, and run tests.

```bash
git clone https://github.com/BlockRunAI/ClawRouter.git
cd ClawRouter
npm install
npm run build
npm test
```

--------------------------------

### Run in Watch Mode

Source: https://github.com/blockrunai/clawrouter/blob/main/CLAUDE.md

Starts the project in watch mode for development.

```bash
npm run dev
```

--------------------------------

### ClawRouter Doctor Diagnostic Output Example

Source: https://github.com/blockrunai/clawrouter/blob/main/README.md

This is an example of the output from the ClawRouter doctor command, showing system, wallet, and network status, along with AI analysis for troubleshooting.

```text
🩺 BlockRun Doctor v0.12.24

System
  ✓ OS: darwin arm64
  ✓ Node: v22.14.0

Wallet
  ✓ Address: 0x1234...abcd
  ✓ Balance: $12.50

Network
  ✓ BlockRun API: reachable (142ms)
  ✗ Local proxy: not running on :8402

📤 Sending to Claude Sonnet 4.6 (~$0.003)...

🤖 AI Analysis:
The local proxy isn't running. Run `openclaw gateway restart` to fix.
```

--------------------------------

### Automatic Tier Routing Example

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/clawrouter-cuts-llm-api-costs-500x.md

This example demonstrates how ClawRouter classifies requests to different LLM tiers based on task complexity and cost. It shows routing for simple heartbeats to a cheaper model, complex code reviews to a mid-tier model, and reasoning tasks to a high-tier model.

```text
heartbeat status check     →  SIMPLE   →  gemini-2.5-flash      (~0.04¢ / request)
code review, refactor      →  COMPLEX  →  claude-sonnet-4-6      (~5¢ / request)
formal proof, reasoning    →  REASONING →  o3 / claude-opus      (~30¢ / request)
```

--------------------------------

### Manual Deployment Steps

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-02-13-e2e-docker-deployment.md

Steps for manually deploying the project, including version updates, building, committing, tagging, publishing, and creating GitHub releases.

```bash
# 1. Update version
npm version patch  # or minor, or major

# 2. Update src/version.ts
echo 'export const VERSION = "0.8.31";' > src/version.ts

# 3. Build
npm run build

# 4. Commit
git add package.json package-lock.json src/version.ts
git commit -m "0.8.31"
git tag -a v0.8.31 -m "Release v0.8.31"

# 5. Publish
npm publish --access public

# 6. Push
git push origin main
git push origin v0.8.31

# 7. Create GitHub release
gh release create v0.8.31 --title "v0.8.31" --generate-notes
```

--------------------------------

### Setup Smart Routing

Source: https://github.com/blockrunai/clawrouter/blob/main/skills/clawrouter/SKILL.md

Enables smart routing to automatically select the cheapest model per request.

```bash
# Enable smart routing (auto-picks cheapest model per request)
openclaw models set blockrun/auto
```

--------------------------------

### NPM Install for OpenClaw

Source: https://github.com/blockrunai/clawrouter/blob/main/README.md

Install ClawRouter via npm for OpenClaw integration. Ensure you run the setup command to complete the integration, which registers the plugin and configures models.

```bash
npm install -g @blockrun/clawrouter
clawrouter setup            # finishes OpenClaw integration — REQUIRED
openclaw gateway restart
```

--------------------------------

### LLM Benchmarking Setup and Configuration

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/smart-llm-router-14-dimension-classifier.md

Defines the environment, providers, prompts, and configuration used for benchmarking LLM performance. Includes end-to-end measurement details.

```text
Setup:     ClawRouter v0.12.47 proxy on localhost
           → BlockRun x402 gateway (Base EVM chain)
           → Provider APIs (OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, MiniMax, Z.AI)

Prompts:   3 Python coding tasks (IPv4 validation, LCS algorithm, LRU cache)
           2 requests per model per prompt
Config:    256 max tokens, non-streaming, temperature 0.7
Measured:  End-to-end wall clock time (includes x402 payment verification)
```

--------------------------------

### Automated Deployment Process

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-02-13-e2e-docker-deployment.md

Recommended automated deployment using the 'deploy' script. Includes optional wallet key setup and runs through a series of checks and publishing steps.

```bash
# Set wallet key for E2E tests (optional)
export BLOCKRUN_WALLET_KEY=0x...

# Run deployment script
npm run deploy
```

--------------------------------

### Find /stats GET Handler in src/proxy.ts

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-03-18-error-classification.md

Locate the existing handler for the `/stats` endpoint in `src/proxy.ts`. This code block is the starting point for the modification.

```typescript
if (req.url === "/stats" || req.url?.startsWith("/stats?")) {
  try {
    const url = new URL(req.url, "http://localhost");
    const days = parseInt(url.searchParams.get("days") || "7", 10);
    const stats = await getStats(Math.min(days, 30));

    res.writeHead(200, {
      "Content-Type": "application/json",
      "Cache-Control": "no-cache",
    });
    res.end(JSON.stringify(stats, null, 2));
```

--------------------------------

### Programmatic StartProxy Options

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/configuration.md

Configuration options for the `startProxy` function, including wallet key, port, timeouts, API base, callbacks, and routing configuration overrides.

```typescript
import { startProxy } from "@blockrun/clawrouter";

const proxy = await startProxy({
  walletKey: "0x...",

  // Port configuration
  port: 8402, // Default: 8402 or BLOCKRUN_PROXY_PORT

  // Timeouts
  requestTimeoutMs: 180000, // 3 minutes (covers on-chain tx + LLM response)

  // API base (for testing)
  apiBase: "https://blockrun.ai/api",

  // Callbacks
  onReady: (port) => console.log(`Proxy ready on ${port}`),
  onError: (error) => console.error(error),
  onRouted: (decision) => console.log(decision.model, decision.tier),
  onLowBalance: (info) => console.warn(`Low balance: ${info.balanceUSD}`),
  onInsufficientFunds: (info) => console.error(`Need ${info.requiredUSD}`),
  onPayment: (info) => console.log(`Paid ${info.amount} for ${info.model}`),

  // Routing config overrides
  routingConfig: {
    // See Routing Configuration below
  },
});
```

--------------------------------

### Programmatic Proxy Usage with OpenClaw

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/configuration.md

Use ClawRouter with OpenClaw for managing wallets and payments. This example shows how to start a proxy, send a request to an OpenAI-compatible client, and close the proxy.

```typescript
import { startProxy } from "@blockrun/clawrouter";

const proxy = await startProxy({
  walletKey: process.env.BLOCKRUN_WALLET_KEY!,
  onReady: (port) => console.log(`Proxy on port ${port}`),
  onRouted: (d) => console.log(`${d.model} saved ${(d.savings * 100).toFixed(0)}%`),
});

// Any OpenAI-compatible client works
const res = await fetch(`${proxy.baseUrl}/v1/chat/completions`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "blockrun/auto",
    messages: [{ role: "user", content: "What is 2+2?" }],
  }),
});

await proxy.close();
```

--------------------------------

### Run Router and Proxy Tests

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/configuration.md

Command-line instructions for running various tests. These include router tests, proxy end-to-end smoke tests, and proxy reuse tests, all executable without a wallet.

```bash
# Router tests (no wallet needed)
npx tsx test/e2e.ts

# Proxy end-to-end smoke (mock upstream, no wallet needed)
npm run test:e2e

# Proxy reuse tests
npx tsx test/proxy-reuse.ts
```

--------------------------------

### Direct Router Usage (No Proxy/Payments)

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/configuration.md

Use the router directly without a proxy or payments. This example demonstrates building a pricing map and using the `route` function to get routing decisions.

```typescript
import { route, DEFAULT_ROUTING_CONFIG, BLOCKRUN_MODELS } from "@blockrun/clawrouter";

// Build pricing map
const modelPricing = new Map();
for (const m of BLOCKRUN_MODELS) {
  modelPricing.set(m.id, { inputPrice: m.inputPrice, outputPrice: m.outputPrice });
}

const decision = route("Prove sqrt(2) is irrational", undefined, 4096, {
  config: DEFAULT_ROUTING_CONFIG,
  modelPricing,
});

console.log(decision);
// {
//   model: "deepseek/deepseek-reasoner",
//   tier: "REASONING",
//   confidence: 0.97,
//   method: "rules",
//   savings: 0.994,
//   costEstimate: 0.002,
// }
```

--------------------------------

### Bash Test Script for Docker Deployment

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-02-13-e2e-docker-deployment.md

This script contains multiple test cases to verify the installation, uninstallation, upgrade, and plugin functionality of the @blockrun/clawrouter package in a Dockerized environment. It includes setup for colors and a test runner function.

```bash
#!/bin/bash
set -e

PASS=0
FAIL=0

# Colors
GREEN='\033[0;32m'
RED='\033[0;31m'
NC='\033[0m' # No Color

# Test runner
test_case() {
  local name=$1
  local fn=$2

  echo ""
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo "Test: $name"
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

  if $fn; then
    echo -e "${GREEN}✓ PASS${NC}"
    ((PASS++))
  else
    echo -e "${RED}✗ FAIL${NC}"
    ((FAIL++))
  fi
}

# Test 1: Fresh npm global installation
test_fresh_install() {
  echo "Installing @blockrun/clawrouter globally..."
  npm install -g @blockrun/clawrouter@latest

  echo "Verifying clawrouter command exists..."
  which clawrouter || return 1

  echo "Checking version..."
  clawrouter --version || return 1

  echo "Verifying package is in npm global list..."
  npm list -g @blockrun/clawrouter || return 1

  return 0
}

# Test 2: Uninstall verification
test_uninstall() {
  echo "Uninstalling @blockrun/clawrouter..."
  npm uninstall -g @blockrun/clawrouter

  echo "Verifying clawrouter command is gone..."
  if which clawrouter 2>/dev/null; then
    echo "ERROR: clawrouter command still exists after uninstall"
    return 1
  fi

  echo "Verifying package is not in npm global list..."
  if npm list -g @blockrun/clawrouter 2>/dev/null; then
    echo "ERROR: package still in npm list after uninstall"
    return 1
  fi

  return 0
}

# Test 3: Reinstall after uninstall
test_reinstall() {
  echo "Reinstalling @blockrun/clawrouter..."
  npm install -g @blockrun/clawrouter@latest

  echo "Verifying reinstall works..."
  clawrouter --version || return 1

  return 0
}

# Test 4: Installation as OpenClaw plugin (if OpenClaw available)
test_openclaw_plugin_install() {
  echo "Installing OpenClaw..."
  npm install -g openclaw@latest || {
    echo "OpenClaw not available, skipping test"
    return 0
  }

  echo "Installing ClawRouter as OpenClaw plugin..."
  openclaw plugins install @blockrun/clawrouter || return 1

  echo "Verifying plugin is listed..."
  openclaw plugins list | grep -q "clawrouter" || return 1

  return 0
}

# Test 5: OpenClaw plugin uninstall
test_openclaw_plugin_uninstall() {
  if ! which openclaw 2>/dev/null; then
    echo "OpenClaw not available, skipping test"
    return 0
  fi

  echo "Uninstalling ClawRouter plugin..."
  openclaw plugins uninstall clawrouter || return 1

  echo "Verifying plugin is removed..."
  if openclaw plugins list 2>/dev/null | grep -q "clawrouter"; then
    echo "ERROR: plugin still listed after uninstall"
    return 1
  fi

  return 0
}

# Test 6: Upgrade from previous version
test_upgrade() {
  echo "Installing older version (0.8.25)..."
  npm install -g @blockrun/clawrouter@0.8.25

  echo "Verifying old version..."
  local old_version=$(clawrouter --version)
  echo "Installed: $old_version"

  echo "Upgrading to latest..."
  npm install -g @blockrun/clawrouter@latest

  echo "Verifying upgrade..."
  local new_version=$(clawrouter --version)
  echo "Upgraded to: $new_version"

  if [ "$old_version" = "$new_version" ]; then
    echo "ERROR: version did not change after upgrade"
    return 1
  fi

  return 0
}

# Test 7: Installation with custom wallet key
test_custom_wallet() {
  echo "Setting custom wallet key..."
  export BLOCKRUN_WALLET_KEY="0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"

  echo "Installing with wallet key..."
  npm install -g @blockrun/clawrouter@latest

  echo "Verifying installation..."
  clawrouter --version || return 1

  unset BLOCKRUN_WALLET_KEY
  return 0
}

# Test 8: Verify package files exist
test_package_files() {
  echo "Installing @blockrun/clawrouter..."
  npm install -g @blockrun/clawrouter@latest

  echo "Finding package installation directory..."
  local pkg_dir=$(npm root -g)/@blockrun/clawrouter

  echo "Checking for required files..."
  [ -f "$pkg_dir/dist/index.js" ] || { echo "Missing dist/index.js"; return 1; }
  [ -f "$pkg_dir/dist/cli.js" ] || { echo "Missing dist/cli.js"; return 1; }
  [ -f "$pkg_dir/package.json" ] || { echo "Missing package.json"; return 1; }
  [ -f "$pkg_dir/openclaw.plugin.json" ] || { echo "Missing openclaw.plugin.json"; return 1; }

  echo "All required files present"
  return 0
}

# Test 9: Version command accuracy
test_version_command() {
  echo "Installing @blockrun/clawrouter..."
  npm install -g @blockrun/clawrouter@latest

  echo "Running version command..."
  local cli_version=$(clawrouter --version)

  echo "Reading package.json version..."
  local pkg_dir=$(npm root -g)/@blockrun/clawrouter
  local pkg_version=$(node -p "require('$pkg_dir/package.json').version")

  echo "CLI version: $cli_version"
  echo "Package version: $pkg_version"

  if [ "$cli_version" != "$pkg_version" ]; then
    echo "ERROR: version mismatch"
    return 1
  fi

  return 0
}

```

--------------------------------

### Install ClawRouter with Smart Routing

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/clawrouter-cuts-llm-api-costs-500x.md

Install ClawRouter using curl and enable smart routing. This command automatically updates your OpenClaw installation and restarts the gateway.

```bash
curl -fsSL https://blockrun.ai/ClawRouter-update | bash
openclaw gateway restart
```

--------------------------------

### Smart Routing Examples

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/anthropic-cost-savings.md

Illustrates how ClawRouter routes prompts to different models based on complexity and reasoning requirements, prioritizing free or cheaper options.

```text
"What is the capital of France?"
  → SIMPLE → nvidia/gpt-oss-120b (FREE)

"Extract JSON from this text"
  → SIMPLE → nvidia/gpt-oss-120b (FREE)

"Refactor this auth module with OAuth2 + PKCE"
  → COMPLEX → anthropic/claude-sonnet-4.6 ($3/$15)

"Prove sqrt(2) is irrational, show every step"
  → REASONING → xai/grok-4-1-fast-reasoning ($0.20/$0.50)
```

--------------------------------

### Build Project

Source: https://github.com/blockrunai/clawrouter/blob/main/CLAUDE.md

Compiles the project using tsup.

```bash
npm run build
```

--------------------------------

### Build Project with Bun

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-03-18-error-classification.md

Executes the build command for the project using Bun and displays the last 5 lines of the output. Use this to verify compilation after code changes.

```bash
cd /Users/vickyfu/Documents/blockrun-web/ClawRouter && bun run build 2>&1 | tail -5
```

--------------------------------

### OpenAI SDK Python Example

Source: https://github.com/blockrunai/clawrouter/blob/main/README.md

Use the OpenAI Python SDK to interact with ClawRouter. Initialize the client with the local base URL and API key, then create chat completions.

```python
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8402", api_key="x402")
response = client.chat.completions.create(model="blockrun/auto", messages=[...])
```

--------------------------------

### Install ClawRouter

Source: https://github.com/blockrunai/clawrouter/blob/main/README.md

Installs the ClawRouter update script. This is used to manage updates for the ClawRouter LLM router.

```bash
curl -fsSL https://blockrun.ai/ClawRouter-update | bash
```

--------------------------------

### Run Full Test Suite

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-03-19-exclude-models.md

Command to execute all tests within the project.

```bash
npx vitest run
```

--------------------------------

### Image Generation Response Example

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/image-generation.md

Example JSON response when an image is successfully generated, containing a URL to the created image.

```json
{
  "created": 1741460000,
  "data": [
    {
      "url": "https://files.catbox.moe/abc123.png"
    }
  ]
}
```

--------------------------------

### Payment Flow Example

Source: https://github.com/blockrunai/clawrouter/blob/main/README.md

Illustrates the payment authentication process using x402, including the price and the non-custodial nature of USDC.

```text
Request → 402 (price: $0.003) → wallet signs USDC → retry → response
```

--------------------------------

### Commit Docker Installation Tests

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-02-13-e2e-docker-deployment.md

This command stages and commits the newly added Docker installation test files to the git repository.

```bash
git add test/Dockerfile.install-test test/docker-install-tests.sh test/run-docker-test.sh
git commit -m "test: add Docker-based installation testing (10 test cases)

Test coverage:
- Fresh npm global installation
- Uninstall verification
- Reinstall after uninstall
- OpenClaw plugin install/uninstall
- Upgrade from previous version
- Custom wallet key installation
- Package files verification
- Version command accuracy
- Full cleanup verification

Validates installation, upgrade, uninstall workflows in isolated Docker
environment."
```

--------------------------------

### Start ClawRouter Worker

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/worker-network.md

Execute this command to start ClawRouter in worker mode, pointing it to the local API base. Ensure you are in the ClawRouter directory.

```bash
CLAWROUTER_WORKER=1 BLOCKRUN_API_BASE=http://localhost:3000/api npx openclaw gateway start
```

--------------------------------

### Wallet and Command-Line Interface Commands

Source: https://github.com/blockrunai/clawrouter/blob/main/README.md

Provides a list of essential CLI commands for managing the wallet, checking balances, exporting/recovering keys, switching chains, viewing statistics, and managing model exclusions.

```bash
/wallet              # Check balance and address (both chains)
/wallet export       # Export mnemonic + keys for backup
/wallet recover      # Restore wallet from mnemonic on a new machine
/wallet solana       # Switch to Solana USDC payments
/wallet base         # Switch back to Base (EVM) USDC payments
/chain solana        # Alias for /wallet solana
/stats               # View usage and savings
/stats clear         # Reset usage statistics
/exclude             # Show excluded models
/exclude add <model> # Block a model from routing (aliases work: "grok-4", "free")
/exclude remove <model> # Unblock a model
/exclude clear       # Remove all exclusions
```

--------------------------------

### Create Deployment Script

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-02-13-e2e-docker-deployment.md

This bash script outlines the initial steps for the ClawRouter deployment pipeline, including setting up color codes for output and checking for a clean git working directory.

```bash
#!/bin/bash
set -e

# Colors
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
RED='\033[0;31m'
NC='\033[0m' # No Color

echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo -e "${GREEN}  ClawRouter Deployment Pipeline${NC}"
echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"

# Step 1: Check git status (must be clean)
echo ""
echo -e "${YELLOW}1. Checking git status...${NC}"
if [[ -n $(git status --porcelain) ]]; then
  echo -e "${RED}ERROR: Working directory is not clean. Commit or stash changes first.${NC}"
  exit 1
fi
echo "✓ Working directory is clean"

```

--------------------------------

### ClawRouter Architecture Overview

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-02-03-smart-routing-design.md

Illustrates the multi-step process of the ClawRouter, from initial scoring to final model selection and routing.

```text
OpenClaw Agent
     |
     v
┌─────────────────────────────────────────────────┐
│              ClawRouter (src/router/)             │
│                                                   │
│  ┌─────────────────────────────────────────────┐ │
│  │  Step 1: Weighted Scoring Engine (< 1ms)    │ │
│  │  • 14 scoring dimensions, each [-1, 1]      │ │
│  │  • Weighted sum → float score               │ │
│  │  • Sigmoid confidence calibration           │ │
│  │  • Returns: tier or null (ambiguous)        │ │
│  └─────────────────────┬───────────────────────┘ │
│                        |                          │
│          ┌─────────────┴──────────────┐          │
│          |                            |           │
│     confident                    ambiguous        │
│   (conf >= 0.70)              (conf < 0.70)       │
│          |                            |           │
│          |  ┌─────────────────────────┴────────┐ │
│          |  │  Step 2: LLM Classifier (~200ms) │ │
│          |  │  • Send to gemini-flash (cheapest)│ │
│          |  │  • "Classify: SIMPLE/MEDIUM/..."  │ │
│          |  │  • Cache classification result    │ │
│          |  └─────────────────────────┬────────┘ │
│          |                            |           │
│          └────────────┬───────────────┘           │
│                       |                           │
│  ┌────────────────────┴────────────────────────┐ │
│  │  Step 3: Tier → Model Selection             │ │
│  │  • Look up cheapest model for tier          │ │
│  │  • Calculate cost estimate + savings        │ │
│  └────────────────────┬────────────────────────┘ │
│                       |                           │
│  ┌────────────────────┴────────────────────────┐ │
│  │  Step 4: RoutingDecision metadata           │ │
│  │  { model, tier, confidence, reasoning }     │ │
│  └────────────────────┬────────────────────────┘ │
│                       |                           │
└───────────────────────┼─────────────────────────┘
                        |
                        v
               BlockRun API (x402)
                        |
                        v
                  LLM Provider

```

--------------------------------

### Start ClawRouter in Worker Mode

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-02-28-worker-network.md

Execute this command in the ClawRouter directory to start the worker. Ensure BLOCKRUN_API_BASE is set to your local API endpoint.

```bash
cd /Users/vickyfu/Documents/blockrun-web/ClawRouter
CLAWROUTER_WORKER=1 BLOCKRUN_API_BASE=http://localhost:3000/api npx openclaw gateway start
```

--------------------------------

### Build Final Project

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-03-18-error-classification.md

Command to build the project for production using Bun.

```bash
cd /Users/vickyfu/Documents/blockrun-web/ClawRouter && bun run build 2>&1
```

--------------------------------

### Install ClawRouter-Hermes Plugin

Source: https://github.com/blockrunai/clawrouter/blob/main/README.md

Installs the ClawRouter Python plugin for Hermes agents. This plugin integrates ClawRouter's routing and payment features with the hermes-agent framework.

```bash
pip install hermes-plugin-clawrouter
```

--------------------------------

### Example /stats JSON Response with Provider Errors

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-03-18-error-classification.md

This is an example of the augmented JSON response from the `/stats` endpoint, now including the `providerErrors` field which details error counts for each provider.

```json
{
  "providerErrors": {
    "openai/gpt-4o": {
      "auth_failure": 0,
      "rate_limited": 2,
      "overloaded": 1,
      "server_error": 0,
      "payment_error": 0,
      "config_error": 0,
      "quota_exceeded": 0
    },
    "anthropic/claude-3-7-sonnet": {
      "auth_failure": 1,
      "rate_limited": 0,
      "overloaded": 0,
      "server_error": 3,
      "payment_error": 0,
      "config_error": 0,
      "quota_exceeded": 0
    }
  }
}
```

--------------------------------

### Install BRCC (BlockRun for Claude Code)

Source: https://github.com/blockrunai/clawrouter/blob/main/README.md

Installs the BlockRun for Claude Code (BRCC) tool. This enables running Claude Code with various models without rate limits or Anthropic accounts.

```bash
curl -fsSL https://blockrun.ai/brcc-install | bash
```

--------------------------------

### Check ClawRouter Version and Status

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/troubleshooting.md

Use these commands to verify your ClawRouter installation and ensure the proxy is running. Check the wallet for EVM and Solana addresses and balances. Monitor logs for routing activity and view cost savings.

```bash
cat ~/.openclaw/extensions/clawrouter/package.json | grep version
```

```bash
curl http://localhost:8402/health
```

```bash
/wallet
```

```bash
openclaw logs --follow
```

```bash
/stats
```

--------------------------------

### Update run-docker-test.sh for Installation Tests

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-02-13-e2e-docker-deployment.md

This bash script configures the Docker build and run commands to execute the ClawRouter installation tests within a Docker container. It copies the test script into the container and executes it.

```bash
#!/bin/bash
set -e

cd "$(dirname "$0")"..

echo "🐳 Building Docker test environment for installation tests..."
docker build -f test/Dockerfile.install-test -t clawrouter-install-test .

echo ""
echo "🧪 Running installation test suite (10 test cases)..."
docker run --rm \
    -v "$(pwd)/test/docker-install-tests.sh:/test.sh:ro" \
    clawrouter-install-test \
    bash -c "cp /test.sh /tmp/test.sh && chmod +x /tmp/test.sh && /tmp/test.sh"

echo ""
echo "✅ Docker installation tests completed successfully!"

```

--------------------------------

### ClawRouter Request Routing Example

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/anthropic-third-party-harness-changes.md

Illustrates how ClawRouter directs different types of agent requests to appropriate LLM models based on complexity and cost. This helps visualize the smart routing strategy.

```text
Your Agent → ClawRouter (localhost:8402) → Best model for the job

SIMPLE  ("what is X?")          → Free model         $0.00
MEDIUM  ("review this code")    → Kimi-K2.5           $0.002
COMPLEX ("refactor this OAuth") → Claude Sonnet 4.6   $0.009
REASONING ("prove this theorem")→ Grok-4-Reasoning    $0.001
```

--------------------------------

### Get Matching Markets

Source: https://github.com/blockrunai/clawrouter/blob/main/skills/predexon/SKILL.md

Retrieves a list of matching markets.

```APIDOC
## GET /v1/pm/matching-markets

### Description
Retrieves a list of matching markets.

### Method
GET

### Endpoint
/v1/pm/matching-markets

### Parameters
#### Query Parameters
- **limit** (integer) - Description not provided
- **offset** (integer) - Description not provided
```

--------------------------------

### Request and Response Caching Example

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/anthropic-cost-savings.md

Demonstrates how ClawRouter caches responses, providing instant, zero-cost results for identical requests within a 10-minute window.

```text
Request 1: "Summarize this document" → API call → $0.02 → cached
Request 2: "Summarize this document" → cache hit → $0.00 → instant
Request 3: "Summarize this document" → cache hit → $0.00 → instant
```

--------------------------------

### Get dFlow Trades

Source: https://github.com/blockrunai/clawrouter/blob/main/skills/predexon/SKILL.md

Retrieves a list of dFlow trades.

```APIDOC
## GET /v1/pm/dflow/trades

### Description
Retrieves a list of dFlow trades.

### Method
GET

### Endpoint
/v1/pm/dflow/trades

### Parameters
#### Query Parameters
- **wallet** (string) - Description not provided
- **limit** (integer) - Description not provided
```

--------------------------------

### Get Predict.Fun Markets

Source: https://github.com/blockrunai/clawrouter/blob/main/skills/predexon/SKILL.md

Retrieves a list of Predict.Fun markets.

```APIDOC
## GET /v1/pm/predictfun/markets

### Description
Retrieves a list of Predict.Fun markets.

### Method
GET

### Endpoint
/v1/pm/predictfun/markets

### Parameters
#### Query Parameters
- **search** (string) - Description not provided
- **limit** (integer) - Description not provided
- **offset** (integer) - Description not provided
- **status** (string) - Description not provided
```

--------------------------------

### Programmatic Image Generation with startProxy (TypeScript)

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/image-generation.md

Use the startProxy function to programmatically interact with ClawRouter. This example generates an image using DALL-E 3.

```typescript
import { startProxy } from "@blockrun/clawrouter";

const proxy = await startProxy({ walletKey: process.env.BLOCKRUN_WALLET_KEY! });

const response = await fetch(`${proxy.baseUrl}/v1/images/generations`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "openai/dall-e-3",
    prompt: "a serene Japanese garden in autumn",
    size: "1792x1024",
    n: 1,
  }),
});

const { data } = await response.json();
console.log(data[0].url);

await proxy.close();
```

--------------------------------

### Get Opinion Markets

Source: https://github.com/blockrunai/clawrouter/blob/main/skills/predexon/SKILL.md

Retrieves a list of Opinion markets.

```APIDOC
## GET /v1/pm/opinion/markets

### Description
Retrieves a list of Opinion markets.

### Method
GET

### Endpoint
/v1/pm/opinion/markets

### Parameters
#### Query Parameters
- **search** (string) - Description not provided
- **limit** (integer) - Description not provided
- **offset** (integer) - Description not provided
- **status** (string) - Description not provided
```

--------------------------------

### Get Limitless Markets

Source: https://github.com/blockrunai/clawrouter/blob/main/skills/predexon/SKILL.md

Retrieves a list of Limitless markets.

```APIDOC
## GET /v1/pm/limitless/markets

### Description
Retrieves a list of Limitless markets.

### Method
GET

### Endpoint
/v1/pm/limitless/markets

### Parameters
#### Query Parameters
- **search** (string) - Description not provided
- **limit** (integer) - Description not provided
- **offset** (integer) - Description not provided
- **status** (string) - Description not provided
```

--------------------------------

### Run Full Test Suite

Source: https://github.com/blockrunai/clawrouter/blob/main/docs/plans/2026-03-18-error-classification.md

Command to execute the entire test suite and display the last 20 lines of output, ensuring all tests pass after the version bump.

```bash
cd /Users/vickyfu/Documents/blockrun-web/ClawRouter && bun test 2>&1 | tail -20
```

--------------------------------

### Get Kalshi Trades

Source: https://github.com/blockrunai/clawrouter/blob/main/skills/predexon/SKILL.md

Retrieves a list of Kalshi trades.

```APIDOC
## GET /v1/pm/kalshi/trades

### Description
Retrieves a list of Kalshi trades.

### Method
GET

### Endpoint
/v1/pm/kalshi/trades

### Parameters
#### Query Parameters
- **limit** (integer) - Description not provided
```

--------------------------------

### Get Kalshi Markets

Source: https://github.com/blockrunai/clawrouter/blob/main/skills/predexon/SKILL.md

Retrieves a list of Kalshi markets.

```APIDOC
## GET /v1/pm/kalshi/markets

### Description
Retrieves a list of Kalshi markets.

### Method
GET

### Endpoint
/v1/pm/kalshi/markets

### Parameters
#### Query Parameters
- **search** (string) - Description not provided
- **limit** (integer) - Description not provided
```