@blockrun/clawrouter 0.12.62 → 0.12.64

package/docs/routing-profiles.md

@@ -0,0 +1,81 @@
+# Routing Profiles & Pricing
+
+ClawRouter offers four routing profiles to balance cost vs quality. Prices are in **$/M tokens** (input/output).
+
+## ECO (Absolute Cheapest)
+
+Use `blockrun/eco` for maximum cost savings.
+
+| Tier      | Primary Model                | Input | Output |
+| --------- | ---------------------------- | ----- | ------ |
+| SIMPLE    | nvidia/gpt-oss-120b          | $0.00 | $0.00  |
+| MEDIUM    | google/gemini-2.5-flash-lite | $0.10 | $0.40  |
+| COMPLEX   | google/gemini-2.5-flash-lite | $0.10 | $0.40  |
+| REASONING | xai/grok-4-1-fast-reasoning  | $0.20 | $0.50  |
+
+---
+
+## AUTO (Balanced - Default)
+
+Use `blockrun/auto` for the best quality/price balance.
+
+| Tier      | Primary Model                 | Input | Output |
+| --------- | ----------------------------- | ----- | ------ |
+| SIMPLE    | moonshot/kimi-k2.5            | $0.60 | $3.00  |
+| MEDIUM    | xai/grok-code-fast-1          | $0.20 | $1.50  |
+| COMPLEX   | google/gemini-3.1-pro         | $2.00 | $12.00 |
+| REASONING | xai/grok-4-1-fast-reasoning   | $0.20 | $0.50  |
+
+---
+
+## PREMIUM (Best Quality)
+
+Use `blockrun/premium` for maximum quality.
+
+| Tier      | Primary Model        | Input | Output |
+| --------- | -------------------- | ----- | ------ |
+| SIMPLE    | moonshot/kimi-k2.5   | $0.60 | $3.00  |
+| MEDIUM    | openai/gpt-5.2-codex | $1.75 | $14.00 |
+| COMPLEX   | claude-opus-4.6      | $5.00 | $25.00 |
+| REASONING | claude-sonnet-4.6    | $3.00 | $15.00 |
+
+---
+
+## AGENTIC (Multi-Step Tasks)
+
+Use `blockrun/agentic` for autonomous multi-step tasks, or let ClawRouter auto-detect agentic patterns.
+
+| Tier      | Primary Model        | Input | Output |
+| --------- | -------------------- | ----- | ------ |
+| SIMPLE    | moonshot/kimi-k2.5   | $0.60 | $3.00  |
+| MEDIUM    | xai/grok-code-fast-1 | $0.20 | $1.50  |
+| COMPLEX   | claude-sonnet-4.6    | $3.00 | $15.00 |
+| REASONING | claude-sonnet-4.6    | $3.00 | $15.00 |
+
+---
+
+## ECO vs AUTO Savings
+
+| Tier      | ECO   | AUTO   | Savings  |
+| --------- | ----- | ------ | -------- |
+| SIMPLE    | FREE  | $3.60  | **100%** |
+| MEDIUM    | $0.50 | $1.70  | **71%**  |
+| COMPLEX   | $0.50 | $14.00 | **96%**  |
+| REASONING | $0.70 | $0.70  | 0%       |
+
+---
+
+## How Tiers Work
+
+ClawRouter automatically classifies your query into one of four tiers:
+
+- **SIMPLE**: Basic questions, short responses, simple lookups
+- **MEDIUM**: Code generation, moderate complexity tasks
+- **COMPLEX**: Large context, multi-step reasoning, complex code
+- **REASONING**: Logic puzzles, math, chain-of-thought tasks
+
+The router picks the cheapest model capable of handling your query's tier.
+
+---
+
+_Last updated: v0.12.24_

package/docs/subscription-failover.md

