Claude Code Router：用于高效编码的多模型路由

了解如何使用 Claude Code Router 连接多个提供商，为每个任务使用最合适的 LLM，并在不更改工作流的情况下降低 API 成本。

已更新 2026年10月6日 · 13分钟阅读

使用 AI 探索

当我开始大量使用Claude Code时，很快就注意到两件事：质量极佳，账单也实打实。无论是三行的文档字符串，还是完整的架构重构，所有请求都会以相同的费率打到同一个 Anthropic 端点。

久而久之，这种单一供应商依赖不仅带来成本压力，还会带来风险。这也意味着某个模型的速率限制就能让您的整个工作流陷入停滞。

Claude Code Router（CCR）正面解决这两个问题。它是一个开源代理，在您的 Claude Code 请求到达任何提供商之前进行拦截，然后将每个请求重定向到最适合该任务的后端模型。

在本教程中，我将带您完成完整的设置流程：安装路由器、配置多提供商路由路径，并加固系统以满足日常运维使用。要跟着操作，请准备好您想使用的提供商的 API 密钥（DeepSeek、Gemini、OpenRouter 或其他受支持的后端），然后打开终端。我们开始吧。

想了解不同新 LLM 的特点与优势，可以参考我们关于以下最新模型的指南：

什么是 Claude Code Router？

在开始设置之前，值得先了解 CCR 究竟是什么，以及它为何以这种方式工作。如果您还没有使用过 Claude Code，请先查看我们的Claude Code 2.1 实用指南。

Claude Code Router 是一个本地代理网关。启动后，它会绑定到您机器上的一个端口（默认 127.0.0.1:3456），位于您的 Claude Code 客户端与任何外部 LLM 提供商之间。对 Claude Code 来说，它只是与本地端点通信。而在幕后，CCR 会实时决定请求实际要去往的地方。

它解决的核心问题是单一供应商依赖。当所有请求都通过一个提供商时，您会继承该提供商的所有限制：

定价层级
速率限制
上下文窗口上限

CCR 通过允许您定义路由规则来消除这种情况，能够根据任务类型、token 数量或您编写的任何自定义逻辑自动切换模型。后台文件扫描不需要与计划模式推理会话相同的模型，而有了 CCR，它也不会再去用同一个模型了。

让 CCR 有别于直接使用提供商 API 或云端聚合器的，是它的运行位置。

由于代理在本地执行，您的请求载荷在到达目的地之前不会经过第三方聚合服务。您还可以通过完全在本机运行的 transformer 系统，对请求转换进行细粒度控制，包括修改请求头、剥离缓存字段、限制 token 上限等。

对我而言，本地执行模型让 CCR 不再只是一个巧妙的权宜之计，而是真正实用：相比将一切都路由到单一云端供应商，这种方案更省钱、更具韧性，也更注重隐私。

Claude Code Router 架构与前置条件

在明确 CCR 的作用后，我们来看看它在幕后如何工作，以及安装前需要准备什么。

核心概念模型

理解 CCR 的架构能让配置变得更容易上手，我发现一旦从头到尾看过这个代理模式，思路就会很快打开。

当您启动 CCR 时，它会在到达默认的 Anthropic 端点之前拦截来自终端的所有出站请求。针对每个请求，它会：

检查请求；
应用您的路由规则；
将载荷转换为目标提供商期望的格式；
转发请求。

响应也会以相同路径返回，并被转换回 Claude Code 期望的格式，因此客户端不会察觉任何变化。

拦截中的关键机制是基于任务的路由。CCR 会按类型对传入请求分类，并将其映射到合适的模型。以下是主要任务类别在实践中的表现：

任务类型	触发时机	典型模型选择
`background`	文件扫描、上下文收集	快速本地模型（如 Ollama）
`think`	计划模式、复杂推理	推理模型（如 DeepSeek）
`longContext`	超过 token 阈值的请求	大上下文模型（如 Gemini）
`webSearch`	网页搜索任务	原生支持搜索的模型
`default`	其他所有情况	中端能力模型

每种任务类型都能匹配到合适的工具，且一旦配置完成，无需人工干预。就我的经验而言，background 路由带来的即时回报最大：这些在编码会话中不断发生的静默文件扫描请求，在使用 CCR 之前我根本没意识到它们悄悄累积了多少费用。

必要前置条件

在安装 CCR 之前，请确认以下条件已就绪：

