From 2dde6235cccec46045118053493342fa460e5ba9 Mon Sep 17 00:00:00 2001 From: 1bcMax Date: Tue, 10 Feb 2026 10:22:56 -0500 Subject: [PATCH] docs: add subscription failover guide (OpenClaw-native approach) - Explains why subscriptions aren't integrated into ClawRouter - Provides complete setup guide for OpenClaw failover - Covers Claude, ChatGPT, and other providers - Includes troubleshooting and cost analysis Related: #14, #15 --- docs/subscription-failover.md | 305 ++++++++++++++++++++++++++++++++++ 1 file changed, 305 insertions(+) create mode 100644 docs/subscription-failover.md diff --git a/docs/subscription-failover.md b/docs/subscription-failover.md new file mode 100644 index 0000000..26ab675 --- /dev/null +++ b/docs/subscription-failover.md @@ -0,0 +1,305 @@ +# 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-5 + +# Option B: Using ChatGPT Plus (via OpenAI provider) +openclaw models set openai/gpt-4o + +# Option C: Using any other provider +openclaw models set / +``` + +#### 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-5 +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-5", + "fallbacks": ["blockrun/auto"] + } + }, + "coding": { + "model": { + "primary": "anthropic/claude-sonnet-4-5", + "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-5 +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)