git:20260506.b9a9593 to v1.1.0

+ version: 1.1.0

+ 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.

+ - name: GROQ_API_KEY

+ description: Optional, only used with --providers groq

+ required: false

+ secret: true

+ - name: GEMINI_API_KEY

+ description: Optional (GOOGLE_API_KEY also accepted), only used with --providers gemini --allow-training-providers

+ required: false

+ secret: true

+ - name: GOOGLE_API_KEY

+ description: Optional alias for GEMINI_API_KEY

+ required: false

+ secret: true

+ - name: CEREBRAS_API_KEY

+ description: Optional, only used with --providers cerebras

+ required: false

+ secret: true

+ - api.groq.com (only with --providers groq)

+ - generativelanguage.googleapis.com (only with --providers gemini)

+ - api.cerebras.ai (only with --providers cerebras)

+ reads:

+ - ~/.openclaw/openclaw.json

+ - ~/.openclaw/.env (API keys, read only)

+ - ~/.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)

+ - ~/.openclaw/openclaw.json.freeride-tmp (temporary, replaced atomically)

+ - ~/.openclaw/openclaw.json.freeride-bak (copy taken before every write)

+ - ~/.openclaw/.freeride-state.json (+ .freeride-tmp sibling)

+ - ~/.openclaw/.freeride-watcher-state.json (+ .tmp sibling)

+ - ~/.openclaw/freeride-watcher.log (only via the suggested nohup redirect)

+ - ~/.openclaw/ (created if missing)

+ never-writes:

+ - API keys, anywhere

+ - ~/.openclaw/.env

+ - auth-profiles.json

+ runs:

+ - openclaw plugins list --json (read only, only with --providers)

+ - openclaw models list --all --provider <id> --json (read only, only with --providers)

+ 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 .

+ ## 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 `env` or `printenv`, or `cat ~/.openclaw/.env`. The user sets keys themselves.

+ - To check whether a key is set, run `freeride status`. It shows keys masked (for example `sk-or-v1-...abcd`) or `NOT SET`.

+ - Before running a command with `--setup-auth`, tell the user what it adds (see below) and only pass `--yes` once they agree.

+ - 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`.

+

+ 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`:

+ OPENROUTER_API_KEY=<their key>

+ ```

+ (or exports it in their own shell). Do not type the key on a command line for them.

+ cd ~/.openclaw/workspace/skills/@shaivpidadi/free-ride # older installs: ~/.openclaw/workspace/skills/free-ride

+ 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.

+

+ | `freeride auto` | User wants free AI set up (most common). Saves their old primary first. |

+ | `freeride status` | Check current FreeRide configuration (keys shown masked) |

+ | `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) |

+ ## What It Writes

+ - `agents.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 `/model` shows 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 use `OPENROUTER_API_KEY`; it contains no key.

+ 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 (for `freeride 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` / `*.tmp` siblings during atomic writes

+

+ FreeRide **never** writes API keys, never writes `~/.openclaw/.env`, and never touches `auth-profiles.json`.

+

+ ## Who owns the primary

+

+ - A primary set by `freeride auto`, `freeride switch`, `freeride rotate` or 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, and `freeride rotate` refuses to touch it.

+ - `freeride restore` puts 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:

+

+ ```bash

+ 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 after `openrouter/free`.

+ - **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`.

+ - **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.

+

+ # Persistent background (writes the log file ~/.openclaw/freeride-watcher.log)

+ 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

+ | `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` |

+