Skip to content

fix(free): the free tier had been dead since June — rebuild it #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
VickyXAI merged 1 commit into from
Aug 31, 2026
Merged

fix(free): the free tier had been dead since June — rebuild it #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 17 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ This is the stack that lets agents operate autonomously: **x402 + USDC + local r

## Quick Start

> **No wallet? <!-- br:models.free -->7<!-- /br:models.free --> models work free out of the box.** Install, run, and pin `free/gpt-oss-120b` (or any of the 7) — no crypto, no signup, no balance required. Add USDC later when you want paid models.
> **No wallet? <!-- br:models.free -->7<!-- /br:models.free --> models work free out of the box.** Install, run, and pin `free/nemotron-3.5-lightning` (or any of the 7) — no crypto, no signup, no balance required. Add USDC later when you want paid models.

### Option A — OpenClaw Agent

Expand Down Expand Up @@ -127,7 +127,7 @@ npx @blockrun/xclawrouter
```

**2. Fund your wallet** — optional, skip for free tier
Your wallet address is printed on first run. For paid models, send a few USDC on Base or Solana — $5 covers thousands of requests. To stay at $0, pin any of the 7 free models (e.g. `free/gpt-oss-120b`) or use `/model free` inside OpenClaw.
Your wallet address is printed on first run. For paid models, send a few USDC on Base or Solana — $5 covers thousands of requests. To stay at $0, pin any of the 7 free models (e.g. `free/nemotron-3.5-lightning`) or use `/model free` inside OpenClaw.

**3. Point your client at `http://localhost:8402`**

Expand Down Expand Up @@ -216,12 +216,12 @@ Choose your routing strategy with `/model <profile>`:
Request → Weighted Scorer (15 dimensions) → Tier → Best Model → Response
```

| Tier | ECO Model | AUTO Model | PREMIUM Model |
| --------- | ----------------------------------- | ------------------------------------- | ---------------------------- |
| SIMPLE | free/gpt-oss-120b (**FREE**) | gemini-2.5-flash ($0.30/$2.50) | kimi-k2.6 |
| MEDIUM | gemini-3.1-flash-lite ($0.25/$1.50) | kimi-k2.5 ($0.60/$3.00) | gpt-5.3-codex ($1.75/$14.00) |
| COMPLEX | gemini-3.1-flash-lite ($0.25/$1.50) | gemini-3.1-pro ($2/$12) | claude-opus-4.6 ($5/$25) |
| REASONING | grok-4-1-fast ($0.20/$0.50) | grok-4-1-fast-reasoning ($0.20/$0.50) | claude-sonnet-4.6 ($3/$15) |
| Tier | ECO Model | AUTO Model | PREMIUM Model |
| --------- | -------------------------------------- | ------------------------------------- | ---------------------------- |
| SIMPLE | free/nemotron-3.5-lightning (**FREE**) | gemini-2.5-flash ($0.30/$2.50) | kimi-k2.6 |
| MEDIUM | gemini-3.1-flash-lite ($0.25/$1.50) | kimi-k2.5 ($0.60/$3.00) | gpt-5.3-codex ($1.75/$14.00) |
| COMPLEX | gemini-3.1-flash-lite ($0.25/$1.50) | gemini-3.1-pro ($2/$12) | claude-opus-4.6 ($5/$25) |
| REASONING | grok-4-1-fast ($0.20/$0.50) | grok-4-1-fast-reasoning ($0.20/$0.50) | claude-sonnet-4.6 ($3/$15) |

**Blended average: $2.05/M** vs $25/M for Claude Opus = **<!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% savings**

Expand Down Expand Up @@ -305,13 +305,13 @@ Edit existing images with `/img2img`:

| Model | Input $/M | Output $/M | ~$/request | Context | Features |
| ------------------------------------------- | --------: | ---------: | ---------: | ------- | -------------------------------------------- |
| free/gpt-oss-120b | **FREE** | **FREE** | **$0** | 128K | default free model |
| free/gpt-oss-20b | **FREE** | **FREE** | **$0** | 128K | smaller, faster |
| free/deepseek-v4-flash | **FREE** | **FREE** | **$0** | 1M | reasoning, ~5x faster than v4-pro |
| free/qwen3-coder-480b | **FREE** | **FREE** | **$0** | 131K | coding |
| free/llama-4-maverick | **FREE** | **FREE** | **$0** | 131K | reasoning |
| free/nemotron-3.5-lightning | **FREE** | **FREE** | **$0** | 1M | reasoning — default free model |
| free/nemotron-3-nano-30b | **FREE** | **FREE** | **$0** | 131K | reasoning, fastest free model (~121 tok/s) |
| free/laguna-xs-2.1 | **FREE** | **FREE** | **$0** | 131K | coding |
| free/north-mini-code | **FREE** | **FREE** | **$0** | 256K | coding |
| free/nemotron-3-nano-omni-30b-a3b-reasoning | **FREE** | **FREE** | **$0** | 256K | reasoning, **vision** (text+img+video+audio) |
| free/glm-4.7 | **FREE** | **FREE** | **$0** | 131K | reasoning |
| free/nemotron-3-ultra-550b | **FREE** | **FREE** | **$0** | 1M | reasoning |
| free/llama-3.2-11b-vision | **FREE** | **FREE** | **$0** | 128K | **vision** |
| openai/gpt-5-nano | $0.05 | $0.40 | $0.0002 | 128K | tools |
| openai/gpt-4.1-nano | $0.10 | $0.40 | $0.0003 | 128K | tools |
| google/gemini-2.5-flash-lite | $0.10 | $0.40 | $0.0003 | 1M | tools |
Expand Down Expand Up @@ -382,7 +382,7 @@ Edit existing images with `/img2img`:
| openai/gpt-5.2-pro | $21.00 | $168.00 | $0.0945 | 400K | reasoning, tools |
| openai/gpt-5.4-pro | $30.00 | $180.00 | $0.1050 | 400K | reasoning, tools |

> **Free tier:** <!-- br:models.free -->7<!-- /br:models.free --> models cost nothing — `/model free` points to gpt-oss-120b, or pick any free model directly (e.g., `/model nemotron-omni` for vision, `/model qwen-coder` for coding, `/model deepseek-v4-flash` for reasoning + 1M context, `/model maverick` for general chat).
> **Free tier:** <!-- br:models.free -->7<!-- /br:models.free --> models cost nothing — `/model free` points to nemotron-3.5-lightning, or pick any free model directly (e.g., `/model nemotron-omni` for vision, `/model north-mini-code` for coding, `/model nemotron-3-ultra-550b` for reasoning + 1M context).
> **Best value:** `gpt-5-nano` and `gemini-2.5-flash-lite` deliver strong results at ~$0.0003/request.

---
Expand Down Expand Up @@ -458,7 +458,7 @@ For basic usage, no configuration needed. For advanced options:
Block specific models from being routed to. Useful if a model doesn't follow your agent instructions or you want to control costs.

```bash
/exclude add free/gpt-oss-120b # Block the default free model
/exclude add free/nemotron-3.5-lightning # Block the default free model
/exclude add grok-4 # Aliases work — blocks all grok-4 variants
/exclude add gpt-5.4 # Skip expensive models
/exclude # Show current exclusions
Expand Down Expand Up @@ -622,7 +622,7 @@ ClawRouter works with any tool that makes OpenAI-compatible API calls — point

