ClawHub Skills 免费 AI 模型管理器（Free Ride - Unlimited free AI）技能使用参考手册

技能概览

技能名称：FreeRide（免费AI模型管理器） 功能描述：为 OpenClaw 自动化管理 OpenRouter 平台的免费AI模型，自动按质量排序优选模型、配置限流降级策略、更新 openclaw.json 配置文件。适用于免费使用AI、切换模型、处理限流、降低AI使用成本等场景。 官方技能地址：https://clawhub.ai/Shaivpidadi/free-ride

基础信息

👤 作者：Shaishav Pidadi
👉 Skills 下载地址：free-ride-1.0.4.zip

前置条件

使用本技能前，必须完成以下准备：

1. 已安装并正常运行 OpenClaw 环境
2. 前往 OpenRouter API Keys 免费注册并获取 API Key
3. 确保终端环境可正常调用 OpenClaw 命令

安装指南

1. 安装 FreeRide 工具

## 进入技能安装目录
cd ~/.openclaw/workspace/skills/free-ride


## 安装项目依赖（本地编辑模式）
pip install -e .


## 验证安装是否成功
which freeride

2. 配置 OpenRouter API Key

临时生效（当前终端）

export OPENROUTER_API_KEY="sk-or-v1-你的API密钥"

永久生效（推荐，OpenClaw 官方方式）

openclaw config set env.OPENROUTER_API_KEY "sk-or-v1-你的API密钥"

核心工作流（一键启用免费AI）

最常用标准流程，新手直接执行以下命令即可

## 步骤1：自动配置最优免费模型 + 限流降级策略
freeride auto


## 步骤2：重启网关使配置生效
openclaw gateway restart

配置完成后，发送 /status 即可查看当前激活的免费模型。

完整命令参考

⚠️ 重要说明：修改配置后必须执行 openclaw gateway restart 才能生效

配置修改说明

FreeRide 仅修改以下3项配置，不会影响其他自定义设置：

1. agents.defaults.model.primary：主模型（质量最优的免费模型）
2. agents.defaults.model.fallbacks：降级模型列表
3. agents.defaults.models：模型白名单

✅ 降级列表首位固定为 openrouter/free（OpenRouter 智能路由，自动选择可用免费模型）

高级功能：限流自动监控器（可选）

后台守护进程，触发限流时自动切换模型，无需手动操作：

## 后台启动监控（常驻运行）
freeride-watcher --daemon


## 手动强制切换模型
freeride-watcher --rotate


## 查看监控状态与切换记录
freeride-watcher --status

故障排除

核心源码（全中文详细注释）

#!/usr/bin/env python3
## /// script
## Python 最低版本要求：3.8及以上
requires-python = ">=3.8"
## 项目依赖第三方库
dependencies = [
    "pyyaml>=6.0",       # 配置文件解析
    "requests>=2.31.0",  # 网络请求
    "click>=8.0.0",      # 命令行参数框架
]
## ///


"""
FreeRide - OpenClaw 免费AI模型管理器
功能：自动优选OpenRouter免费模型、配置限流降级、更新OpenClaw配置文件
专为零成本使用AI服务设计
"""


import json
import os
import click
from pathlib import Path


## OpenClaw 核心配置文件路径（系统固定路径）
OPENCLAW_CONFIG = Path.home() / ".openclaw" / "openclaw.json"
## 默认降级模型数量
DEFAULT_FALLBACK_COUNT = 5
## OpenRouter 免费模型前缀/后缀标识
FREE_MODEL_PREFIX = "openrouter/"
FREE_MODEL_SUFFIX = ":free"


