Free Ride - Unlimited free AI

FreeRide — OpenClaw 的免费 AI 支持方案

此技能的作用

将 OpenClaw 配置为使用来自 [OpenRouter](https://openrouter.ai) 的 免费 AI 模型。自动选取当前最优的免费模型作为主用模型，同时按优先级顺序添加多个备用模型（fallback），确保在遭遇速率限制（rate limit）时服务不中断，并完整保留用户原有的配置。

前置条件

在执行任何 FreeRide 命令前，请确认以下两项均已满足：

1. 已设置 OPENROUTER_API_KEY 环境变量。
   运行 echo $OPENROUTER_API_KEY 检查是否已配置。若输出为空，用户需前往 https://openrouter.ai/keys 免费获取 API Key，并完成设置：

   export OPENROUTER_API_KEY="sk-or-v1-..."
   ## 或持久化写入配置（推荐）：
   openclaw config set env.OPENROUTER_API_KEY "sk-or-v1-..."

2. 已安装 freeride CLI 工具。
   运行 which freeride 检查是否可用。若未找到，请执行：

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

主工作流（推荐流程）

当用户希望启用免费 AI 服务时，请严格按顺序执行以下两步：

## 第一步：自动配置最优免费模型 + 备用链
freeride auto

## 第二步：重启 gateway，使 OpenClaw 加载新配置
openclaw gateway restart

至此即完成部署。用户现已获得具备自动 fallback 切换能力的免费 AI 服务。

验证方式：提示用户向 Bot 发送 /status 指令，查看当前激活的模型名称。

命令参考表

⚠️ 重要提醒：
所有会修改配置的命令执行后，必须立即运行 openclaw gateway restart，否则变更不会生效。

配置文件写入说明

FreeRide 仅修改 ~/.openclaw/openclaw.json 中以下三个键：

• agents.defaults.model.primary — 示例值：openrouter/qwen/qwen3-coder:free
• agents.defaults.model.fallbacks — 示例值：["openrouter/free", "nvidia/nemotron:free", ...]
• agents.defaults.models — 白名单字段，确保 /model 命令中仅显示用户可选的免费模型

其余所有配置项（包括 gateway、channels、plugins、env、customInstructions、命名 Agent 等）均保持原样，不做任何改动。

✅ 补充说明：首个 fallback 永远固定为 openrouter/free —— 这是 OpenRouter 提供的智能路由模型，可根据请求内容动态选择当前最优、可用且免费的底层模型。

Watcher（后台守护进程）

为应对“整条 fallback 链路均被限速”的极端死锁场景（此时 Agent 自身无法调用 freeride rotate，因为推理能力本身已不可用），用户可启动一个轻量级后台守护进程实现自主恢复：

## 前台运行（调试用）
freeride-watcher

## 后台常驻运行（推荐生产环境）
nohup freeride-watcher > ~/.openclaw/freeride-watcher.log 2>&1 &

## 单次检测（非循环，适合脚本集成）
freeride-watcher --once

## 查看当前状态与历史记录
freeride-watcher --status

Watcher 默认每 60 秒探测一次当前主用模型的可用性；一旦发现失效，将自动执行 freeride rotate，基于实时连通性测试重建 fallback 链。
✅ 强烈建议：在用户部署无人值守的 OpenClaw 实例（如长期运行的服务器或自动化工作流）时启用此守护进程。

故障排查指南