### Is ClawRouter free?

ClawRouter itself is free and MIT licensed. You pay only for the LLM API calls routed through it — and several NVIDIA-hosted models (`gpt-oss-120b`, `gpt-oss-20b`, `deepseek-v4-flash`, `qwen3-coder-480b`, `llama-4-maverick`, `nemotron-3-nano-omni-30b-a3b-reasoning`) are completely free. Use `/model free` to smart-route across them, or pick any by name.
ClawRouter itself is free and MIT licensed. You pay only for the LLM API calls routed through it — and several models (`nemotron-3.5-lightning`, `nemotron-3-nano-30b`, `laguna-xs-2.1`, `north-mini-code`, `nemotron-3-nano-omni-30b-a3b-reasoning`, `nemotron-3-ultra-550b`, `llama-3.2-11b-vision`) are completely free. Use `/model free` to smart-route across them, or pick any by name.

---

Expand Down
4 changes: 2 additions & 2 deletions skills/xclawrouter/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ metadata: { "openclaw": { "emoji": "🦀", "requires": { "config": ["models.prov

# XClawRouter

Smart LLM router that saves <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% on inference costs by routing each request to the cheapest model that can handle it. <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models across 9 providers (11 free NVIDIA models), all through one wallet.
Smart LLM router that saves <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% on inference costs by routing each request to the cheapest model that can handle it. <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models across 9 providers (<!-- br:models.free -->7<!-- /br:models.free --> free models), all through one wallet.

## Install

Expand Down Expand Up @@ -55,7 +55,7 @@ Rules handle ~~80% of requests in <1ms. Only ambiguous queries hit the LLM class

## Available Models

<!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models including: gpt-5.5, gpt-5.4, gpt-4o, o3, claude-opus-4.8, claude-opus-4.7, claude-sonnet-4.6, gemini-3.1-pro, gemini-3.5-flash, deepseek-v4-pro, deepseek-chat, grok-4.3, grok-build-0.1, kimi-k2.6, kimi-k2.5, and free NVIDIA-hosted models (gpt-oss-120b [default], gpt-oss-20b, deepseek-v4-flash, qwen3-coder-480b, llama-4-maverick, nemotron-3-nano-omni-30b-a3b-reasoning [vision]).
<!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models including: gpt-5.5, gpt-5.4, gpt-4o, o3, claude-opus-4.8, claude-opus-4.7, claude-sonnet-4.6, gemini-3.1-pro, gemini-3.5-flash, deepseek-v4-pro, deepseek-chat, grok-4.3, grok-build-0.1, kimi-k2.6, kimi-k2.5, and the free models (nemotron-3.5-lightning [default], nemotron-3-nano-30b, laguna-xs-2.1, north-mini-code, nemotron-3-nano-omni-30b-a3b-reasoning [vision], nemotron-3-ultra-550b, llama-3.2-11b-vision [vision]).

## Example Output

Expand Down
10 changes: 5 additions & 5 deletions src/exclude-models.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,12 +81,12 @@ describe("ExcludeModels", () => {
expect(set.size).toBe(1);
});

it("resolves aliases — 'nvidia' becomes 'free/gpt-oss-120b'", () => {
it("resolves aliases — 'nvidia' becomes 'free/nemotron-3.5-lightning'", () => {
const resolved = addExclusion("nvidia", filePath);
expect(resolved).toBe("free/gpt-oss-120b");
expect(resolved).toBe("free/nemotron-3.5-lightning");

const set = loadExcludeList(filePath);
expect(set.has("free/gpt-oss-120b")).toBe(true);
expect(set.has("free/nemotron-3.5-lightning")).toBe(true);
expect(set.size).toBe(1);
});

Expand All @@ -99,8 +99,8 @@ describe("ExcludeModels", () => {
});

it("remove resolves aliases too", () => {
addExclusion("nvidia", filePath); // "nvidia" alias → "free/gpt-oss-120b"
const removed = removeExclusion("gpt-120b", filePath); // different alias for same model
addExclusion("nvidia", filePath); // "nvidia" alias → "free/nemotron-3.5-lightning"
const removed = removeExclusion("free", filePath); // different alias for same model
expect(removed).toBe(true);

const set = loadExcludeList(filePath);
Expand Down
2 changes: 1 addition & 1 deletion src/models.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ describe("resolveModelAlias", () => {
it("strips openai/ prefix from virtual routing profiles (issue #78)", () => {
// OpenClaw sends virtual profiles as "openai/eco", "openai/auto", etc.
expect(resolveModelAlias("openai/eco")).toBe("eco");
expect(resolveModelAlias("openai/free")).toBe("free/gpt-oss-120b"); // "free" is now an alias, not a virtual profile
expect(resolveModelAlias("openai/free")).toBe("free/nemotron-3.5-lightning"); // "free" is now an alias, not a virtual profile
expect(resolveModelAlias("openai/auto")).toBe("auto");
expect(resolveModelAlias("openai/premium")).toBe("premium");
});
Expand Down
107 changes: 101 additions & 6 deletions src/models.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,11 +112,14 @@ export const MODEL_ALIASES: Record<string, string> = {
"xai/grok-3-fast": "xai/grok-4-fast-reasoning", // delisted (too expensive)

// NVIDIA — backward compat aliases (nvidia/xxx → free/xxx)
// Default free model is gpt-oss-120b (heavy user demand). New free models
// added 2026-04-29 — deepseek-v4-pro/flash, nemotron-omni — are additions,
// not replacements. Retired-with-redirect entries below mirror BlockRun
// server-side decommissioning of slow models (nemotron family, etc.).
nvidia: "free/gpt-oss-120b",
// Default free model is nemotron-3.5-lightning as of the 2026-08-31 rebuild;
// gpt-oss-120b held this slot until it died upstream on 2026-08-16. The
// model-specific aliases below still resolve to their original targets even
// where those are retired — the entries stay in BLOCKRUN_MODELS so an
// explicit pin keeps working; they are simply off the picker and the
// auto-pick cascade. Retired-with-redirect entries mirror BlockRun's own
// server-side decommissioning.
nvidia: "free/nemotron-3.5-lightning",
"gpt-120b": "free/gpt-oss-120b",
"gpt-20b": "free/gpt-oss-20b",
"nvidia/gpt-oss-120b": "free/gpt-oss-120b",
Expand Down Expand Up @@ -172,7 +175,7 @@ export const MODEL_ALIASES: Record<string, string> = {
devstral: "free/qwen3-coder-480b",
"devstral-2": "free/qwen3-coder-480b",
maverick: "free/llama-4-maverick",
free: "free/gpt-oss-120b",
free: "free/nemotron-3.5-lightning",

// MiniMax (minimax → current flagship: M3)
minimax: "minimax/minimax-m3",
Expand Down Expand Up @@ -1136,6 +1139,98 @@ export const BLOCKRUN_MODELS: BlockRunModel[] = [
reasoning: true,
vision: true,
},
{
// Nemotron 3.5 Lightning 30B-A3B — the new free default. blockrun's own
// redirect target for the retired step-3.7-flash, so following it keeps the
// proxy and the gateway naming the same model. Served from OpenRouter's $0
// pool (4.9s median vs 16.3s direct) which also publishes a 1M window
// against the 131K the NVIDIA NIM path gives; blockrun carries a hidden
// "-nim" twin as its fallback. Probed 1.3s with tools.
id: "free/nemotron-3.5-lightning",
name: "[Free] Nemotron 3.5 Lightning",
version: "3.5-lightning",
inputPrice: 0,
outputPrice: 0,
contextWindow: 1000000,
maxOutput: 16384,
reasoning: true,
},
{
// Nemotron 3 Nano 30B-A3B — the fastest free model in the catalog
// (~121 tok/s on a realistic workload, not a 16-token ping). Returns
// reasoning_content. Also the tertiary rung of blockrun's own free cascade.
id: "free/nemotron-3-nano-30b",
name: "[Free] Nemotron 3 Nano 30B",
version: "3-nano-30b",
inputPrice: 0,
outputPrice: 0,
contextWindow: 131072,
maxOutput: 16384,
reasoning: true,
},
{
// Poolside Laguna XS 2.1 on OUR NVIDIA key (~161 tok/s). Deliberately not
// the OpenRouter twin, which 429s on every attempt — so this rung and
// north-mini-code sit on DIFFERENT capacity pools, which is why they are
// adjacent in the cascade.
// NOTE: NOT an nvidia/* id upstream — see FREE_UPSTREAM_OVERRIDES in proxy.ts.
id: "free/laguna-xs-2.1",
name: "[Free] Poolside Laguna XS 2.1",
version: "xs-2.1",
inputPrice: 0,
outputPrice: 0,
contextWindow: 131072,
maxOutput: 16384,
},
{
// Cohere North Mini Code, on OpenRouter's $0 pool — 607ms median, the
// fastest thing in the tier. Emits reasoning_content (content is clean once
// the budget is large enough to finish, verified live).
// NOTE: NOT an nvidia/* id upstream — see FREE_UPSTREAM_OVERRIDES in proxy.ts.
id: "free/north-mini-code",
name: "[Free] Cohere North Mini Code",
version: "north-mini-code",
inputPrice: 0,
outputPrice: 0,
contextWindow: 256000,
maxOutput: 16384,
reasoning: true,
},
{
// Nemotron 3 Ultra 550B-A55B — the largest free model ever listed, 1M ctx,
// reachable ONLY through OpenRouter's $0 pool (build.nvidia.com answers 503).
// Deliberately LOW in the cascade: 16.8s on the tools probe, and blockrun
// measured 3 of 15 calls coming back as an HTTP 200 carrying an upstream
// 502/503 error object instead of choices.
id: "free/nemotron-3-ultra-550b",
name: "[Free] Nemotron 3 Ultra 550B",
version: "3-ultra-550b",
inputPrice: 0,
outputPrice: 0,
contextWindow: 1000000,
maxOutput: 16384,
reasoning: true,
},
{
// Meta Llama 3.2 11B Vision — restores a free Llama after nemotron-super-49b
// (Llama-3.3-based) hit NVIDIA's 410 EOL. A 12-model sweep found exactly two
// survivors and only the 11B finishes a real completion. Older than the rest
// of the tier and deliberately so: it is a real Llama that actually answers.
// Slowest in the tier (~18 tok/s) — last rung of the cascade.
id: "free/llama-3.2-11b-vision",
name: "[Free] Llama 3.2 11B Vision",
version: "3.2-11b-vision",
inputPrice: 0,
outputPrice: 0,
contextWindow: 128000,
maxOutput: 16384,
// NO `vision: true` despite the name and blockrun's `categories:
// ["chat","vision"]` — 2026-08-31, three consecutive 64x64 PNG probes came
// back "I'm unable to see the image" / "you haven't provided an image",
// while a plain-text control on the same id answered fine. The model is
// alive; the image path is not. Mirroring the catalog's claim here would
// have routed image turns to it. See the nano-omni note above.
},

// Z.AI GLM-5 Models
{
Expand Down
Loading
Loading