FreeRide — OpenClaw 的免费 AI 支持

该技能的作用

将 OpenClaw 配置为使用 OpenRouter 提供的免费 AI 模型：自动将当前最优免费模型设为首选，按优先级添加备用模型以规避速率限制导致的中断，并完整保留用户原有配置。

前置条件

运行任意 FreeRide 命令前，请确保满足以下条件：

1. 已设置 OPENROUTER_API_KEY 环境变量。 使用 echo $OPENROUTER_API_KEY 检查。若为空，用户需前往 https://openrouter.ai/keys 免费获取 API 密钥并完成设置：

   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 时，请按顺序执行以下步骤：

# 步骤 1：自动配置最优免费模型及备用链
freeride auto

# 步骤 2：重启网关，使 OpenClaw 加载新配置
openclaw gateway restart

完成！用户现已启用免费 AI，并支持自动故障转移切换。

可通过提示用户发送 /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 命令可正确列出所有免费模型

其余所有配置项（包括网关、频道、插件、环境变量、customInstructions、命名 agent 等）均保持不变。

首个备用模型始终为 openrouter/free —— 这是 OpenRouter 提供的智能路由模型，可根据请求内容实时选择当前最优可用模型。

Watcher（后台守护进程）

为应对“整条备用链均被限速”这类代理自身无法恢复的死锁场景（因调用 freeride rotate 本身需要推理能力，而推理服务恰恰已不可用），用户可启动一个轻量级后台守护进程：

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

# 后台持久运行
nohup freeride-watcher > ~/.openclaw/freeride-watcher.log 2>&1 &

# 单次探测（不循环）
freeride-watcher --once

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

该守护进程每 60 秒探测一次当前首选模型；若探测失败，则基于实时验证结果重建备用链。建议在用户长期无人值守运行 OpenClaw 的场景下启用此功能。

故障排查