Claude Code Router: The Complete 2026 Guide

Claude Code is one of the strongest AI coding assistants available today, but "only runs on Anthropic's official models" is becoming a real pain point for more and more developers: official API pricing isn't cheap, direct access outside the US can be unstable, ban risk creates constant anxiety, and when 80% of the tokens in your workflow go toward low-value tasks like "read a file, format it, write a comment," burning $15/M-token Opus on that is straightforwardly wasteful.

claude-code-router (CCR) is an open-source proxy middleware on GitHub built around a simple idea: insert a smart routing layer between Claude Code and whatever model sits upstream, so different types of requests automatically flow to the most appropriate — and cheapest — model. Complex architecture decisions go to Opus, everyday code completion goes to DeepSeek, ultra-long context goes to Gemini 2.5 Pro — all automatic, with the Claude Code experience unchanged on your end.

This is the most complete CCR guide available, covering: why you'd use it, how it works, how to install it, how to configure it, relay integration, routing strategy design, and common pitfalls. It runs about 4,600 words — worth bookmarking and reading in sections.

1. Why You Need Claude Code Router

1.1 Just how bad is Claude Code's cost problem

Claude Code runs on claude-opus-4-6 by default. For heavy users, monthly API bills easily reach $100–$300. The problem is that these tokens have wildly uneven "value density":

• About 40% goes to mechanical work: reading files, traversing directories, formatting code
• About 25% is boilerplate generation and filling in test cases — low-complexity tasks
• About 20% is simple single-file edits and comments
• Only around 15% genuinely requires Opus-level reasoning — multi-file architecture design, debugging gnarly bugs, drafting technical proposals

In other words, roughly 85% of what you're paying Opus for doesn't actually need Opus. DeepSeek V3 (about $0.27/M input) handles these tasks with barely any noticeable difference, at more than 50x lower cost.

1.2 Extra pain points for developers outside the US

Direct access to the Anthropic API typically requires a proxy in mainland China, with high latency and poor stability — a network hiccup can kill a task mid-run. A large number of relay providers (SiliconFlow, PoloAPI, and others) offer direct-connect endpoints domestically with much lower latency. CCR lets you route requests to these relays with ease, sidestepping network instability entirely.

1.3 Ban risk and multi-account strategy

In 2026, Anthropic tightened detection of policy-violating usage, and some heavy users have run into bans. CCR lets you configure multiple Providers (different relays, different API keys) as a rotation pool, so if one account gets banned, it automatically switches over without breaking your workflow.

1.4 The real value of model diversity

Gemini 2.5 Pro offers up to a 1-million-token context window, crushing Opus when working with massive codebases; DeepSeek R1 has a distinct edge in math reasoning and algorithmic problems; local Ollama models are irreplaceable for privacy-sensitive enterprise scenarios. CCR lets all of these models slot seamlessly into one workflow, without you manually switching environment variables or restarting processes.

2. How CCR Works

CCR's architecture can be summed up in one sentence: it spins up a local proxy on localhost that's compatible with the Anthropic API; Claude Code sends every request to that proxy; the proxy decides, based on routing rules, which upstream model to forward the request to; and the response is routed back to Claude Code the same way it came in.

Claude Code → http://localhost:3456 (CCR proxy)
                           ↓ routing decision
        ┌──────────────────┼──────────────────┐
        ↓                  ↓                  ↓
  background task     deep reasoning    ultra-long context
  DeepSeek Chat     DeepSeek R1      Gemini 2.5 Pro
  ($0.27/M)        ($0.55/M)        ($1.25/M)
        └──────────────────┼──────────────────┘
                           ↓
                    response returned to Claude Code

CCR has a few key internal components:

• Gateway Service: listens on a local port (3456 by default), accepting Anthropic Messages-format requests from Claude Code
• Router Engine: uses the routing rules in config.json to determine which "scenario" the current request falls under (background / think / longContext / webSearch / default)
• Protocol Adapter: converts Anthropic-format requests into whatever format the target Provider needs (OpenAI Chat Completions / Gemini Generate Content / etc.), and converts the response back
• Fallback Handler: when the primary Provider fails, tries backup Providers in order

From Claude Code's perspective, the whole process is transparent — it only sees "a local Anthropic API endpoint" and has no idea who's actually handling the request behind the scenes. You just set one environment variable:

export ANTHROPIC_BASE_URL="http://localhost:3456"

3. Installing CCR

3.1 Prerequisites

