Stop overpaying for AI. Route every request to the right model β automatically, with your own API keys. No middleman, no markup.
You already have API keys. Why pay someone else to use them?
| Pain | How FreeRouter Fixes It |
|---|---|
| πΈ Middleman markup β OpenRouter and similar services charge on top of provider prices | Zero markup. Self-hosted, runs locally. You pay providers directly. |
| π₯ Every message hits your expensive model β Opus at 75γγ«/M output tokens for "hello"? | 14-dimension classifier routes simple messages to cheap models automatically. Save 60-80%. |
| π° No control over routing β auto-classifiers get it wrong sometimes | Mode overrides. Prefix /max or [simple] to force a tier when you know better. |
| β³ Proxies that hang β upstream is slow, your app freezes | Request timeouts + auto-fallback. Times out β retries with fallback model. |
| π§ Hardcoded configs β want to change a model? Edit source code, recompile, restart | External config file. Edit JSON, hit /reload-config. No restart needed. |
- Smart routing β 14-dimension weighted classifier scores every request and picks the best model
- Mode overrides (new in v1.3.0) β force a tier with
/max,/simple,[complex],deep mode:etc. - Zero cost β no subscription, no per-token fees, no payment layer
- External config β
freerouter.config.jsonfor providers, tiers, boundaries, auth - Request timeouts β per-tier timeouts with automatic fallback to secondary model
- Tool call translation β bidirectional Anthropic β OpenAI format translation
- OpenAI-compatible API β drop-in replacement; works with any client that speaks
/v1/chat/completions - 75/75 test suite β core routing, streaming, tool calls, unicode, concurrency, mode overrides
Your App β FreeRouter (:18800) β Classifier β Best Model
βββ SIMPLE β Kimi K2.5 (near-zero cost)
βββ MEDIUM β Sonnet 4.5 (balanced)
βββ COMPLEX β Opus 4.6 (powerful)
βββ REASONING β Opus 4.6 (max thinking)
The classifier scores each message on 14 dimensions (vocabulary complexity, reasoning depth, code complexity, domain specificity, etc.) and routes to the cheapest model that can handle it. Context-aware β includes last 3 messages in scoring.
Sometimes you know better than the classifier. Prefix your prompt to force a tier:
/simple What's 2+2?
/max Analyze this distributed system architecture for race conditions
/reasoning Prove that P(A|B) = P(B|A)P(A)/P(B)
[complex] Refactor this module to use dependency injection
[simple] Translate "hello" to French
deep mode: Why does this recursive CTE produce duplicates?
basic mode, What time is it in Tokyo?
| Aliases | Routes to |
|---|---|
simple, basic, cheap |
SIMPLE β cheapest model |
medium, balanced |
MEDIUM β general purpose |
complex, advanced |
COMPLEX β powerful model |
max, reasoning, think, deep |
REASONING β maximum thinking |
The prefix is stripped before forwarding β the LLM never sees it. When no prefix is detected, normal classification runs.
git clone https://github.com/openfreerouter/freerouter.git
cd freerouter
npm install
npx tscCopy and edit the config file:
cp freerouter.config.json ~/.config/freerouter/config.json # Edit providers, API keys, tier mappings
Or set API keys via environment variables. See Configuration below.
node dist/src/server.js
# Listening on http://localhost:18800Point any OpenAI-compatible client at http://localhost:18800/v1/chat/completions.
# Health check curl http://localhost:18800/health # Chat curl http://localhost:18800/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'
FreeRouter looks for config in this order:
FREEROUTER_CONFIGenvironment variable./freerouter.config.json(working directory)~/.config/freerouter/config.json
If no config file exists, built-in defaults apply.
{
"providers": {
"anthropic": { "baseUrl": "https://api.anthropic.com", "api": "anthropic" },
"kimi": { "baseUrl": "https://api.moonshot.cn", "api": "openai" }
},
"tiers": {
"SIMPLE": { "model": "kimi-for-coding", "provider": "kimi", "fallback": "claude-haiku-4-5-20250315" },
"MEDIUM": { "model": "claude-sonnet-4-5-20250514", "provider": "anthropic" },
"COMPLEX": { "model": "claude-opus-4-0-20250115", "provider": "anthropic" },
"REASONING": { "model": "claude-opus-4-0-20250115", "provider": "anthropic" }
}
}Reload without restart: curl http://localhost:18800/reload-config
Add to your openclaw.json:
{
"providers": {
"freerouter": {
"baseUrl": "http://localhost:18800",
"api": "openai-completions",
"models": [{ "id": "auto" }]
}
},
"agents": {
"defaults": { "model": "freerouter/auto" }
}
}| Endpoint | Description |
|---|---|
POST /v1/chat/completions |
Main chat endpoint (OpenAI-compatible) |
GET /health |
Health check with uptime and timeout count |
GET /stats |
Request statistics by tier |
GET /v1/models |
List available models |
GET /config |
View current config (secrets redacted) |
POST /reload |
Reload auth keys |
POST /reload-config |
Reload config file |
Each message is scored across 14 dimensions:
| Dimension | What It Measures |
|---|---|
| Token count | Message length |
| Vocabulary complexity | Rare/technical words |
| Syntax complexity | Nested clauses, conditionals |
| Domain specificity | Specialized knowledge needed |
| Ambiguity | How open-ended the request is |
| Context dependency | Needs prior conversation |
| Reasoning depth | Logical steps required |
| Creativity level | Original generation needed |
| Emotional complexity | Nuance in tone/sentiment |
| Multimodality | References to images/files |
| Instruction complexity | Multi-step instructions |
| Knowledge recency | Needs current information |
| Code complexity | Programming difficulty |
| Mathematical complexity | Formal math/proofs |
Scores are weighted and combined. Tier boundaries are configurable.
| Scenario | Estimated Daily Cost |
|---|---|
| All Opus (no routing) | ~50γγ«/day |
| With FreeRouter | ~10γγ«-15/day |
| Savings | 60-80% |
Most messages are simple. Those go to Kimi at near-zero cost. Only complex work hits Opus.
freerouter/
βββ src/
β βββ server.ts # HTTP server + mode override detection
β βββ provider.ts # Multi-provider forwarding + SSE translation
β βββ auth.ts # API key management
β βββ config.ts # External config loader
β βββ logger.ts # Request logging
β βββ router/
β βββ index.ts # 14-dimension classifier
β βββ config.ts # Tier mappings + scoring weights
β βββ rules.ts # Keyword-based overrides
βββ tests/
β βββ test-proxy.sh # Core tests (33 + 5 mode override tests)
β βββ test-proxy-extended.sh # Extended tests (37)
βββ freerouter.config.json # Example config
βββ tsconfig.json
βββ package.json
Forked from BlockRunAI/ClawRouter (MIT License). Routing engine preserved; x402 payment protocol removed entirely. Credit to BlockRunAI for the original classifier design.