Claude Code Router 完整指南（2026）

Claude Code 是目前最强的 AI 编程助手之一，但"只能跑在 Anthropic 官方模型上"这件事正在成为越来越多开发者的痛点：官方 API 价格不低、国内直连不稳、封号风险让人焦虑、而且当你的工作流里 80% 的 token 都花在"读文件、格式化、写注释"这类低价值任务上时，用 $15/M token 的 Opus 来处理这些显然是在烧钱。

claude-code-router（CCR） 是 GitHub 上开源的代理中间件，它的核心思想极其简单：在 Claude Code 和上游模型之间插一层智能路由，让不同类型的请求自动流向最合适（也最便宜）的模型。复杂的架构决策给 Opus，日常的代码补全给 DeepSeek，超长上下文给 Gemini 2.5 Pro——全部自动，Claude Code 这边的体验不变。

本文是目前中文社区最完整的 CCR 教程，涵盖：为什么要用、它怎么工作、如何安装、如何配置、国内中转站接入、路由策略设计、常见问题与避坑指南。全文约 5000 字，建议收藏后分段阅读。

一、为什么需要 Claude Code Router

1.1 Claude Code 的费用问题有多严重

Claude Code 默认运行在 claude-opus-4-6 上。对于重度用户，每个月的 API 账单很容易达到 $100–$300。问题在于，这些 token 的"价值密度"极度不均匀：

• 约 40% 花在文件读取、目录遍历、代码格式化等机械操作上
• 约 25% 是模板代码生成、测试用例填写等低复杂度任务
• 约 20% 是简单的单文件编辑和注释
• 只有约 15% 是真正需要 Opus 级别推理能力的复杂任务——多文件架构设计、Debug 复杂 Bug、生成技术方案

也就是说，你花在 Opus 上的账单里，大约 85% 其实用不着 Opus。DeepSeek V3（约 $0.27/M input）来处理这些，效果几乎无差别，成本节省 50 倍以上。

1.2 国内开发者的额外痛点

在中国大陆直接访问 Anthropic API 通常需要代理，延迟高、稳定性差，遇到网络抖动时任务直接中断。而大量国内中转站（硅基流动、PoloAPI、诗云API 等）的 API 端点在国内直连，延迟低得多。CCR 让你可以轻松把请求路由到这些中转站，彻底摆脱网络不稳的困扰。

1.3 封号风险与多账号策略

2026 年 Anthropic 加强了对违规使用的检测，部分重度用户遭遇封号。CCR 允许你将多个 Provider（不同中转站、不同 API Key）配置为轮转池，单账号被封后自动切换，不影响工作流。

1.4 模型多样化的实际价值

Gemini 2.5 Pro 提供高达 100 万 token 的上下文窗口，处理超大代码库时碾压 Opus；DeepSeek R1 在数学推理和算法题上有独到之处；本地 Ollama 模型在隐私敏感的企业场景中不可替代。CCR 让这些模型可以无缝融入一个工作流，而不需要你手动切换环境变量、重启进程。

二、CCR 是如何工作的

CCR 的架构可以用一句话概括：它在 localhost 上启动一个兼容 Anthropic API 的本地代理，Claude Code 把所有请求发给这个代理，代理根据路由规则决定把请求转给哪个上游模型，再把响应原路返回给 Claude Code。

Claude Code → http://localhost:3456 (CCR 代理)
                           ↓ 路由判断
        ┌──────────────────┼──────────────────┐
        ↓                  ↓                  ↓
  背景任务             复杂推理          超长上下文
  DeepSeek Chat     DeepSeek R1      Gemini 2.5 Pro
  ($0.27/M)        ($0.55/M)        ($1.25/M)
        └──────────────────┼──────────────────┘
                           ↓
                    响应返回 Claude Code

CCR 内部有几个关键组件：

• Gateway Service：监听本地端口（默认 3456），接收来自 Claude Code 的 Anthropic Messages 格式请求
• Router Engine：根据 config.json 中的路由规则，判断当前请求属于哪个"场景"（background / think / longContext / webSearch / default）
• Protocol Adapter：将 Anthropic 格式的请求转换为目标 Provider 所需的格式（OpenAI Chat Completions / Gemini Generate Content / 等），并处理响应的格式转换
• Fallback Handler：当主 Provider 失败时，按顺序尝试备用 Provider

对 Claude Code 来说，整个过程是透明的——它只看到一个"本地 Anthropic API 端点"，完全不知道背后转发给了谁。你设置一个环境变量即可：

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

三、安装 CCR

3.1 前置条件

• Node.js 18 或更高版本（node -v 确认）
• 已安装 Claude Code（npm install -g @anthropic-ai/claude-code）
• 至少一个可用的 AI API Key（Anthropic、DeepSeek、SiliconFlow 等任意一家均可）

3.2 通过 npm 安装（推荐）

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

安装完成后，ccr 命令即可使用。验证安装：

ccr --version

3.3 通过 GitHub 源码安装

git clone https://github.com/musistudio/claude-code-router
cd claude-code-router
npm install
npm run build
npm link   # 将 ccr 命令链接到全局