• Node.js 18 or later (check with node -v)
• Claude Code already installed (npm install -g @anthropic-ai/claude-code)
• At least one usable AI API key (Anthropic, DeepSeek, SiliconFlow — any of them will do)

3.2 Install via npm (recommended)

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

Once installed, the ccr command becomes available. Verify the install:

ccr --version

3.3 Install from GitHub source

git clone https://github.com/musistudio/claude-code-router
cd claude-code-router
npm install
npm run build
npm link   # Link the ccr command globally

3.4 Desktop version (GUI)

If you prefer a graphical interface, download the installer for your platform from GitHub Releases:

• macOS (Apple Silicon / Intel): .dmg or .zip
• Windows: .exe installer
• Linux: .AppImage

The desktop version has a built-in visual Provider manager, a routing rules editor, a request log panel, and usage stats — good for anyone not comfortable editing raw JSON. This guide focuses on the command-line version, since it's easier to use on a server or in CI environments.

4. Basic Configuration: config.json Explained

CCR's config file lives at ~/.claude-code-router/config.json by default. The directory is created automatically on first run, but you need to create this file yourself.

4.1 The simplest config (single Provider)

If you just want to forward all of Claude Code's requests to one Provider, here's the leanest possible config:

{
  "Providers": [
    {
      "name": "anthropic",
      "api_key": "sk-ant-api03-your-key",
      "api_base_url": "https://api.anthropic.com",
      "models": ["claude-opus-4-6", "claude-sonnet-4-6"]
    }
  ],
  "Router": {
    "default": "anthropic,claude-sonnet-4-6"
  }
}

4.2 Breaking down the config structure

config.json has two top-level fields:

Provider field reference:

4.3 Router routing keys explained

The Router object supports the following routing scenario keys:

Route values use the format "provider_name,model_name" (comma-separated, no spaces).

5. For Developers Using Relays: Integration Guide

For developers outside the US, direct calls to official Anthropic, OpenAI, and similar APIs can be unstable over the network. CCR pairs perfectly with relay providers — just point api_base_url at the relay's endpoint.

5.1 SiliconFlow integration

SiliconFlow is one of the broadest open-model relay platforms available, covering DeepSeek, Qwen, GLM, and more, with a direct connection and free credit for new users.

{
  "Providers": [
    {
      "name": "siliconflow",
      "api_key": "sk-your-siliconflow-key",
      "api_base_url": "https://api.siliconflow.cn/v1",
      "protocol": "openai",
      "models": [
        "deepseek-ai/DeepSeek-V3",
        "deepseek-ai/DeepSeek-R1",
        "Qwen/Qwen2.5-Coder-32B-Instruct"
      ]
    }
  ],
  "Router": {
    "default": "siliconflow,deepseek-ai/DeepSeek-V3",
    "background": "siliconflow,Qwen/Qwen2.5-Coder-32B-Instruct",
    "think": "siliconflow,deepseek-ai/DeepSeek-R1"
  }
}

5.2 Hybrid config: relay + official (the recommended setup)

The most recommended production config: everyday tasks go through SiliconFlow (low cost, direct connect), complex tasks and ultra-long context go through OpenRouter (widest model coverage), and only tasks that genuinely need top-tier quality go to official Anthropic.

{
  "Providers": [
    {
      "name": "siliconflow",
      "api_key": "sk-your-siliconflow-key",
      "api_base_url": "https://api.siliconflow.cn/v1",
      "protocol": "openai"
    },
    {
      "name": "openrouter",
      "api_key": "sk-or-your-openrouter-key",
      "api_base_url": "https://openrouter.ai/api/v1",
      "protocol": "openai"
    },
    {
      "name": "anthropic",
      "api_key": "sk-ant-official-or-relay-key",
      "api_base_url": "https://api.anthropic.com",
      "protocol": "anthropic"
    }
  ],
  "Router": {
    "default": "siliconflow,deepseek-ai/DeepSeek-V3",
    "background": "siliconflow,Qwen/Qwen2.5-Coder-32B-Instruct",
    "think": "siliconflow,deepseek-ai/DeepSeek-R1",
    "longContext": "openrouter,google/gemini-2.5-pro-preview"
  }
}

5.3 More relay config references

{
  "name": "poloapi",
  "api_key": "sk-your-poloapi-key",
  "api_base_url": "https://poloapi.top/v1",
  "protocol": "openai"
}

{
  "name": "openrouter",
  "api_key": "sk-or-your-openrouter-key",
  "api_base_url": "https://openrouter.ai/api/v1",
  "protocol": "openai",
  "models": [
    "google/gemini-2.5-pro-preview",
    "anthropic/claude-opus-4-6",
    "deepseek/deepseek-chat"
  ]
}

