当我开始大量使用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 之前,请确认以下条件已就绪:
您无需一开始就注册所有提供商。一个可用的后端足以完成本教程,后续可随时添加更多。
若想将 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 ) {
return null ;
} ; 技术支持
例如,您可以在此实现“遇到 429 速率限制自动重试并改道到备选提供商”的逻辑。任何配置更改后,记得重启服务以生效:
ccr restart技术支持
运行与故障排查 Claude Code Router
在路由正常工作后,重点转向如何保持系统的可观测性、安全性,以及在出现问题时便于调试。
监控用量并执行预算约束
CCR 提供两套值得了解的日志系统:
定期查看服务器日志,您就能清楚了解哪些路由被触发、调用了哪些模型,以及是否发生了提供商错误。
为获得实时可见性,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" 以抑制冗长的调试输出。
一种务实的做法是将所有 API 密钥保存在您的 shell 配置中,并在 config.json 中通过 $VAR_NAME 语法引用。这样,配置文件本身不包含任何机密,可以安全共享或纳入版本控制。
如果您不确定是否有密钥泄漏到日志中,先检查日志级别设置。切换到 "LOG_LEVEL": "warn" 是在不完全禁用日志的前提下,最快减少落盘内容的方法。
排查常见路由故障
当出现故障时,分层诊断流程能节省大量时间。我建议从最外层开始,逐步向内排查。
步骤 1:检查代理是否在运行
运行 ccr code 并查看服务启动确认信息。如果端口被占用或服务启动失败,您会在 Claude Code 中看到连接被拒绝的错误。
检查 ~/.claude-code-router/logs/ 中的服务器日志以获取详情。大多数启动失败要么是端口冲突,要么是 config.json 配置格式有误。
步骤 2:核对模型名称一致性
最常见的配置错误是 Providers 中的模型名与 Router 中的不一致。两者必须完全相同。
如果不一致,CCR 会发送一个没有模型字段的请求,您会看到 Missing model in request body 错误。修正配置后,务必运行 ccr restart 重新加载。
步骤 3:检查提供商侧设置
如果模型名正确但请求仍以 404 失败,请检查您的提供商账户设置。例如,OpenRouter 的默认隐私策略会阻止免费模型向第三方提供商发送数据。您会看到类似 No endpoints found matching your data policy 的错误。
解决方法是访问 OpenRouter 隐私设置并启用免费模型使用。若遇到意外的 4xx 错误,其他提供商也可能有类似的账户级开关值得检查。
如果请求能到达提供商,但响应格式错误或工具调用失败,通常是缺失或错误的 transformer 所致。请将您的提供商与内置 transformer 列表交叉核对,并确保在 "use" 数组中配置了正确的 transformer。
多数情况下,按上述四个步骤依次排查即可快速定位问题。服务器日志会同时捕获发出的请求与提供商的原始响应,为您提供定位故障所需的一切信息。
结语
至此,您已经在 Claude Code 之上构建好了一个可用的多提供商路由基础设施。后台任务走快速本地模型,重推理工作路由到专长模型,长上下文请求由高容量提供商处理,且一切都基于您自定义的规则自动完成。
直接收益包括更低的 API 成本、在速率限制下不再有单点故障,以及无需更改工作流即可灵活更换提供商。
为长期保持高效,请定期查看路由日志。服务器日志会显示哪些路由最常触发,以及是否有昂贵模型被用于本可由更便宜替代方案处理的任务。基于真实使用情况微调 longContextThreshold 与回退规则,远比“一次设置不再过问”有效。
最后,如果您的工作涉及专有代码,我强烈建议将这些请求路由到 通过 Ollama 的本地 LLM。我会在任何涉及未发布代码的客户项目中采用这种做法。将其添加为提供商不到一分钟,且您最敏感的查询永远不会离开本机。
如果您希望进一步提升 AI 应用开发能力,强烈推荐报名我们的 AI Engineering with LangChain 技能路径。课程内容由 AI 原生驱动,为您配备一位私人导师,教授成为 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执行:要让该
PATH变更永久生效,请将export这一行添加到~/.bashrc或~/.zshrc并重新加载 shell。然后安装 CCR:这会让
ccrCLI 在您的 shell 中全局可用。接下来启动路由服务:CCR 默认绑定到
http://127.0.0.1:3456。当您在启动输出中看到服务已绑定该端口时,代理就已准备好接收请求。配置基础提供商
所有 CCR 配置位于
~/.claude-code-router/config.json。在接入多个提供商之前,我建议先从一个已知稳定的提供商开始,以隔离变量并确认基线可用。OpenRouter 是一个不错的起点,也是我在新机器上设置 CCR 时首先选择的。它通过一个 API 密钥提供数十个模型(包括若干免费层级),非常适合在承诺具体提供商之前先让路由层跑通。您可以在 OpenRouter 注册并获取密钥。
以下是使用 OpenRouter 的最小化配置:
有几点需要注意:
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会同时启动代理服务并启动 Claude Code,且自动预配置好环境。您无需先单独运行ccr start。要验证路由是否生效,请查看
~/.claude-code-router/logs/文件夹。里面名为ccr-*.log的文件表明代理已启动并接收请求。您可以通过以下方式实时查看请求: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:此时请确保先运行
ccr start,因为activate只会设置环境变量,并不会启动服务本身。实现多提供商路由
在验证好基线后,我们扩展配置,将不同任务类型路由到不同提供商。以下是更完整的
Router配置:每个键都将任务类别映射到一个
"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以回退到默认规则:例如,您可以在此实现“遇到 429 速率限制自动重试并改道到备选提供商”的逻辑。任何配置更改后,记得重启服务以生效:
运行与故障排查 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"以抑制冗长的调试输出。一种务实的做法是将所有 API 密钥保存在您的 shell 配置中,并在
config.json中通过$VAR_NAME语法引用。这样,配置文件本身不包含任何机密,可以安全共享或纳入版本控制。如果您不确定是否有密钥泄漏到日志中,先检查日志级别设置。切换到
"LOG_LEVEL": "warn"是在不完全禁用日志的前提下,最快减少落盘内容的方法。排查常见路由故障
当出现故障时,分层诊断流程能节省大量时间。我建议从最外层开始,逐步向内排查。
步骤 1:检查代理是否在运行
运行
ccr code并查看服务启动确认信息。如果端口被占用或服务启动失败,您会在 Claude Code 中看到连接被拒绝的错误。检查
~/.claude-code-router/logs/中的服务器日志以获取详情。大多数启动失败要么是端口冲突,要么是config.json配置格式有误。步骤 2:核对模型名称一致性
最常见的配置错误是
Providers中的模型名与Router中的不一致。两者必须完全相同。如果不一致,CCR 会发送一个没有模型字段的请求,您会看到
Missing model in request body错误。修正配置后,务必运行ccr restart重新加载。步骤 3:检查提供商侧设置
如果模型名正确但请求仍以 404 失败,请检查您的提供商账户设置。例如,OpenRouter 的默认隐私策略会阻止免费模型向第三方提供商发送数据。您会看到类似
No endpoints found matching your data policy的错误。解决方法是访问 OpenRouter 隐私设置并启用免费模型使用。若遇到意外的 4xx 错误,其他提供商也可能有类似的账户级开关值得检查。
步骤 4:检查 transformer 配置
如果请求能到达提供商,但响应格式错误或工具调用失败,通常是缺失或错误的 transformer 所致。请将您的提供商与内置 transformer 列表交叉核对,并确保在
"use"数组中配置了正确的 transformer。多数情况下,按上述四个步骤依次排查即可快速定位问题。服务器日志会同时捕获发出的请求与提供商的原始响应,为您提供定位故障所需的一切信息。
结语
至此,您已经在 Claude Code 之上构建好了一个可用的多提供商路由基础设施。后台任务走快速本地模型,重推理工作路由到专长模型,长上下文请求由高容量提供商处理,且一切都基于您自定义的规则自动完成。
直接收益包括更低的 API 成本、在速率限制下不再有单点故障,以及无需更改工作流即可灵活更换提供商。
为长期保持高效,请定期查看路由日志。服务器日志会显示哪些路由最常触发,以及是否有昂贵模型被用于本可由更便宜替代方案处理的任务。基于真实使用情况微调
longContextThreshold与回退规则,远比“一次设置不再过问”有效。最后,如果您的工作涉及专有代码,我强烈建议将这些请求路由到通过 Ollama 的本地 LLM。我会在任何涉及未发布代码的客户项目中采用这种做法。将其添加为提供商不到一分钟,且您最敏感的查询永远不会离开本机。
如果您希望进一步提升 AI 应用开发能力,强烈推荐报名我们的 AI Engineering with LangChain 技能路径。课程内容由 AI 原生驱动,为您配备一位私人导师,教授成为 AI 工作流工程高手所需的硬核技能。