claude-code-router with an OpenAI-Compatible Backend

By the aitokensai editors · Verified 2026-10-14 Sources: Anthropic docs · OpenAI API docs

Claude Code is hard-locked to Anthropic's API. It speaks the Anthropic message format and it will not be talked out of it by a config file. claude-code-router (CCR) sits in the middle and translates: Claude Code talks to a local port, and the router turns each Anthropic-shaped request into an OpenAI-shaped one for whatever backend you point it at.

That protocol gap is the whole reason the tool exists, and it also explains why its config is the least standardised of any tool on this site. Two layouts are in circulation, and the field names differ between them.

Which layout your config uses

Both of the following appear in current guides, and they are not interchangeable:

Layout A is the one that matches the npm package's own documentation. If your config file has a Providers array, you are on A. If it has a provider object with a default key inside it, you are on B, and copying a layout A file into it fails without an explanation.

Read your existing file before writing a new one. If the file does not exist yet, create ~/.claude-code-router/config.json and start from layout A.

Layout A, which is the one to use

{
  "LOG": true,
  "HOST": "127.0.0.1",
  "PORT": 3456,
  "APIKEY": "local-router-token",
  "API_TIMEOUT_MS": "600000",
  "Providers": [
    {
      "name": "gw",
      "api_base_url": "https://gw.example.com/v1",
      "api_key": "sk-your-gateway-key",
      "models": ["claude-sonnet-5", "deepseek-v4-pro", "glm-5.3"],
      "transformer": { "use": [] }
    }
  ],
  "Router": {
    "default": "gw,claude-sonnet-5",
    "background": "gw,glm-5.3",
    "think": "gw,deepseek-v4-pro",
    "longContext": "gw,claude-sonnet-5",
    "longContextThreshold": 60000,
    "webSearch": "gw,claude-sonnet-5"
  }
}

The Router block is a routing table, not a preference list. Claude Code issues several distinct kinds of request and CCR maps each to a model:

The value format is provider,model, a comma, not a colon. That single character is a frequent typo because most other tools use a colon.

Putting a cheap model on background is the one routing change that reliably pays for itself, because those calls are frequent and their answers are rarely read.

The version segment

Here the guidance in the wild conflicts, and the reason is that a gateway can be reached two ways.

• api_base_url as a version root — https://gw.example.com/v1. This is the right value when the backend serves the OpenAI-compatible API and CCR appends the operation path.
• The bare host — some guides show https://api.example.com with no version, which works only if the backend serves its API at the root.

What never works is pasting the full operation path (.../v1/chat/completions), because the router appends its own. That produces the doubled path failure, and it surfaces as a 404 alongside a message about the upstream provider rather than about the URL.

For an OpenAI-compatible gateway, use the version root.

Transformers decide whether tools work

Claude Code is an agent. It calls tools constantly, and a backend that returns tool calls in a different shape than Claude Code expects will appear to work for plain questions and fail the moment it tries to read a file.

The transformer.use array is where that is corrected. ["deepseek", "tooluse"] is the common pairing: one entry adapts the provider's response shape and the other normalises tool-call emission.

Leaving it empty is correct only for a backend already emitting Anthropic-shaped tool calls. For everything else, an empty array produces an agent that chats well and cannot act, which reads as a Claude Code bug rather than a config gap.

Launching it

The router is a server, and Claude Code needs two environment variables pointed at it. The ccr code subcommand starts the server if it is not running, exports both, and then launches Claude Code:

npm install -g @musistudio/claude-code-router
ccr code

The two variables it sets are worth knowing for the case where you launch the pieces by hand:

export ANTHROPIC_BASE_URL="http://127.0.0.1:3456"
export ANTHROPIC_API_KEY="placeholder"

The key here is not your gateway key. Claude Code performs a login check and rejects an unset value, so a dummy string satisfies it; the real credential is the api_key inside the provider block, which the router applies upstream. Setting this variable to a real Anthropic key changes nothing about where the traffic goes.

Switch models inside a session with the /model command using the same provider,model form as the routing table.

Why this setup costs less than it looks

Routing Claude Code to a gateway is mostly a cost decision, and the saving comes from two places.

Per-token rate. A gateway's rate for an equivalent model is lower than the first-party one. On an agent that re-sends the whole conversation on every tool call, that difference compounds over a long task rather than over a long message.

Routing. background calls are frequent and cheap to serve with a small model. think turns are rare and worth a strong one. Sending everything to one frontier model pays frontier rates for both.

A day on this page's workload is 300k input and 40k output tokens, or 6M input and 0.8M output across 20 working days. It is the highest input figure of any tool on this site, and it is high for the same reason the site exists: a coding agent reads far more than it writes.

One day = 300k input + 40k output on this page's workload. 20 days = 6M input and 0.8M output. Rates checked 2026-10-14 (gateway rates move with upstream promotions), so verify the current number in your dashboard before committing to a budget.

Verifying the route

1. Open your existing config file first and see whether it uses Providers or provider. Match the layout you find.
2. Address each provider by the name in the config, because the routing table references providers by that name and a mismatch fails silently at routing time.
3. Write routing values as provider,model with a comma.
4. Set the version root in api_base_url, not the operation path.
5. Fill transformer.use unless your backend already returns Anthropic-shaped tool calls.
6. Launch with ccr code so the environment variables are set for you.
7. Check /status inside the session to confirm which model is actually serving.

FAQ

FAQ

Related

• Claude Code with a custom API, setting the endpoint directly, without a translation layer
• Claude Code cost — what an agent loop actually bills
• Claude Code 429 rate limits — which limit you are hitting when it throttles
• OpenAI-compatible endpoints — the request shape the router converts to
• litellm model name mapping — the same routing idea as a proxy rather than a local server
• Tools that take one endpoint — the full matrix

Get API access