freeride

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

# FreeRide - Free AI for OpenClaw

Configures OpenClaw to use free AI models from OpenRouter with automatic fallback switching.

## Quick Start

```bash
# Set API key (free at openrouter.ai/keys)
export OPENROUTER_API_KEY="sk-or-v1-..."

# Auto-configure best model + fallbacks
freeride auto
```

## Commands

### `list` - View available models

```bash
freeride list              # Top 15 models
freeride list -n 30        # More models
freeride list --refresh    # Force API refresh
```

### `auto` - Auto-configure

```bash
freeride auto              # Best model + 5 fallbacks
freeride auto -f           # Fallbacks only (keep current primary)
freeride auto -c 10        # 10 fallbacks
freeride auto --setup-auth # Also configure auth profile
```

### `switch` - Set specific model

```bash
freeride switch qwen3-coder         # Set as primary
freeride switch deepseek -f         # Add to fallbacks only
freeride switch nvidia/nemotron --no-fallbacks
```

### `status` - Check configuration

```bash
freeride status
```

### `fallbacks` - Update fallbacks only

```bash
freeride fallbacks         # 5 fallbacks
freeride fallbacks -c 10   # 10 fallbacks
```

### `refresh` - Update model cache

```bash
freeride refresh
```

## Behavior

**Primary model**: Best specific model (not router) for consistent responses.

**First fallback**: Always `openrouter/free` - OpenRouter's smart router that auto-selects based on request features (vision, tools, etc.).

**Additional fallbacks**: Ranked by quality score.

**Config preservation**: Only updates model-related sections; preserves gateway, channels, plugins, etc.

## Model Ranking

Score (0-1) based on:
- Context length (40%)
- Capabilities (30%)
- Recency (20%)
- Provider trust (10%)

## Flags

| Flag | Commands | Description |
|------|----------|-------------|
| `-f` | switch, auto | Fallback only, keep primary |
| `-c N` | auto, fallbacks | Number of fallbacks |
| `--no-fallbacks` | switch | Skip fallback configuration |
| `--setup-auth` | switch, auto | Add OpenRouter auth profile |
| `-n N` | list | Models to display |
| `-r` | list | Force refresh |

## Config Output

Updates `~/.openclaw/openclaw.json`:

```json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/qwen/qwen3-coder:free",
        "fallbacks": [
          "openrouter/free:free",
          "nvidia/nemotron-3-nano-30b-a3b:free"
        ]
      }
    }
  }
}
```

## Troubleshooting

**"OPENROUTER_API_KEY not set"**: Export the key or add to shell profile.

**Config not updating**: Check file permissions on `~/.openclaw/openclaw.json`.

**Changes not taking effect**: Restart OpenClaw.

---

## 中文说明

# FreeRide - Free AI for OpenClaw

将 OpenClaw 配置为使用来自 OpenRouter 的免费 AI 模型，并自动切换后备。

## 快速开始

```bash
# Set API key (free at openrouter.ai/keys)
export OPENROUTER_API_KEY="sk-or-v1-..."

# Auto-configure best model + fallbacks
freeride auto
```

## 命令

### `list` - 查看可用模型

```bash
freeride list              # Top 15 models
freeride list -n 30        # More models
freeride list --refresh    # Force API refresh
```

### `auto` - 自动配置

```bash
freeride auto              # Best model + 5 fallbacks
freeride auto -f           # Fallbacks only (keep current primary)
freeride auto -c 10        # 10 fallbacks
freeride auto --setup-auth # Also configure auth profile
```

### `switch` - 设置特定模型

```bash
freeride switch qwen3-coder         # Set as primary
freeride switch deepseek -f         # Add to fallbacks only
freeride switch nvidia/nemotron --no-fallbacks
```

### `status` - 检查配置

```bash
freeride status
```

### `fallbacks` - 仅更新后备

```bash
freeride fallbacks         # 5 fallbacks
freeride fallbacks -c 10   # 10 fallbacks
```

### `refresh` - 更新模型缓存

```bash
freeride refresh
```

## 行为

**主模型**：最佳的特定模型（非路由器），以获得一致的响应。

**首个后备**：始终为 `openrouter/free` —— OpenRouter 的智能路由器，根据请求特性（视觉、工具等）自动选择。

**额外后备**：按质量分数排名。

**配置保留**：仅更新与模型相关的部分；保留 gateway、channels、plugins 等。

## 模型排名

分数（0-1）基于：
- 上下文长度（40%）
- 能力（30%）
- 新近度（20%）
- 提供商信任度（10%）

## 标志

| 标志 | 命令 | 说明 |
|------|----------|-------------|
| `-f` | switch, auto | 仅后备，保留主模型 |
| `-c N` | auto, fallbacks | 后备数量 |
| `--no-fallbacks` | switch | 跳过后备配置 |
| `--setup-auth` | switch, auto | 添加 OpenRouter 认证配置 |
| `-n N` | list | 要显示的模型数 |
| `-r` | list | 强制刷新 |

## 配置输出

更新 `~/.openclaw/openclaw.json`：

```json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/qwen/qwen3-coder:free",
        "fallbacks": [
          "openrouter/free:free",
          "nvidia/nemotron-3-nano-30b-a3b:free"
        ]
      }
    }
  }
}
```

## 故障排查

**“OPENROUTER_API_KEY not set”**：导出该密钥或将其添加到 shell 配置文件。

**配置未更新**：检查 `~/.openclaw/openclaw.json` 的文件权限。

**更改未生效**：重启 OpenClaw。