OmniRoute + Claude Code: setup, free-tier limits, and CCSub as a fallback provider

OmniRoute is an open-source local AI gateway (MIT licence, code on GitHub). It runs a service on your machine; Claude Code, Codex, Cursor and other tools send requests to it, and it routes them to providers by rules you set: use free tiers first, and move to the next provider when quota runs out or a request fails.

Most people searching for OmniRoute have seen a "use Claude Code for free" video. This guide covers three things: how to set it up, the real limits of the free tiers, and how to add CCSub as a paid fallback.

Install OmniRoute

Install Node.js first, then pick one method:

On first run, omniroute setup walks you through the basics and omniroute doctor runs a self-check. npm 11 and later may block install scripts; reinstall with the --allow-scripts list given in the OmniRoute README.

Point Claude Code at OmniRoute

Claude Code is configured through environment variables only; there is no base URL flag. Set three:

If you would rather not set variables by hand, OmniRoute ships two commands:

• omniroute launch starts Claude Code with your current OmniRoute settings.
• omniroute setup-claude writes per-model profiles to ~/.claude/profiles/<name>/settings.json; start one with omniroute launch --profile <name>. Run it with --dry-run first to see which files it will write.

To pick OmniRoute models from the /model list, you need Claude Code v2.1.129 or later and CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1. The list only shows model IDs starting with claude or anthropic; set anything else with ANTHROPIC_MODEL.

What "free" really means

OmniRoute itself costs nothing, but the free quota it routes to belongs to third parties:

• The numbers are estimates. The README's roughly 1.62 billion free tokens a month and 150+ free tiers are OmniRoute's own sum of other providers' free tiers, not quota it grants. Each provider sets its own quotas and rate limits and can change them at any time.
• A fresh install may have no usable route. The auto model needs at least one eligible route. Right after install, before you connect any accounts, there may be none, and some keyless services reject third-party clients.
• Some providers are off by default. Providers that OmniRoute flags as risky under their terms are excluded from automatic routing, even if you connect an account.
• Free models are not the model you are used to. Most free tiers serve other vendors' models. Whether Claude Code's tool calls and long contexts run reliably on them is something you need to test yourself.

In practice, small tasks often fit in free quota, while long tasks hit a limit or a rate cap halfway through. That is when you want a paid provider to take over, which is what the next section sets up.

Add CCSub as an OmniRoute provider

OmniRoute supports custom Anthropic Compatible and OpenAI Compatible providers, and CCSub works with both. Claude Code speaks the Anthropic format, so use the first:

1. In the OmniRoute dashboard open Providers and click Add Anthropic Compatible.
2. Fill in the form and save:

3. Open the new CCSub provider, click Add Connection, paste the key you created in the CCSub dashboard (it starts with sk-) into API Key, save, and test the connection.
4. Models are now named ccsub/model, for example ccsub/claude-sonnet-5. All model IDs are on the models page.

To use GPT models through OmniRoute as well, add an Add OpenAI Compatible provider with the same Base URL https://www.ccsub.net/v1 and API type Chat Completions.

Fall back to CCSub when free quota runs out

An OmniRoute combo is an ordered list of models. Use the priority strategy, put free models first and CCSub last:

omniroute combo create cc-fallback \
  --strategy priority \
  --targets <your-free-model>,ccsub/claude-sonnet-5

Then set Claude Code's ANTHROPIC_MODEL to the combo name, cc-fallback. When the providers ahead of CCSub run out of quota, get rate-limited or fail, requests land on CCSub and the task keeps going. You can also build the combo on the Combos page of the dashboard; use the target format your version's Combos page shows.

Check that it works

• The OmniRoute request log shows which provider served each request.
• Requests that went to CCSub also appear on the Usage page of the CCSub dashboard, with matching token counts and charges.
• /status inside Claude Code shows the address actually in use.

What it costs

OmniRoute is free; cost depends on which provider a request ends up at:

• Requests served from free tiers follow that provider's terms. They never reach CCSub and cost nothing on CCSub.
• Requests that reach CCSub are billed by CCSub's rules. Pay-as-you-go: ¥1 buys $1 of credit that never expires, charged per request by input / output tokens at the model's price (see the models page). Monthly plans: the day's quota is used first (it resets at midnight Beijing time) and then your balance.
• If OmniRoute token compression is on, fewer tokens reach CCSub and the charge drops with them.
• Requests that fail authentication (401) are not charged. Every request's tokens and charge are listed on the Usage page.

Who it is for

• People who want to use free quota first and only pay when it is not enough.
• People who use several model providers and want keys and routing rules in one place.
• If you just want Claude Code to work without running another local service, set two environment variables as in the Claude Code setup guide. To switch between services by hand, see the CC Switch guide.