前言
前段时间随着Claude Code CLI的爆火也随之火了一款Claude Code CLI扩展Claude Code Router,该扩展工具可以很方便的将各大主流模型接入到Claude Code CLI中使用(那段时间国内各大模型还没有支持Claude Code CLI,Claude Code CLI只能使用Claude Code模型),今天我们也来了解一下这款神奇的工具。对往期内容感兴趣的小伙伴也可以看往期内容:
当前版本
claude-code-router version: 1.0.49
优势
- 开源免费
- 支持配置文件和Web UI交互配置方式
- 灵活配置,可为不同场景指定不同供应商,为不同模型设置请求和响应转换器,一键切换模型配置
限制
- 每个用户的并发限制为 1,这意味着我们需要将后台请求路由到其他模型
简介
Claude Code Router 是一个开源工具,是 Claude Code 的扩展,旨在增强 AI 编码工作流程。它能将编码请求路由到不同的 AI 模型,为用户提供更灵活的模型交互方式。
Github地址:github.com/musistudio/...

随着Claude Code的爆火,Claude Code Router也受到越来越多小伙伴的喜爱,在Github上目前已坐拥18.3K Star。
对Claude Code Router开源项目原理感兴趣的小伙伴可以看这里:github.com/musistudio/...
功能特性
- 模型路由:根据您的需求(例如,后台任务、思维、长上下文)将请求路由到不同的模型。
- 多提供商支持:支持各种模型提供商,如 OpenRouter、DeepSeek、Ollama、Gemini、Volcengine 和 SiliconFlow。
- 请求/响应转换:使用转换器为不同的提供商自定义请求和响应。
- 动态模型切换:使用 /model 命令在 Claude Code 中动态切换模型。
- GitHub Actions集成:在 GitHub 工作流程中触发 Claude Code 任务。
- 插件系统:使用自定义转换器扩展功能
工作原理示意图
Claude Code Router工作原理大致如下:

环境安装
前提条件
- NodeJS18及以上版本
- 安装Claude Code CLI
为什么需要依赖Claude Code CLI呢?通过Claude Code Router开源项目原理部分我们知道,Claude Code Router是对Claude Code CLI的逆向拦截,因此Claude Code CLI还是应用主体。对Claude Code CLI还不了解的小伙伴可以看往期内容:Claude Code CLI初体验
ruby
$ npm install -g @anthropic-ai/claude-code
安装Claude Code Router
安装Claude Code Router只需要在命令行终端输入如下指令:
ruby
$ npm install -g @musistudio/claude-code-router

在命令行终端执行 ccr -v 输出如下信息表示安装成功

基本使用
命令行参数
在命令行终端输入 ccr --help 查看命令行文档

命令后参数:
- start:启动服务器,默认使用 ccr code 时会自行启动
- stop:停止服务器
- restart:重启服务器,修改配置时需要重启
- status:显示服务器状态
- statusline:集成状态栏
- code:执行 claude CLI 命令
- ui:在浏览器中打开网页界面
Claude Code Router包含 后台服务 和 CLI 两部分,CLI的终止不影响后台服务的状态。使用【Ctrl+C】终止 ccr code 后,在命令行终端输入 ccr status 仍然可以查看Claude Code Router服务的状态

修改配置文件时需要在命令行终端输入 ccr restart 重启后台服务

不需要使用Claude Code Router时在命令行终端输入 ccr stop 终止后台服务

使用 ccr ui 可用于启动网页版配置

