Free Ride - Unlimited free AI
Manages free AI models from OpenRouter for OpenClaw. Automatically ranks models by quality, configures fallbacks for rate-limit handling, and updates openclaw.json. Optional Groq, Gemini and Cerebras free tiers are opt-in. Use when the user mentions free AI, OpenRouter, model switching, rate limits, or wants to reduce AI costs.
FreeRide - Free AI for OpenClaw
What This Skill Does
Configures OpenClaw to use free AI models from OpenRouter. Sets the best free model as primary, adds ranked fallbacks so rate limits don't interrupt the user, and preserves existing config.
Rules for the agent
- Never print, echo, log, or ask the user to paste an API key into chat. Don't echo key variables, run
envorprintenv, orcat ~/.openclaw/.env. The user sets keys themselves. - To check whether a key is set, run
freeride status. It shows keys masked (for examplesk-or-v1-...abcd) orNOT SET. - Before running a command with
--setup-auth, tell the user what it adds (see below) and only pass--yesonce they agree. - Don't pass
--providersor--allow-training-providersunless the user asked for those providers. For Gemini, tell the user Google may use free-tier prompts for training before passing--allow-training-providers.
Prerequisites
Before running any FreeRide command, ensure:
-
OPENROUTER_API_KEY is set. Check with
freeride status. If it saysNOT SET, the user gets a free key at https://openrouter.ai/keys and adds it themselves, in their editor, as a line in~/.openclaw/.env:text OPENROUTER_API_KEY=<their key>(or exports it in their own shell). Do not type the key on a command line for them.
-
The
freerideCLI is installed. Check withwhich freeride. If not found:bash cd ~/.openclaw/workspace/skills/@shaivpidadi/free-ride # older installs: ~/.openclaw/workspace/skills/free-ride pip install -e .
Primary Workflow
When the user wants free AI, run these steps in order:
# Step 1: Configure best free model + fallbacks
freeride auto
# Step 2: Restart gateway so OpenClaw picks up the changes
openclaw gateway restart
That's it. The user now has free AI with automatic fallback switching.
Verify by telling the user to send /status to check the active model.
If the user already has a primary model they want to keep (for example a paid one), use freeride auto -f instead. FreeRide then marks that primary as theirs and never changes it.
Commands Reference
| Command | When to use it |
|---|---|
freeride auto | User wants free AI set up (most common). Saves their old primary first. |
freeride auto -f | User wants fallbacks but wants to keep their current primary model |
freeride auto -c 10 | User wants more fallbacks (default is 5) |
freeride list | User wants to see available free models |
freeride list -n 30 | User wants to see all free models |
freeride switch <model> | User wants a specific model (e.g. freeride switch qwen3-coder) |
freeride switch <model> -f | Add specific model as fallback only |
freeride status | Check current FreeRide configuration (keys shown masked) |
freeride fallbacks | Update only the fallback models |
freeride refresh | Force refresh the cached model list |
freeride rotate | User is rate-limited / fallback chain is dead — live-test and rebuild (only if FreeRide set the primary) |
freeride restore | Put back the primary and fallbacks from before FreeRide changed them (--dry-run to preview) |
After any command that changes config, always run openclaw gateway restart.
What It Writes
FreeRide updates only these keys in ~/.openclaw/openclaw.json:
agents.defaults.model.primary— e.g.openrouter/qwen/qwen3-coder:freeagents.defaults.model.fallbacks— e.g.["openrouter/openrouter/free", "openrouter/nvidia/nemotron:free", ...]. Fallbacks the user added themselves are kept, ahead of FreeRide's.agents.defaults.models.<model-ref>— allowlist entries so/modelshows the free models. Existing entries are left as they are.auth.profiles["openrouter:default"]={"provider": "openrouter", "mode": "api_key"}— only with--setup-auth, after FreeRide shows this entry and the user confirms (or--yes). It tells OpenClaw to useOPENROUTER_API_KEY; it contains no key.
Everything else (gateway, channels, plugins, env, customInstructions, named agents) is preserved.
Before every write FreeRide copies the file to ~/.openclaw/openclaw.json.freeride-bak and writes the new file atomically. If openclaw.json has JSON5 comments or trailing commas, or uses $include, FreeRide refuses to write it and says why.
Other files FreeRide writes, all under ~/.openclaw/:
.freeride-state.json— which primary/fallbacks FreeRide set, and the user's previous ones (forfreeride restore).freeride-cache.json— 6-hour cache of the OpenRouter model list.freeride-watcher-state.json— watcher rotation count and last reason- temporary
*.freeride-tmp/*.tmpsiblings during atomic writes
FreeRide never writes API keys, never writes ~/.openclaw/.env, and never touches auth-profiles.json.
The first fallback is always openrouter/free — OpenRouter's smart router that auto-picks the best available model based on the request.
Who owns the primary
- A primary set by
freeride auto,freeride switch,freeride rotateor the watcher is FreeRide's. FreeRide may rotate it when it fails. - Any other primary (one the user set, a paid model, or one kept with
-f) is the user's. FreeRide never tests it, never replaces it, andfreeride rotaterefuses to touch it. freeride restoreputs back what was there before and hands the primary back to the user.
Optional providers (opt-in)
OpenRouter free models stay the default. Only when the user asks, add more free tiers to the fallback chain:
freeride auto --providers groq,cerebras
freeride auto --providers groq,gemini --allow-training-providers # Gemini needs explicit consent
freeride auto --providers openrouter # turn them off again
- Groq (
GROQ_API_KEY): tool-capable models only, placed right afteropenrouter/free. - Gemini (
GEMINI_API_KEYorGOOGLE_API_KEY): Flash / Flash-Lite / Gemma only. Google may use prompts on the free tier for training, so it also needs--allow-training-providers. - Cerebras (
CEREBRAS_API_KEY): last in the chain, and only after a live tool-call check passes.
For each one FreeRide checks that the OpenClaw plugin is loaded (openclaw plugins list) and that OpenClaw already lists the model ref (openclaw models list --provider ...). If not, it skips the provider and prints the openclaw plugins install ... command for the user to run. FreeRide does not install plugins and never selects a paid OpenRouter model. The choice is remembered for later runs and the watcher. FREERIDE_PROVIDERS / FREERIDE_ALLOW_TRAINING env vars work the same as the flags.
Watcher (Background Daemon)
For autonomous recovery from a "whole chain is rate-limited" deadlock — which
the agent can't fix by itself, since calling freeride rotate requires
inference and inference is exactly what's failing — the user can run a slim
background daemon:
# Foreground
freeride-watcher
# Persistent background (writes the log file ~/.openclaw/freeride-watcher.log)
nohup freeride-watcher > ~/.openclaw/freeride-watcher.log 2>&1 &
# One-shot check (no loop)
freeride-watcher --once
# State / history
freeride-watcher --status
The daemon probes the current primary every 60s, but only if FreeRide set it; if it fails, it rebuilds the chain with live-verified models. A primary the user configured is left alone. Recommend this whenever the user is leaving an unattended OpenClaw setup running.
Troubleshooting
| Problem | Fix |
|---|---|
freeride: command not found | cd ~/.openclaw/workspace/skills/@shaivpidadi/free-ride && pip install -e . |
OPENROUTER_API_KEY not set | User adds OPENROUTER_API_KEY=... to ~/.openclaw/.env (key from https://openrouter.ai/keys) |
... is not plain JSON | The config has comments or trailing commas. The user removes them, then re-runs. Nothing was written. |
rotate says the primary is not FreeRide's | Expected for a user's own primary. freeride auto hands it to FreeRide (old one saved). |
| Want the old model back | freeride restore --dry-run, then freeride restore |
| Changes not taking effect | openclaw gateway restart then /new for fresh session |
| Agent shows 0 tokens | Check freeride status — primary should be openrouter/<provider>/<model>:free |
Related skills
- Downloads
- 73.1kAll time
- Security audit
- Review
- Last updated
- 3d ago
- Current version
- v1.1.0
- License
- MIT-0
