infinity-router

What it does

Configures OpenClaw (or Claude Code) to use free AI models from OpenRouter. Selects the best tool-capable model as primary, builds a ranked fallback chain so rate limits cause zero interruption, and leaves the rest of the config untouched.

Only chat models are selected — audio, image, video, and embedding models are automatically filtered out. Models that claim tool support but fail at runtime (e.g. Gemma) are excluded from tool scoring.

Prerequisites

1. API key(s)

# Single key
openclaw config set env.OPENROUTER_API_KEY "sk-or-v1-..."

# Multiple keys (comma-separated) — recommended to avoid daily free-tier limits
openclaw config set env.OPENROUTER_API_KEY "sk-or-v1-KEY1,sk-or-v1-KEY2,sk-or-v1-KEY3"

For OpenClaw inference key rotation, add each key as a separate profile in ~/.openclaw/agents/main/agent/auth-profiles.json:

{
  "version": 1,
  "profiles": {
    "openrouter:default": { "type": "api_key", "provider": "openrouter", "key": "sk-or-v1-KEY1" },
    "openrouter:key2":    { "type": "api_key", "provider": "openrouter", "key": "sk-or-v1-KEY2" },
    "openrouter:key3":    { "type": "api_key", "provider": "openrouter", "key": "sk-or-v1-KEY3" }
  }
}

Note: the file is auth-profiles.json (with s), not auth-profile.json.

2. Install

On Debian/Ubuntu servers (Python 3.12+), use the provided script:

cd /path/to/infinity-router
chmod +x install.sh
./install.sh
which infinity-router    # should return /usr/local/bin/infinity-router

To uninstall: ./uninstall.sh

Standard workflow

# 1. Configure best model + fallback chain
infinity-router pick

# 2. Apply to the running gateway
openclaw gateway restart

For a safer run that validates each model before writing (avoids stale/broken models):

infinity-router pick --validate
openclaw gateway restart

Command reference

Command	When to run
infinity-router pick	Set up best free model + fallbacks (most common)
infinity-router pick --validate	Probe each candidate before writing — avoids "Unknown model" errors
infinity-router pick -f	Keep current primary, rebuild fallbacks only
infinity-router pick -c 10	Use 10 fallbacks instead of default 5
infinity-router pick --auth	Also add OpenRouter auth profile to OpenClaw
infinity-router scan	Browse all available free models
infinity-router scan -n 30	Show all 30+ models
infinity-router use deepseek	Set a specific model (partial name OK)
infinity-router use qwen3-coder -f	Add model to fallbacks only
infinity-router use deepseek --validate	Set model and validate fallbacks
infinity-router bench	Latency-test top 5 models
infinity-router bench -c 10	Test top 10 models
infinity-router status	Show current config, all API keys, cache age
infinity-router watch	Tail gateway log, auto-rotate + restart on failures
infinity-router watch --verbose	Also print every matched failure line
infinity-router watch --notify URL	POST rotation event to webhook on each rotate
infinity-router reset	Remove model config from target
infinity-router reset --clear-rl	Also clear rate-limit cooldown records

Always run openclaw gateway restart after any command that changes config.

Config targets

infinity-router pick                        # default: openclaw
infinity-router pick --target claude-code   # Claude Code settings.json

What gets written (OpenClaw)

Only these keys in ~/.openclaw/openclaw.json:

• agents.defaults.model.primary — e.g. openrouter/meta-llama/llama-3.3-70b-instruct:free
• agents.defaults.model.fallbacks — e.g. ["openrouter/free", "mistralai/mistral-small:free", …]
• agents.defaults.models — model allowlist

The first fallback is always openrouter/free — OpenRouter's smart router that auto-picks the best available model for each request.

Daemon (auto-rotation)

infinity-router-daemon            # one-shot check
infinity-router-daemon --loop     # continuous monitoring
infinity-router-daemon --rotate   # force rotate now
infinity-router-daemon --status   # rotation history
infinity-router-daemon --clear-rl # reset all cooldowns

Daily maintenance

Run once a day or when models start failing:

rm -f ~/.infinity-router/model-cache.json
infinity-router pick
openclaw gateway restart

Troubleshooting

Problem	Fix
infinity-router: command not found	Run ./install.sh from the project directory
OPENROUTER_API_KEY not set	Get a free key at https://openrouter.ai/keys
Config not taking effect	openclaw gateway restart, then /new in Telegram
Unknown model errors in gateway log	Stale cache — rm ~/.infinity-router/model-cache.json && infinity-router pick --validate
Agent gives fake/hallucinated responses	Model doesn't support tools — run infinity-router pick --validate to get a real tool-capable model
All probes return rate_limit	Daily free quota exhausted — wait for UTC midnight reset, or add more API keys
HTTP 429: free-models-per-day	Add more keys comma-separated in env.OPENROUTER_API_KEY, or add separate profiles to auth-profiles.json
Something went wrong in Telegram	Run infinity-router status to see active model, then openclaw gateway restart and /new