Claude Code Router in practice: one entry point, several upstreams

Why a router layer at all

Claude Code is a native Anthropic-protocol client: it calls /v1/messages, sends x-api-key, and uses tool_use / tool_result semantics. It does not accept an OpenAI-format endpoint.

So you have a choice:

• Point it straight at a relay site that supports the Anthropic protocol — simple, but you are locked to one supplier.
• Put a router layer in between — one more thing to maintain, but it can reach any upstream and split traffic by rule.

A router solves three core problems:

1. Protocol conversion: turn an Anthropic-format request into an OpenAI-format request for the upstream, then convert the response back.
2. Multi-upstream management: several upstreams in one config file, selected by rule.
3. Cost routing: easy tasks to cheap models, hard tasks to strong models.

A minimal working configuration skeleton

Taking claude-code-router as the example, the config file looks roughly like this. Field names follow whichever project you pick; what matters here is the structural relationship.

{
  "Providers": [
    {
      "name": "upstream-a",
      "api_base_url": "https://<relay-domain>/v1/chat/completions",
      "api_key": "<KEY>",
      "models": ["claude-sonnet-4-6", "claude-opus-4-7"]
    },
    {
      "name": "upstream-b",
      "api_base_url": "https://<another>/v1/chat/completions",
      "api_key": "<KEY>",
      "models": ["gpt-5.1", "claude-sonnet-4-6"]
    }
  ],
  "Router": {
    "default":     "upstream-a,claude-sonnet-4-6",
    "background":  "upstream-b,gpt-5.1",
    "think":       "upstream-a,claude-opus-4-7",
    "longContext": "upstream-a,claude-sonnet-4-6"
  }
}

Points worth noting:

• api_base_url usually has to go all the way to /v1/chat/completions, the OpenAI-compatible endpoint, rather than stopping at the domain. Different routers want different things; follow the documentation.
• Values inside Router are formatted upstream-name,model-name. The comma is not optional.
• Sending background to a cheap model is the single biggest cost win, because background tasks are the largest volume by far.
• After editing the config you must restart the router process. Most implementations do not hot-reload.

The three failures you are most likely to hit

A router is a request-rewriting layer, and rewriting carries the risk of protocol drift. In order of investigation:

One: tool call drift (the most common)

Symptom: Claude Code chats fine, but file edits and command execution misbehave — an edit reports success with the wrong content, or command arguments arrive mangled.

Cause: the router got the conversion between Anthropic's tool_use (where input is an object) and OpenAI's tool_calls (where arguments is a string) wrong.

How to investigate:

1. Bypass the router first: point Claude Code directly at a relay site with native Anthropic support.
2. Behaviour returns to normal → confirmed as a router conversion problem.
3. Still broken → the problem is on the upstream site.

This bisection saves a lot of time. One lesson the industry keeps repeating: prefer router implementations that rewrite as little as possible, because less rewriting means less drift.

Two: wrong model name mapping

Symptom: the router asks for a model name the upstream does not have and gets 404 or 400 back.

Claude Code requests its own built-in model names, things like claude-sonnet-4-5, while the upstream may call them something else. The router has to map between them, and you supply the mapping table.

How to investigate: look at the model field the router actually sends, in its log. The log is the only reliable evidence. Do not guess.

Using a family name such as claude-sonnet is usually lower risk, since most upstreams match by prefix. Spelling out a full version number can fail when the upstream does not carry that exact version.

Three: broken streaming chunks

Symptom: duplicated tokens or missing characters in Claude Code's terminal UI, or a response that hangs and never finishes.

Cause: OpenAI's SSE and Anthropic's SSE do not share an event structure. If the conversion layer only reshapes the format without understanding the event semantics, chunk boundaries end up misaligned.

How to investigate: use curl -N against the upstream's OpenAI endpoint first to confirm the upstream streams correctly on its own. Then add the router back and compare. That isolates which layer is at fault.

What cost routing actually saves

Configured well, the Router split saves real money. Rules of thumb:

• Background tasks — generating commit messages, summarising files, producing titles — account for the bulk of call volume. Send all of them to cheap models.
• The main conversation goes to a mid-tier model.
• Only when complex reasoning is genuinely needed do you use the strongest model (think).

Most people's Claude Code usage is "a large number of trivial calls plus a small number of hard reasoning steps". Routing background away typically cuts more than half the cost with almost no perceptible difference.

When a router is the wrong answer

• You use one upstream and it supports the Anthropic protocol natively → connect directly. One less layer means one less class of failure.
• You are unwilling to maintain extra configuration → router config has to be updated as upstreams change, in both model names and endpoints.
• Your core use is file editing and command execution → tool-call stability is a hard requirement, and every extra conversion is extra risk. Choose a native-protocol site instead.

Summary

The value of a router is decoupling: it breaks the hard binding between client and upstream supplier. The price is a component that needs maintaining and debugging.

The test is simple:

• Your upstream may change → a router is worth it.
• Your upstream is stable → it is not.

Once configured, run the four cases from our tool use compatibility article before anything else. That is the test most likely to expose a router's conversion problems.