🎢 FreeRide

Stop paying for AI. Start riding free.

🚀 FreeRide v3 is out — works with any OpenAI-compatible agent

The version on this repo (v2) is OpenClaw-specific and OpenRouter-only.
FreeRide v3 is a local
OpenAI-compatible gateway that routes across 5 free-tier providers
(OpenRouter, Groq, NVIDIA NIM, Cloudflare Workers AI, HuggingFace) with
automatic failover, and works with Aider, Continue, Hermes, OpenClaw,
the OpenAI Python SDK, and any other OpenAI-shaped client.
curl -sSL https://api.free-ride.xyz/install.sh | sh
export OPENROUTER_API_KEY=sk-or-v1-...
freeride serve
Then point any agent at http://localhost:11343/v1 — or use a binder:
freeride bind aider       # writes ~/.aider.conf.yml
freeride bind continue    # writes ~/.continue/config.yaml
freeride bind hermes      # writes ~/.hermes/config.yaml
freeride bind openclaw    # writes ~/.openclaw/openclaw.json
👉 Repo: https://github.com/Shaivpidadi/FreeRideV3 · Site: https://free-ride.xyz · PyPI: pip install freeride-gateway

The v2 surface below still works for existing OpenClaw users — v3 ships
v2 backwards-compat shims (freeride auto/list/switch/...), so an
in-place upgrade preserves your existing setup.

FreeRide gives you unlimited free AI in OpenClaw by automatically managing OpenRouter's free models.

You: *hits rate limit*
FreeRide: "I got you." *switches to next best model*
You: *keeps coding*

The Problem

You're using OpenClaw. You love it. But:

💸 API costs add up fast
🚫 Free models have rate limits
😤 Manually switching models is annoying
🤷 You don't know which free model is actually good

The Solution

One command. Free AI. Forever.

freeride auto

That's it. FreeRide:

Finds the 30+ free models on OpenRouter
Ranks them by quality (context length, capabilities, speed)
Sets the best one as your primary
Configures smart fallbacks for when you hit rate limits
Preserves your existing OpenClaw config

Installation

npx clawhub@latest install free-ride
cd ~/.openclaw/workspace/skills/free-ride
pip install -e .

That's it. freeride and freeride-watcher are now available as global commands.

Quick Start

1. Get a Free OpenRouter Key

Go to openrouter.ai/keys → Create account → Generate key

No credit card. No trial. Actually free.

2. Set Your Key

export OPENROUTER_API_KEY="sk-or-v1-..."

# Or, multiple keys (shown in `freeride status`):
export OPENROUTER_API_KEY='["sk-or-v1-key1","sk-or-v1-key2"]'

Or add it to your OpenClaw config:

openclaw config set env.OPENROUTER_API_KEY "sk-or-v1-..."

3. Run FreeRide

freeride auto

4. Restart OpenClaw

openclaw gateway restart

5. Verify It Works

Message your agent on WhatsApp/Telegram/Discord or the dashboard:

You:    /status
Agent:  (shows the free model name + token count)

Done. You're now running on free AI with automatic fallbacks.

What You Get

Primary Model: openrouter/nvidia/nemotron-3-nano-30b-a3b:free (256K context)

Fallbacks:
  1. openrouter/free          ← Smart router (auto-picks best available)
  2. qwen/qwen3-coder:free    ← Great for coding
  3. stepfun/step-3.5:free    ← Fast responses
  4. deepseek/deepseek:free   ← Strong reasoning
  5. mistral/mistral:free     ← Reliable fallback

When you hit a rate limit, OpenClaw automatically tries the next model. You keep working. No interruptions.

Commands

Command	What it does
`freeride auto`	Auto-configure best model + fallbacks
`freeride list`	See all 30+ free models ranked
`freeride switch <model>`	Use a specific model
`freeride status`	Check your current setup
`freeride fallbacks`	Update fallbacks only
`freeride refresh`	Force refresh model cache
`freeride rotate`	Live-test primary; swap to a working model if it's failing

Pro Tips

# Already have a model you like? Just add fallbacks:
freeride auto -f

# Want more fallbacks for maximum uptime?
freeride auto -c 10

# Coding? Switch to the best coding model:
freeride switch qwen3-coder

# See what's available:
freeride list -n 30

# Always restart OpenClaw after changes:
openclaw gateway restart

How It Ranks Models

FreeRide scores each model (0-1) based on:

Factor	Weight	Why
Context Length	40%	Longer = handle bigger codebases
Capabilities	30%	Vision, tools, structured output
Recency	20%	Newer models = better performance
Provider Trust	10%	Google, Meta, NVIDIA, etc.

The smart fallback openrouter/free is always first - it auto-selects based on what your request needs.

Testing with Your OpenClaw Agent

After running freeride auto and openclaw gateway restart:

# Check OpenClaw sees the models
openclaw models list

