FreeRide Prefix Fix - Free AI for OpenClaw

Fixes OpenClaw's OpenRouter model prefix routing bug for reliable automatic fallback switching using free AI models with proper prefixes.

Security Scan

The code and instructions largely fit the stated purpose (fixing OpenRouter prefix handling and configuring free fallbacks), but there are multiple metadata and packaging inconsistencies and one behaviour (scanning other OpenClaw agent auth files) that deserve explanation before installing.

Purpose & Capability

The skill's code (main.py, watcher.py) implements exactly the advertised behavior: it queries OpenRouter, ranks free models, updates ~/.openclaw/openclaw.json, and optionally runs a watcher to rotate models. However, registry-level metadata provided at the top of the report claims 'Required env vars: none' while the SKILL.md and skill.json both require OPENROUTER_API_KEY. Also packaging/CLI name mismatches exist (README/SKILL.md refer to 'freeride-fix' but setup.py/egg-info install console scripts 'freeride' and 'freeride-watcher'; skill.json claims binaries with '-fix' suffix). These inconsistencies are not obviously malicious but are incoherent and could confuse users during install.

Instruction Scope

Runtime instructions tell the user to set OPENROUTER_API_KEY, pip install the package, and restart OpenClaw. The contained code reads/writes only files under the user's ~/.openclaw directory (openclaw.json, watcher and cache/state files) and makes API calls to OpenRouter. That is within the stated purpose (configuring OpenClaw and probing OpenRouter models). One thing to note: get_api_key() intentionally attempts to auto-detect keys by scanning ~/.openclaw/agents/*/agent/auth-profiles.json; this reads other agent auth files to find an OpenRouter key — functionally convenient but sensitive because it reads other stored credentials in the OpenClaw workspace (it filters for provider == 'openrouter').

Install Mechanism

No remote downloads or obscure installers are used. The recommended install is 'pip install -e .' from the skill folder (local editable install) and the package only depends on requests. setup.py and requirements.txt are present. This is a standard, low-risk install mechanism assuming the package source is trusted. The lack of a centralized install spec in the registry (no install field or contradictory guidance) is a packaging/metadata mismatch but not a direct install risk.

Credentials

The skill legitimately needs an OpenRouter API key to call the OpenRouter API; skill.json and SKILL.md declare OPENROUTER_API_KEY as required. The top-level registry metadata saying 'Required env vars: none' is inconsistent and should be corrected. Additionally, the tool will try to auto-detect an OpenRouter key by reading OpenClaw config and auth-profiles in ~/.openclaw/agents/*/agent/auth-profiles.json; while the code filters for provider == 'openrouter', this behavior reads other files that may contain credentials — users should be aware the skill will attempt to find and use keys stored elsewhere in their OpenClaw workspace.

Persistence & Privilege

The skill does not request 'always: true' and is user-invocable only. It writes state/cache files under ~/.openclaw and modifies ~/.openclaw/openclaw.json to change agents.defaults.model/models — which is exactly its purpose. It also provides a watcher that can be run as a daemon (user must start it). Nothing in the package attempts to change other skills or system-wide agent settings outside the stated OpenClaw config path.

What to consider before installing

What to check before installing: - Metadata mismatches: the registry summary said there are no required env vars, but SKILL.md and skill.json require OPENROUTER_API_KEY — plan to supply that key. Also the README/SKILL.md command names (freeride, freeride-fix) do not match setup.py entry_points and skill.json. Expect to run 'pip install -e .' locally and confirm which console script names were installed. - Key auto-detection: the code will try to locate an OpenRouter key in ~/.openclaw/openclaw.json and in ~/.openclaw/agents/*/agent/auth-profiles.json. This is convenient but means the skill will read other agent auth files in your OpenClaw workspace; if you keep secrets there you should be comfortable with this behavior. - Back up your OpenClaw config: the tool modifies ~/.openclaw/openclaw.json (agents.defaults.model and models). Back up that file before running so you can restore your prior configuration if needed. - Review/run locally first: pip-installing from local source is low-risk, but inspect setup.py/entry_points to confirm the console script names and entrypoints. Run the commands with read-only options (e.g., 'freeride list') before 'auto' to see what it would change. - Watcher behavior: the watcher can run continuously and will call the OpenRouter API to test models and rotate configs. Only run it as a daemon if you want automatic rotations and accept periodic API calls. - Source trust: this is a community fork with source included. If you don't trust the uploader, obtain the original upstream repo (author credited) or review the repository history/commit author. The code presented performs expected network and file io for the feature and contains no obvious exfiltration endpoints, but metadata/packaging inconsistencies warrant extra caution. If you want, I can extract the exact console-scripts installed by setup.py, point out the precise lines that read auth-profiles.json, or produce a short checklist of commands to safely test the skill without making persistent config changes.