运行环境为 Node.js v18 或更高版本
使用 npm 作为包管理器
全局安装 Claude Code（npm install -g @anthropic-ai/claude-code）
至少一个模型后端：要么来自受支持外部提供商的 API 密钥（DeepSeek、Gemini、OpenRouter、Groq、火山引擎、SiliconFlow 等），要么是本地 Ollama 实例并已拉取模型，如果您完全不想使用外部提供商

您无需一开始就注册所有提供商。一个可用的后端足以完成本教程，后续可随时添加更多。

若想将 Claude Code 与其热门替代方案进行对比，推荐阅读我们的OpenClaw 与 Claude Code 对比。

分步教程：设置 Claude Code Router

现在概念与前置条件都已清晰，我们一步步完成搭建。

安装并启动路由器

在具备前置条件后，您可以用 npm 全局安装 CCR。不过在 Linux 上，全局安装包可能会遇到权限错误，因为 npm 尝试写入由 root 拥有的 /usr/lib/node_modules。推荐的解决方式是将 npm 的全局目录重定向到一个您已拥有的文件夹，而不是使用 sudo 执行：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

要让该 PATH 变更永久生效，请将 export 这一行添加到 ~/.bashrc 或 ~/.zshrc 并重新加载 shell。然后安装 CCR：

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

这会让 ccr CLI 在您的 shell 中全局可用。接下来启动路由服务：

ccr start

CCR 默认绑定到 http://127.0.0.1:3456。当您在启动输出中看到服务已绑定该端口时，代理就已准备好接收请求。

配置基础提供商

所有 CCR 配置位于 ~/.claude-code-router/config.json。在接入多个提供商之前，我建议先从一个已知稳定的提供商开始，以隔离变量并确认基线可用。

OpenRouter 是一个不错的起点，也是我在新机器上设置 CCR 时首先选择的。它通过一个 API 密钥提供数十个模型（包括若干免费层级），非常适合在承诺具体提供商之前先让路由层跑通。您可以在 OpenRouter 注册并获取密钥。

以下是使用 OpenRouter 的最小化配置：

{
  "Providers": [
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "YOUR_OPENROUTER_API_KEY",
      "models": ["openai/gpt-oss-120b:free"],
      "transformer": {
        "use": ["openrouter"]
      }
    }
  ],
  "Router": {
    "default": "openrouter,openai/gpt-oss-120b:free"
  }
}

有几点需要注意：

api_base_url 必须指向提供商的完整 chat completions 端点，而不仅是基础域名。
transformer 指定 CCR 应使用的内置载荷适配器，因为不同提供商的请求格式不同。适配器会在后台静默完成转换。
Router.default 使用 provider,model 语法，为未命中更具体规则的任何请求设置回退模型。

出于安全考虑，避免将密钥直接硬编码到文件中。CCR 支持环境变量插值：将 YOUR_OPENROUTER_API_KEY 替换为 $OPENROUTER_API_KEY，并在您的 shell 中导出该变量。插值会在整个配置中递归生效，因此随着您添加更多提供商，这种模式也能干净扩展。

将 Claude Code 连接到代理

配置就绪后，通过路由器启动 Claude Code 只需一条命令：

ccr code

就这样。ccr code 会同时启动代理服务并启动 Claude Code，且自动预配置好环境。您无需先单独运行 ccr start。

要验证路由是否生效，请查看 ~/.claude-code-router/logs/ 文件夹。里面名为 ccr-*.log 的文件表明代理已启动并接收请求。您可以通过以下方式实时查看请求：

tail -f ~/.claude-code-router/logs/$(ls -t ~/.claude-code-router/logs/ | head -1)

Claude Code Router 日志

关于验证，有两点值得了解。Claude Code 页眉始终显示当前默认的 Claude 模型，而不管 CCR 实际路由到哪个模型，因为它反映的是您的 Anthropic 账户会话，而非活动后端。如果您询问模型“你是哪一个模型？”，它也会回答“Claude Sonnet 4.6”，因为这是 Claude Code 客户端要求它自报的身份。这两者都不可靠。

Claude Code Router 会话

日志才是唯一的真实来源。请在响应条目中查找 "model" 字段。如果您看到那里有您配置的模型名，例如 "model":"openai/gpt-oss-120b:free"，则说明路由正常工作。

如果您希望让 CCR 持久化，以便直接使用 claude 命令而无需 ccr code，请将以下内容添加到 ~/.bashrc or ~/.zshrc：