配置文件
这是Claude Code Router原始的配置形式,为Claude Code Router提供供应商、模型等相关配置,这里先提供一份Claude Code Router完整配置文件参考:
json
{
"APIKEY": "your-secret-key",
"PROXY_URL": "http://127.0.0.1:7890",
"LOG": true,
"API_TIMEOUT_MS": 600000,
"NON_INTERACTIVE_MODE": false,
"Providers": [
{
"name": "openrouter",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "sk-xxx",
"models": [
"google/gemini-2.5-pro-preview",
"anthropic/claude-sonnet-4",
"anthropic/claude-3.5-sonnet",
"anthropic/claude-3.7-sonnet:thinking"
],
"transformer": {
"use": ["openrouter"]
}
},
{
"name": "deepseek",
"api_base_url": "https://api.deepseek.com/chat/completions",
"api_key": "sk-xxx",
"models": ["deepseek-chat", "deepseek-reasoner"],
"transformer": {
"use": ["deepseek"],
"deepseek-chat": {
"use": ["tooluse"]
}
}
},
{
"name": "ollama",
"api_base_url": "http://localhost:11434/v1/chat/completions",
"api_key": "ollama",
"models": ["qwen2.5-coder:latest"]
},
{
"name": "gemini",
"api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
"api_key": "sk-xxx",
"models": ["gemini-2.5-flash", "gemini-2.5-pro"],
"transformer": {
"use": ["gemini"]
}
},
{
"name": "volcengine",
"api_base_url": "https://ark.cn-beijing.volces.com/api/v3/chat/completions",
"api_key": "sk-xxx",
"models": ["deepseek-v3-250324", "deepseek-r1-250528"],
"transformer": {
"use": ["deepseek"]
}
},
{
"name": "modelscope",
"api_base_url": "https://api-inference.modelscope.cn/v1/chat/completions",
"api_key": "",
"models": ["Qwen/Qwen3-Coder-480B-A35B-Instruct", "Qwen/Qwen3-235B-A22B-Thinking-2507"],
"transformer": {
"use": [
[
"maxtoken",
{
"max_tokens": 65536
}
],
"enhancetool"
],
"Qwen/Qwen3-235B-A22B-Thinking-2507": {
"use": ["reasoning"]
}
}
},
{
"name": "dashscope",
"api_base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
"api_key": "",
"models": ["qwen3-coder-plus"],
"transformer": {
"use": [
[
"maxtoken",
{
"max_tokens": 65536
}
],
"enhancetool"
]
}
},
{
"name": "aihubmix",
"api_base_url": "https://aihubmix.com/v1/chat/completions",
"api_key": "sk-",
"models": [
"Z/glm-4.5",
"claude-opus-4-20250514",
"gemini-2.5-pro"
]
},
{
"name": "siliconflow",
"api_base_url": "https://api.siliconflow.cn/v1/chat/completions",
"api_key": "sk-xxx",
"models": ["moonshotai/Kimi-K2-Instruct"],
"transformer": {
"use": [
[
"maxtoken",
{
"max_tokens": 16384
}
]
]
}
}
],
"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"
}
}
首次使用需要创建 ~/.claude-code-router/config.json 文件,以魔搭社区Qwen3和OpenRouter为例,配置如下内容,对魔搭社区API Key申请还不了解的小伙伴可以看往期内容:Claude Code CLI平台与中转站接入汇总及避坑
json
{
"Providers": [
{
"name": "modelscope",
"api_base_url": "https://api-inference.modelscope.cn/v1/chat/completions",
"api_key": "魔搭API Key",
"models": ["Qwen/Qwen3-Coder-480B-A35B-Instruct", "Qwen/Qwen3-235B-A22B-Thinking-2507"],
"transformer": {
"use": [
[
"maxtoken",
{
"max_tokens": 65536
}
],
"enhancetool"
],
"Qwen/Qwen3-235B-A22B-Thinking-2507": {
"use": ["reasoning"]
}
}
},
{
"name": "openrouter",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "OpenRouter API Key",
"models": [
"deepseek/deepseek-chat-v3.1:free",
"deepseek/deepseek-r1-0528:free"
],
"transformer": {
"use": ["openrouter"]
}
}
],
"Router": {
"default": "modelscope,Qwen/Qwen3-Coder-480B-A35B-Instruct"
}
}

config.json 文件有几个关键部分:
- PROXY_URL:可以为 API 请求设置代理,例如: "PROXY_URL": "http://127.0.0.1:7890" 。
- LOG:可以通过将其设置为 true 来启用日志记录。设置为 false 时,不会创建任何日志文件。默认值为 true。
- LOG_LEVEL:设置日志记录级别。可用选项包括:fatal、error、warn、info、debug、trace。默认值为 debug。
- APIKEY:设置密钥来验证请求。设置后,客户端必须在 Authorization 标头(例如,Bearer your-secret-key)或 x-api-key 标头中提供此密钥。示例:"APIKEY": "your-secret-key"。
- HOST:设置服务器的主机地址。如果未设置 APIKEY,出于安全考虑,主机将被强制设置为 127.0.0.1,以防止未经授权的访问。示例:"HOST": "0.0.0.0"。
- NON_INTERACTIVE_MODE:设置为 true 时,启用与非交互式环境(如 GitHub Actions、Docker 容器或其他 CI/CD 系统)的兼容性。这会设置适当的环境变量(CI=true、FORCE_COLOR=0 等)并配置标准处理以防止进程在自动化环境中挂起。示例:"NON_INTERACTIVE_MODE": true。
- Providers:用于配置不同的模型提供者
- name:提供程序的唯一名称
- api_base_url:用于聊天的完整 API endpoint
- api_key:提供商的 API 密钥
- models:此提供程序提供的型号名称列表
- transformer:指定用于处理请求和响应的转换器,可以指定将转换器应用于特定模型
- Router:用于设置路由规则,default 指定默认模型,如果未配置其他路由,则该模型将用于所有请求
- default:常规任务的默认模型
- background:后台任务的模型。这可以是一个较小的本地模型,以节省成本
- think:推理繁重的任务的模型,例如计划模式
- longContext:用于处理长上下文(例如,> 60K 令牌)的模型
- longContextThreshold:触发长上下文模型的令牌计数阈值。如果未指定,则默认为 60000
- webSearch:用于处理 Web 搜索任务,这需要模型本身支持该功
- image:用于处理与图像相关的任务(由 CCR 的内置代理支持)。如果模型不支持工具调用,则需要将config.forceUseImageAgent 属性设置为 true
- API_TIMEOUT_MS:指定 API 调用的超时时间(以毫秒为单位)
UI配置
Claude Code Router提供了可视化UI配置方式来配置 ~/.claude-code-router/config.json 文件,对配置文件形式不习惯的小伙伴也可以使用可视化交互配置形式。
在命令行终端输入 ccr ui 即可在浏览器打开Web配置界面