# Validate config
openclaw doctor --fix

# Open the dashboard and chat
openclaw dashboard
# Or message your agent on WhatsApp/Telegram/Discord

Useful agent commands to verify:

Command	What it tells you
`/status`	Current model + token usage
`/model`	Available models (your free models should be listed)
`/new`	Start fresh session with the new model

Watcher (Background Daemon)

The watcher is a long-running process that probes your current primary model
every minute and rotates the config the moment it starts failing. Because it
runs outside the agent's inference loop, it can recover from a "everything
is 429" deadlock that the agent itself can't escape (the agent would need
inference to call freeride rotate, but inference is exactly what's broken).

# Foreground (good for trying it out)
freeride-watcher

# Background, persistent across logout
nohup freeride-watcher > ~/.openclaw/freeride-watcher.log 2>&1 &

# One-off check (no loop)
freeride-watcher --once

# See state (rotation count, last reason)
freeride-watcher --status

# Custom interval (seconds)
freeride-watcher --interval 120

For an actual service, point your favorite supervisor (launchd, systemd,
tmux, pm2) at freeride-watcher. There is no PID file — stop it with
Ctrl-C or kill <pid>.

FAQ

Is this actually free?

Yes. OpenRouter provides free tiers for many models. You just need an account (no credit card).

What about rate limits?

Three layers of defense:

OpenClaw's runtime fallback chain — when the primary returns 429, the gateway transparently tries fallback 1, 2, 3 at routing time. The agent never sees the 429.
openrouter/free smart router is always fallback #1 — server-side smart routing onto whatever free model is actually available.
freeride-watcher daemon — runs in the background, probes the primary every 60s, rotates the config the moment it starts failing. This is what saves you when the entire fallback chain is dead and the agent has nothing left to route to.

If you've set multiple keys via OPENROUTER_API_KEY='["key1","key2"]', every layer above also rotates through them on 429.

Will it mess up my OpenClaw config?

No. FreeRide only touches agents.defaults.model and agents.defaults.models. Your gateway, channels, plugins, workspace, customInstructions - all preserved.

Which models are free?

Run freeride list to see current availability. It changes, which is why FreeRide exists.

Do I need to restart OpenClaw after changes?

Yes. Run openclaw gateway restart after any FreeRide command that changes your config.

The Math

Scenario	Monthly Cost
GPT-4 API	$50-200+
Claude API	$50-200+
OpenClaw + FreeRide	$0

You're welcome.

Requirements

OpenClaw installed (Node ≥22)
Python 3.8+
Free OpenRouter account (get key)

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
│  You         │ ──→ │  FreeRide    │ ──→ │  OpenRouter API  │
│  "freeride   │     │              │     │  (30+ free       │
│   auto"      │     │  • Fetch     │     │   models)        │
└──────────────┘     │  • Rank      │     └──────────────────┘
                     │  • Configure │
                     └──────┬───────┘
                            │
                            ▼
                     ┌──────────────┐
                     │ ~/.openclaw/ │
                     │ openclaw.json│
                     └──────┬───────┘
                            │
                     openclaw gateway restart
                            │
                            ▼
                     ┌──────────────┐
                     │  OpenClaw    │
                     │  (free AI!)  │
                     └──────────────┘

Contributing

Found a bug? Want a feature? PRs welcome.

cd ~/.openclaw/workspace/skills/free-ride

# Test commands
freeride list
freeride status
freeride auto --help

OpenClaw - The AI coding agent
OpenRouter - The model router
ClawHub - Skill marketplace

License

MIT - Do whatever you want.

Stop paying. Start riding.

⭐ Star us on GitHub · 🔑 Get OpenRouter Key · 🦞 Install OpenClaw

freeride

🎢 FreeRide

Stop paying for AI. Start riding free.

🚀 FreeRide v3 is out — works with any OpenAI-compatible agent

The Problem

The Solution

Installation

Quick Start

1. Get a Free OpenRouter Key

2. Set Your Key

3. Run FreeRide

4. Restart OpenClaw

5. Verify It Works

What You Get

Commands

Pro Tips

How It Ranks Models

Testing with Your OpenClaw Agent

Watcher (Background Daemon)

FAQ

The Math

Requirements

Architecture

Contributing

License

find-skills

frontend-design

github-workflow-automation

using-git-worktrees

optimize

🎢 FreeRide

Stop paying for AI. Start riding free.

🚀 FreeRide v3 is out — works with any OpenAI-compatible agent

The Problem

The Solution

Installation

Quick Start

1. Get a Free OpenRouter Key

2. Set Your Key

3. Run FreeRide

4. Restart OpenClaw

5. Verify It Works

What You Get

Commands

Pro Tips

How It Ranks Models

Testing with Your OpenClaw Agent

Watcher (Background Daemon)

FAQ

The Math

Requirements

Architecture

Contributing

Related Projects

License