eval "$(ccr activate)"

此时请确保先运行 ccr start，因为 activate 只会设置环境变量，并不会启动服务本身。

实现多提供商路由

在验证好基线后，我们扩展配置，将不同任务类型路由到不同提供商。以下是更完整的 Router 配置：

{
  "Router": {
    "default": "deepseek,deepseek-chat",
    "background": "ollama,qwen2.5-coder:latest",
    "think": "deepseek,deepseek-reasoner",
    "longContext": "openrouter,google/gemini-2.5-pro-preview",
    "longContextThreshold": 60000,
    "webSearch": "gemini,gemini-2.5-flash"
  }
}

每个键都将任务类别映射到一个 "provider,model" 对：

background 路由处理文件扫描与上下文收集请求。这些请求可以安全地交给本地 Ollama 模型，从而保持零成本，这一改动对我每月的 API 账单影响最大。
think 路由覆盖计划模式和复杂推理任务，此处像 deepseek-reasoner 这样的模型物有所值。
longContext 路由会在请求超过 longContextThreshold（默认 60,000）token 时自动激活，无需手动切换即可重定向到高容量模型。
对于 webSearch，请注意模型本身必须原生支持网页搜索。如果您通过 OpenRouter 路由，还需要在模型名后追加 :online 后缀（例如 "anthropic/claude-3.5-sonnet:online"）。

为了增强在速率限制下的韧性，CCR 的自定义路由器功能允许您用 JavaScript 定义回退逻辑。可在任意路径创建一个文件，在配置中通过 "CUSTOM_ROUTER_PATH": "/path/to/custom-router.js" 引用它，然后导出一个异步函数，返回 "provider,model" 字符串，或返回 null 以回退到默认规则：

module.exports = async function router(req, config) {
  // Primary logic here. Return null to fall back to config-defined rules.
  return null;
};

例如，您可以在此实现“遇到 429 速率限制自动重试并改道到备选提供商”的逻辑。任何配置更改后，记得重启服务以生效：

ccr restart

运行与故障排查 Claude Code Router

在路由正常工作后，重点转向如何保持系统的可观测性、安全性，以及在出现问题时便于调试。

监控用量并执行预算约束

CCR 提供两套值得了解的日志系统：

服务器级日志覆盖 HTTP 请求、API 调用与服务器事件，写入 ~/.claude-code-router/logs/ 中的 ccr-*.log 文件。这是您实际中最常用的日志。
应用级日志记录路由决策，写入 ~/.claude-code-router/claude-code-router.log，但此文件是否存在取决于您的设置与日志级别配置。

定期查看服务器日志，您就能清楚了解哪些路由被触发、调用了哪些模型，以及是否发生了提供商错误。

为获得实时可见性，CCR 还包含一个状态栏工具（v1.0.40 及以上可用），可通过 ccr ui 启用。启用后，它会在 Claude Code 运行时将当前路由状态直接显示在终端中，让您一目了然每个请求由哪个模型处理。

在预算方面，最有效的护栏就是您的路由配置本身。通过确保 background 和 default 路由指向更便宜或本地的模型，可以避免为低价值任务调用高端模型。将 think 和 longContext 留给物有所值的模型，并将 longContext 的 token 阈值设置在您的工作流可接受的尽可能高的水平。

就我的经验而言，这种配置层面的自律比事后监控更可靠，因为它是在超支发生前就加以预防，而不是事后捕捉。

保护凭证与访问控制

随着提供商列表的增长，凭证管理值得单独重视。我遵循的规则很直接：

切勿将明文 API 密钥提交到被版本控制追踪的 config.json。始终使用 "$PROVIDER_API_KEY" 语法进行环境变量插值，并从 shell 配置或机密管理器导出密钥。
在个人开发环境中将代理限制在 localhost。如果您未在配置中设置 APIKEY，CCR 会自动强制服务器仅绑定到 127.0.0.1，以防止在共享机器或网络上被外部访问。
团队部署时设置 APIKEY，如果您需要将主机开放为 0.0.0.0。每个连接到路由器的客户端都必须在 Authorization: Bearer 或 x-api-key 请求头中包含该密钥。
在路由敏感代码时禁用或降低日志级别。日志默认启用 ("LOG": true)。将 "LOG": false 可停止将请求载荷写入磁盘，或将 "LOG_LEVEL": "warn" 以抑制冗长的调试输出。