@@ -0,0 +1,320 @@
+# Using Subscriptions with ClawRouter Failover
+
+This guide explains how to use your existing LLM subscriptions (Claude Pro/Max, ChatGPT Plus, etc.) as primary providers, with ClawRouter x402 micropayments as automatic failover.
+
+## Why Not Built Into ClawRouter?
+
+After careful consideration, we decided **not** to integrate subscription support directly into ClawRouter for several important reasons:
+
+### 1. Terms of Service Compliance
+
+- Most subscription ToS (Claude Code, ChatGPT Plus) are designed for personal use
+- Using them through a proxy/API service may violate provider agreements
+- We want to keep ClawRouter compliant and low-risk for all users
+
+### 2. Security & Privacy
+
+- Integrating subscriptions would require ClawRouter to access your credentials/sessions
+- Spawning external processes (like Claude CLI) introduces security concerns
+- Better to keep authentication at the OpenClaw layer where you control it
+
+### 3. Maintenance & Flexibility
+
+- Each subscription provider has different APIs, CLIs, and authentication methods
+- OpenClaw already has a robust provider system that handles this
+- Duplicating this in ClawRouter would increase complexity without added value
+
+### 4. Better Architecture
+
+- OpenClaw's native failover mechanism is more flexible and powerful
+- Works with **any** provider (not just Claude)
+- Zero code changes needed in ClawRouter
+- You maintain full control over your credentials
+
+## How It Works
+
+OpenClaw has a built-in **model fallback chain** that automatically tries alternative providers when the primary fails:
+
+```
+User Request
+    ↓
+Primary Provider (e.g., Claude subscription via OpenClaw)
+    ↓ (rate limited / quota exceeded / auth failed)
+OpenClaw detects failure
+    ↓
+Fallback Chain (try each in order)
+    ↓
+ClawRouter (blockrun/auto)
+    ↓
+Smart routing picks cheapest model
+    ↓
+x402 micropayment to BlockRun API
+    ↓
+Response returned to user
+```
+
+**Key benefits:**
+
+- ✅ Automatic failover (no manual intervention)
+- ✅ Works with any subscription provider OpenClaw supports
+- ✅ Respects provider ToS (you configure authentication directly)
+- ✅ ClawRouter stays focused on cost optimization
+
+## Setup Guide
+
+### Prerequisites
+
+1. **OpenClaw Gateway installed** with ClawRouter plugin
+
+   ```bash
+   npm install -g openclaw
+   openclaw plugins install @blockrun/clawrouter
+   ```
+
+2. **Subscription configured in OpenClaw**
+   - For Claude: Use `claude setup-token` or API key
+   - For OpenAI: Set `OPENAI_API_KEY` environment variable
+   - For others: See [OpenClaw provider docs](https://docs.openclaw.ai)
+
+3. **ClawRouter wallet funded** (for failover)
+   ```bash
+   openclaw gateway logs | grep "Wallet:"
+   # Send USDC to the displayed address on Base network
+   ```
+
+### Configuration Steps
+
+#### Step 1: Set Primary Model (Your Subscription)
+
+```bash
+# Option A: Using Claude subscription
+openclaw models set anthropic/claude-sonnet-4.6
+
+# Option B: Using ChatGPT Plus (via OpenAI provider)
+openclaw models set openai/gpt-4o
+
+# Option C: Using any other provider
+openclaw models set <provider>/<model>
+```
+
+#### Step 2: Add ClawRouter as Fallback
+
+```bash
+# Add blockrun/auto for smart routing (recommended)
+openclaw models fallbacks add blockrun/auto
+
+# Or specify a specific model
+openclaw models fallbacks add blockrun/google/gemini-2.5-pro
+```
+
+#### Step 3: Verify Configuration
+
+```bash
+openclaw models show
+```
+
+Expected output:
+
+```
+Primary: anthropic/claude-sonnet-4.6
+Fallbacks:
+  1. blockrun/auto
+```
+
+#### Step 4: Test Failover (Optional)
+
+To verify failover works:
+
+1. **Temporarily exhaust your subscription quota** (or wait for rate limit)
+2. **Make a request** - OpenClaw should automatically failover to ClawRouter
+3. **Check logs:**
+   ```bash
+   openclaw gateway logs | grep -i "fallback\|blockrun"
+   ```
+
+### Advanced Configuration
+
+#### Configure Multiple Fallbacks
+
+```bash
+openclaw models fallbacks add blockrun/google/gemini-2.5-flash  # Fast & cheap
+openclaw models fallbacks add blockrun/deepseek/deepseek-chat   # Even cheaper
+openclaw models fallbacks add blockrun/nvidia/gpt-oss-120b      # Free tier
+```
+
+#### Per-Agent Configuration
+
+Edit `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "agents": {
+    "main": {
+      "model": {
+        "primary": "anthropic/claude-opus-4.6",
+        "fallbacks": ["blockrun/auto"]
+      }
+    },
+    "coding": {
+      "model": {
+        "primary": "anthropic/claude-sonnet-4.6",
+        "fallbacks": ["blockrun/google/gemini-2.5-pro", "blockrun/deepseek/deepseek-chat"]
+      }
+    }
+  }
+}
+```
+
+#### Tier-Based Configuration (ClawRouter Smart Routing)
+
+When using `blockrun/auto`, ClawRouter automatically classifies your request and picks the cheapest capable model:
+
+- **SIMPLE** queries → Gemini 2.5 Flash, DeepSeek Chat (~$0.0001/req)
+- **MEDIUM** queries → GPT-4o-mini, Gemini Flash (~$0.001/req)
+- **COMPLEX** queries → Claude Sonnet, Gemini Pro (~$0.01/req)
+- **REASONING** queries → DeepSeek R1, o3-mini (~$0.05/req)
+
+Learn more: [ClawRouter Smart Routing](./smart-routing.md)
+
+## Monitoring & Troubleshooting
+
+### Check If Failover Is Working
+
+```bash
+# Watch real-time logs
+openclaw gateway logs --follow | grep -i "fallback\|blockrun\|rate.limit\|quota"
+
+# Check ClawRouter proxy logs
+openclaw gateway logs | grep "ClawRouter"
+```
+
+**Success indicators:**
+
+- ✅ "Rate limit reached" or "Quota exceeded" → primary failed
+- ✅ "Trying fallback: blockrun/auto" → failover triggered
+- ✅ "ClawRouter: Success with model" → failover succeeded
+
+### Common Issues
+
+#### Issue: Failover never triggers
+
+**Symptoms:** Always uses primary, never switches to ClawRouter
+
+**Solutions:**
+
+1. Check fallbacks are configured:
+   ```bash
+   openclaw models show
+   ```
+2. Verify primary is actually failing (check provider dashboard for quota/rate limits)
+3. Check OpenClaw logs for authentication errors
+
+#### Issue: "Wallet empty" errors during failover
+
+**Symptoms:** Failover triggers but ClawRouter returns balance errors
+
+**Solutions:**
+
+1. Check ClawRouter wallet balance:
+   ```bash
+   openclaw gateway logs | grep "Balance:"
+   ```
+2. Fund wallet on Base network (USDC)
+3. Verify wallet key is configured correctly
+
+#### Issue: Slow failover (high latency)
+
+**Symptoms:** 5-10 second delay when switching to ClawRouter
+
+**Cause:** OpenClaw tries multiple auth profiles before failover
+
+**Solutions:**
+
+1. Reduce auth profile retry attempts (see OpenClaw config)
+2. Use `blockrun/auto` as primary for faster responses
+3. Accept the latency as a tradeoff for cheaper requests
+
+## Cost Analysis
+
+### Example Scenario
+
+**Usage pattern:**
+
+- 100 requests/day
+- 50% hit Claude subscription quota (rate limited)
+- 50% use ClawRouter failover
+
+**Without failover:**
+
+- Pay Anthropic API: $50/month (100% API usage)
+
+**With failover:**
+
+- Claude subscription: $20/month (covers 50%)
+- ClawRouter x402: ~$5/month (50 requests via smart routing)
+- **Total: $25/month (50% savings)**
+
+### When Does This Make Sense?
+
+✅ **Good fit:**
+
+- You already have a subscription for personal use
+- You occasionally exceed quota/rate limits
+- You want cost optimization without managing API keys
+
+❌ **Not ideal:**
+
+- You need 100% reliability (subscriptions have rate limits)
+- You prefer a single provider (no failover complexity)
+- Your usage is low (< 10 requests/day)
+
+## FAQ
+
+### Q: Will this violate my subscription ToS?
+
+**A:** You configure the subscription directly in OpenClaw using your own credentials. ClawRouter only receives requests after your subscription fails. This is similar to using multiple API keys yourself.
+
+However, each provider has different ToS. Check yours before proceeding:
+
+- [Claude Code Terms](https://claude.ai/terms)
+- [ChatGPT Terms](https://openai.com/policies/terms-of-use)
+
+### Q: Can I use multiple subscriptions?
+
+**A:** Yes! Configure multiple providers with failback chains:
+
+```bash
+openclaw models set anthropic/claude-opus-4.6
+openclaw models fallbacks add openai/gpt-4o          # ChatGPT Plus
+openclaw models fallbacks add blockrun/auto           # x402 as final fallback
+```
+
+### Q: Does this work with Claude Max API Proxy?
+
+**A:** Yes! Configure the proxy as a custom provider in OpenClaw, then add `blockrun/auto` as fallback.
+
+See: [Claude Max API Proxy Guide](https://github.com/anthropics/claude-code/blob/main/docs/providers/claude-max-api-proxy.md)
+
+### Q: How is this different from PR #15?
+
+**A:** PR #15 integrated Claude CLI directly into ClawRouter. Our approach:
+
+- ✅ Works with any provider (not just Claude)
+- ✅ Respects provider ToS (no proxy/wrapper)
+- ✅ Uses OpenClaw's native failover (more reliable)
+- ✅ Zero maintenance burden on ClawRouter
+
+## Feedback & Support
+
+We'd love to hear your experience with subscription failover:
+
+- **GitHub Discussion:** [Share your setup](https://github.com/BlockRunAI/ClawRouter/discussions)
+- **Issues:** [Report problems](https://github.com/BlockRunAI/ClawRouter/issues)
+- **Telegram:** [Join community](https://t.me/blockrunAI)
+
+## Related Documentation
+
+- [OpenClaw Model Failover](https://docs.openclaw.ai/concepts/model-failover)
+- [OpenClaw Provider Configuration](https://docs.openclaw.ai/gateway/configuration)
+- [ClawRouter Smart Routing](./smart-routing.md)
+- [ClawRouter x402 Micropayments](./x402-payments.md)