3.4 Desktop 版（图形界面）

如果你更喜欢图形界面，可以从 GitHub Releases 下载对应平台的安装包：

• macOS（Apple Silicon / Intel）：.dmg 或 .zip
• Windows：.exe 安装程序
• Linux：.AppImage

Desktop 版内置了可视化的 Provider 管理、路由规则编辑器、请求日志面板和使用量统计，适合不熟悉 JSON 配置的用户。本文的配置说明以命令行版本为主，因为它更便于在服务器或 CI 环境中使用。

四、基础配置：config.json 详解

CCR 的配置文件默认位于 ~/.claude-code-router/config.json。第一次运行时会自动创建目录，你需要手动创建这个文件。

4.1 最简配置（单 Provider）

如果你只想把 Claude Code 的请求转发给一个 Provider，以下是最精简的配置：

{
  "Providers": [
    {
      "name": "anthropic",
      "api_key": "sk-ant-api03-你的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 配置结构解析

config.json 有两个顶层字段：

Provider 字段说明：

4.3 Router 路由键说明

Router 对象支持以下路由场景键：

路由值格式为 "provider_name,model_name"（逗号分隔，无空格）。

五、国内开发者：中转站接入配置

对于国内开发者，直接调用 Anthropic、OpenAI 等官方 API 存在网络不稳的问题。CCR 可以完美搭配国内 AI API 中转站使用——只需把 api_base_url 改成中转站的端点即可。

5.1 硅基流动（SiliconFlow）接入

硅基流动 是国内覆盖开源模型最广的平台之一，DeepSeek、Qwen、GLM 系列均有，国内直连，新用户有免费额度。

{
  "Providers": [
    {
      "name": "siliconflow",
      "api_key": "sk-你在硅基流动的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 混合配置：中转站 + 官方（推荐方案）

最推荐的生产配置：日常任务走硅基流动（低成本、国内直连），复杂任务和超长上下文走 OpenRouter（模型覆盖最广），真正需要最顶级效果时才走官方 Anthropic。

{
  "Providers": [
    {
      "name": "siliconflow",
      "api_key": "sk-硅基流动Key",
      "api_base_url": "https://api.siliconflow.cn/v1",
      "protocol": "openai"
    },
    {
      "name": "openrouter",
      "api_key": "sk-or-OpenRouter的Key",
      "api_base_url": "https://openrouter.ai/api/v1",
      "protocol": "openai"
    },
    {
      "name": "anthropic",
      "api_key": "sk-ant-官方Key或中转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 其他中转站配置参考

{
  "name": "poloapi",
  "api_key": "sk-你的PoloAPI-Key",
  "api_base_url": "https://poloapi.top/v1",
  "protocol": "openai"
}

{
  "name": "openrouter",
  "api_key": "sk-or-你的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.1 启动 CCR

配置完 config.json 后，运行：

# 启动 CCR 代理服务（默认监听 localhost:3456）
ccr start

# 另开一个终端窗口，启动 Claude Code 并指向 CCR
export ANTHROPIC_BASE_URL="http://localhost:3456"
claude

或者使用 CCR 的快捷命令，它会自动设置环境变量并启动 Claude Code：

ccr code

6.2 background 路由：最大化成本节省的关键

background 是 CCR 中对成本影响最大的路由键。Claude Code 在执行以下操作时会自动标记为 background 模式：

• 读取大量文件内容（Read tool）
• 目录遍历和文件搜索（Glob/Grep tool）
• 代码总结和格式化任务
• 自动生成测试用例

这些任务的 token 消耗量往往非常大，但对模型智能程度的要求极低。把 background 路由到 Qwen/Qwen2.5-Coder-32B-Instruct（硅基流动免费）或者本地 Ollama，直接把这部分成本降为零或接近零。

6.3 think 路由：为推理密集型任务提速

当 Claude Code 进入 extended thinking 模式（通常是你提出了复杂的架构问题或算法题时），CCR 可以把这些请求路由到 DeepSeek R1 这类专门为推理优化的模型。DeepSeek R1 在数学、代码推理任务上和 Opus 4.6 在同一级别，但价格低得多。

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

6.4 longContext 路由：处理超大代码库

当单次请求的输入 token 超过 60,000（默认阈值）时，CCR 自动切换到 longContext 路由。Claude Opus 4.6 只有 200k 的上下文窗口，而 Gemini 2.5 Pro 提供高达 100 万 token 的上下文，对于分析大型项目非常有价值。

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

可以自定义阈值（单位：token）：

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

6.5 完整四层路由策略

以下是一个经过实践验证的"四层路由"配置，适合大多数独立开发者场景：

{
  "Providers": [
    {
      "name": "siliconflow",
      "api_key": "sk-你的硅基Key",
      "api_base_url": "https://api.siliconflow.cn/v1",
      "protocol": "openai"
    },
    {
      "name": "openrouter",
      "api_key": "sk-or-你的OpenRouterKey",
      "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
  }
}

这个配置的逻辑：

• 默认 → DeepSeek V3（国内直连，性价比最高的代码生成模型）
• 后台任务 → Qwen2.5-Coder-32B（在硅基流动上部分免费，速度快）
• 深度推理 → DeepSeek R1（推理能力接近 Opus，成本低 10 倍）
• 超长上下文 → Gemini 2.5 Pro（百万 token 窗口，处理超大项目）

七、进阶配置：Fallback 与 Fusion 模型

7.1 Fallback 自动切换

当主 Provider 报错或超时时，Fallback 机制会自动尝试备用 Provider，确保工作流不中断。格式为数组：

{
  "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 按数组顺序尝试，第一个失败就切第二个，以此类推。这对于中转站可用性不稳定的场景非常实用。

7.2 API Key 轮转（防单账号封禁）

同一 Provider 的多个 API Key 可以配置为轮转池，CCR 会自动在它们之间负载均衡：

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

7.3 Fusion 组合模型

Fusion 模型是 CCR Desktop 版的特有功能：将一个基础模型与特定能力（视觉、联网搜索、MCP 工具）组合成一个"虚拟模型"，在路由规则中当作单一模型使用。

例如，配置一个"支持视觉能力的 DeepSeek"：当你给 Claude Code 发送截图时，视觉处理部分走 Gemini Flash（便宜快速），文本生成部分仍然走 DeepSeek V3。

7.4 自定义路由函数（高级）

CCR 支持用 JavaScript 函数定义自定义路由逻辑，适合需要精细控制的场景：

{
  "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'; }"
  }
}

ctx 对象包含 scenario（路由场景）、tokenCount（输入 token 数）、model（请求中的模型名）等字段，可以基于这些信息实现任意路由逻辑。

八、实际成本对比

8.1 按月账单对比

假设你是重度 Claude Code 用户，每月 API 用量约 100M tokens（输入+输出）：

8.2 现实期望值

社区真实用户反馈的成本降幅：

• 所有任务全路由到 DeepSeek：成本降至原来的 5–10%，但复杂架构任务质量有明显下降
• 四层混合路由（推荐）：成本降至原来的 20–40%，质量几乎无感知差异
• 仅 background 路由到廉价模型：成本降至原来的 50–60%，最安全的入门策略

网上流传的"降低 80–99%"的数字，通常建立在"将大量任务路由到本地 Ollama 或免费模型"的基础上，实际效果高度依赖你的工作负载类型。建议先跑一周的请求日志，再根据实际的 token 分布来调整路由策略。

九、常见问题与避坑指南

❌ 问题1：CCR 启动后 Claude Code 报 Connection Refused

原因：ANTHROPIC_BASE_URL 端口设置错误，或 CCR 未正常启动。
解决：运行 ccr start 后确认输出中显示监听端口，然后对应设置环境变量。命令行版默认是 3456，Desktop 版默认是 8080。

# 命令行版
export ANTHROPIC_BASE_URL="http://localhost:3456"

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

❌ 问题2：路由到便宜模型后，Claude Code 的文件编辑功能失效

原因：部分模型不支持 tool calling（工具调用），而 Claude Code 的 Write/Edit/Bash 等工具依赖这一能力。
解决：确认所选模型支持 function calling / tool use。以下模型经过社区验证可用：

• DeepSeek V3 ✓
• DeepSeek R1 ✓（部分版本需要通过 OpenRouter 调用）
• Qwen2.5-Coder-32B-Instruct ✓
• Gemini 2.5 Pro / Flash ✓
• Ollama 本地模型：需要确认具体版本是否支持

❌ 问题3：中文输出乱码或响应中断

原因：部分中转站对 streaming 响应的处理存在 BUG，或者模型本身的中文编码支持有问题。
解决：尝试在 config 中为该 Provider 添加 "stream": false，改为非流式响应；或换用其他中转站/模型。

❌ 问题4：background 任务没有被路由到设置的便宜模型

原因：background 路由依赖 Claude Code 在请求中附带 scenario 标记，不同版本的 Claude Code 行为可能有差异。
解决：升级到最新版 Claude Code（npm update -g @anthropic-ai/claude-code），并在 CCR 日志中确认路由判断是否正确执行。

❌ 问题5：config.json 改动后不生效

原因：CCR 服务在运行期间会缓存配置，修改文件后不会自动重载。
解决：ccr stop 停止服务，再 ccr start 重启。

安全与隐私注意事项

十、结语

claude-code-router 本质上是一个"让你重新掌控 Claude Code 底层模型选择权"的工具。它的技术门槛不高——核心就是一个 JSON 配置文件和两个环境变量——但它能带来的成本节省和灵活性是显著的。

对于国内开发者，CCR + 国内中转站的组合解决了两个最核心的问题：网络稳定性（国内直连）和成本控制（按任务类型路由到最性价比的模型）。从长远来看，随着 AI 编程工具竞争加剧，这种"与特定厂商解耦"的架构会越来越有价值。

如果你在配置过程中遇到问题，欢迎在 GitHub Issues 中查找或提交。社区很活跃，大多数常见问题都有解决方案。