可以看到这里也正确展示了我们使用配置文件添加的供应商及模型配置

点击【设置】可以进行通用设置配置

点击【状态栏配置】可以设置状态栏展示效果(本人尝试没有看到效果)

点击【JOSN】可以以编辑器形式对config.json进行配置

点击【日志】可以查看日志信息

点击【添加供应商】,选择【deepseek】模版,输入【API密钥】,点击【保存】

保存成功后,即可在供应商列表查看刚刚添加的供应商信息,切换默认路由配置为【deepseek,deepseek-chat】,点击【保存并重启】保存配置文件重启Claude Code Router服务

使用 ccr code 重启Claude Code Router即可使用

启动Claude Code Router
在命令行终端输入 ccr code 即可启动 Claude Code Router 和 Claude Code CLI,并通过 Router 拦截并路由所有请求。
css
$ ccr code
启动成功后,效果如下,对Claude Code CLI还不了解的小伙伴可以看往期内容:Claude Code CLI初体验

可以看到【API Base URL】地址为本机地址:http://127.0.0.1:3456,输入提示词测试一下,看到正常回复即为配置成功

自定义转换器
Claude Code Router提供自定义转换器功能为非官方供应商提供模型支持,这里以Gemini CLI为例对Gemini提供非官方支持, gemini-cli插件地址:gist.github.com/musistudio/...
下载文件保存到 ~/.claude-code-router/plugins/gemini-cli.js,点击【添加自定义转换器】输入转换器插件文件路径和project参数

保存成功后完整配置如下:
bash
{
"LOG": false,
"LOG_LEVEL": "debug",
"CLAUDE_PATH": "",
"HOST": "127.0.0.1",
"PORT": 3456,
"APIKEY": "",
"API_TIMEOUT_MS": "600000",
"PROXY_URL": "",
"transformers": [
{
"name": "",
"path": "$HOME/.claude-code-router/plugins/gemini-cli.js",
"options": {
"project": "your-google-cloud-project-id"
}
}
],
"Providers": [
{
"name": "gemini",
"api_base_url": "https://cloudcode-pa.googleapis.com/v1internal",
"api_key": "gemini api key",
"models": [
"gemini-2.5-flash",
"gemini-2.5-pro"
],
"transformer": {
"use": [
"gemini-cli"
]
}
}
],
"Router": {
"default": "gemini,gemini-2.5-flash",
"background": "",
"think": "",
"longContext": "",
"longContextThreshold": 60000,
"webSearch": "",
"image": ""
},
"CUSTOM_ROUTER_PATH": ""
}
本人这里配置失败了,有需求的小伙伴可以再深入研究研究

常见问题
修改配置文件不生效
有时通过配置文件修改了配置,配置确认无误,但是不管如何使用 ccr code 重启Claude Code CLI就是无法正常使用,遇到这种问题,我们可以尝试在命令行终端输入以下命令重启 Claude Code Router 服务
php
$ ccr restart

重启完成后,再次使用 ccr code 重启Claude Code Router。
总结
Claude Code Router提供了整合多模型共同高效完成任务的能力,同时提供灵活的配置方式,告别单一模型的局限性和高昂的成本,但是与此同时也带来了一定的问题,多模型整合意味着无法详细计算tokens消耗,无法知晓都使用了哪些模型,再加上目前工具尚有一些bug,我们还是需要根据自己的情况酌情使用。随着目前各大供应商陆续支持Claude Code CLI,在Claude Code CLI中使用不同模型也不再是限制问题,只需在在命令行终端配置Base URL和API Key即可,甚至比Claude Code Router配置更简单,所以对于使用单模型的小伙伴来说使用Claude Code Router就显得没有必要了。
友情提示
见原文:使用Claude Code Router轻松切换各种高性价比模型
本文同步自微信公众号 "程序员小溪" ,这里只是同步,想看及时消息请移步我的公众号,不定时更新我的学习经验。友情提示友情提示