Openrouter Free Failover

OpenRouter Free Model Failover

Purpose

Ensure OpenClaw always uses free OpenRouter models with intelligent priority-based failover. No paid model should ever be invoked. The cascade is ranked by coding/agentic capability and falls over automatically on rate limits, downtime, moderation blocks, or context overflow.

Architecture (Two-Layer Failover)

Layer 1: OpenClaw-side fallback chain (primary)

OpenClaw's native failover via agents.defaults.model.primary + agents.defaults.model.fallbacks:

• Tries primary model first
• On ANY error (rate limit, auth, billing, timeout, overloaded), rotates to next fallback
• Exponential cooldown: 1min → 5min → 25min → 1hr cap
• Session-sticky: pins to working model until session reset or cooldown clears
• FallbackSummaryError when all candidates exhausted (includes soonest cooldown expiry)

Layer 2: OpenRouter-side server failover (complementary)

OpenRouter's models array parameter handles per-request failover transparently:

• If a model returns error (429, 503, moderation, context overflow), tries next in array
• Pricing based on model actually used (all free = $0)
• Works automatically with OpenAI-compatible API

Combined: OpenClaw chains across models; within each model attempt, OpenRouter can cascade if the models param is forwarded.

Rate Limits (Critical Constraints)

Implications:

• Free tier (50/day) is extremely limited for agentic coding — consider purchasing 10 credits ($10 one-time) for 20x daily capacity
• 20 req/min shared across ALL free model calls on the key
• Multiple API keys do NOT bypass limits (governed globally per account)
• Different models have different per-model rate limits (spreading across models helps)

Prioritized Free Model Cascade (Coding/Agentic)

Ranked by: coding benchmark scores, parameter count, context window, tool/function calling support.

Tier 1: Heavy Hitters (primary + first fallbacks)

Tier 2: Solid Performers (secondary fallbacks)

Tier 3: Lightweight Fallbacks (emergency)

Meta-Router (last resort)

OpenClaw Configuration

Config location

~/.openclaw/openclaw.json (Windows: %USERPROFILE%\.openclaw\openclaw.json)

Required config changes (JSON5)

{
  // Environment
  env: {
    OPENROUTER_API_KEY: "sk-or-v1-...",
  },

  // Model cascade — free only
  agents: {
    defaults: {
      model: {
        primary: "openrouter/qwen/qwen3-coder:free",
        fallbacks: [
          "openrouter/nvidia/nemotron-3-super-120b-a12b:free",
          "openrouter/minimax/minimax-m2.5:free",
          "openrouter/nousresearch/hermes-3-llama-3.1-405b:free",
          "openrouter/openai/gpt-oss-120b:free",
          "openrouter/meta-llama/llama-3.3-70b-instruct:free",
          "openrouter/z-ai/glm-4.5-air:free",
          "openrouter/arcee-ai/trinity-large-preview:free",
          "openrouter/openai/gpt-oss-20b:free",
          "openrouter/google/gemma-3-27b-it:free",
          "openrouter/google/gemma-4-26b-a4b-it:free",
          "openrouter/nvidia/nemotron-3-nano-30b-a3b:free",
          "openrouter/google/gemma-3-12b-it:free",
        ],
      },
      // Allowlist — all free models
      models: {
        "openrouter/qwen/qwen3-coder:free": { alias: "qwen-coder" },
        "openrouter/nvidia/nemotron-3-super-120b-a12b:free": { alias: "nemotron-super" },
        "openrouter/minimax/minimax-m2.5:free": { alias: "minimax" },
        "openrouter/nousresearch/hermes-3-llama-3.1-405b:free": { alias: "hermes" },
        "openrouter/openai/gpt-oss-120b:free": { alias: "gpt-oss" },
        "openrouter/meta-llama/llama-3.3-70b-instruct:free": { alias: "llama" },
        "openrouter/z-ai/glm-4.5-air:free": { alias: "glm" },
        "openrouter/arcee-ai/trinity-large-preview:free": { alias: "trinity" },
        "openrouter/openai/gpt-oss-20b:free": { alias: "gpt-oss-sm" },
        "openrouter/google/gemma-3-27b-it:free": { alias: "gemma-27b" },
        "openrouter/google/gemma-4-26b-a4b-it:free": { alias: "gemma-4" },
        "openrouter/nvidia/nemotron-3-nano-30b-a3b:free": { alias: "nemotron-nano" },
        "openrouter/google/gemma-3-12b-it:free": { alias: "gemma-12b" },
      },
      // Image model (multimodal free)
      imageModel: {
        primary: "openrouter/google/gemma-3-27b-it:free",
        fallbacks: [
          "openrouter/google/gemma-4-26b-a4b-it:free",
          "openrouter/google/gemma-3-12b-it:free",
        ],
      },
    },
  },

  // OpenRouter provider definition
  models: {
    providers: {
      openrouter: {
        baseUrl: "https://openrouter.ai/api/v1",
        apiKey: "${OPENROUTER_API_KEY}",
        api: "openai-completions",
        models: [
          // Populate via `openclaw models scan` or manually
        ],
      },
    },
  },
}