📌 This is a community fork of the original FreeRide by Shaishav Pidadi.

What's fixed: Model ID prefix routing in the format_model_for_openclaw() function. The original skill wrote fallback model IDs without the openrouter/ routing prefix, causing OpenClaw to fail with "Unknown model" errors. This fork ensures all specific models are prefixed with openrouter/ while preserving the openrouter/free smart router ID.

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.

Prerequisites

1. OPENROUTER_API_KEY is set:

   export OPENROUTER_API_KEY="sk-or-v1-..."
   # Or persist it:
   openclaw config set env.OPENROUTER_API_KEY "sk-or-v1-..."
   

2. The freeride-fix CLI is installed:

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

Primary Workflow

# Step 1: Configure best free model + fallbacks
freeride-fix auto

# Step 2: Restart gateway
openclaw gateway restart

Commands Reference

Command	When to use it
freeride-fix auto	Auto-select best free model (most common)
freeride-fix auto -f	Add fallbacks only, keep current primary
freeride-fix auto -c 10	More fallbacks (default: 5)
freeride-fix list	List available free models
freeride-fix list -n 30	Show more models
freeride-fix switch <model>	Switch to a specific model
freeride-fix switch <model> -f	Add as fallback only
freeride-fix status	Check current config
freeride-fix fallbacks	Update fallback models
freeride-fix refresh	Refresh model cache

After any config change, run openclaw gateway restart.

The Bug That Was Fixed

Before (broken):

{
  "primary": "openrouter/qwen/qwen3.6-plus-preview:free",  // ✅ had prefix
  "fallbacks": [
    "openrouter/free",                      // ✅ smart router (ID includes prefix)
    "nvidia/nemotron-3-super-120b-a12b:free"  // ❌ missing openrouter/ prefix!
  ]
}

After (fixed):

{
  "primary": "openrouter/qwen/qwen3.6-plus-preview:free",  // ✅
  "fallbacks": [
    "openrouter/free",                      // ✅ preserved (no double-prefix)
    "openrouter/nvidia/nemotron-3-super-120b-a12b:free"  // ✅ correct routing prefix
  ]
}

Code Change (main.py format_model_for_openclaw)

Original (buggy):

if with_provider_prefix:
    return f"openrouter/{base_id}"
return base_id  # ❌ fallbacks get NO prefix → "Unknown model" error

Fixed:

# openrouter/free is already a fully-qualified router ID, don't double-prefix
if model_id in ("openrouter/free", "openrouter/free:free"):
    return "openrouter/free"

# All other specific models need the routing prefix
# Remove existing prefix first, normalize, then add it back
if base_id.startswith("openrouter/"):
    base_id = base_id[len("openrouter/"):]
if append_free and ":free" not in base_id:
    base_id = f"{base_id}:free"

return f"openrouter/{base_id}"  # ✅ always prefixed (except smart router)

Troubleshooting

Problem	Fix
freeride-fix: command not found	cd skills/free-ride-prefix-fix && pip install -e .
OPENROUTER_API_KEY not set	Get a free key at https://openrouter.ai/keys
Changes not taking effect	openclaw gateway restart then /new

Attribution

• Original author: Shaishav Pidadi (FreeRide)
• License: MIT (unchanged from original)
• Fix by: rongtianhua (2026-04-01)