Claude Code Router — route Claude Code to any model, or skip the router entirely

Most people searching for Claude Code Router want one of two different things: route Claude Code across several model providers, or just run Claude Code somewhere cheaper than Anthropic's list price. Only the first needs the router. Claude Code reads ANTHROPIC_BASE_URL natively, so the second is three environment variables and no extra software at all.

This guide covers both paths, with the exact variable names, the credential trap that produces a silent 401, and an honest list of what stops working behind any gateway. If you have read another CCR write-up recently, skip to Option B first: the config.json those articles tell you to edit is no longer the configuration the router reads.

Which one do you actually need?

The router is a local service: one more process to run, configure and keep current — and, as of 2026, a desktop app with its own UI rather than a file you edit. It earns that cost when you genuinely need multi-provider routing, per-request accounting, or subagent-level model selection. It does not earn it when a base URL would have done.

Option A — the base URL swap (no install)

Kunavo serves the native Anthropic Messages API at /v1/messages, which is the endpoint Claude Code calls. Point it there:

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...              # create at kunavo.com/app/keys
export ANTHROPIC_MODEL=claude-sonnet-4-6           # exact slug — see the table below
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5   # background tasks

ANTHROPIC_BASE_URL is the origin only — Claude Code appends /v1/messages itself, so don't include a path. Get the key from the dashboard after signing up and topping up $10; it's shown once.

Which credential variable — and why it matters

Claude Code sends the two credential variables in different HTTP headers, and a key in the header the server doesn't read fails with 401:

Prefer ANTHROPIC_AUTH_TOKEN for two concrete reasons. First, ANTHROPIC_API_KEY needs a one-time approval in an interactive session, and a key you declined once is ignored afterwards with no prompt — a confusing failure where the variable is plainly set and plainly unused. Second, Claude Code's gateway model discovery sends only the bearer token when ANTHROPIC_AUTH_TOKEN is set, and falls back to x-api-key otherwise — and Kunavo's /v1/models endpoint reads the bearer header only. With ANTHROPIC_API_KEY, discovery fails silently.

Make it stick

Shell exports only apply to that terminal and anything launched from it — an editor opened from the dock won't see them, and neither will background agents. Put the values in a settings file to cover everything:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Use ~/.claude/settings.json for all projects. Never put a key in a project's .claude/settings.json — that file gets committed.

Verify before you trust it

Test the endpoint directly first, so a failure points at the configuration rather than at Claude Code:

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

# A response starting with {"id":"msg_ means the URL and key both work.
# 401 -> the key is in the wrong header; see "Which credential variable" below.

Then start claude from the same shell and run /status. An Anthropic base URL line showing api.kunavo.com and an Auth token line naming your variable confirm both halves are live.

Set a custom model — pick the slug explicitly

Kunavo resolves model slugs by exact match and does not alias date-suffixed names, so claude-sonnet-4-5-20250929 returns 404 where claude-sonnet-4-6 succeeds. Always set ANTHROPIC_MODEL rather than relying on the built-in default:

The alias variables give you per-task routing without any router at all: ANTHROPIC_DEFAULT_OPUS_MODEL backs the opus alias and plan mode, ANTHROPIC_DEFAULT_SONNET_MODEL backs sonnet, and ANTHROPIC_DEFAULT_HAIKU_MODEL backs haiku plus Claude Code's background work — the summaries and titles that quietly accumulate cost. Pointing that one at claude-haiku-4-5 is the single highest-value line in the config. (ANTHROPIC_SMALL_FAST_MODEL is the deprecated spelling of the same setting.)

Optional: show every model in the picker

Set CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 (Claude Code v2.1.129+) and Claude Code queries GET /v1/models at startup, adding what it finds to the /model picker labelled From gateway. Kunavo serves that endpoint, so every enabled Claude model shows up and /model becomes a live menu instead of a list you maintain by hand. This is the path that requires ANTHROPIC_AUTH_TOKEN — see above.

Option B — claude-code-router, as it actually works now

Start here, because almost everything written about CCR is describing a version that no longer exists. The router used to be a JSON file and a ccr code command. It is now a local control plane with a desktop app, a management UI, request logs and a model gateway — and the config.json every tutorial shows you does not configure it any more.

CCR keeps its runtime configuration in ~/.claude-code-router/config.sqlite (%APPDATA%\claude-code-router\config.sqlite on Windows). A legacy config.json is read once, as a migration source, when no SQLite configuration exists yet. After that first run, editing it does not affect the running configuration — with no error and no warning. Your carefully pasted Providers block is simply not the config.

That includes this page before 2026-09-06: the JSON snippet that used to sit here was wrong, and it is the kind of wrong that costs an afternoon, because nothing tells you it was ignored. Configuration now happens in the UI (or, for backup, Settings → Export data — do not copy live SQLite files while CCR is running).

Install and launch

CCR ships two ways: a desktop app from GitHub Releases (tray, auto update, desktop integrations) and an npm CLI for headless or supervised deployments. They share the same configuration directory.

# CCR ships as a desktop app (GitHub Releases) or an npm CLI. Both read the
# same ~/.claude-code-router directory. The CLI needs Node.js 22+.
npm install -g @musistudio/claude-code-router
ccr ui        # management UI on :3458, model gateway on :3456

# Configure the provider and an Agent Config profile in that UI, then launch
# Claude Code through the profile by name:
ccr "Claude Code - Kunavo"        # npm CLI
ccr-app "Claude Code - Kunavo"    # the desktop app's own launcher