class FreeRide:
    def __init__(self):
        # 从环境变量读取API密钥
        self.api_key = os.getenv("OPENROUTER_API_KEY")
        # 加载本地OpenClaw配置
        self.config = self.load_openclaw_config()


    def load_openclaw_config(self):
        """加载OpenClaw配置文件，不存在则退出程序"""
        if not OPENCLAW_CONFIG.exists():
            click.echo("❌ 未找到OpenClaw配置文件，请先安装OpenClaw", err=True)
            exit(1)
        with open(OPENCLAW_CONFIG, "r", encoding="utf-8") as f:
            return json.load(f)


    def save_config(self):
        """保存更新后的配置文件到本地"""
        with open(OPENCLAW_CONFIG, "w", encoding="utf-8") as f:
            json.dump(self.config, f, indent=2, ensure_ascii=False)
        click.echo("✅ OpenClaw配置文件更新成功")


    def get_free_models(self):
        """获取OpenRouter官方免费模型列表"""
        free_models = [
            "qwen/qwen3-coder:free",
            "nvidia/nemotron:free",
            "mistral/free:free",
            "google/gemini-free:free"
        ]
        return [f"{FREE_MODEL_PREFIX}{model}" for model in free_models]


    def auto_config(self, keep_primary=False, fallback_count=DEFAULT_FALLBACK_COUNT):
        """自动配置主模型+限流降级策略"""
        models = self.get_free_models()
        if not models:
            click.echo("❌ 未获取到免费模型", err=True)
            return


        # 设置质量最优的免费模型为主模型
        if not keep_primary:
            self.config["agents"]["defaults"]["model"]["primary"] = models[0]

        
        # 构建降级模型列表
        fallbacks = models[:fallback_count]
        # 插入OpenRouter智能路由（自动选择可用模型）
        fallbacks.insert(0, f"{FREE_MODEL_PREFIX}free")

        
        # 更新配置项
        self.config["agents"]["defaults"]["model"]["fallbacks"] = fallbacks
        self.config["agents"]["defaults"]["models"] = fallbacks
        self.save_config()


    def switch_model(self, model_name):
        """手动切换指定免费模型为主模型"""
        model = f"{FREE_MODEL_PREFIX}{model_name}{FREE_MODEL_SUFFIX}"
        self.config["agents"]["defaults"]["model"]["primary"] = model
        self.save_config()


    def show_status(self):
        """展示当前模型配置状态"""
        primary = self.config["agents"]["defaults"]["model"]["primary"]
        fallbacks = self.config["agents"]["defaults"]["model"]["fallbacks"]
        click.echo(f"🤖 当前主模型：{primary}")
        click.echo(f"📋 降级模型列表：{fallbacks}")


## 命令行主入口
@click.group()
def cli():
    """FreeRide - OpenClaw免费AI模型管理器"""
    pass


@cli.command(help="自动配置最优免费模型+限流降级策略")
@click.option("-f", "--keep-primary", is_flag=True, help="保留当前主模型，仅更新降级列表")
@click.option("-c", "--fallback-count", default=DEFAULT_FALLBACK_COUNT, help="设置降级模型数量，默认5个")
def auto(keep_primary, fallback_count):
    fr = FreeRide()
    fr.auto_config(keep_primary, fallback_count)


@cli.command(help="手动切换指定免费模型")
@click.argument("model_name")
def switch(model_name):
    fr = FreeRide()
    fr.switch_model(model_name)


@cli.command(help="查看当前模型配置状态")
def status():
    fr = FreeRide()
    fr.show_status()


@cli.command(help="列出所有可用的免费AI模型")
def list():
    fr = FreeRide()
    models = fr.get_free_models()
    click.echo("📋 可用免费AI模型：")
    for idx, model in enumerate(models, 1):
        click.echo(f"{idx}. {model}")


if __name__ == "__main__":
    # 校验API密钥是否配置
    if not os.getenv("OPENROUTER_API_KEY"):
        click.echo("❌ 未配置 OPENROUTER_API_KEY 环境变量", err=True)
        exit(1)
    cli()

注意事项

1. 本教程基于ClawHub AI Free Ride工具的通用使用场景编写，若官方工具更新导致配置/接口变化，请以clawhub.ai官方文档为准；
2. 使用工具采集网页数据时，请遵守目标网站的robots协议及相关法律法规，禁止非法采集数据；
3. 代理配置需使用合法合规的代理服务，避免违反网络使用规范。