Skip to content
Back to search

freeride

SkillWorks with Claude CodeGitHub

Same as --allow-training-providers (e.g. gemini).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shaivpidadi--freeride/badge.svg)](/listings/shaivpidadi--freeride)

HTML

<a href="/listings/shaivpidadi--freeride"><img src="/api/listings/shaivpidadi--freeride/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx clawhub@0.23.3 --workdir ~/.openclaw/workspace install @shaivpidadi/free-ride --version 1.1.0
cd ~/.openclaw/workspace/skills/@shaivpidadi/free-ride
pip install -e .

The command pins the ClawHub CLI version, the skill owner (`@shaivpidadi`), and the skill version. `requests` is capped below 3.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 236 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: freeride
  3. version: 1.1.0
  4. description: 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.
  5. env:
  6. - name: OPENROUTER_API_KEY
  7. description: OpenRouter API key — get a free one at openrouter.ai/keys
  8. required: true
  9. secret: true
  10. - name: GROQ_API_KEY
  11. description: Optional, only used with --providers groq
  12. required: false
  13. secret: true
  14. - name: GEMINI_API_KEY
  15. description: Optional (GOOGLE_API_KEY also accepted), only used with --providers gemini --allow-training-providers
  16. required: false
  17. secret: true
  18. - name: GOOGLE_API_KEY
  19. description: Optional alias for GEMINI_API_KEY
  20. required: false
  21. secret: true
  22. - name: CEREBRAS_API_KEY
  23. description: Optional, only used with --providers cerebras
  24. required: false
  25. secret: true
  26. network:
  27. - openrouter.ai
  28. - api.groq.com (only with --providers groq)
  29. - generativelanguage.googleapis.com (only with --providers gemini)
  30. - api.cerebras.ai (only with --providers cerebras)
  31. reads:
  32. - ~/.openclaw/openclaw.json
  33. - ~/.openclaw/.env (API keys, read only)
  34. writes:
  35. - ~/.openclaw/openclaw.json (keys: agents.defaults.model.primary, agents.defaults.model.fallbacks, agents.defaults.models.<model-ref>; and auth.profiles.openrouter:default only with --setup-auth after confirmation)
  36. - ~/.openclaw/openclaw.json.freeride-tmp (temporary, replaced atomically)
  37. - ~/.openclaw/openclaw.json.freeride-bak (copy taken before every write)
  38. - ~/.openclaw/.freeride-state.json (+ .freeride-tmp sibling)
  39. - ~/.openclaw/.freeride-cache.json
  40. - ~/.openclaw/.freeride-watcher-state.json (+ .tmp sibling)
  41. - ~/.openclaw/freeride-watcher.log (only via the suggested nohup redirect)
  42. - ~/.openclaw/ (created if missing)
  43. never-writes:
  44. - API keys, anywhere
  45. - ~/.openclaw/.env
  46. - auth-profiles.json
  47. runs:
  48. - openclaw plugins list --json (read only, only with --providers)
  49. - openclaw models list --all --provider <id> --json (read only, only with --providers)
  50. install: npx clawhub@0.23.3 --workdir ~/.openclaw/workspace install @shaivpidadi/free-ride --version 1.1.0 && cd ~/.openclaw/workspace/skills/@shaivpidadi/free-ride && pip install -e .
  51. metadata:
  52. openclaw:
  53. emoji: "\U0001F3A2"
  54. homepage: https://github.com/Shaivpidadi/FreeRide
  55. requires:
  56. env:
  57. - OPENROUTER_API_KEY
  58. bins:
  59. - openclaw
  60. anyBins:
  61. - python3
  62. - python
  63. primaryEnv: OPENROUTER_API_KEY
  64. envVars:
  65. - name: OPENROUTER_API_KEY
  66. required: true
  67. description: OpenRouter API key, free at openrouter.ai/keys. Set it in ~/.openclaw/.env, never in chat.
  68. - name: GROQ_API_KEY
  69. required: false
  70. description: Groq key, used only with --providers groq.
  71. - name: GEMINI_API_KEY
  72. required: false
  73. description: Gemini key, used only with --providers gemini --allow-training-providers.
  74. - name: GOOGLE_API_KEY
  75. required: false
  76. description: Alias for GEMINI_API_KEY.
  77. - name: CEREBRAS_API_KEY
  78. required: false
  79. description: Cerebras key, used only with --providers cerebras.
  80. - name: FREERIDE_PROVIDERS
  81. required: false
  82. description: Same as --providers (e.g. groq,cerebras). Unset means OpenRouter only.
  83. - name: FREERIDE_ALLOW_TRAINING
  84. required: false
  85. description: Same as --allow-training-providers (e.g. gemini).
  86. ---
  87. # FreeRide - Free AI for OpenClaw
  88. ## What This Skill Does
  89. 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.
  90. ## Rules for the agent
  91. - **Never print, echo, log, or ask the user to paste an API key into chat.** Don't echo key variables, run `env` or `printenv`, or `cat ~/.openclaw/.env`. The user sets keys themselves.
  92. - To check whether a key is set, run `freeride status`. It shows keys masked (for example `sk-or-v1-...abcd`) or `NOT SET`.
  93. - Before running a command with `--setup-auth`, tell the user what it adds (see below) and only pass `--yes` once they agree.
  94. - Don't pass `--providers` or `--allow-training-providers` unless the user asked for those providers. For Gemini, tell the user Google may use free-tier prompts for training before passing `--allow-training-providers`.
  95. ## Prerequisites
  96. Before running any FreeRide command, ensure:
  97. 1. **OPENROUTER_API_KEY is set.** Check with `freeride status`. If it says `NOT 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`:
  98. ```
  99. OPENROUTER_API_KEY=<their key>
  100. ```
  101. (or exports it in their own shell). Do not type the key on a command line for them.
  102. 2. **The `freeride` CLI is installed.** Check with `which freeride`. If not found:
  103. ```bash
  104. cd ~/.openclaw/workspace/skills/@shaivpidadi/free-ride # older installs: ~/.openclaw/workspace/skills/free-ride
  105. pip install -e .
  106. ```
  107. ## Primary Workflow
  108. When the user wants free AI, run these steps in order:
  109. ```bash
  110. # Step 1: Configure best free model + fallbacks
  111. freeride auto
  112. # Step 2: Restart gateway so OpenClaw picks up the changes
  113. openclaw gateway restart
  114. ```
  115. That's it. The user now has free AI with automatic fallback switching.
  116. Verify by telling the user to send `/status` to check the active model.
  117. 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.
  118. ## Commands Reference
  119. | Command | When to use it |
  120. |---------|----------------|
  121. | `freeride auto` | User wants free AI set up (most common). Saves their old primary first. |
  122. | `freeride auto -f` | User wants fallbacks but wants to keep their current primary model |
  123. | `freeride auto -c 10` | User wants more fallbacks (default is 5) |
  124. | `freeride list` | User wants to see available free models |
  125. | `freeride list -n 30` | User wants to see all free models |
  126. | `freeride switch <model>` | User wants a specific model (e.g. `freeride switch qwen3-coder`) |
  127. | `freeride switch <model> -f` | Add specific model as fallback only |
  128. | `freeride status` | Check current FreeRide configuration (keys shown masked) |
  129. | `freeride fallbacks` | Update only the fallback models |
  130. | `freeride refresh` | Force refresh the cached model list |
  131. | `freeride rotate` | User is rate-limited / fallback chain is dead — live-test and rebuild (only if FreeRide set the primary) |
  132. | `freeride restore` | Put back the primary and fallbacks from before FreeRide changed them (`--dry-run` to preview) |
  133. **After any command that changes config, always run `openclaw gateway restart`.**
  134. ## What It Writes
  135. FreeRide updates only these keys in `~/.openclaw/openclaw.json`:
  136. - `agents.defaults.model.primary` — e.g. `openrouter/qwen/qwen3-coder:free`
  137. - `agents.defaults.model.fallbacks` — e.g. `["openrouter/openrouter/free", "openrouter/nvidia/nemotron:free", ...]`. Fallbacks the user added themselves are kept, ahead of FreeRide's.
  138. - `agents.defaults.models.<model-ref>` — allowlist entries so `/model` shows the free models. Existing entries are left as they are.
  139. - `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 use `OPENROUTER_API_KEY`; it contains no key.
  140. Everything else (gateway, channels, plugins, env, customInstructions, named agents) is preserved.
  141. 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.
  142. Other files FreeRide writes, all under `~/.openclaw/`:
  143. - `.freeride-state.json` — which primary/fallbacks FreeRide set, and the user's previous ones (for `freeride restore`)
  144. - `.freeride-cache.json` — 6-hour cache of the OpenRouter model list
  145. - `.freeride-watcher-state.json` — watcher rotation count and last reason
  146. - temporary `*.freeride-tmp` / `*.tmp` siblings during atomic writes
  147. FreeRide **never** writes API keys, never writes `~/.openclaw/.env`, and never touches `auth-profiles.json`.
  148. The first fallback is always `openrouter/free` — OpenRouter's smart router that auto-picks the best available model based on the request.
  149. ## Who owns the primary
  150. - A primary set by `freeride auto`, `freeride switch`, `freeride rotate` or the watcher is FreeRide's. FreeRide may rotate it when it fails.
  151. - 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, and `freeride rotate` refuses to touch it.
  152. - `freeride restore` puts back what was there before and hands the primary back to the user.
  153. ## Optional providers (opt-in)
  154. OpenRouter free models stay the default. Only when the user asks, add more free tiers to the fallback chain:
  155. ```bash
  156. freeride auto --providers groq,cerebras
  157. freeride auto --providers groq,gemini --allow-training-providers # Gemini needs explicit consent
  158. freeride auto --providers openrouter # turn them off again
  159. ```
  160. - **Groq** (`GROQ_API_KEY`): tool-capable models only, placed right after `openrouter/free`.
  161. - **Gemini** (`GEMINI_API_KEY` or `GOOGLE_API_KEY`): Flash / Flash-Lite / Gemma only. Google may use prompts on the free tier for training, so it also needs `--allow-training-providers`.
  162. - **Cerebras** (`CEREBRAS_API_KEY`): last in the chain, and only after a live tool-call check passes.
  163. 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.
  164. ## Watcher (Background Daemon)
  165. For autonomous recovery from a "whole chain is rate-limited" deadlock — which
  166. the agent can't fix by itself, since calling `freeride rotate` requires
  167. inference and inference is exactly what's failing — the user can run a slim
  168. background daemon:
  169. ```bash
  170. # Foreground
  171. freeride-watcher
  172. # Persistent background (writes the log file ~/.openclaw/freeride-watcher.log)
  173. nohup freeride-watcher > ~/.openclaw/freeride-watcher.log 2>&1 &
  174. # One-shot check (no loop)
  175. freeride-watcher --once
  176. # State / history
  177. freeride-watcher --status
  178. ```
  179. The daemon probes the current primary every 60s, but only if FreeRide set it;
  180. if it fails, it rebuilds the chain with live-verified models. A primary the
  181. user configured is left alone. Recommend this whenever the user is leaving
  182. an unattended OpenClaw setup running.
  183. ## Troubleshooting
  184. | Problem | Fix |
  185. |---------|-----|
  186. | `freeride: command not found` | `cd ~/.openclaw/workspace/skills/@shaivpidadi/free-ride && pip install -e .` |
  187. | `OPENROUTER_API_KEY not set` | User adds `OPENROUTER_API_KEY=...` to `~/.openclaw/.env` (key from https://openrouter.ai/keys) |
  188. | `... is not plain JSON` | The config has comments or trailing commas. The user removes them, then re-runs. Nothing was written. |
  189. | `rotate` says the primary is not FreeRide's | Expected for a user's own primary. `freeride auto` hands it to FreeRide (old one saved). |
  190. | Want the old model back | `freeride restore --dry-run`, then `freeride restore` |
  191. | Changes not taking effect | `openclaw gateway restart` then `/new` for fresh session |
  192. | Agent shows 0 tokens | Check `freeride status` — primary should be `openrouter/<provider>/<model>:free` |
README.md · README · 422 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 🎢 FreeRide
  2. ### Stop paying for AI. Start riding free.
  3. [![License: MIT-0](https://img.shields.io/badge/License-MIT--0-green.svg)](https://opensource.org/license/mit-0)
  4. [![OpenClaw Compatible](https://img.shields.io/badge/OpenClaw-Compatible-blue.svg)](https://github.com/openclaw/openclaw)
  5. ---
  6. > ## 🚀 Want more than OpenClaw + OpenRouter? Try FreeRide v3
  7. >
  8. > This skill (1.x) is a small config writer: it picks OpenRouter free models
  9. > for OpenClaw and writes them into `openclaw.json`.
  10. > **[FreeRide v3](https://github.com/Shaivpidadi/FreeRideV3)** is a local
  11. > gateway on `localhost:11343` that routes every request across free tiers
  12. > (OpenRouter, Gemini, Groq, Ollama Cloud, Z.ai, NVIDIA NIM, Cloudflare and
  13. > more) and fails over **inside the same response** when one rate-limits.
  14. > It works with OpenClaw, Aider, Continue, Hermes, OpenCode, the Claude /
  15. > Codex / Gemini CLIs, and anything that speaks the OpenAI API.
  16. >
  17. > ```bash
  18. > uv tool install freeride-gateway==0.4.0a28 # or: pipx install freeride-gateway==0.4.0a28
  19. > freeride init # asks for keys, stores them in ~/.freeride/.env
  20. > freeride serve
  21. > freeride bind openclaw # points OpenClaw at the gateway
  22. > ```
  23. >
  24. > See [Should I use v3?](#should-i-use-1x-or-v3) below for the differences before you switch.
  25. > 👉 **Repo:** https://github.com/Shaivpidadi/FreeRideV3 · **Site:** https://free-ride.xyz
  26. ---
  27. **FreeRide** gives you unlimited free AI in [OpenClaw](https://github.com/openclaw/openclaw) by automatically managing OpenRouter's free models.
  28. ```
  29. You: *hits rate limit*
  30. FreeRide: "I got you." *switches to next best model*
  31. You: *keeps coding*
  32. ```
  33. ## The Problem
  34. You're using OpenClaw. You love it. But:
  35. - 💸 API costs add up fast
  36. - 🚫 Free models have rate limits
  37. - 😤 Manually switching models is annoying
  38. - 🤷 You don't know which free model is actually good
  39. ## The Solution
  40. One command. Free AI. Forever.
  41. ```bash
  42. freeride auto
  43. ```
  44. That's it. FreeRide:
  45. 1. **Finds** the 30+ free models on OpenRouter
  46. 2. **Ranks** them by quality (context length, capabilities, speed)
  47. 3. **Sets** the best one as your primary
  48. 4. **Configures** smart fallbacks for when you hit rate limits
  49. 5. **Preserves** your existing OpenClaw config
  50. ## Installation
  51. ```bash
  52. npx clawhub@0.23.3 --workdir ~/.openclaw/workspace install @shaivpidadi/free-ride --version 1.1.0
  53. cd ~/.openclaw/workspace/skills/@shaivpidadi/free-ride
  54. pip install -e .
  55. ```
  56. The command pins the ClawHub CLI version, the skill owner (`@shaivpidadi`), and the skill version. `requests` is capped below 3.
  57. That's it. `freeride` and `freeride-watcher` are now available as global commands.
  58. ## Quick Start
  59. ### 1. Get a Free OpenRouter Key
  60. Go to [openrouter.ai/keys](https://openrouter.ai/keys) → Create account → Generate key
  61. No credit card. No trial. Actually free.
  62. ### 2. Set Your Key
  63. Open `~/.openclaw/.env` in your editor and add a line (OpenClaw reads this file too):
  64. ```
  65. OPENROUTER_API_KEY=<your key>
  66. ```
  67. Several keys are also accepted: `OPENROUTER_API_KEY=["<key 1>","<key 2>"]`. You can export the variable in your shell profile instead.
  68. Don't paste keys into an agent chat or onto a command line, where they end up in history and logs. `freeride status` shows whether a key is set, masked like `sk-or-v1-...abcd`. FreeRide reads keys from the environment, `~/.openclaw/.env`, and the `env` block of `openclaw.json`; it never writes them.
  69. ### 3. Run FreeRide
  70. ```bash
  71. freeride auto
  72. ```
  73. ### 4. Restart OpenClaw
  74. ```bash
  75. openclaw gateway restart
  76. ```
  77. ### 5. Verify It Works
  78. Message your agent on WhatsApp/Telegram/Discord or the dashboard:
  79. ```
  80. You: /status
  81. Agent: (shows the free model name + token count)
  82. ```
  83. Done. You're now running on free AI with automatic fallbacks.
  84. ## What You Get
  85. ```
  86. Primary Model: openrouter/nvidia/nemotron-3-nano-30b-a3b:free (256K context)
  87. Fallbacks:
  88. 1. openrouter/free ← Smart router (auto-picks best available)
  89. 2. qwen/qwen3-coder:free ← Great for coding
  90. 3. stepfun/step-3.5:free ← Fast responses
  91. 4. deepseek/deepseek:free ← Strong reasoning
  92. 5. mistral/mistral:free ← Reliable fallback
  93. ```
  94. When you hit a rate limit, OpenClaw automatically tries the next model. You keep working. No interruptions.
  95. ## Commands
  96. | Command | What it does |
  97. |---------|--------------|
  98. | `freeride auto` | Auto-configure best model + fallbacks |
  99. | `freeride list` | See all 30+ free models ranked |
  100. | `freeride switch <model>` | Use a specific model |
  101. | `freeride status` | Check your current setup |
  102. | `freeride fallbacks` | Update fallbacks only |
  103. | `freeride refresh` | Force refresh model cache |
  104. | `freeride rotate` | Live-test primary; swap to a working model if it's failing (only a primary FreeRide set) |
  105. | `freeride restore` | Put back the primary and fallbacks you had before FreeRide (`--dry-run` to preview) |
  106. ### Pro Tips
  107. ```bash
  108. # Already have a model you like (even a paid one)? Keep it, just add fallbacks.
  109. # FreeRide marks it as yours and never changes it:
  110. freeride auto -f
  111. # Changed your mind? Put back what you had before:
  112. freeride restore --dry-run
  113. freeride restore
  114. # Want more fallbacks for maximum uptime?
  115. freeride auto -c 10
  116. # Coding? Switch to the best coding model:
  117. freeride switch qwen3-coder
  118. # See what's available:
  119. freeride list -n 30
  120. # Always restart OpenClaw after changes:
  121. openclaw gateway restart
  122. ```
  123. ## Optional Providers (opt-in)
  124. OpenRouter free models stay the default, and nothing changes unless you opt in. You can add other free tiers to the fallback chain:
  125. ```bash
  126. freeride auto --providers groq,cerebras
  127. freeride auto --providers groq,gemini --allow-training-providers
  128. freeride auto --providers openrouter # back to OpenRouter only
  129. ```
  130. | Provider | Key | What FreeRide adds | Position |
  131. |----------|-----|--------------------|----------|
  132. | Groq | `GROQ_API_KEY` | A tool-capable free model, e.g. `groq/openai/gpt-oss-120b` | Right after `openrouter/free` |
  133. | Gemini | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | A Flash / Flash-Lite / Gemma model, e.g. `google/gemini-3-flash-preview` | After Groq |
  134. | Cerebras | `CEREBRAS_API_KEY` | A model that passes a live tool-call check | Last |
  135. - **Gemini needs explicit consent** (`--allow-training-providers`). Google may use prompts sent on the unpaid tier to improve its products. EEA/UK/CH accounts are paid-only.
  136. - FreeRide only writes a `groq/`, `google/` or `cerebras/` ref when the OpenClaw plugin is loaded and OpenClaw already lists that model (`openclaw plugins list`, `openclaw models list --provider ...`). Otherwise it skips the provider and prints the `openclaw plugins install ...` command for you to run.
  137. - Put the keys in `~/.openclaw/.env` like the OpenRouter key. FreeRide never writes keys or provider blocks.
  138. - The choice is remembered for later runs and for the watcher. `FREERIDE_PROVIDERS=groq,cerebras` and `FREERIDE_ALLOW_TRAINING=gemini` work the same as the flags.
  139. - The fallback count (`-c`) is still a total: with `-c 5` and all three enabled you get `openrouter/free`, Groq, Gemini, one OpenRouter free model, Cerebras.
  140. ## How It Ranks Models
  141. FreeRide scores each model (0-1) based on:
  142. | Factor | Weight | Why |
  143. |--------|--------|-----|
  144. | Context Length | 40% | Longer = handle bigger codebases |
  145. | Capabilities | 30% | Vision, tools, structured output |
  146. | Recency | 20% | Newer models = better performance |
  147. | Provider Trust | 10% | Google, Meta, NVIDIA, etc. |
  148. The **smart fallback** `openrouter/free` is always first - it auto-selects based on what your request needs.
  149. ## Testing with Your OpenClaw Agent
  150. After running `freeride auto` and `openclaw gateway restart`:
  151. ```bash
  152. # Check OpenClaw sees the models
  153. openclaw models list
  154. # Validate config
  155. openclaw config validate
  156. # Open the dashboard and chat
  157. openclaw dashboard
  158. # Or message your agent on WhatsApp/Telegram/Discord
  159. ```
  160. Useful agent commands to verify:
  161. | Command | What it tells you |
  162. |---------|-------------------|
  163. | `/status` | Current model + token usage |
  164. | `/model` | Available models (your free models should be listed) |
  165. | `/new` | Start fresh session with the new model |
  166. ## Watcher (Background Daemon)
  167. The watcher is a long-running process that probes your current primary model
  168. every minute and rotates the config the moment it starts failing. Because it
  169. runs **outside** the agent's inference loop, it can recover from a "everything
  170. is 429" deadlock that the agent itself can't escape (the agent would need
  171. inference to call `freeride rotate`, but inference is exactly what's broken).
  172. ```bash
  173. # Foreground (good for trying it out)
  174. freeride-watcher
  175. # Background, persistent across logout
  176. nohup freeride-watcher > ~/.openclaw/freeride-watcher.log 2>&1 &
  177. # One-off check (no loop)
  178. freeride-watcher --once
  179. # See state (rotation count, last reason)
  180. freeride-watcher --status
  181. # Custom interval (seconds)
  182. freeride-watcher --interval 120
  183. ```
  184. For an actual service, point your favorite supervisor (launchd, systemd,
  185. tmux, pm2) at `freeride-watcher`. There is no PID file — stop it with
  186. `Ctrl-C` or `kill <pid>`.
  187. The watcher only probes and rotates a primary that FreeRide set. If you set
  188. your own primary (or kept it with `freeride auto -f`), the watcher logs
  189. "primary is user-configured, not touching it" once and leaves it alone. It
  190. never sends test requests to a model you chose.
  191. ## FAQ
  192. **Is this actually free?**
  193. Yes. OpenRouter provides free tiers for many models. You just need an account (no credit card).
  194. **What about rate limits?**
  195. Three layers of defense:
  196. 1. **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.
  197. 2. **`openrouter/free` smart router** is always fallback #1 — server-side smart routing onto whatever free model is actually available.
  198. 3. **`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.
  199. If you've set multiple keys via `OPENROUTER_API_KEY='["key1","key2"]'`, every layer above also rotates through them on 429.
  200. **Will it mess up my OpenClaw config?**
  201. No. FreeRide only touches `agents.defaults.model.primary`, `agents.defaults.model.fallbacks` and entries under `agents.defaults.models`. Your gateway, channels, plugins, workspace, customInstructions - all preserved. Fallbacks you added yourself are kept.
  202. Before every change it saves a copy to `~/.openclaw/openclaw.json.freeride-bak` and writes the new file atomically. If your `openclaw.json` has JSON5 comments or trailing commas, or uses `$include`, FreeRide refuses to write it rather than risk losing anything.
  203. **What exactly does FreeRide write?**
  204. | Path | What |
  205. |------|------|
  206. | `~/.openclaw/openclaw.json` | `agents.defaults.model.primary`, `agents.defaults.model.fallbacks`, `agents.defaults.models.<model-ref>`; `auth.profiles["openrouter:default"]` only with `--setup-auth` (shown first, needs your yes or `--yes`) |
  207. | `~/.openclaw/openclaw.json.freeride-bak` | Copy of your config taken before each write |
  208. | `~/.openclaw/.freeride-state.json` | Which primary/fallbacks FreeRide set, and what you had before |
  209. | `~/.openclaw/.freeride-cache.json` | 6-hour cache of OpenRouter's model list |
  210. | `~/.openclaw/.freeride-watcher-state.json` | Watcher rotation count |
  211. | `*.freeride-tmp`, `*.tmp` | Short-lived files used for atomic writes |
  212. It never writes API keys, never writes `~/.openclaw/.env`, and never touches `auth-profiles.json`. `--setup-auth` adds `{"provider": "openrouter", "mode": "api_key"}`, which only tells OpenClaw to use your `OPENROUTER_API_KEY`.
  213. **I'm upgrading from 1.0.x. What changes for me?**
  214. - The first time you run any command, FreeRide works out who owns your primary. An OpenRouter `:free` model (or `openrouter/free`) counts as FreeRide's; anything else, including a paid model, counts as yours and is saved for `freeride restore`. If you hand-picked a free model and want it left alone, run `freeride auto -f`.
  215. - The watcher and `freeride rotate` stop touching a primary you set.
  216. - If an older FreeRide already replaced your paid primary, it was never saved, so `restore` can't bring it back. Set it again yourself (and then `freeride auto -f` to keep it).
  217. - Nothing else changes unless you opt into extra providers.
  218. **Which models are free?**
  219. Run `freeride list` to see current availability. It changes, which is why FreeRide exists.
  220. **Do I need to restart OpenClaw after changes?**
  221. Yes. Run `openclaw gateway restart` after any FreeRide command that changes your config.
  222. ## The Math
  223. | Scenario | Monthly Cost |
  224. |----------|--------------|
  225. | GPT-4 API | $50-200+ |
  226. | Claude API | $50-200+ |
  227. | OpenClaw + FreeRide | **$0** |
  228. You're welcome.
  229. ## Requirements
  230. - [OpenClaw](https://github.com/openclaw/openclaw) installed (Node ≥22)
  231. - Python 3.8+
  232. - Free OpenRouter account ([get key](https://openrouter.ai/keys))
  233. - Optional: Groq / Gemini / Cerebras keys if you opt into those providers
  234. ## Architecture
  235. ```
  236. ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
  237. │ You │ ──→ │ FreeRide │ ──→ │ OpenRouter API │
  238. │ "freeride │ │ │ │ (30+ free │
  239. │ auto" │ │ • Fetch │ │ models) │
  240. └──────────────┘ │ • Rank │ └──────────────────┘
  241. │ • Configure │
  242. └──────┬───────┘
  243. │
  244. ▼
  245. ┌──────────────┐
  246. │ ~/.openclaw/ │
  247. │ openclaw.json│
  248. └──────┬───────┘
  249. │
  250. openclaw gateway restart
  251. │
  252. ▼
  253. ┌──────────────┐
  254. │ OpenClaw │
  255. │ (free AI!) │
  256. └──────────────┘
  257. ```
  258. ## Should I use 1.x or v3?
  259. | | FreeRide 1.x (this skill) | FreeRide v3 |
  260. |---|---|---|
  261. | What it is | Writes model refs into `openclaw.json`, then gets out of the way | A local gateway process that serves every request |
  262. | Agents | OpenClaw | OpenClaw, Aider, Continue, Hermes, OpenCode, Claude / Codex / Gemini CLIs, any OpenAI-compatible client |
  263. | Providers | OpenRouter free models; Groq, Gemini, Cerebras opt-in | OpenRouter, Gemini, Groq, Ollama Cloud, Z.ai, NVIDIA NIM, Cloudflare, local Ollama and more |
  264. | When a model fails | OpenClaw walks the fallback list; `freeride-watcher` rotates the primary | The gateway retries the next provider inside the same request |
  265. | Runs in the background | Nothing (the watcher is optional) | `freeride serve` must be running |
  266. | Network calls of its own | Only to the model providers | Model providers, plus an hourly aggregate usage beacon that is on by default (`freeride telemetry` shows it, `freeride telemetry off` stops it) |
  267. Stay on 1.x if you only use OpenClaw and want nothing running in the background. Move to v3 if you use other agents, keep hitting OpenRouter's daily limit, or want failover that doesn't depend on a fallback list.
  268. **Switching from 1.x to v3:**
  269. ```bash
  270. freeride restore --dry-run # optional: see what you had before FreeRide
  271. freeride restore # optional: put it back first
  272. pip uninstall freeride # v3 installs its own `freeride` and `freeride-watcher` commands
  273. uv tool install freeride-gateway==0.4.0a28
  274. freeride init && freeride serve
  275. freeride bind openclaw
  276. openclaw gateway restart
  277. ```
  278. Stop `freeride-watcher` from 1.x before you switch. `freeride bind openclaw` adds a `models.providers.freeride` block and an `auth.profiles["freeride:default"]` pointer, and sets the primary to a `freeride/...` ref. FreeRide 1.x treats that primary as yours and never replaces it. v3 also has `freeride auto` / `list` / `switch` for OpenClaw; those follow 1.0.x behavior and don't have 1.1.0's ownership tracking or `restore`.
  279. ## Contributing
  280. Found a bug? Want a feature? PRs welcome.
  281. ```bash
  282. cd ~/.openclaw/workspace/skills/@shaivpidadi/free-ride # skills/free-ride for older installs
  283. # Test commands
  284. freeride list
  285. freeride status
  286. freeride auto --help
  287. # Run the test suite (no network needed)
  288. pip install -e ".[test]"
  289. python -m pytest -q
  290. ```
  291. ## Related Projects
  292. - [OpenClaw](https://github.com/openclaw/openclaw) - The AI coding agent
  293. - [OpenRouter](https://openrouter.ai) - The model router
  294. - [ClawHub](https://github.com/clawhub) - Skill marketplace
  295. ## License
  296. [MIT-0](LICENSE) (MIT No Attribution), the license ClawHub uses for every published skill. Do whatever you want; no attribution needed.
  297. ---
  298. <p align="center">
  299. <b>Stop paying. Start riding.</b>
  300. <br>
  301. <br>
  302. <a href="https://github.com/Shaivpidadi/FreeRide">⭐ Star us on GitHub</a>
  303. ·
  304. <a href="https://openrouter.ai/keys">🔑 Get OpenRouter Key</a>
  305. ·
  306. <a href="https://github.com/openclaw/openclaw">🦞 Install OpenClaw</a>
  307. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.