# There is no 'ccr code' in the current command reference. The service commands
# are start / ui / stop / serve / web; everything else is a profile name.

Adding Kunavo is one provider entry — Providers → Add provider, preset Other / custom API endpoint, endpoint https://api.kunavo.com, your sk-kn- key — and one Agent Config → Add profile → Claude Code profile. The field-by-field version, including Check Connection and model discovery, is on the Claude Code Router integration page. The rest of this section is what that page doesn't cover: the credentials, the economics and the failure modes.

Three credentials, and which one a 401 is about

This is the most common way a working setup looks broken. CCR has three separate secrets and they authenticate three different hops:

The port pairing catches people too: management defaults to 127.0.0.1:3458 and the model gateway to 127.0.0.1:3456. A base URL pointed at 3458 reaches the UI, not the gateway. (Docker deliberately collapses both behind one Nginx endpoint, which is why Docker instructions look different.) A reachable UI is not a working gateway: check /health on the gateway address, and confirm Server shows Running.

The per-tier map is the point

Claude Code does not ask for a model, it asks for a tier — the main loop wants Sonnet or Opus, and background work (subagents, search, summaries, conversation titles) wants the small fast one. A Claude Code profile in Agent Config exposes those as separate fields: a default Model plus optional Fable, Opus, Sonnet and Haiku overrides, each taking a Provider/model value. Leave a tier empty and Claude Code picks it.

Read that table before you copy someone's tier map, because the obvious split does not pay here: claude-opus-5 and claude-sonnet-5 cost the same on Kunavo ($2.00 / $10.00 each), so demoting the Opus tier to Sonnet 5 saves nothing at all. Two levers do pay. The Haiku tier is 5× cheaper than either, and it carries volume you never see — every subagent, every file-triage pass, every generated title. And claude-sonnet-4-6 on the main loop is 40% below Sonnet 5 if you can live on the previous generation.

Subagent routing — the thing the tier map can't do

Tier overrides pin all subagents to one model. CCR can go finer: when a Claude Code request matches the built-in route, it injects the list of available models into the Agent / Task tool description, and Claude Code prefixes each spawned agent's prompt with a tag naming the model it wants:

<CCR-SUBAGENT-MODEL>provider/model</CCR-SUBAGENT-MODEL>

CCR strips the tag and routes that one request accordingly, so a search subagent can run on Haiku while a review subagent runs on Opus, chosen per task rather than pinned. The switch is easy to miss: the mechanism is off until at least one model has a Description on the Models page. With no descriptions CCR injects nothing, and every subagent quietly falls back to the profile default. Write the descriptions as task fit — “code search, file triage, cheap parallel subagents” on Haiku, “architecture analysis, high-risk review” on Opus. When it works, request logs show builtin:claude-code-subagent as the route reason.

Protocol choice, and what it costs you in cache

CCR probes the endpoint and picks a wire protocol. Give it the bare origin https://api.kunavo.com and it talks Anthropic Messages; give it https://api.kunavo.com/v1 and it talks the OpenAI-compatible format. Both surfaces are live on the same key, and you can override the auto-detection in Advanced settings.

Prefer the Anthropic Messages form. It keeps cache_control on the wire, so prompt caching reaches the model and cached input bills at 10% of the input rate (how it works) — on an agent loop that resends a stable prefix every step, the largest single saving available. The honest caveat is that a router in the path still edits requests: CCR removes the billing-header system message Claude Code injects, and adds the model list to tool descriptions when subagent routing is on. Both sit ahead of your cache breakpoints, so each change to that content costs one cache miss while the new prefix warms. It is stable after that — but it is a real reason Option A caches marginally better than Option B, on top of being less to run.

Fallback: retry versus failover

The Routing page's Default on failure is worth setting before you need it. Retry re-sends to the same model on 408, 409, 429 and 5xx, honouring Retry-After and otherwise backing off exponentially from 1s to a 30s cap. Fallback targets walks an ordered list of backup models and triggers on any 4xx or 5xx, on the theory that model-not-found or a provider rejection may only affect the current target. Individual rules can override the global setting. When a fallback runs, the response carries x-ccr-fallback-attempts and x-ccr-fallback-model so you can tell after the fact.

Verify it is actually in the path

Launch Claude Code from the profile, send one message, then open Request logs in CCR. The row shows request model (what Claude Code asked for), resolved provider and resolved model (where it went) — that triple is the proof. Inside the CLI, /model lists the models CCR exposes. If Claude Code replies but no log row appears, you started Claude Code yourself rather than through CCR, and the profile's scope is Only opened from CCR.

What a coding session costs

Claude Code resends the system prompt, conversation and fresh file context on every step, so the per-token rate compounds quickly. At Kunavo rates on claude-sonnet-4-6:

That is roughly 60% off on the mainline model, before prompt caching. Full rates are in the Claude API pricing guide, and the cost calculator takes your own token counts.

What still works — and what doesn't

Pointing Claude Code at any gateway changes a few things. The list is short and worth knowing before you commit:

On that last row: token counting is the one endpoint Anthropic's own gateway specification marks optional, and Claude Code estimates context usage locally when it is absent. Kunavo does not serve /v1/messages/count_tokens today, so your /context figure is an estimate rather than an exact count. Nothing degrades beyond that number — auto-compaction and the session itself are unaffected.

Troubleshooting

The base-URL path

…and when the router is in the path

Error-by-error fixes for the API itself are in the invalid API key and rate limit troubleshooting pages.

FAQ