@blockrun/clawrouter 0.12.62 → 0.12.63

package/docs/troubleshooting.md

@@ -0,0 +1,159 @@
+# Troubleshooting
+
+Quick solutions for common ClawRouter issues.
+
+> Need help? [Open a Discussion](https://github.com/BlockRunAI/ClawRouter/discussions) or check [existing issues](https://github.com/BlockRunAI/ClawRouter/issues).
+
+## Table of Contents
+
+- [Quick Checklist](#quick-checklist)
+- [Common Errors](#common-errors)
+- [Security Scanner Warnings](#security-scanner-warnings)
+- [Port Conflicts](#port-conflicts)
+- [How to Update](#how-to-update)
+- [Verify Routing](#verify-routing)
+
+---
+
+## Quick Checklist
+
+```bash
+# 1. Check your version (should be 0.12+)
+cat ~/.openclaw/extensions/clawrouter/package.json | grep version
+
+# 2. Check proxy is running
+curl http://localhost:8402/health
+
+# 3. Check wallet (both EVM + Solana addresses and balance)
+/wallet
+
+# 4. Watch routing in action
+openclaw logs --follow
+# Should see: kimi-k2.5 $0.0012 (saved 99%)
+
+# 5. View cost savings
+/stats
+```
+
+---
+
+## Common Errors
+
+### "Unknown model: blockrun/auto" or "Unknown model: auto"
+
+Plugin isn't loaded or outdated. **Don't change the model name** — `blockrun/auto` is correct.
+
+**Fix:** Update to v0.3.21+ which handles both `blockrun/auto` and `auto` (OpenClaw strips provider prefix). See [How to Update](#how-to-update).
+
+### "No API key found for provider blockrun"
+
+Auth profile is missing or wasn't created properly.
+
+**Fix:** See [How to Update](#how-to-update) — the reinstall script automatically injects the auth profile.
+
+### "Config validation failed: plugin not found: clawrouter"
+
+Plugin directory was removed but config still references it. This blocks all OpenClaw commands until fixed.
+
+**Fix:** See [How to Update](#how-to-update) for complete cleanup steps.
+
+### "No USDC balance" / "Insufficient funds"
+
+Wallet needs funding. ClawRouter accepts **USDC** (not SOL or ETH) on either chain.
+
+**Fix:**
+
+1. Find your wallet address: run `/wallet` in any OpenClaw conversation
+2. Choose your preferred chain and send **USDC** to that address:
+   - **Base (EVM):** Send USDC on Base network to your EVM address (`0x...`)
+   - **Solana:** Send USDC on Solana network to your Solana address (base58)
+3. $1–5 is enough for hundreds of requests
+4. Restart OpenClaw (or wait up to 60s for balance cache to refresh)
+
+---
+
+## Security Scanner Warnings
+
+### "WARNING: dangerous code patterns — possible credential harvesting"
+
+This is a **false positive**. ClawRouter legitimately:
+
+1. Reads `BLOCKRUN_WALLET_KEY` from environment (for authentication)
+2. Sends authenticated requests to BlockRun API (for x402 micropayments)
+
+This pattern triggers OpenClaw's security scanner, but it's the intended behavior — the wallet key is required to sign payment transactions. The code is fully open source and auditable.
+
+### "env-harvesting" Warning
+
+OpenClaw's security scanner may flag ClawRouter with:
+
+```
+[env-harvesting] Environment variable access combined with network send
+```
+
+**This is a false positive.** The scanner's heuristic (`env variable + network request = suspicious`) flags all payment plugins, but this pattern is inherently required for non-custodial payments.
+
+ClawRouter reads `BLOCKRUN_WALLET_KEY` to sign x402 payment transactions — this is required and intentional:
+
+- The wallet key is used **locally** for cryptographic signing (EIP-712)
+- The **signature** is transmitted, not the private key itself
+- The key **never leaves the machine** — only cryptographic proofs are sent
+- This is standard [x402 payment protocol](https://x402.org) behavior
+- Source code is [MIT licensed and fully auditable](https://github.com/BlockRunAI/ClawRouter)
+
+See [`openclaw.security.json`](../openclaw.security.json) for detailed security documentation and [this discussion](https://x.com/bc1beat/status/2020158972561428686) for more context.
+
+---
+
+## Port Conflicts
+
+### Port 8402 already in use
+
+As of v0.4.1, ClawRouter automatically detects and reuses an existing proxy on the configured port instead of failing with `EADDRINUSE`. You should no longer see this error.
+
+If you need to use a different port:
+
+```bash
+# Set custom port via environment variable
+export BLOCKRUN_PROXY_PORT=8403
+openclaw gateway restart
+```
+
+To manually check/kill the process:
+
+```bash
+lsof -i :8402
+# Kill the process or restart OpenClaw
+```
+
+---
+
+## How to Update
+
+```bash
+npx @blockrun/clawrouter@latest
+openclaw gateway restart
+```
+
+This installs the latest version and restarts the gateway. Alternatively:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/BlockRunAI/ClawRouter/main/scripts/reinstall.sh | bash
+openclaw gateway restart
+```
+
+---
+
+## Verify Routing
+
+```bash
+openclaw logs --follow
+```
+
+You should see model selection for each request:
+
+```
+[plugins] [SIMPLE] google/gemini-2.5-flash $0.0012 (saved 99%)
+[plugins] [MEDIUM] deepseek/deepseek-chat $0.0003 (saved 99%)
+[plugins] [REASONING] deepseek/deepseek-reasoner $0.0005 (saved 99%)
+```

package/docs/vision.md

@@ -0,0 +1,49 @@
+# BlockRun Worker Network — Vision
+
+## The Problem
+
+Every company with a public API — blockchain protocols, AI providers, SaaS businesses — needs to prove to investors, customers, and regulators that their service is reliable. Today, that proof comes from centralized monitoring tools like UptimeRobot or Pingdom. The fundamental flaw: these reports are self-referential. A company can choose which tool monitors them, when to show the data, and how to present it. There is no independent, tamper-proof verification.
+
+Meanwhile, ClawRouter users run AI agents that are idle the vast majority of the time. That idle compute has no economic value today.
+
+## The Vision
+
+Turn ClawRouter's distributed user base into the world's first **decentralized high-availability validation network** — where AI agents earn USDC by doing real verification work, and any company can purchase cryptographically verifiable proof that their service is always on.
+
+The core insight: a health check result signed by 50 independent nodes across 30 countries is fundamentally different from the same check run by a single company's monitoring vendor. It cannot be fabricated. It cannot be cherry-picked. It is, for the first time, **objective proof of uptime**.
+
+## Why This Matters
+
+We are entering a world where AI agents are the primary consumers of APIs. As agents proliferate, the reliability of the infrastructure they depend on becomes critical. A DeFi protocol that goes down at the wrong moment, an AI API that drops requests under load, a SaaS backend that silently fails — these are existential risks for the services built on top of them.
+
+The companies that can prove they never go down will win. BlockRun provides that proof.
+
+## Long-Term Ambition
+
+Start with uptime monitoring. Expand to any verification task that benefits from decentralized, independent execution:
+
+- **Phase 1**: HTTP health checks, latency measurement, SSL/DNS validation
+- **Phase 2**: API contract verification (does the endpoint return what it promises?)
+- **Phase 3**: Full agentic tasks — scheduled jobs, data pipelines, anything a ClawRouter agent can run
+
+The worker network becomes the backbone of a new trust layer for the internet — not maintained by a single company, but by thousands of independent agents earning for their work.
+
+## The Flywheel
+
+```
+More ClawRouter users
+  → More worker nodes → Better geographic coverage
+    → Better product for verification buyers
+      → More revenue → Higher worker earnings
+        → More incentive to run ClawRouter
+          → More ClawRouter users
+```
+
+Each side of the marketplace strengthens the other. ClawRouter users are simultaneously the supply (workers) and a natural demand source (they build services that need monitoring). There is no cold start problem.
+
+## Why BlockRun Wins This
+
+1. **Infrastructure already exists**: x402 micropayments, USDC wallets, distributed user base — all live today
+2. **No new trust required**: Workers are already ClawRouter users who've onboarded with a funded wallet
+3. **Crypto-native from day one**: USDC settlement on Base, x402 protocol — the payment layer is the differentiator
+4. **Partnership leverage**: Built on Coinbase's x402 protocol, natural alignment with Base ecosystem

package/docs/vs-openrouter.md

@@ -0,0 +1,157 @@
+# ClawRouter vs OpenRouter
+
+OpenRouter is a popular LLM routing service. Here's why ClawRouter is built differently — and why it matters for agents.
+
+## TL;DR
+
+**OpenRouter is built for developers. ClawRouter is built for agents.**
+
+| Aspect             | OpenRouter                            | ClawRouter                             |
+| ------------------ | ------------------------------------- | -------------------------------------- |
+| **Setup**          | Human creates account, pastes API key | Agent generates wallet, receives funds |
+| **Authentication** | API key (shared secret)               | Wallet signature (cryptographic)       |
+| **Payment**        | Prepaid balance (custodial)           | Per-request USDC (non-custodial)       |
+| **Routing**        | Server-side, proprietary              | Client-side, open source, <1ms         |
+| **Rate limits**    | Per-key quotas                        | None (your wallet, your limits)        |
+| **Empty balance**  | Request fails                         | Auto-fallback to free tier             |
+
+---
+
+## The Problem with API Keys
+
+OpenRouter (and every traditional LLM gateway) uses API keys for authentication. This breaks agent autonomy:
+
+### 1. Key Leakage in LLM Context
+
+**OpenClaw Issue [#11202](https://github.com/openclaw/openclaw/issues/11202)**: API keys configured in `openclaw.json` are resolved and serialized into every LLM request payload. Every provider sees every other provider's keys.
+
+> "OpenRouter sees your NVIDIA key, Anthropic sees your Google key... keys are sent on every turn."
+
+**ClawRouter**: No API keys. Authentication happens via cryptographic wallet signatures. There's nothing to leak because there are no shared secrets.
+
+### 2. Rate Limit Hell
+
+**OpenClaw Issue [#8615](https://github.com/openclaw/openclaw/issues/8615)**: Single API key support means heavy users hit rate limits (429 errors) quickly. Users request multi-key load balancing, but that's just patching a broken model.
+
+**ClawRouter**: Non-custodial wallets. You control your own keys. No shared rate limits. Scale by funding more wallets if needed.
+
+### 3. Setup Friction
+
+**OpenClaw Issues [#16257](https://github.com/openclaw/openclaw/issues/16257), [#16226](https://github.com/openclaw/openclaw/issues/16226)**: Latest installer skips model selection, shows "No auth configured for provider anthropic". Users can't even get started without debugging config.
+
+**ClawRouter**: One-line install. 30+ models auto-configured. No API keys to paste.
+
+### 4. Model Path Collision
+
+**OpenClaw Issue [#2373](https://github.com/openclaw/openclaw/issues/2373)**: `openrouter/auto` is broken because OpenClaw prefixes all OpenRouter models with `openrouter/`, so the actual model becomes `openrouter/openrouter/auto`.
+
+**ClawRouter**: Clean namespace. `blockrun/auto` just works. No prefix collision.
+
+### 5. False Billing Errors
+
+**OpenClaw Issue [#16237](https://github.com/openclaw/openclaw/issues/16237)**: The regex `/\b402\b/` falsely matches normal content (e.g., "402 calories") as a billing error, replacing valid AI responses with error messages.
+
+**ClawRouter**: Native x402 protocol support. Precise error handling. No regex hacks.
+
+### 6. Unknown Model Failures
+
+**OpenClaw Issues [#16277](https://github.com/openclaw/openclaw/issues/16277), [#10687](https://github.com/openclaw/openclaw/issues/10687)**: Static model catalog causes "Unknown model" errors when providers add new models or during sub-agent spawns.
+
+**ClawRouter**: 30+ models pre-configured, auto-updated catalog.
+
+---
+
+## Agent-Native: Why It Matters
+
+Traditional LLM gateways require a human in the loop:
+
+```
+Traditional Flow (Human-in-the-loop):
+  Human → creates account → gets API key → pastes into config → agent runs
+
+Agent-Native Flow (Fully autonomous):
+  Agent → generates wallet → receives USDC → pays per request → runs
+```
+
+| Capability           | OpenRouter              | ClawRouter                 |
+| -------------------- | ----------------------- | -------------------------- |
+| **Account creation** | Requires human          | Agent generates wallet     |
+| **Authentication**   | Shared secret (API key) | Cryptographic signature    |
+| **Payment**          | Human prepays balance   | Agent pays per request     |
+| **Funds custody**    | They hold your money    | You hold your keys         |
+| **Empty balance**    | Request fails           | Auto-fallback to free tier |
+
+### The x402 Difference
+
+```
+Request → 402 Response (price: $0.003)
+       → Agent's wallet signs payment
+       → Response delivered
+
+No accounts. No API keys. No human intervention.
+```
+
+**Agents can:**
+
+- Spawn with a fresh wallet
+- Receive funds programmatically
+- Pay for exactly what they use
+- Never trust a third party with their funds
+
+---
+
+## Routing: Cloud vs Local
+
+### OpenRouter
+
+- Routing decisions happen on OpenRouter's servers
+- You trust their proprietary algorithm
+- No visibility into why a model was chosen
+- Adds latency for every request
+
+### ClawRouter
+
+- **100% local routing** — 15-dimension weighted scoring runs on YOUR machine
+- **<1ms decisions** — no API calls for routing
+- **Open source** — inspect the exact scoring logic in [`src/router.ts`](../src/router.ts)
+- **Transparent** — see why each model is chosen
+
+---
+
+## Quick Start
+
+Already using OpenRouter? Switch in 60 seconds:
+
+```bash
+# 1. Install ClawRouter
+curl -fsSL https://blockrun.ai/ClawRouter-update | bash
+
+# 2. Restart gateway
+openclaw gateway restart
+
+# 3. Fund wallet (address shown during install)
+# $5 USDC on Base = thousands of requests
+
+# 4. Switch model
+/model blockrun/auto
+```
+
+Your OpenRouter config stays intact — ClawRouter is additive, not replacement.
+
+---
+
+## Summary
+
+> **OpenRouter**: Built for developers who paste API keys
+>
+> **ClawRouter**: Built for agents that manage their own wallets
+
+The future of AI isn't humans configuring API keys. It's agents autonomously acquiring and paying for resources.
+
+---
+
+<div align="center">
+
+**Questions?** [Telegram](https://t.me/blockrunAI) · [X](https://x.com/BlockRunAI) · [GitHub](https://github.com/BlockRunAI/ClawRouter)
+
+</div>