freeride

Name: freeride
Author: shaivpidadi

Configures OpenClaw to use free AI models from OpenRouter with automatic fallback ranking. Automatically selects the best free model as primary and ranks 5+ fallbacks to handle rate limits without interrupting workflows Includes freeride auto for one-command setup, freeride list to browse available models, and freeride switch to pin a specific model Preserves all existing OpenClaw config (gateway, channels, plugins, env) and updates only model settings in openclaw.json Optional freeride-watcher daemon monitors rate limits and auto-rotates to the next fallback model when needed Requires OPENROUTER_API_KEY environment variable and openclaw gateway restart after any configuration change

INSTALLATION

npx skills add https://github.com/shaivpidadi/freeride --skill freeride

Run in your project or agent environment. Adjust flags if your CLI version differs.

SKILL.md

$29

**The freeride CLI is installed.** Check with which freeride. If not found:

cd ~/.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.

Commands Reference

Command

When to use it

freeride auto

User wants free AI set up (most common)

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

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

**After any command that changes config, always run openclaw gateway restart.**

What It Writes to Config

FreeRide updates only these keys in ~/.openclaw/openclaw.json:

agents.defaults.model.primary — e.g. openrouter/qwen/qwen3-coder:free

agents.defaults.model.fallbacks — e.g. ["openrouter/free", "nvidia/nemotron:free", ...]

agents.defaults.models — allowlist so /model command shows the free models

Everything else (gateway, channels, plugins, env, customInstructions, named agents) is preserved.

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

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

nohup freeride-watcher > ~/.openclaw/freeride-watcher.log 2>&#x26;1 &#x26;

# One-shot check (no loop)

freeride-watcher --once

# State / history

freeride-watcher --status

The daemon probes the current primary every 60s; if it fails, it rebuilds the

chain with live-verified models. Recommend this whenever the user is leaving

an unattended OpenClaw setup running.

Troubleshooting

Problem

Fix

freeride: command not found

cd ~/.openclaw/workspace/skills/free-ride && pip install -e .

OPENROUTER_API_KEY not set

User needs a key from https://openrouter.ai/keys

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