# OmniRoute: a backup plan when your AI hits its limit

Full guide: https://www.skoa.online/blog/omniroute-chatgpt-claude/

OmniRoute 3.8.50 · Node.js 24 LTS · Reviewed 2026-09-21

## The problem we solve

Your tool always requests `work-backup`. OmniRoute tries a primary model and can switch to a backup after a recoverable failure such as a 429. You need two valid connections with access and available quota. It does not expand subscriptions or refill balances.

## 1. Start locally

macOS / Linux:

```sh
export OMNIROUTE_SERVER_HOST=127.0.0.1
npx omniroute@3.8.50 --no-open --no-tray
```

Windows PowerShell:

```powershell
$env:OMNIROUTE_SERVER_HOST="127.0.0.1"
npx omniroute@3.8.50 --no-open --no-tray
```

Open http://localhost:20128 and keep the terminal running. On a fresh installation of this version, sign in with CHANGEME and change the password in Settings → Security before adding accounts. Use your existing password for a previously configured installation.

## 2. Two working connections

GPT + Claude route: Providers → OpenAI → Add Connection, with an OpenAI Platform key; Providers → Anthropic → Add Connection, with a Claude Console key. Both APIs have separate billing. Check prices and limits before testing.

OpenAI Codex → OAuth also exists for accounts with Codex access through ChatGPT. This is an OmniRoute connector, subject to compatibility, quotas and provider conditions; it does not turn all of ChatGPT into an API. Your backup can be another independent provider or a compatible local model you already run.

OmniRoute includes a Claude Code OAuth connector, but its existence does not authorize every use case. Anthropic does not permit third-party developers to route Free/Pro/Max plans on behalf of their users. Use the Anthropic API for application integration; do not copy cookies or tokens.

Test each model individually in Playground and inspect Request Logs. A text response alone does not establish compatibility with an agent’s tools.

## 3. Create the combo

1. Combos → Create Combo.
2. Basics: name `work-backup` → Next.
3. Steps: choose provider, model and account; Add step. Primary first, backup second.
4. Strategy: Priority (`priority`). Keep the other initial options.
5. Review: check and save both steps.

Use the exact combo name as the model. `auto` is a separate mechanism; it does not automatically call this combo.

## 4. Use it from the same tool

Create a key in OmniRoute’s API Keys. It differs from your provider key.

- OpenAI-compatible app base URL: http://localhost:20128/v1
- API Key: your OmniRoute key
- Model: `work-backup`

Test on macOS / Linux:

```sh
curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer YOUR_OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"work-backup","messages":[{"role":"user","content":"Explain an API in two sentences."}],"stream":false}'
```

Windows PowerShell:

```powershell
$headers = @{ Authorization = "Bearer YOUR_OMNIROUTE_KEY" }
$body = @{
  model = "work-backup"
  messages = @(@{ role = "user"; content = "Explain an API in two sentences." })
  stream = $false
} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Uri "http://localhost:20128/v1/chat/completions" -Method Post -Headers $headers -ContentType "application/json" -Body $body
```

Check `choices[0].message.content` and the provider/model in the logs.

Claude Code needs compatible Claude destinations; Anthropic does not support non-Claude models through gateways. Its native base URL is http://localhost:20128, without /v1. For Codex CLI, verify that your provider supports the client’s protocol and tools.

## 5. Validate the backup

Create a copy named `backup-check`, remove the primary only from that copy and repeat the request with `model: backup-check`. The backup should answer. This checks the backup path; it does not simulate a 429. Keep both steps in `work-backup`.

SKOA also verified a controlled failure with real OmniRoute and two simulated HTTP services: primary 429 → backup 200 → client receives BACKUP_OK. No ChatGPT/Claude accounts were connected and no paid API usage was consumed.

## Limits that matter

- Two keys in one project can share a quota.
- An oversized context or a truncated response is different from an exhausted quota.
- The backup needs compatible context, tools and formats; it may be slower or cost more.
- Do not assume continuity in the middle of an already-started response.
- Messages can reach any provider included in your combo.
- The tool must be able to reach `localhost`; inside Docker, it points at that container.
- Ctrl+C stops the gateway; repeat startup to use it again. Configuration persists.

## What about OpenRouter?

OpenRouter is hosted and also supports fallback. OmniRoute runs under your control and groups your connections. You can use OpenRouter as an OmniRoute provider, but you do not need both if one already solves your problem.

## Sources

- https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/docs/routing/AUTO-COMBO.md
- https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/docs/guides/USAGE_QUOTA_GUIDE.md
- https://developers.openai.com/codex/auth/
- https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use
- https://code.claude.com/docs/en/llm-gateway
- https://openrouter.ai/docs/guides/routing/model-fallbacks