Key config rules

1. Every model ref must use openrouter/ prefix in OpenClaw (e.g., openrouter/qwen/qwen3-coder:free)
2. :free suffix is part of the model ID — OpenRouter uses this to route to free endpoints
3. agents.defaults.models acts as an allowlist — if set, only listed models can be selected
4. Config hot-reloads — model/agent changes apply without gateway restart
5. Remove ALL paid models from models.providers.openrouter.models array

Dynamic Model Refresh (canonical — use this, not manual CLI)

scripts/refresh-openclaw-models.js replaces all manual model selection.

It:

1. Fetches /api/v1/models live from OpenRouter.
2. Filters to :free models only (zero prompt + completion cost).
3. Scores each model per task profile using quantitative signals.
4. Reads the current Windows OpenClaw config via SSH.
5. Writes the new ranked chain (primary + fallbacks) back via SCP.
6. Verifies the result with openclaw models status.

Scoring formula

For each model:

score = log2(context_length) × ctxWeight
      + log2(max_completion_tokens) × outWeight
      + boostScore  (if model id matches profile keyword set)

Context length is weighted most heavily for coding because agentic coding tasks require reading full file trees, long diffs, and accumulated context.

Usage

# Session start or after any model changes — coding tasks (default)
npm run models:refresh

# For general-purpose work
npm run models:refresh:general

# For multimodal / image-input tasks
npm run models:refresh:image

# Custom: top-N, explicit profile
node scripts/refresh-openclaw-models.js coding 10

Run at session start and after any reported model degradation or failover exhaustion.

CLI Operations (fallback — when script cannot run)

Troubleshoot failures

# Check model status and auth
openclaw models status --probe

# Check cooldown state
cat ~/.openclaw/agents/default/agent/auth-state.json

# Check gateway health
openclaw health
openclaw doctor

# View recent logs
openclaw logs --tail 50

# Force clear cooldowns (nuclear option)
rm ~/.openclaw/agents/default/agent/auth-state.json
openclaw gateway restart

Failover Behavior Reference

What triggers failover

Cooldown recovery

• Cooldowns use exponential backoff: 1min → 5min → 25min → 1hr cap
• Billing disables: 5hr → doubling → 24hr cap
• Counters reset after 24hr of no failures
• Primary model can be probed near cooldown expiry (auto-recovery)

Edge Cases & Gotchas

1. Expiring models: Some free models (e.g., trinity-large-preview) are temporary promotions. Check OpenRouter's model page for expiry dates. Remove expired models from fallbacks.

2. Negative credit balance: Even free models return 402 if account balance is negative. Keep balance ≥ $0.

3. Tool calling support: Not all free models support function/tool calling. The openclaw models scan probes for this. Prefer models with confirmed tool support for agentic work.

4. Context window mismatch: Free models range from 65K to 262K tokens. OpenClaw does NOT failover on context overflow — it retries with compaction. Set maxTokens appropriately per model.

5. Model ID normalization: OpenRouter uses provider/model:free format. OpenClaw prepends openrouter/ prefix. The full ref is openrouter/provider/model:free.

6. Z.AI normalization: OpenClaw normalizes z.ai/* to zai/* internally. Use openrouter/z-ai/glm-4.5-air:free as the ref.

7. Daily limit exhaustion: At 50 req/day (free tier), an agentic coding session can exhaust limits in ~30 minutes. Buying 10 credits ($10) increases to 1,000/day.

8. Config validation: OpenClaw strictly validates openclaw.json. Unknown keys prevent gateway startup. Always run openclaw doctor after manual edits.

Maintenance Schedule

Quick Decision Matrix