OpenClaw Agent
130 lines
3.4 KiB
Markdown
130 lines
3.4 KiB
Markdown
# OmniRoute — Free Multi-Provider LLM Gateway
|
||
|
||
> Setup reference for OpenClaw agents. Last updated: 2026-08-06
|
||
|
||
## Overview
|
||
|
||
OmniRoute is a free, MIT-licensed AI gateway that aggregates **290+ providers** and **500+ models** through a single OpenAI-compatible endpoint. It provides:
|
||
- Auto-fallback across free tiers (~1.6B free tokens/month)
|
||
- Smart model routing (`auto/best-coding`, `auto/best-fast`, etc.)
|
||
- No API keys needed for local use
|
||
|
||
**Repo:** https://github.com/diegosouzapw/OmniRoute
|
||
**Version:** 3.8.49 (Docker)
|
||
**Local URL:** http://localhost:20128
|
||
|
||
---
|
||
|
||
## Current Deployment (wm's MacBook Pro)
|
||
|
||
### Docker Container
|
||
```bash
|
||
docker run -d \
|
||
--name omniroute-local \
|
||
--restart unless-stopped \
|
||
-p 20128:20128 \
|
||
diegosouzapw/omniroute:latest
|
||
```
|
||
|
||
### OpenClaw Provider Config
|
||
Added to `~/.openclaw/openclaw.json`:
|
||
|
||
```json
|
||
{
|
||
"models": {
|
||
"providers": {
|
||
"omniroute": {
|
||
"api": "openai-completions",
|
||
"baseUrl": "http://localhost:20128/v1",
|
||
"models": [
|
||
{"id": "auto/best-coding", "name": "OmniRoute Best Coding"},
|
||
{"id": "auto/best-fast", "name": "OmniRoute Best Fast"},
|
||
{"id": "auto/best-reasoning", "name": "OmniRoute Best Reasoning"},
|
||
{"id": "auto/best-chat", "name": "OmniRoute Best Chat"}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Fallback Chain
|
||
```json
|
||
{
|
||
"agents": {
|
||
"defaults": {
|
||
"model": {
|
||
"primary": "groq/llama-3.3-70b-versatile",
|
||
"fallbacks": [
|
||
"omniroute/auto/best-coding",
|
||
"omniroute/auto/best-fast",
|
||
"omniroute/auto/best-reasoning"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Available Auto-Routing Models
|
||
|
||
OmniRoute exposes smart `auto/*` prefixes that route to the best available free model:
|
||
|
||
| Prefix | Description | Use Case |
|
||
|---|---|---|
|
||
| `auto/best-coding` | Best free coding model | Code generation, debugging |
|
||
| `auto/best-reasoning` | Best reasoning model | Math, logic, analysis |
|
||
| `auto/best-fast` | Fastest free model | Quick responses, chat |
|
||
| `auto/best-chat` | Best conversational model | General chat |
|
||
| `auto/best-vision` | Best vision model | Image understanding |
|
||
| `auto/cheap` | Cheapest option | High-volume, low-priority |
|
||
|
||
---
|
||
|
||
## CLI Commands Reference
|
||
|
||
### Test OmniRoute directly
|
||
```bash
|
||
openclaw infer model run --model omniroute/auto/best-fast --prompt "Hello" --local
|
||
```
|
||
|
||
### Add more OmniRoute models as fallbacks
|
||
```bash
|
||
openclaw models fallbacks add omniroute/auto/best-chat
|
||
openclaw models fallbacks list
|
||
```
|
||
|
||
### Check OmniRoute health
|
||
```bash
|
||
curl -s http://localhost:20128/v1/models | jq '.data | length'
|
||
```
|
||
|
||
### Restart OmniRoute
|
||
```bash
|
||
docker restart omniroute-local
|
||
```
|
||
|
||
---
|
||
|
||
## Verified Test Results
|
||
|
||
All models tested and passing (2026-08-06):
|
||
|
||
| Model | Latency | Test |
|
||
|---|---|---|
|
||
| `auto/best-coding` | 2624ms | Python reverse string ✅ |
|
||
| `auto/best-fast` | 2270ms | Arithmetic (15×37) ✅ |
|
||
| `auto/best-reasoning` | 2049ms | Train speed/distance problem ✅ |
|
||
|
||
---
|
||
|
||
## Notes for Agents
|
||
|
||
- OmniRoute runs as a Docker container on the host — no API keys required
|
||
- When primary model (Groq) hits rate limits or fails, fallback auto-kicks to OmniRoute
|
||
- OmniRoute internally rotates across free provider tiers to maximize uptime
|
||
- The `auto/*` routing prefix handles provider selection internally — no need to specify individual providers
|
||
- OmniRoute models are NOT listed by `openclaw models list` by default; they are custom provider models
|