Claude Code Router: 介绍与使用指南

claude-code-router 是一个功能强大的工具，它允许将来自 Claude Code 的请求路由到不同的模型，并能自定义任何请求。通过它，可以灵活地将任务分配给最合适的模型，例如使用本地模型处理后台任务以节约成本，或使用高性能模型处理复杂的“思考”任务。

开源项目地址
https://github.com/musistudio/claude-code-router

功能特性

模型路由: 根据需求（如后台任务、思考、长上下文等）将请求路由到不同的模型。
多提供商支持: 支持多种模型提供商，如 OpenRouter、DeepSeek、Ollama、Gemini 等。
请求/响应转换: 使用转换器（Transformers）为不同的提供商自定义请求和响应。
动态模型切换: 在 Claude Code 中使用 /model 命令即时切换模型。
CLI 模型管理: 通过 ccr model 命令直接在终端管理模型和提供商。
UI 模式: 提供一个网页界面，让配置管理更直观。
GitHub Actions 集成: 在 GitHub 工作流中触发 Claude Code 任务。

快速上手

1. 安装

首先，确保已经安装了 Claude Code：

1
npm install -g @anthropic-ai/claude-code

然后，安装 Claude Code Router：

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

2. 运行

通过以下命令启动 Claude Code Router，它会自动配置好 Claude Code 的代理：

1
ccr code

如果修改了配置文件，需要使用 ccr restart 来重启服务使之生效。

3. 配置

claude-code-router 的核心是其配置文件 ~/.claude-code-router/config.json。这个文件主要包含两个部分：Providers 和 Router。

Providers: 在这里定义您想要使用的不同模型提供商及其 API 信息。
Router: 在这里设置路由规则，决定何种类型的任务由哪个 Provider 的哪个模型来处理。

可以通过 ccr ui 命令启动一个网页界面来更方便地编辑配置。

示例：如何接入 OpenAI 格式的接口

接下来，将以接入 Siliconflow 提供商的模型，展示如何配置 claude-code-router 来接入一个兼容 OpenAI API 格式的服务。

该提供商的配置如下：

API Base URL: https://api.siliconflow.cn/v1/chat/completions
API Key: sk-your-secret-api-key
可用模型: Qwen/Qwen3-Next-80B-A3B-Instruct, Qwen/Qwen3-Next-80B-A3B-Thinking

以下是配置步骤：

步骤 1: 添加一个新的 Provider

打开 config.json 文件（或通过 ccr ui 打开配置界面），在 Providers 数组中添加一个新的对象。

这个对象需要包含 name, api_base_url, api_key 和 models 字段。由于对方是标准的 OpenAI 格式接口，我们通常不需要配置 transformer。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "Providers": [
    // ... 您可能有的其他 provider
    {
      "name": "siliconflow",
      "api_base_url": "https://api.siliconflow.cn/v1/chat/completions",
      "api_key": "sk-your-siliconflow-key",
      "models": [
      	"Qwen/Qwen3-8B",
        "Qwen/Qwen3-Next-80B-A3B-Instruct",
        "Qwen/Qwen3-Next-80B-A3B-Thinking",
        "zai-org/GLM-4.6"
      ],
      "transformer": {
        "use": [
          [
            // 这里配置最大 token 的限制
            "maxtoken",
            {
              "max_tokens": 16384
            }
          ]
        ]
      }
    }
  ],
  "Router": {
    // ... 路由配置见下一步
  }
}

提示: 为了安全，建议使用环境变量来管理您的 API 密钥。您可以在 config.json 中使用 $VAR_NAME 的格式，claude-code-router 会自动替换它。例如：

1
"api_key": "$SILICONFLOW_API_KEY"

然后在终端环境中设置该环境变量：

1
export SILICONFLOW_API_KEY="sk-your-secret-api-key"

步骤 2: 配置路由规则

现在，可以设置路由规则，将 Claude Code 的请求指向刚刚添加的服务。在 Router 对象中，可以将 default 路由设置为新的模型。

路由规则的格式是 "provider_name,model_name"。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "Providers": [
    // ... 上一步的 providers 配置
  ],
  "Router": {
    "default": "siliconflow,Qwen/Qwen3-8B",
    "background": "siliconflow,Qwen/Qwen3-Next-80B-A3B-Instruct",
    "think": "siliconflow,Qwen/Qwen3-Next-80B-A3B-Thinking",
    "longContext": "siliconflow,zai-org/GLM-4.6"
    // ... 其他路由规则
  }
}

各任务类型详解

`default`

含义: 这是默认路由。当 Claude Code 执行一个没有被其他规则（如 background, think 等）匹配的常规任务时，就会使用这个模型。
配置解析: 例子中，它将常规任务交给 siliconflow 提供商的 Qwen/Qwen3-8B 模型处理。

`background`

含义: 这个路由用于处理后台任务。例如，通过 GitHub Actions 触发的、或者在 Claude Code 中不需要你等待其即时完成的任务。
配置解析: 例子中，它将后台任务分配给了 siliconflow 的 Qwen/Qwen3-Next-80B-A3B-Instruct 模型。

`think`

含义: 这个路由用于处理需要深度思考、复杂推理或代码生成的任务。当你明确要求 Claude Code 进行深入分析时，它会触发此规则。
配置解析: 例子中，它将这类“重脑力活”交给了 siliconflow 的 Qwen/Qwen3-Next-80B-A3B-Thinking 模型。

`longContext`

含义: 这个路由专门用于处理需要长上下文窗口的任务，比如分析一个非常大的代码库、总结一篇长篇报告或者基于大量文档进行问答。
配置解析: 例子中，它将长上下文的任务分配给了 siliconflow 的 zai-org/GLM-4.6 模型。

步骤 3: 重启并使用

保存 config.json 文件后，执行以下命令重启服务：

1
ccr restart

现在，当使用 Claude Code 时，请求就会根据路由规则被发送到配置的 OpenAI 格式接口了。

也可以在 Claude Code 的聊天界面中使用 /model example-model-v1 来动态切换模型。