{
  "name": "ollama",
  "api_key": "ollama",
  "api_base_url": "http://localhost:11434/v1",
  "protocol": "openai",
  "models": ["qwen2.5-coder:32b", "deepseek-coder-v2:16b"]
}

6. A Deep Dive into Routing Strategy

6.1 Starting CCR

Once config.json is set up, run:

# Start the CCR proxy service (listens on localhost:3456 by default)
ccr start

# In a separate terminal window, launch Claude Code pointed at CCR
export ANTHROPIC_BASE_URL="http://localhost:3456"
claude

Or use CCR's shortcut command, which sets the environment variable and launches Claude Code automatically:

ccr code

6.2 The background route: the key to maximizing cost savings

background is the routing key with the biggest impact on cost in CCR. Claude Code automatically flags requests as background mode when performing:

• Reading large amounts of file content (Read tool)
• Directory traversal and file search (Glob/Grep tools)
• Code summarization and formatting tasks
• Auto-generating test cases

These tasks tend to consume a huge number of tokens but require very little model intelligence. Routing background to Qwen/Qwen2.5-Coder-32B-Instruct (partially free on SiliconFlow) or a local Ollama instance drops this share of your cost to zero or close to it.

6.3 The think route: speeding up reasoning-heavy tasks

When Claude Code enters extended thinking mode (usually because you've asked a complex architecture question or an algorithm problem), CCR can route these requests to a model like DeepSeek R1 that's specifically optimized for reasoning. DeepSeek R1 is on par with Opus 4.6 for math and code reasoning tasks, at a much lower price.

"Router": {
  "think": "siliconflow,deepseek-ai/DeepSeek-R1"
}

6.4 The longContext route: handling massive codebases

When a single request's input exceeds 60,000 tokens (the default threshold), CCR automatically switches to the longContext route. Claude Opus 4.6 tops out at a 200K context window, while Gemini 2.5 Pro offers up to 1 million tokens — extremely valuable when analyzing large projects.

"Router": {
  "longContext": "openrouter,google/gemini-2.5-pro-preview"
}

You can customize the threshold (in tokens):

"Router": {
  "longContextThreshold": 80000,
  "longContext": "openrouter,google/gemini-2.5-pro-preview"
}

6.5 The full four-tier routing strategy

Here's a battle-tested "four-tier routing" config that suits most independent developers:

{
  "Providers": [
    {
      "name": "siliconflow",
      "api_key": "sk-your-siliconflow-key",
      "api_base_url": "https://api.siliconflow.cn/v1",
      "protocol": "openai"
    },
    {
      "name": "openrouter",
      "api_key": "sk-or-your-openrouter-key",
      "api_base_url": "https://openrouter.ai/api/v1",
      "protocol": "openai"
    }
  ],
  "Router": {
    "default": "siliconflow,deepseek-ai/DeepSeek-V3",
    "background": "siliconflow,Qwen/Qwen2.5-Coder-32B-Instruct",
    "think": "siliconflow,deepseek-ai/DeepSeek-R1",
    "longContext": "openrouter,google/gemini-2.5-pro-preview",
    "longContextThreshold": 60000
  }
}

The logic behind this config:

• Default → DeepSeek V3 (direct connect, the best cost-performance code-generation model)
• Background tasks → Qwen2.5-Coder-32B (partially free on SiliconFlow, fast)
• Deep reasoning → DeepSeek R1 (reasoning power close to Opus, 10x cheaper)
• Ultra-long context → Gemini 2.5 Pro (million-token window, handles massive projects)

7. Advanced Config: Fallback and Fusion Models

7.1 Automatic fallback

When the primary Provider errors out or times out, the fallback mechanism automatically tries a backup Provider, so your workflow doesn't break. Use an array:

{
  "Router": {
    "default": ["siliconflow,deepseek-ai/DeepSeek-V3", "openrouter,deepseek/deepseek-chat"],
    "background": ["siliconflow,Qwen/Qwen2.5-Coder-32B-Instruct", "ollama,qwen2.5-coder:32b"]
  }
}

CCR tries entries in array order — if the first fails, it moves to the second, and so on. This is very useful when a relay's uptime is unreliable.

7.2 API key rotation (guards against single-account bans)

Multiple API keys for the same Provider can be configured as a rotation pool, and CCR will automatically load-balance across them:

{
  "Providers": [
    {
      "name": "siliconflow",
      "api_key": ["sk-key1", "sk-key2", "sk-key3"],
      "api_base_url": "https://api.siliconflow.cn/v1",
      "protocol": "openai"
    }
  ]
}

7.3 Fusion composite models

Fusion models are a feature unique to CCR's Desktop version: they combine a base model with specific capabilities (vision, web search, MCP tools) into a single "virtual model" that gets used as one entry in your routing rules.

For example, you could set up a "vision-capable DeepSeek": when you send Claude Code a screenshot, the vision processing goes to Gemini Flash (cheap and fast) while text generation still goes to DeepSeek V3.

7.4 Custom routing functions (advanced)

CCR supports defining custom routing logic in JavaScript, for scenarios that need fine-grained control:

{
  "Router": {
    "customRouter": "function route(ctx) { if (ctx.tokenCount > 100000) return 'openrouter,google/gemini-2.5-pro-preview'; if (ctx.scenario === 'background') return 'ollama,qwen2.5-coder:32b'; return 'siliconflow,deepseek-ai/DeepSeek-V3'; }"
  }
}

The ctx object includes fields like scenario (the routing scenario), tokenCount (input token count), and model (the model name in the request) — you can implement any routing logic based on these.

8. Real Cost Comparisons

8.1 Monthly bill comparison

Assume you're a heavy Claude Code user with about 100M tokens of API usage per month (input + output):

8.2 Realistic expectations

Cost reductions reported by real users in the community:

• Routing everything to DeepSeek: cost drops to 5–10% of the original, but quality on complex architecture tasks noticeably declines
• Four-tier hybrid routing (recommended): cost drops to 20–40% of the original, with almost no perceptible quality difference
• Only routing background tasks to a cheap model: cost drops to 50–60% of the original, the safest starting strategy

The "80–99% reduction" numbers you see floating around online are usually based on routing a large share of tasks to local Ollama or free models — actual results depend heavily on your specific workload. It's worth running your request logs for a week first, then tuning your routing strategy based on the actual token distribution.

9. FAQ and Common Pitfalls

❌ Issue 1: Claude Code shows Connection Refused after starting CCR

Cause: the port in ANTHROPIC_BASE_URL is wrong, or CCR didn't start correctly.
Fix: run ccr start, confirm the listening port shown in the output, then set the environment variable to match. The CLI version defaults to 3456, the Desktop version defaults to 8080.

# CLI version
export ANTHROPIC_BASE_URL="http://localhost:3456"

# Desktop version
export ANTHROPIC_BASE_URL="http://localhost:8080"

❌ Issue 2: File editing stops working after routing to a cheaper model

Cause: some models don't support tool calling, which Claude Code's Write/Edit/Bash tools rely on.
Fix: confirm the model you picked supports function calling / tool use. The following are community-verified to work:

• DeepSeek V3 ✓
• DeepSeek R1 ✓ (some versions need to go through OpenRouter)
• Qwen2.5-Coder-32B-Instruct ✓
• Gemini 2.5 Pro / Flash ✓
• Local Ollama models: check whether the specific version you're running supports it

❌ Issue 3: garbled output or interrupted responses

Cause: some relays have bugs in how they handle streaming responses, or the model itself has issues with a particular character encoding.
Fix: try adding "stream": false to that Provider's config to switch to non-streaming responses, or switch to a different relay/model.

❌ Issue 4: background tasks aren't routed to the cheap model you set

Cause: the background route depends on Claude Code attaching a scenario tag to the request, and this behavior can vary between Claude Code versions.
Fix: update to the latest Claude Code (npm update -g @anthropic-ai/claude-code), and check the CCR logs to confirm the routing decision is being made correctly.

❌ Issue 5: changes to config.json don't take effect

Cause: CCR caches the config while it's running and won't auto-reload it after a file change.
Fix: run ccr stop to stop the service, then ccr start to restart it.

Security and privacy notes

10. Conclusion

claude-code-router is, at its core, a tool that "gives you back control over which model actually powers Claude Code." Its technical bar is low — it's essentially a JSON config file and two environment variables — but the cost savings and flexibility it delivers are substantial.

For developers outside the US, CCR paired with a relay solves the two most core problems at once: network stability (direct connection) and cost control (routing each task type to the most cost-effective model). Looking ahead, as competition among AI coding tools intensifies, this kind of "decoupled from any single vendor" architecture will only become more valuable.

If you run into trouble during setup, search or file an issue on GitHub Issues. The community is active, and most common problems already have a documented fix.