做开发这几年命令行里的AI编程工具换了一茬又一茬Claude Code算是我目前用得最顺手的一个。但很多人上手后都会撞到同一个问题它默认只认Anthropic官方接口而手里的私有模型、国产API、或者公司内网部署的开源模型根本没法直接接进去。网上各种教程东一榔头西一棒槌有人改环境变量有人写中转脚本折腾半天还是报错。我这边实际跑通了一套方案用ccrClaude Code Router这类路由代理工具把Claude Code的请求转发到私有模型上。文章里会把这套代理方案的思路、选型、完整配置步骤和常见的坑都拆开讲清楚适合那些已经在用或准备用Claude Code但不想被绑死在官方模型上的开发者。看完你就能自己接上DeepSeek、Qwen这类第三方API也能接到本地部署的vLLM或Ollama服务上。1. 整体设计思路为什么Claude Code非要套一层代理1.1 Clode Code原生架构的限制Claude Code虽然是命令行工具但它的模型调用链路其实是固定的客户端通过Anthropic Messages API格式发请求目标地址默认指向官方接口鉴权走的是Anthropic的API Key体系。这就带来一个现实问题——如果你想用别的模型直接把环境变量ANTHROPIC_BASE_URL指向第三方地址是能通但很快会遇到接口格式不兼容、鉴权方式对不上、模型名不被识别这类问题。深层原因在于Claude Code的代码里写死了很多Anthropic专有的东西。比如请求体里的某些参数结构、流式输出的事件格式、甚至错误处理逻辑都依赖Anthropic API的规范。第三方服务就算兼容了Messages API的大框架细节上也总有出入。我没有去改Claude Code的源码而是在它和模型服务中间加一个代理层。1.2 ccr在链路中扮演的角色ccr做的事情说穿了就是一个协议翻译和流量分发的过程。Claude Code发出的请求先打到ccr监听的本地端口上ccr拿到请求后按照配置好的规则去改写目标地址、替换鉴权头、调整请求体结构然后再转发给真正的模型服务。响应回来的时候ccr再做一次逆向的格式规整把不同模型服务的返回格式统一成Claude Code能识别的样子。这个思路其实和nginx反向代理很像。nginx是对流量做转发和负载均衡ccr则是在应用层对API请求做语义级别的转换。你完全可以把它理解成一个私人的API网关只不过这个网关服务的对象是Claude Code这一个客户端。这样做的好处是Claude Code本身不需要任何改动它始终以为自己在和Anthropic官方API对话。1.3 什么场景下值得用这套方案根据我自己的经验下面这三种情况最适合用ccr优先级也是从高到低公司或团队内部部署了私有模型出于数据合规的考虑代码和对话内容不能出内网只能用代理切到内网地址。你同时有多个模型的API额度比如DeepSeek、通义千问、GLM想在一个Claude Code会话里灵活切换而不是反复改环境变量重启。依赖官方模型但需要模型名兼容、请求格式转换或者想统一统计多模型的调用量。如果你的需求只是临时试一个第三方模型那手动改环境变量就够了不必上ccr。但如果你打算长期把它当主力工具用代理层带来的统一入口和可配置性投入产出比是值得的。2. 环境准备与工具选型2.1 ccr项目到底怎么选目前社区里这类工具挺多但其实核心功能大同小异差别主要在配置格式和维护活跃度上。我用的ccr主指claude-code-router这一类实现。它和其他的代理工具相比最大的优势是配置方式直白——用JSON文件管理上游提供商改完不用重启热加载后就生效。选型时我建议优先看三点一是是否支持OpenAI和Anthropic两种协议格式的转换这决定了你能不能接OpenAI兼容接口的国产模型二是是否支持模型名的映射改写这直接决定Claude Code能不能识别你配置的模型名三是社区活跃度这个决定了你踩坑后能不能快速找到答案。2.2 运行环境依赖准备ccr基于Node.js开发所以环境里先得有Node.js。版本建议16以上我实际用的是18和20两个版本都跑得挺稳。装Node的时候顺手把npm配上国内环境如果遇到下载慢可以考虑用镜像源这一步和普通的Node项目没有区别。node -v npm -v这两个命令能输出版本号就说明环境没问题。另外需要注意的是如果你打算把ccr作为后台常驻服务建议装一个pm2或者用systemd来守护进程不然终端一关代理就断了Claude Code也跟着全挂。2.3 安装ccr的两种方式安装方式主要有两种一种是npm全局安装装完直接有命令行工具另一种是clone仓库自己跑。我推荐第一种省事升级也方便。npm install -g cloudflare/claude-code-router装完后运行一下版本号确认安装成功ccr --version如果你更习惯用Docker来隔离环境也可以走容器方案把配置文件用volume挂载进去。不过我个人觉得一个Node工具没必要上Docker除非你是在服务器上跑需要和宿主机隔离的时候才考虑。2.4 配置目录结构说明ccr装完后第一次运行会在用户目录下生成一个配置文件夹里面主要有几个关键文件config.json全局配置定义服务端口、日志级别等。providers.json上游模型服务商的连接信息包括API地址、密钥、模型列表。settings.json运行时的偏好设置比如模型映射规则。实际修改时我建议先用默认路径跑通再考虑自定义。千万别一开始就改目录位置不然报错都分不清是路径问题还是配置问题。3. 核心配置与参数详解3.1 上游提供商配置逻辑ccr的配置模型是“提供商 模型”的两层结构。一个提供商对应一个API服务比如你接入DeepSeek就要在providers里加一项deepseek的配置填上它的Base URL和API Key然后在模型列表里列出你想用的模型名。这里有个关键的坑要提前说很多第三方API同时兼容OpenAI格式和Anthropic格式但Claude Code只走Anthropic格式。ccr在转发时会帮你做转换但前提是提供商配置里明确标注了协议的兼容类型。如果标错了后续请求大概率会报400或者404。我当前用的DeepSeek配置示例是这样的{ providers: { deepseek: { baseUrl: https://api.deepseek.com/v1, apiKey: sk-你的密钥, models: [deepseek-chat, deepseek-reasoner] } } }注意这里的baseUrl要写到能直接接受Messages请求的路径如果填错了二级路径ccr转发时拼出来的URL就会打到不存在的接口上。3.2 模型映射规则详解模型映射是ccr里最核心、也最容易踩坑的部分。默认情况下Claude Code会请求claude-sonnet-4-20250514这类Anthropic官方模型名如果不做映射ccr就会拿着这个名字去第三方服务找同名的模型那肯定找不到。映射规则本质上是做一次字符串替换。我的习惯是把Claude Code默认请求的模型名映射到第三方提供商的实际模型名上同时把提供商指定为DeepSeek{ modelMapping: { claude-sonnet-4-20250514: { provider: deepseek, model: deepseek-chat }, claude-opus-4-20250514: { provider: deepseek, model: deepseek-reasoner } } }这样做的好处是Claude Code内部逻辑不需要感知真实的模型名它只知道自己在用官方模型。映射之后的实际流量去向由ccr全权掌控。你要是同时接了好几个提供商可以按前缀区分映射比如把不同的官方模型名映射到不同提供商实现真正意义上的多模型混用。3.3 密钥认证与安全实践安全这块我吃过不小的亏。一开始图省事直接把API Key明文写在providers.json里结果有一次不小心把这个配置文件提交到仓库Key直接泄露。后来养成了两个习惯。第一API Key优先用环境变量注入。ccr支持在配置值里写${DEEPSEEK_API_KEY}这种占位符启动时会自动从环境变量读取真实值。这样即使配置文件被查看也不会暴露密钥本体。{ apiKey: ${DEEPSEEK_API_KEY} }第二如果ccr部署在服务器上只监听127.0.0.1不要监听0.0.0.0。这个工具本身没有鉴权谁拿到端口都能用你的代理相当于裸奔。监听本地地址能挡住绝大多数误用风险。3.4 与Claude Code的对接环境变量ccr配置好后还需要让Claude Code知道请求要发到本地代理。这一步是通过Claude Code的环境变量完成的。需要设置两个ANTHROPIC_BASE_URLhttp://127.0.0.1:3456 ANTHROPIC_AUTH_TOKEN任意占位字符串第一个变量把API请求地址指到ccr的监听端口第二个变量是Claude Code用来做鉴权头部填充的因为流量到了ccr之后会重新替换成真实的API Key所以这里填什么其实无所谓但不能为空否则Claude Code启动时会直接报错。4. 实操过程与核心环节实现4.1 快速接入DeepSeek的完整流程我把之前跑通DeepSeek的步骤整理成了一套可直接照抄的流程。在开始之前先确认你的Claude Code能用官方接口正常对话这是基础前提。第一步安装并启动ccrnpm install -g cloudflare/claude-code-router ccr启动后看到类似proxy listening on http://127.0.0.1:3456的日志说明ccr已经就绪接下来就去配置上游。第二步编辑providers.json加入DeepSeek提供商信息。这里有几个容易出错的小细节baseUrl建议带到/v1层级因为DeepSeek的OpenAI兼容接口是以/v1为前缀的模型名需要确认是最新的版本更新后旧模型名可能已经下线。第三步编辑settings.json配置模型映射。我上面那套映射规则直接复制过去改一下就行。跑完这三步ccr的热加载机制会自动读取新配置不用重启。第四步设置Claude Code的环境变量export ANTHROPIC_BASE_URLhttp://127.0.0.1:3456 export ANTHROPIC_AUTH_TOKENccr-local-proxy然后启动Claude Code随便问一个问题。如果能看到DeepSeek风格的回答说明链路已经通了。4.2 接入本地vLLM服务的操作细节本地部署的私有模型走的是另一条路线。以vLLM起服务的场景为例假设你已经在本机或者内网服务器上起好了一个vLLM服务监听在8000端口。那么ccr的提供商配置要按下面的方式写{ local: { baseUrl: http://127.0.0.1:8000/v1, apiKey: EMPTY, models: [local-model-name] } }本地服务一般不需要鉴权apiKey可以随便填一个占位值但字段不能不写否则ccr组装请求头的时候会漏掉Authorization字段。映射规则的原理和DeepSeek一样只是把目标模型名改成你vLLM里实际部署的模型名。这里有一个需要特别注意的问题vLLM的模型名和你在启动服务时--served-model-name参数传的名字保持一致否则虽然请求能发到8000端口但服务端会返回model not found。如果vLLM服务部署在另外一台机器上直接把baseUrl里的IP换掉就行。因为ccr是跑在本地的Claude Code访问ccr走localhostccr访问vLLM走内网IP这个链路里的网络权限需要提前放通。4.3 验证代理是否生效的方法通不通不能只看Claude Code的界面那是结果表象。我更推荐直接用curl去测ccr的转发效果。在配置好DeepSeek映射之后手动发一个最小的Messages请求curl http://127.0.0.1:3456/v1/messages \ -H x-api-key: test-key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: ping}] }如果配置正确你会看到返回的结果是DeepSeek模型生成的但响应格式是Anthropic风格的。如果这里能通Claude Code对接也基本不会出问题。排除故障时这一招能快速判断问题出在ccr配置还是Claude Code侧。4.4 日常使用中的多模型切换技巧ccr还有一个让我用得很舒服的特性不用退出Claude Code就能切换底层模型。做法是在Claude Code的交互界面里用/model命令选择映射配置中定义过的模型名或者通过修改settings.json中的映射规则热加载后立刻生效。我通常会为一个项目准备两套映射日常写代码用deepseek-chat追求深度推理时切到字节或通义的推理型模型。Claude Code内部不感知底层模型的切换它只知道自己把请求发出去了返回的结果是合理的就行。这套模式特别适合多模型对比的场景同一段代码让不同模型分别重写然后人工挑最优方案。5. 常见问题与排查技巧实录5.1 高频问题速查表我把这半年遇到的高频问题整理成了一个速查表按出现频率排序基本上照着排查就能解决大部分问题。报错现象可能原因解决方案返回400提到reasoning_content第三方推理模型返回了非标准字段在ccr配置中过滤或映射该字段提示模型名不被Claude Code识别模型名被Claude Code白名单拦截用映射把官方模型名改写为目标模型名请求超时或连接被重置网络不通或ccr未监听正确端口确认ANTHROPIC_BASE_URL端口和ccr一致返回401鉴权失败API Key配错或环境变量未注入检查providers中的密钥和env中的占位符返回404baseUrl路径错误确认provider的baseUrl包含正确的API版本前缀流式输出卡住不动SSE流式格式不兼容在ccr中关闭或重写流式响应格式5.2 400错误thinking模式下reasoning_content报错这个报错是我在接入带推理能力的模型时遇到的最具迷惑性。现象是Claude Code发送请求后上游模型正常返回了内容但ccr在转成Anthropic格式时报400日志里能看到reasoning_content字段相关的异常。原因在于DeepSeek这类推理模型在“思考模式”下返回体里会多出一个reasoning_content字段用来承载模型的推理过程。但Anthropic Messages API的规范里没有这个字段ccr在做格式转换时如果不做特殊处理就会把这个多出来的字段原样塞进响应里Claude Code一解析就直接报错。解决办法有两个层面。第一个层面是在ccr配置里打开对该字段的过滤开关让代理在转发响应时把reasoning_content剥离掉或转换成Anthropic支持的thinking块。第二个层面是换用非推理模型比如deepseek-chat而不是deepseek-reasoner绕开这个字段。如果两个都不行那就得检查一下你用的模型API版本是不是正式版有些测试版接口返回结构不稳定。5.3 模型名不被Claude Code识别的处理[deepseek-v4-pro] is not a model this version of Claude Code recognizes这种报错和上游没啥关系纯粹是Claude Code客户端自己做了模型名校验。它有一个内部的模型白名单你传入的模型名如果不在名单里客户端直接就拦截了请求根本不会发到ccr。理解这个机制后解决思路就清晰了永远不要让Claude Code看到真实的目标模型名。也就是说在Claude Code的对话界面上你只能选它认识的那些模型比如claude-sonnet-4-20250514然后让ccr在代理层把模型名替换成实际的第三方模型。配置上就是前面的modelMapping这是唯一的正解。另外提一句Claude Code的模型白名单会跟着版本更新变化升级新版本后之前能用的模型名可能被移除需要在claude code里重新选择一遍映射用的官方模型名。5.4 超时与响应卡顿的优化思路接入私有模型后最影响体验的就是响应慢。尤其本地部署的模型如果显卡配置不高首字延迟会非常明显。Claude Code本身对请求超时有一套自己的逻辑时间太短的直接中断表现为“请求失败请重试”。我的经验是从三个方向来优化。第一检查ccr是否开了流式输出stream开启后效果会好很多模型边生成边输出就算速度慢也不至于让Claude Code判定为超时。第二调整Claude Code的超时参数允许更多等待时间这样本地模型推理慢一点也不会被打断。第三如果问题出在模型推理本身那就得优化部署方案了比如换量化版本、调整并发数这个和代理本身无关。另外一个不太起眼但容易踩的坑是ccr日志在长时间运行后会把磁盘撑满。日志级别如果开到debug每轮对话都会产生大量log。建议在生产环境把日志级设置为info或warn并加上日志滚动能力。6. 一些值得留意的实战心得文章最后分享几个我实际用下来的心得不一定适合所有人但至少能帮你少走弯路。先说说ccr的值不值得长期用。如果你只是拿Claude Code试用一下改环境变量就够了没必要上代理层。但如果你每天十几个小时泡在终端里让Claude Code成为主要编码助手那代理层的价值就体现出来了——所有模型调用统一走一个入口切换模型不用重启故障排查也有日志可看。这个投入产出比是值得的。再说一个很多人问过我的问题多个Claude Code窗口同时跑会不会冲突。在我的实践里多个窗口的请求都发到同一个ccr端口是不会有冲突的因为Claude Code本身是独立的会话ccr只负责转发。但如果你的上游API有并发限制多个窗口同时跑大批量任务时还是会触发限流这就要靠上游服务的配额管理来解决了。最后提一个小技巧把ccr的启动命令和Claude Code的环境变量写成一个简单的启动脚本。我这边就是一个start.sh里面依次设置环境变量、启动ccr、然后进入Claude Code。这样每次开新终端只需要一条命令省去了重复敲环境变量的麻烦。习惯之后你会觉得这种“官方客户端 私有模型代理”的组合才是命令行AI编程的王道。 
长河君 · 2026/9/9 9:54:32 · 阅读 1.2k Claude Code接入私有模型：用代理路由打通DeepSeek与本地服务
做开发这几年命令行里的AI编程工具换了一茬又一茬Claude Code算是我目前用得最顺手的一个。但很多人上手后都会撞到同一个问题它默认只认Anthropic官方接口而手里的私有模型、国产API、或者公司内网部署的开源模型根本没法直接接进去。网上各种教程东一榔头西一棒槌有人改环境变量有人写中转脚本折腾半天还是报错。我这边实际跑通了一套方案用ccrClaude Code Router这类路由代理工具把Claude Code的请求转发到私有模型上。文章里会把这套代理方案的思路、选型、完整配置步骤和常见的坑都拆开讲清楚适合那些已经在用或准备用Claude Code但不想被绑死在官方模型上的开发者。看完你就能自己接上DeepSeek、Qwen这类第三方API也能接到本地部署的vLLM或Ollama服务上。1. 整体设计思路为什么Claude Code非要套一层代理1.1 Clode Code原生架构的限制Claude Code虽然是命令行工具但它的模型调用链路其实是固定的客户端通过Anthropic Messages API格式发请求目标地址默认指向官方接口鉴权走的是Anthropic的API Key体系。这就带来一个现实问题——如果你想用别的模型直接把环境变量ANTHROPIC_BASE_URL指向第三方地址是能通但很快会遇到接口格式不兼容、鉴权方式对不上、模型名不被识别这类问题。深层原因在于Claude Code的代码里写死了很多Anthropic专有的东西。比如请求体里的某些参数结构、流式输出的事件格式、甚至错误处理逻辑都依赖Anthropic API的规范。第三方服务就算兼容了Messages API的大框架细节上也总有出入。我没有去改Claude Code的源码而是在它和模型服务中间加一个代理层。1.2 ccr在链路中扮演的角色ccr做的事情说穿了就是一个协议翻译和流量分发的过程。Claude Code发出的请求先打到ccr监听的本地端口上ccr拿到请求后按照配置好的规则去改写目标地址、替换鉴权头、调整请求体结构然后再转发给真正的模型服务。响应回来的时候ccr再做一次逆向的格式规整把不同模型服务的返回格式统一成Claude Code能识别的样子。这个思路其实和nginx反向代理很像。nginx是对流量做转发和负载均衡ccr则是在应用层对API请求做语义级别的转换。你完全可以把它理解成一个私人的API网关只不过这个网关服务的对象是Claude Code这一个客户端。这样做的好处是Claude Code本身不需要任何改动它始终以为自己在和Anthropic官方API对话。1.3 什么场景下值得用这套方案根据我自己的经验下面这三种情况最适合用ccr优先级也是从高到低公司或团队内部部署了私有模型出于数据合规的考虑代码和对话内容不能出内网只能用代理切到内网地址。你同时有多个模型的API额度比如DeepSeek、通义千问、GLM想在一个Claude Code会话里灵活切换而不是反复改环境变量重启。依赖官方模型但需要模型名兼容、请求格式转换或者想统一统计多模型的调用量。如果你的需求只是临时试一个第三方模型那手动改环境变量就够了不必上ccr。但如果你打算长期把它当主力工具用代理层带来的统一入口和可配置性投入产出比是值得的。2. 环境准备与工具选型2.1 ccr项目到底怎么选目前社区里这类工具挺多但其实核心功能大同小异差别主要在配置格式和维护活跃度上。我用的ccr主指claude-code-router这一类实现。它和其他的代理工具相比最大的优势是配置方式直白——用JSON文件管理上游提供商改完不用重启热加载后就生效。选型时我建议优先看三点一是是否支持OpenAI和Anthropic两种协议格式的转换这决定了你能不能接OpenAI兼容接口的国产模型二是是否支持模型名的映射改写这直接决定Claude Code能不能识别你配置的模型名三是社区活跃度这个决定了你踩坑后能不能快速找到答案。2.2 运行环境依赖准备ccr基于Node.js开发所以环境里先得有Node.js。版本建议16以上我实际用的是18和20两个版本都跑得挺稳。装Node的时候顺手把npm配上国内环境如果遇到下载慢可以考虑用镜像源这一步和普通的Node项目没有区别。node -v npm -v这两个命令能输出版本号就说明环境没问题。另外需要注意的是如果你打算把ccr作为后台常驻服务建议装一个pm2或者用systemd来守护进程不然终端一关代理就断了Claude Code也跟着全挂。2.3 安装ccr的两种方式安装方式主要有两种一种是npm全局安装装完直接有命令行工具另一种是clone仓库自己跑。我推荐第一种省事升级也方便。npm install -g cloudflare/claude-code-router装完后运行一下版本号确认安装成功ccr --version如果你更习惯用Docker来隔离环境也可以走容器方案把配置文件用volume挂载进去。不过我个人觉得一个Node工具没必要上Docker除非你是在服务器上跑需要和宿主机隔离的时候才考虑。2.4 配置目录结构说明ccr装完后第一次运行会在用户目录下生成一个配置文件夹里面主要有几个关键文件config.json全局配置定义服务端口、日志级别等。providers.json上游模型服务商的连接信息包括API地址、密钥、模型列表。settings.json运行时的偏好设置比如模型映射规则。实际修改时我建议先用默认路径跑通再考虑自定义。千万别一开始就改目录位置不然报错都分不清是路径问题还是配置问题。3. 核心配置与参数详解3.1 上游提供商配置逻辑ccr的配置模型是“提供商 模型”的两层结构。一个提供商对应一个API服务比如你接入DeepSeek就要在providers里加一项deepseek的配置填上它的Base URL和API Key然后在模型列表里列出你想用的模型名。这里有个关键的坑要提前说很多第三方API同时兼容OpenAI格式和Anthropic格式但Claude Code只走Anthropic格式。ccr在转发时会帮你做转换但前提是提供商配置里明确标注了协议的兼容类型。如果标错了后续请求大概率会报400或者404。我当前用的DeepSeek配置示例是这样的{ providers: { deepseek: { baseUrl: https://api.deepseek.com/v1, apiKey: sk-你的密钥, models: [deepseek-chat, deepseek-reasoner] } } }注意这里的baseUrl要写到能直接接受Messages请求的路径如果填错了二级路径ccr转发时拼出来的URL就会打到不存在的接口上。3.2 模型映射规则详解模型映射是ccr里最核心、也最容易踩坑的部分。默认情况下Claude Code会请求claude-sonnet-4-20250514这类Anthropic官方模型名如果不做映射ccr就会拿着这个名字去第三方服务找同名的模型那肯定找不到。映射规则本质上是做一次字符串替换。我的习惯是把Claude Code默认请求的模型名映射到第三方提供商的实际模型名上同时把提供商指定为DeepSeek{ modelMapping: { claude-sonnet-4-20250514: { provider: deepseek, model: deepseek-chat }, claude-opus-4-20250514: { provider: deepseek, model: deepseek-reasoner } } }这样做的好处是Claude Code内部逻辑不需要感知真实的模型名它只知道自己在用官方模型。映射之后的实际流量去向由ccr全权掌控。你要是同时接了好几个提供商可以按前缀区分映射比如把不同的官方模型名映射到不同提供商实现真正意义上的多模型混用。3.3 密钥认证与安全实践安全这块我吃过不小的亏。一开始图省事直接把API Key明文写在providers.json里结果有一次不小心把这个配置文件提交到仓库Key直接泄露。后来养成了两个习惯。第一API Key优先用环境变量注入。ccr支持在配置值里写${DEEPSEEK_API_KEY}这种占位符启动时会自动从环境变量读取真实值。这样即使配置文件被查看也不会暴露密钥本体。{ apiKey: ${DEEPSEEK_API_KEY} }第二如果ccr部署在服务器上只监听127.0.0.1不要监听0.0.0.0。这个工具本身没有鉴权谁拿到端口都能用你的代理相当于裸奔。监听本地地址能挡住绝大多数误用风险。3.4 与Claude Code的对接环境变量ccr配置好后还需要让Claude Code知道请求要发到本地代理。这一步是通过Claude Code的环境变量完成的。需要设置两个ANTHROPIC_BASE_URLhttp://127.0.0.1:3456 ANTHROPIC_AUTH_TOKEN任意占位字符串第一个变量把API请求地址指到ccr的监听端口第二个变量是Claude Code用来做鉴权头部填充的因为流量到了ccr之后会重新替换成真实的API Key所以这里填什么其实无所谓但不能为空否则Claude Code启动时会直接报错。4. 实操过程与核心环节实现4.1 快速接入DeepSeek的完整流程我把之前跑通DeepSeek的步骤整理成了一套可直接照抄的流程。在开始之前先确认你的Claude Code能用官方接口正常对话这是基础前提。第一步安装并启动ccrnpm install -g cloudflare/claude-code-router ccr启动后看到类似proxy listening on http://127.0.0.1:3456的日志说明ccr已经就绪接下来就去配置上游。第二步编辑providers.json加入DeepSeek提供商信息。这里有几个容易出错的小细节baseUrl建议带到/v1层级因为DeepSeek的OpenAI兼容接口是以/v1为前缀的模型名需要确认是最新的版本更新后旧模型名可能已经下线。第三步编辑settings.json配置模型映射。我上面那套映射规则直接复制过去改一下就行。跑完这三步ccr的热加载机制会自动读取新配置不用重启。第四步设置Claude Code的环境变量export ANTHROPIC_BASE_URLhttp://127.0.0.1:3456 export ANTHROPIC_AUTH_TOKENccr-local-proxy然后启动Claude Code随便问一个问题。如果能看到DeepSeek风格的回答说明链路已经通了。4.2 接入本地vLLM服务的操作细节本地部署的私有模型走的是另一条路线。以vLLM起服务的场景为例假设你已经在本机或者内网服务器上起好了一个vLLM服务监听在8000端口。那么ccr的提供商配置要按下面的方式写{ local: { baseUrl: http://127.0.0.1:8000/v1, apiKey: EMPTY, models: [local-model-name] } }本地服务一般不需要鉴权apiKey可以随便填一个占位值但字段不能不写否则ccr组装请求头的时候会漏掉Authorization字段。映射规则的原理和DeepSeek一样只是把目标模型名改成你vLLM里实际部署的模型名。这里有一个需要特别注意的问题vLLM的模型名和你在启动服务时--served-model-name参数传的名字保持一致否则虽然请求能发到8000端口但服务端会返回model not found。如果vLLM服务部署在另外一台机器上直接把baseUrl里的IP换掉就行。因为ccr是跑在本地的Claude Code访问ccr走localhostccr访问vLLM走内网IP这个链路里的网络权限需要提前放通。4.3 验证代理是否生效的方法通不通不能只看Claude Code的界面那是结果表象。我更推荐直接用curl去测ccr的转发效果。在配置好DeepSeek映射之后手动发一个最小的Messages请求curl http://127.0.0.1:3456/v1/messages \ -H x-api-key: test-key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: ping}] }如果配置正确你会看到返回的结果是DeepSeek模型生成的但响应格式是Anthropic风格的。如果这里能通Claude Code对接也基本不会出问题。排除故障时这一招能快速判断问题出在ccr配置还是Claude Code侧。4.4 日常使用中的多模型切换技巧ccr还有一个让我用得很舒服的特性不用退出Claude Code就能切换底层模型。做法是在Claude Code的交互界面里用/model命令选择映射配置中定义过的模型名或者通过修改settings.json中的映射规则热加载后立刻生效。我通常会为一个项目准备两套映射日常写代码用deepseek-chat追求深度推理时切到字节或通义的推理型模型。Claude Code内部不感知底层模型的切换它只知道自己把请求发出去了返回的结果是合理的就行。这套模式特别适合多模型对比的场景同一段代码让不同模型分别重写然后人工挑最优方案。5. 常见问题与排查技巧实录5.1 高频问题速查表我把这半年遇到的高频问题整理成了一个速查表按出现频率排序基本上照着排查就能解决大部分问题。报错现象可能原因解决方案返回400提到reasoning_content第三方推理模型返回了非标准字段在ccr配置中过滤或映射该字段提示模型名不被Claude Code识别模型名被Claude Code白名单拦截用映射把官方模型名改写为目标模型名请求超时或连接被重置网络不通或ccr未监听正确端口确认ANTHROPIC_BASE_URL端口和ccr一致返回401鉴权失败API Key配错或环境变量未注入检查providers中的密钥和env中的占位符返回404baseUrl路径错误确认provider的baseUrl包含正确的API版本前缀流式输出卡住不动SSE流式格式不兼容在ccr中关闭或重写流式响应格式5.2 400错误thinking模式下reasoning_content报错这个报错是我在接入带推理能力的模型时遇到的最具迷惑性。现象是Claude Code发送请求后上游模型正常返回了内容但ccr在转成Anthropic格式时报400日志里能看到reasoning_content字段相关的异常。原因在于DeepSeek这类推理模型在“思考模式”下返回体里会多出一个reasoning_content字段用来承载模型的推理过程。但Anthropic Messages API的规范里没有这个字段ccr在做格式转换时如果不做特殊处理就会把这个多出来的字段原样塞进响应里Claude Code一解析就直接报错。解决办法有两个层面。第一个层面是在ccr配置里打开对该字段的过滤开关让代理在转发响应时把reasoning_content剥离掉或转换成Anthropic支持的thinking块。第二个层面是换用非推理模型比如deepseek-chat而不是deepseek-reasoner绕开这个字段。如果两个都不行那就得检查一下你用的模型API版本是不是正式版有些测试版接口返回结构不稳定。5.3 模型名不被Claude Code识别的处理[deepseek-v4-pro] is not a model this version of Claude Code recognizes这种报错和上游没啥关系纯粹是Claude Code客户端自己做了模型名校验。它有一个内部的模型白名单你传入的模型名如果不在名单里客户端直接就拦截了请求根本不会发到ccr。理解这个机制后解决思路就清晰了永远不要让Claude Code看到真实的目标模型名。也就是说在Claude Code的对话界面上你只能选它认识的那些模型比如claude-sonnet-4-20250514然后让ccr在代理层把模型名替换成实际的第三方模型。配置上就是前面的modelMapping这是唯一的正解。另外提一句Claude Code的模型白名单会跟着版本更新变化升级新版本后之前能用的模型名可能被移除需要在claude code里重新选择一遍映射用的官方模型名。5.4 超时与响应卡顿的优化思路接入私有模型后最影响体验的就是响应慢。尤其本地部署的模型如果显卡配置不高首字延迟会非常明显。Claude Code本身对请求超时有一套自己的逻辑时间太短的直接中断表现为“请求失败请重试”。我的经验是从三个方向来优化。第一检查ccr是否开了流式输出stream开启后效果会好很多模型边生成边输出就算速度慢也不至于让Claude Code判定为超时。第二调整Claude Code的超时参数允许更多等待时间这样本地模型推理慢一点也不会被打断。第三如果问题出在模型推理本身那就得优化部署方案了比如换量化版本、调整并发数这个和代理本身无关。另外一个不太起眼但容易踩的坑是ccr日志在长时间运行后会把磁盘撑满。日志级别如果开到debug每轮对话都会产生大量log。建议在生产环境把日志级设置为info或warn并加上日志滚动能力。6. 一些值得留意的实战心得文章最后分享几个我实际用下来的心得不一定适合所有人但至少能帮你少走弯路。先说说ccr的值不值得长期用。如果你只是拿Claude Code试用一下改环境变量就够了没必要上代理层。但如果你每天十几个小时泡在终端里让Claude Code成为主要编码助手那代理层的价值就体现出来了——所有模型调用统一走一个入口切换模型不用重启故障排查也有日志可看。这个投入产出比是值得的。再说一个很多人问过我的问题多个Claude Code窗口同时跑会不会冲突。在我的实践里多个窗口的请求都发到同一个ccr端口是不会有冲突的因为Claude Code本身是独立的会话ccr只负责转发。但如果你的上游API有并发限制多个窗口同时跑大批量任务时还是会触发限流这就要靠上游服务的配额管理来解决了。最后提一个小技巧把ccr的启动命令和Claude Code的环境变量写成一个简单的启动脚本。我这边就是一个start.sh里面依次设置环境变量、启动ccr、然后进入Claude Code。这样每次开新终端只需要一条命令省去了重复敲环境变量的麻烦。习惯之后你会觉得这种“官方客户端 私有模型代理”的组合才是命令行AI编程的王道。