claude-code-router 是什么、怎么配:用官方 API 按任务分发多个模型的配置方法

claude-code-router(CCR)是社区开源的本机请求路由工具,可以把 Claude Code 的日常编码、后台摘要、深度思考和超长上下文分别转发给不同厂商的官方 API 或本机 Ollama。本文按开源仓库文档讲清安装、config.json 写法与启动步骤。

NNathaniel bigo··原创首发·AI 辅助撰写
10 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 免费账号 账号

结论先说

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

claude-code-router 路由槽位对照

图:本站根据 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 文件。

配置 claude-code-router 四步流程

图:本站根据 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
  }
}

配置字段里的几个关键点:

  1. HOST 保持 127.0.0.1:只监听本机回环网卡,避免局域网其他设备直接调用你的本地端口消耗 API 额度;
  2. Providers 数组:每一项定义一个官方上游提供方,name 是你在下方路由表里引用的短名,transformer 用于修正不同官方接口在流式工具调用或推理字段上的格式差异;
  3. 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 槽位当主力编码模型。

相关教程

参考资料

  • musistudio/claude-code-router 官方 GitHub 仓库 — https://github.com/musistudio/claude-code-router
  • Claude Code 官方文档:Model configuration — https://code.claude.com/docs/en/model-config

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    MCP 收费吗:开源协议免费边界、第三方 API 账单与隐形 Token 开销说明

    搜「mcp 收费 吗」的人常担心装多了插件会被扣费。MCP(模型上下文协议)本身和官方 SDK 采用 MIT 协议完全免费;实际使用中可能产生费用的只有两处:挂载过多工具占用的大模型上下文 Token,以及部分外部商业数据源自带的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 协议最新版本更新了什么:无状态架构、OAuth 2.1、结构化输出与异步 Tasks 详解

    搜「mcp 重大 更新」「mcp 协议 更新」想补齐规范演进脉络?本文对照 modelcontextprotocol.io 官方规范更新日志,梳理从 Streamable HTTP 到无状态优先架构、OAuth 2.1 资源服务器、Elicitation 交互补参与异步 Tasks 扩展的核心变化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什么区别:工具连接协议与智能体通信协议的边界和配合

    很多人问「有了 MCP 为什么还要出 A2A,两者是不是二选一的竞争关系」。两份官方规范都明确写明它们是上下互补关系:MCP 负责给单个智能体挂载工具与数据源,A2A 负责让多个独立黑盒智能体跨团队、跨框架互相派单协作。

    Claude其他 AI 工具0
  4. 04

    LangGraph 怎么使用 MCP:用 langchain-mcp-adapters 接入本地与远程工具

    想让自建的 LangGraph 状态图直接调用现成的 MCP 服务器,官方标准方案是安装 langchain-mcp-adapters 并使用 MultiServerMCPClient。本文讲清 stdio 与 streamable_http 两种配置写法、异步图运行及按节点分工具技巧。

    Claude其他 AI 工具0
  5. 05

    LangGraph 入门教程:Python 安装、核心概念与跑通第一个状态图智能体

    面向搜「python 安装 langgraph」和「langgraph 中文 文档」的初学者:本文按 LangChain 官方最新 Graph API 规范,讲清安装步骤、State/Node/Edge 四大概念,并从零写出第一个带工具调用循环的 StateGraph。

    Claude其他 AI 工具0
  6. 06

    Claude Agent SDK 子代理怎么写:AgentDefinition 配置、权限收敛与 Python/TS 示例

    在 Python 或 TypeScript 里用 Claude Agent SDK 编排多角色协作,核心是配置 ClaudeAgentOptions 的 agents 字段与 AgentDefinition。本文讲清必开的 Agent 委派权限、工具收敛、模型分级与完整代码示例。

    Claude0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~