结论先说
claude-code-router(简称 CCR)是一个跑在你本机(默认127.0.0.1:3456)的开源协议转换与路由网关,不是 Anthropic 官方组件。- 它的核心作用是「按请求特征分流」:把 Claude Code 发出的请求识别为默认任务(
default)、后台轻量任务(background)、深度推理(think)和超长上下文(longContext),分别转发给你配置的不同上游接口。 - 只建议填写各模型厂商的官方直连 API 或本机 Ollama 地址,并用
${环境变量名}引用密钥,避免明文密码落盘或把仓库代码发往来路不明的非官方服务。 - 启动时用
ccr code代替直接敲claude,工具会自动为当前子进程注入本机转发地址,不需要手工改动全局 Claude Code 登录配置。

图:本站根据 musistudio/claude-code-router 官方仓库文档 整理的示意图
本文根据开源项目musistudio/claude-code-router官方仓库说明整理,核对日期 2026-11-18。本文只介绍对接各模型厂商官方 API 与本机离线模型的配置方法。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Anthropic 官方网站。
适用于谁
- 搜「claude code router 配置 多 个 模型」「claude-code-router 怎么用」的人;
- 手里有 DeepSeek、Google Gemini 等多家厂商的官方开发者 API Key,或本机装了 Ollama,想在 Claude Code 终端交互界面里按任务分工调用的开发者;
- 想把后台生成标题、超长文件阅读和主力改码拆给不同接口处理的人。
如果你使用的都是 Claude 自家模型,优先用官方原生的 opusplan、/advisor 和子代理分模型机制就够了,不需要额外部署路由层,具体见 /guides/claude-code-multi-model-opusplan-advisor-subagents。
一、工作原理与适用边界
Claude Code 客户端本身发送的是 Anthropic Messages API 格式的请求。当你想接入其他厂商的官方接口(大多采用 OpenAI 兼容格式或各自原生格式,例如 Google Gemini API)时,协议格式并不互通。
claude-code-router 在本机起一个本地 HTTP 服务,做两件事:
- 协议转换(Transformer):把 Claude Code 发出的请求和工具调用结构转换成目标厂商官方 API 接受的格式,再把流式响应转回 Claude Code 能识别的格式;
- 分槽位路由(Router):根据请求里的模型标记、是否开启思考模式以及上下文 Token 长度,自动挑选你在
Router字段里指定的目标模型。
在动手配置前也要清楚它的边界:第三方模型在工具调用稳定性、复杂补丁格式遵循度上可能不如原生 Claude 模型;如果你主要追求开箱即用的编码质量,直接使用官方订阅(可参考 /chongzhi/claude-code 的订阅说明)或官方直连 API Key(见 /guides/claude-code-use-api-key-instead-of-login)会更省心。
二、安装与配置文件位置
先确保本机已经安装 Node.js 和官方 @anthropic-ai/claude-code,然后通过 npm 全局安装路由工具:
bash
npm install -g @musistudio/claude-code-router
安装完成后,主配置文件默认存放在用户目录下的 ~/.claude-code-router/config.json。如果你更习惯图形化表单,也可以在终端运行 ccr ui 打开本地管理面板填写并保存,底层同样会写回这份 JSON 文件。

图:本站根据 musistudio/claude-code-router 官方仓库文档 整理的示意图
三、config.json 配置示例(仅使用官方接口与本机模型)
下面是一个只对接各厂商官方开发者接口与本机 Ollama 的典型结构示例。请先把各家的密钥写进你自己的系统环境变量(如 DEEPSEEK_API_KEY、GEMINI_API_KEY),在配置文件里用插值语法引用:
json
{
"HOST": "127.0.0.1",
"PORT": 3456,
"LOG": true,
"API_TIMEOUT_MS": 600000,
"Providers": [
{
"name": "deepseek",
"api_base_url": "https://api.deepseek.com/chat/completions",
"api_key": "${DEEPSEEK_API_KEY}",
"models": ["deepseek-chat", "deepseek-reasoner"],
"transformer": { "use": ["deepseek"] }
},
{
"name": "gemini",
"api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
"api_key": "${GEMINI_API_KEY}",
"models": ["gemini-2.5-pro", "gemini-2.5-flash"],
"transformer": { "use": ["gemini"] }
},
{
"name": "ollama",
"api_base_url": "http://127.0.0.1:11434/v1/chat/completions",
"api_key": "ollama",
"models": ["qwen2.5-coder:latest"]
}
],
"Router": {
"default": "deepseek,deepseek-chat",
"background": "ollama,qwen2.5-coder:latest",
"think": "deepseek,deepseek-reasoner",
"longContext": "gemini,gemini-2.5-pro",
"longContextThreshold": 60000
}
}
配置字段里的几个关键点:
HOST保持127.0.0.1:只监听本机回环网卡,避免局域网其他设备直接调用你的本地端口消耗 API 额度;Providers数组:每一项定义一个官方上游提供方,name是你在下方路由表里引用的短名,transformer用于修正不同官方接口在流式工具调用或推理字段上的格式差异;Router路由表:值统一采用"提供方name,模型名"的逗号分隔写法。其中longContextThreshold设为60000表示当单次上下文超过约 6 万 Token 时,自动切给longContext绑定的长窗口模型处理。
四、启动会话与日常切换
保存好 config.json 后,进入你的代码仓库目录,用下面这条命令启动:
bash
ccr code
如果修改了 config.json 里的提供方或阈值,先运行 ccr restart 重启后台本地路由服务使其生效。在会话进行中,如果你想临时把当前对话切到你在 Providers 里登记过的另一个模型,也可以按仓库文档支持的 /model 提供方名,模型名 语法手动指定;关于原生 /model 命令的默认行为可对照 /guides/claude-code-switch-model。
常见问题
Q:启动 ccr code 后报 401 或环境变量读不到怎么办?
检查你在终端当前 Shell 会话里是否真的导出了对应的环境变量(例如 echo $DEEPSEEK_API_KEY),以及环境变量名大小写是否与 config.json 里的 ${...} 完全一致。不要把 ~/.claude-code-router/config.json 提交进公开代码仓库。
Q:用了 claude-code-router 之后,平时直接敲 claude 还会走本地路由吗?
只要你没有在 ~/.claude/settings.json(见 /guides/claude-code-settings-json)或系统全局环境变量里永久写死 ANTHROPIC_BASE_URL,单独运行 claude 依然走官方原有通道,只有运行 ccr code 启动的那次终端会话才会经过本地路由。
Q:为什么有的本地小模型接进去后不会改文件、只会打印代码块?
Claude Code 高度依赖模型的结构化工具调用(Tool Use)能力来执行 Read、Edit 和 Bash。参数量过小或不支持工具调用的模型无法稳定生成符合格式的参数,只适合放在 background 槽位做摘要类辅助工作,不适合放在 default 槽位当主力编码模型。
相关教程
- /guides/claude-code-multi-model-opusplan-advisor-subagents:Claude Code 原生多模型配置(opusplan、顾问与子代理)
- /guides/claude-code-use-api-key-instead-of-login:Claude Code 免登录直接配置官方 API Key
- /guides/claude-code-switch-model:Claude Code
/model模型切换与推理强度详解 - /guides/claude-code-settings-json:Claude Code
settings.json配置指南
参考资料
musistudio/claude-code-router官方 GitHub 仓库 — https://github.com/musistudio/claude-code-router- Claude Code 官方文档:Model configuration — https://code.claude.com/docs/en/model-config
0 条评论
还没有评论,来抢沙发~