/FreeRide

name: freeride
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.
env:
  - name: OPENROUTER_API_KEY
    description: OpenRouter API key — get a free one at openrouter.ai/keys
    required: true
    secret: true
  - 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
network:
  - openrouter.ai
  - 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)
writes:
  - ~/.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-cache.json
  - ~/.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 .
metadata:
  openclaw:
    emoji: "\U0001F3A2"
    homepage: https://github.com/Shaivpidadi/FreeRide
    requires:
      env:
        - OPENROUTER_API_KEY
      bins:
        - openclaw
      anyBins:
        - python3
        - python
    primaryEnv: OPENROUTER_API_KEY
    envVars:
      - name: OPENROUTER_API_KEY
        required: true
        description: OpenRouter API key, free at openrouter.ai/keys. Set it in ~/.openclaw/.env, never in chat.
      - name: GROQ_API_KEY
        required: false
        description: Groq key, used only with --providers groq.
      - name: GEMINI_API_KEY
        required: false
        description: Gemini key, used only with --providers gemini --allow-training-providers.
      - name: GOOGLE_API_KEY
        required: false
        description: Alias for GEMINI_API_KEY.
      - name: CEREBRAS_API_KEY
        required: false
        description: Cerebras key, used only with --providers cerebras.
      - name: FREERIDE_PROVIDERS
        required: false
        description: Same as --providers (e.g. groq,cerebras). Unset means OpenRouter only.
      - name: FREERIDE_ALLOW_TRAINING
        required: false
        description: Same as --allow-training-providers (e.g. gemini).

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

Prerequisites

Before running any FreeRide command, ensure:

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.

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

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