freeride

管理来自 OpenRouter for OpenClaw 的免费 AI 模型。按质量自动对模型进行排名，配置速率限制处理的后备，并更新 openclaw.json。当用户提及免费AI、OpenRouter、模型切换、速率限制或希望降低AI成本时使用。

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

## Prerequisites

Before running any FreeRide command, ensure:

1. **OPENROUTER_API_KEY is set.** Check with `echo $OPENROUTER_API_KEY`. If empty, the user must get a free key at https://openrouter.ai/keys and set it:
   ```bash
   export OPENROUTER_API_KEY="sk-or-v1-..."
   # Or persist it:
   openclaw config set env.OPENROUTER_API_KEY "sk-or-v1-..."
   ```

2. **The `freeride` CLI is installed.** Check with `which freeride`. If not found:
   ```bash
   cd ~/.openclaw/workspace/skills/free-ride
   pip install -e .
   ```

## Primary Workflow

When the user wants free AI, run these steps in order:

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

## Commands Reference

| Command | When to use it |
|---------|----------------|
| `freeride auto` | User wants free AI set up (most common) |
| `freeride auto -f` | User wants fallbacks but wants to keep their current primary model |
| `freeride auto -c 10` | User wants more fallbacks (default is 5) |
| `freeride list` | User wants to see available free models |
| `freeride list -n 30` | User wants to see all free models |
| `freeride switch <model>` | User wants a specific model (e.g. `freeride switch qwen3-coder`) |
| `freeride switch <model> -f` | Add specific model as fallback only |
| `freeride status` | Check current FreeRide configuration |
| `freeride fallbacks` | Update only the fallback models |
| `freeride refresh` | Force refresh the cached model list |

**After any command that changes config, always run `openclaw gateway restart`.**

## What It Writes to Config

FreeRide updates only these keys in `~/.openclaw/openclaw.json`:

- `agents.defaults.model.primary` — e.g. `openrouter/qwen/qwen3-coder:free`
- `agents.defaults.model.fallbacks` — e.g. `["openrouter/free", "nvidia/nemotron:free", ...]`
- `agents.defaults.models` — allowlist so `/model` command shows the free models

Everything else (gateway, channels, plugins, env, customInstructions, named agents) is preserved.

The first fallback is always `openrouter/free` — OpenRouter's smart router that auto-picks the best available model based on the request.

## Watcher (Optional)

For auto-rotation when rate limited, the user can run:

```bash
freeride-watcher --daemon    # Continuous monitoring
freeride-watcher --rotate    # Force rotate now
freeride-watcher --status    # Check rotation history
```

## Troubleshooting

| Problem | Fix |
|---------|-----|
| `freeride: command not found` | `cd ~/.openclaw/workspace/skills/free-ride && pip install -e .` |
| `OPENROUTER_API_KEY not set` | User needs a key from https://openrouter.ai/keys |
| Changes not taking effect | `openclaw gateway restart` then `/new` for fresh session |
| Agent shows 0 tokens | Check `freeride status` — primary should be `openrouter/<provider>/<model>:free` |

---

## 中文说明

# FreeRide - 为 OpenClaw 提供免费 AI

## 此技能的作用

配置 OpenClaw 使用来自 OpenRouter 的 **免费** AI 模型。将最佳免费模型设为主模型，添加按排名排序的后备模型，使速率限制不会打断用户，并保留现有配置。

## 前提条件

在运行任何 FreeRide 命令之前，请确保：

1. **已设置 OPENROUTER_API_KEY。** 用 `echo $OPENROUTER_API_KEY` 检查。如果为空，用户必须在 https://openrouter.ai/keys 获取一个免费密钥并设置它：
   ```bash
   export OPENROUTER_API_KEY="sk-or-v1-..."
   # Or persist it:
   openclaw config set env.OPENROUTER_API_KEY "sk-or-v1-..."
   ```

2. **已安装 `freeride` CLI。** 用 `which freeride` 检查。如果未找到：
   ```bash
   cd ~/.openclaw/workspace/skills/free-ride
   pip install -e .
   ```

## 主要工作流

当用户想要免费 AI 时，按顺序运行这些步骤：

```bash
# Step 1: Configure best free model + fallbacks
freeride auto

# Step 2: Restart gateway so OpenClaw picks up the changes
openclaw gateway restart
```

就这样。用户现在拥有了带自动后备切换的免费 AI。

通过让用户发送 `/status` 来检查当前活动模型以进行验证。

## 命令参考

| 命令 | 何时使用 |
|---------|----------------|
| `freeride auto` | 用户想要设置免费 AI（最常见） |
| `freeride auto -f` | 用户想要后备模型但希望保留当前的主模型 |
| `freeride auto -c 10` | 用户想要更多后备模型（默认为 5） |
| `freeride list` | 用户想要查看可用的免费模型 |
| `freeride list -n 30` | 用户想要查看所有免费模型 |
| `freeride switch <model>` | 用户想要某个特定模型（例如 `freeride switch qwen3-coder`） |
| `freeride switch <model> -f` | 仅将特定模型添加为后备 |
| `freeride status` | 检查当前的 FreeRide 配置 |
| `freeride fallbacks` | 仅更新后备模型 |
| `freeride refresh` | 强制刷新缓存的模型列表 |

**在任何更改配置的命令之后，始终运行 `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、命名代理）都会被保留。

第一个后备始终是 `openrouter/free` — OpenRouter 的智能路由器，会根据请求自动挑选最佳可用模型。

## 监视器（可选）

为了在受到速率限制时自动轮换，用户可以运行：

```bash
freeride-watcher --daemon    # Continuous monitoring
freeride-watcher --rotate    # Force rotate now
freeride-watcher --status    # Check rotation history
```

## 故障排查

| 问题 | 修复 |
|---------|-----|
| `freeride: command not found` | `cd ~/.openclaw/workspace/skills/free-ride && pip install -e .` |
| `OPENROUTER_API_KEY not set` | 用户需要一个来自 https://openrouter.ai/keys 的密钥 |
| 更改未生效 | `openclaw gateway restart` 然后 `/new` 开启新会话 |
| 代理显示 0 令牌 | 检查 `freeride status` — 主模型应为 `openrouter/<provider>/<model>:free` |