1. 为什么是 Claude Code又为什么要接国产模型1.1 Claude Code 到底解决了什么问题先说清楚它是谁。Claude Code 是 Anthropic 官方出品的命令行编程助手跑在终端里可以直接读取你的项目目录分析代码结构修改文件执行测试甚至帮你提交 Git。它的使用方式和网页版聊天不一样更像一个坐在你旁边的结对程序员你给它一个任务它会自己规划步骤、调用工具、查看报错、继续修直到把活干完。我是从 2024 年底开始重度使用它的。那个时候大多数 AI 编程工具还停留在“对话生成代码片段”的阶段复制粘贴到项目里再手动调试非常割裂。Claude Code 的模式完全不同它拥有文件系统的读写权限能自己跑命令能看测试输出等于把“AI 写代码”和“AI 跑代码”串成了一条流水线。我实际用下来的体感是与其说它在聊天不如说它在“干活”。但很多小白卡在了门槛上。这工具虽然好用官方默认的使用方式是注册 Anthropic 账号、绑定海外支付方式、用官方 API Key 调用 Claude 系列模型。这一套流程对国内开发者来说每一步都有额外成本。于是“给 Claude Code 换一个国产模型后端”就成了一个非常实际的需求——保留这个强大的终端工作流把底下的模型替换成国内能直接注册、充值、调用的服务。1.2 官方 API 的门槛与国产模型的机会这里我不展开任何灰色手段只说正常渠道下的事实。Anthropic 官方 API 需要海外手机号注册需要支持外币的信用卡绑定而且按美元计费。就算你解决了账号问题付费环节也可能卡住。与此同时国内的大模型服务商提供的是人民币计费、国内直连、扫码充值注册门槛低得多。现在的国产模型已经不是我印象中“写诗可以写代码不行”的阶段了。DeepSeek 的 V3/R1 系列在代码生成和逻辑推理上表现相当能打数学、编程类 benchmark 一度冲到第一梯队。通义千问 Qwen 系列对中文场景理解更细腻智谱 GLM 有很强的函数调用能力Kimi 的长上下文在实际工程里很有优势。所以“Claude Code 国产模型”不是妥协方案而是成本、合规、体验三者平衡后的务实选择。1.3 先搞清楚要走哪条集成路线在动手之前你必须理解一个核心概念Claude Code 是客户端模型是后端。Anthropic 官方客户端默认连接 Anthropic 的 API 服务但客户端本身支持通过环境变量指定一个自定义 API 地址。如果你选的国产模型提供一个“兼容 Anthropic API 格式”的接口那就直接把地址指过去。另一条路线是中间加一个兼容转换层。因为大部分国产模型对外提供的是 OpenAI 风格的接口而 Claude Code 发的是 Anthropic 风格协议格式不一样需要有个工具在中间翻译。这就是 claude-code-router 这类开源项目存在的意义。这两条路线的选择直接决定了后面的配置方式。我个人建议优先用官方支持 Anthropic 兼容协议的模型配置最简单少一个中间环节就少一类故障。下面整个教程的核心都会围绕这条路线展开。2. 环境准备先把 Node.js、npm 和 Git 收拾利索2.1 Node.js 版本要求与安装Claude Code 是一个 npm 包所以 Node.js 是硬前提。官方要求 Node.js 18 及以上我实际测试过 18.18 和 20.x/22.x 的 LTS 版本都可以正常工作。不建议用最新的奇数版本容易被一些依赖的兼容性问题坑到。最省事的安装方式是直接去 Node.js 官网下载 LTS 版本安装包双击一路下一步。但我更推荐有编程打算的人用 nvmNode Version Manager管理 Node 版本因为后面你可能会遇到不同项目需要不同 Node 版本的情况。macOS 或 Linux 下安装curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash装完重开终端然后安装并使用最新的 LTS 版本nvm install --lts nvm use --ltsWindows 用户可以去下载 nvm-windows 的安装包或者干脆直接装官方安装包不用纠结。核心目标只有一个让node -v能输出一个不低于 v18 的版本号。2.2 Git 的作用与基础配置Git 也是必装的这一点很多教程没强调但 Claude Code 的很多关键能力都建立在 Git 之上。它修改代码之前会用git diff查看当前改动改完之后会生成补丁甚至可以用/commit命令帮你提交。如果项目目录不是一个 Git 仓库这些能力会受限。安装方式很简单macOS 执行brew install gitUbuntu 执行apt install gitWindows 装 Git for Windows 客户端。装完以后必须配置用户名和邮箱否则 Claude Code 后续自动提交时可能报错git config --global user.name 你的名字 git config --global user.email 你的邮箱这步做完在项目目录里执行git init初始化仓库。注意Claude Code 读取文件依赖目录内的.git所以新项目先初始化再使用能避免很多奇怪的问题。2.3 安装完成后必做的验证项很多小白装完工具不验证等出了问题才回头排查效率很低。建议按顺序执行下面四条命令全部通过再进入下一步node -v npm -v git --version git config --listNode 和 npm 版本别太低Git 版本没硬性要求但不要太老。git config --list能确认 user.name 和 user.email 写进去了。这四行如果都有正常输出环境部分就算过关了。3. 安装 Claude Codenpm 一行命令背后的细节3.1 全局安装命令与权限问题环境没问题之后安装 Claude Code 本体极其简单npm install -g anthropic-ai/claude-codemacOS 和 Linux 下如果遇到权限报错比如 EACCES通常是你用了系统自带的 Node而不是 nvm 安装的 Node。用 nvm 管理 Node 的时候全局包会装到当前用户目录下一般不会遇权限问题。Windows 下偶尔会遇到 npm 全局目录路径包含中文或空格导致的奇怪问题建议安装时选择默认路径。安装完成后验证claude --version能输出版本号就说明安装成功。如果提示 command not found大概率是 npm 全局 bin 目录没有加入 PATH需要把npm prefix -g的输出加上/bin或/加到系统环境变量里。3.2 安装后的登录与授权机制直接执行claude进入交互界面时它会尝试连接 Anthropic 官方进行登录授权。刚才我说过我们已经准备好走自定义 API 的路线所以这里有一个很多人踩过的坑如果先完成了官方登录后面再用环境变量切到国产模型有可能会因为本地已经有登录态而产生优先级冲突。我推荐的顺序是先配置好国产模型的 API 环境变量再启动claude。这样它会以自定义端点模式运行不依赖官方账号。首次启动时Claude Code 会问你喜欢浅色还是深色主题选一个进入交互界面。界面上有输入框、对话历史、命令面板看起来很复杂实际上核心用法就是直接输入自然语言指令。进入界面后可以用/status命令查看当前连接的 API 端点。如果端点显示的是你设置的自定义地址说明已经接入成功。3.3 升级与卸载的正确姿势Claude Code 更新频率很高基本上每周都有新版本。升级命令npm update -g anthropic-ai/claude-code我遇到过大版本升级后配置不兼容的情况。所以升级后如果发现行为异常第一时间用/status查看版本和端点信息再到官方 changelog 里查有没有破坏性变更。如果新版有问题想回退npm install -g anthropic-ai/claude-code上一版本号卸载更简单npm uninstall -g anthropic-ai/claude-code需要说明的是卸载不会自动删除~/.claude目录下的配置文件如果打算彻底重装手动把这个目录删掉可以避免旧配置干扰。4. 国产大模型 API 准备拿到 Base URL 和 Key4.1 选哪家模型我先说结论市面上国产模型很多但不是每一家都适合放进 Claude Code 里用。我自己的标准有三条第一有没有 Anthropic 兼容端点或成熟转换方案第二编程能力在实测中是否稳定第三API 充值流程是否顺畅。按这个标准我实际在不同场景下测过几家简单整理如下。模型服务代表模型集成方式我的实测感受DeepSeek 深度求索deepseek-chat / deepseek-reasoner官方提供 Anthropic 兼容端点配置最简单代码能力稳定价格便宜适合日常主力通义千问 Qwenqwen-max / qwen-turbo官方 OpenAI 兼容 API需转换层中文理解细腻生成注释和文档效果好智谱 GLMglm-4-plus / glm-4-airOpenAI 兼容 API需转换层函数调用能力不错在工具调用场景表现可靠Kimi 月之暗面moonshot-v1-128kOpenAI 兼容 API需转换层长上下文优势明显适合喂大仓库豆包doubao-pro火山方舟需转换层价格有优势配置路径稍复杂上表里 DeepSeek 能排第一个最大的原因是它提供了原生 Anthropic 兼容端点这意味着你不用额外安装任何转换工具直接把 Claude Code 的请求地址指过去就能跑通。对小白来说少一个环节就是少一个坑。4.2 申请 API Key 的步骤与注意点下面以 DeepSeek 为例把申请流程走一遍。先去它的开放平台注册账号手机上收验证码就能完成不需要海外手机号。登录后左侧菜单找到“API Keys”页面点“创建 API Key”系统生成一串以 sk- 开头的字符串。这串字符只显示一次一定要马上复制保存到本地笔记里关掉页面就再也看不到了。然后去“充值”页面先充一点点钱进去。DeepSeek 的 API 是按 token 计量的日常开发调试消耗很小我刚开始充了二十块钱断断续续用了一星期还没花完。提醒一下余额不足时 API 会直接失败所以用之前先确认余额不为零。其他模型服务商的流程大同小异注册 → 实名认证 → 创建 Key → 充值。需要注意实名认证这一步绝大多数国内大模型 API 服务商都要求完成学生党可以用支付宝或微信快速认证不是障碍。4.3 Base URL / 模型名称 / Key 三者之间是什么关系这是理解整个集成的关键。Claude Code 要连上一个 API 服务必须知道三件事API 地址Base URL告诉客户端往哪里发请求。DeepSeek 的 Anthropic 兼容地址是https://api.deepseek.com/anthropic。身份凭证Auth Token告诉服务端你是谁就是你刚创建的 sk- 开头的 Key。模型名称Model告诉服务端你要调用哪个模型。DeepSeek 对话模型叫deepseek-chat推理模型叫deepseek-reasoner。类比一下API 地址是餐厅的门牌号Key 是预约码模型名称是你要点的菜。三样缺一不可任何一个填错都会报错。Claude Code 这端的设计里还有一个容易被忽略的变量小模型Small Fast Model。Claude Code 在生成标题、简单分类等轻量任务时会调一个小模型来节省成本官方默认使用 Haiku 系列。如果你接的是国产模型没有对应的小模型概念就必须把小模型变量也指向同一个地址否则这些轻量任务可能报错。后面配置的时候我会专门强调这一点。5. 真正的集成步骤通过环境变量改道5.1 ANTHROPIC_BASE_URL 是核心开关Claude Code 读取配置时会依次查看环境变量和本地配置文件。其中最重要的四个环境变量如下环境变量作用示例值ANTHROPIC_BASE_URL自定义 API 地址https://api.deepseek.com/anthropicANTHROPIC_AUTH_TOKEN身份凭证替代官方 Keysk-xxxxxxANTHROPIC_MODEL主模型名称deepseek-chatANTHROPIC_SMALL_FAST_MODEL轻量任务模型名称deepseek-chat核心就一句话设置ANTHROPIC_BASE_URL指向兼容端点同时设置ANTHROPIC_AUTH_TOKEN作为身份凭证Claude Code 就不再连接 Anthropic 官方 API而是把流量全部打到自定义地址上。注意ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN是两个不同的变量。官方文档里ANTHROPIC_API_KEY通常配合官方端点使用而自定义端点更多用ANTHROPIC_AUTH_TOKEN。实测中我遇到过两个变量同时设置时客户端优先读取了 API Key 导致自定义端点鉴权失败的情况所以建议你只设置ANTHROPIC_AUTH_TOKEN把ANTHROPIC_API_KEY留在未定义状态。5.2 环境变量的完整配置清单macOS 和 Linux 下每次开终端都要重新 export 一次比较麻烦。建议直接写进 shell 配置文件~/.zshrc或~/.bashrcexport ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKENsk-你的Key export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat保存后执行source ~/.zshrc让配置立即生效。Windows 用户有两种方式。PowerShell 永久配置[Environment]::SetEnvironmentVariable(ANTHROPIC_BASE_URL, https://api.deepseek.com/anthropic, User) [Environment]::SetEnvironmentVariable(ANTHROPIC_AUTH_TOKEN, sk-你的Key, User) [Environment]::SetEnvironmentVariable(ANTHROPIC_MODEL, deepseek-chat, User) [Environment]::SetEnvironmentVariable(ANTHROPIC_SMALL_FAST_MODEL, deepseek-chat, User)然后重开终端。命令行临时设置也可以但每次开终端都要重新执行一遍适合测试不适合日常。这里有个容易被忽略的点环境变量是进程级配置必须在新开的终端里生效。你已经打开的那个终端窗口不会自动读取新的环境变量一定要重开一次窗口再执行claude。5.3 用 settings.json 做更持久的配置环境变量的好处是干净直接但如果你同时有多个项目要用不同的模型或者你不想污染全局环境我建议改用 Claude Code 的配置文件。编辑全局配置文件vim ~/.claude/settings.json写入以下内容{ env: { ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN: sk-你的Key, ANTHROPIC_MODEL: deepseek-chat, ANTHROPIC_SMALL_FAST_MODEL: deepseek-chat } }保存后重启claude即可。这个文件里的 env 字段会被注入到 Claude Code 的进程环境变量里优先级等同于环境变量。两种方式选一种就行混用容易造成“我以为改了但其实没改”的错觉。我个人的习惯是全局配置用 settings.json临时换模型用环境变量。5.4 如何验证是否真的走了国产模型配置完以后不要急着干活先进客户端里确认一下。启动claude后输入/status输出里会展示当前 API 端点和模型信息。如果你看到 Base URL 还是https://api.anthropic.com说明没生效。先检查环境变量名称有没有拼错再确认是否重开了终端。最常见的原因就是这俩。还有一种验证方式直接发一句“你好用一句话介绍你自己”。如果模型真的来自 DeepSeek它一般会直接介绍自己是 DeepSeek如果回答里出现 Claude 字样说明请求还是被路由到了官方或其他服务。用模型的身份介绍来判断路由是否正确是我觉得最直观的方法。6. 实战测试让 Claude Code 用国产模型干一次活6.1 最小测试跑一个能复现的 demo配置完成后的第一次实战我建议用一个小项目练手不要直接拿生产仓库去试。新建一个测试目录mkdir ~/test-claude cd ~/test-claude git init然后启动claude输入下面这句话帮我创建一个 Python 文件实现一个递归函数计算斐波那契数列再创建一个对应该函数的单元测试最后运行测试并确认全部通过。这句话包含了文件创建、函数实现、测试编写、命令执行、结果反馈五个环节能一次性验证 Claude Code 的基础能力是否完整。如果模型和 API 链路有问题在这一个任务里大概率会暴露出来。我第一次用 DeepSeek 跑这个流程时它大概花了 40 秒钟完成了全部动作创建了fib.py和test_fib.py运行pytest失败了一次原因是参数边界条件没处理好然后它自己读取了报错修改代码再次运行直到测试通过。整个过程我在旁边没有动一个字符。6.2 工具调用与多文件操作的实测表现Claude Code 区别于普通聊天工具的最大特征是工具调用。它会自主决定调用哪些内置工具比如Read读取文件、Write写入文件、Bash执行命令、Glob搜索文件。这些能力是否正常直接决定体验。我测试时特意让它修改一个多文件项目里的接口定义同时更新三处调用方的代码。它会先扫描项目结构找到所有引用该接口的位置逐一修改然后运行测试确认没有遗留问题。整个过程的路径规划和任务拆解能力让我觉得它已经超出了简单的“代码生成器”范畴。但这里我必须说实话国产模型在工具调用上跟原生 Claude 大模型还有差距主要体现在多步骤任务的中段容易“犯迷糊”。比如执行了命令后忘了读取输出或者连续调用了两次相同的工具。如果你遇到这类情况不要急着换模型先在对话里明确追加一句“按上一步的实际输出来继续”通常就能拉回来。这在国产模型上是常见现象不是配置错误。6.3 三个影响体验的隐性问题用一段时间后你会遇到一些不算故障但影响体感的问题。第一是速度。国产模型的流式输出速度普遍比 Claude 官方快但首次响应延迟有时偏高尤其是deepseek-reasoner这类推理模型。它会在思考阶段憋很久才吐出第一个 token给人“卡住了”的错觉。实际上是在后台推理耐心等一下就好。第二是限流。低价模型套餐通常有并发和每分钟请求数限制。Claude Code 这种工具会高频发起请求遇到限流会报 429 错误。遇到时停一下等一两分钟再继续或者降低任务颗粒度——把一个大任务拆成几个小步骤分次执行比一次性甩给它一个巨大的需求更不容易触达限流线。第三是最大输出 token 限制。不同模型单次回复的长度上限不同有些模型在生成较长的代码文件时会被截断。如果发现生成到一半突然停止且没有任何报错大概率是命中了模型单次输出上限。解决办法是在需求里主动要求分批输出比如“先创建文件骨架再逐函数填充实现”。7. 踩坑记录与排查链路我见过的那些状况7.1 报错 authentication_errorKey 没传对有一次我在新电脑上配置完所有环境变量启动claude后随便问了一句直接收到authentication_error。排查链路是这样的先用/status确认端点地址正确再用curl手动请求一次 APIcurl -X POST https://api.deepseek.com/anthropic/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: deepseek-chat, max_tokens: 100, messages: [{role: user, content: hi}] }curl 直接返回 401说明服务端不认这个 Key。我检查发现复制 Key 时多复制了一个空格进去去掉空格后问题解决。这个案例说明一个道理配置类问题先用最原始的工具做最小化验证能快速区分是客户端问题还是服务端问题。7.2 报错 model not found模型名对不上还有一次是在/model命令里切换模型后报出model not found。原因是 DeepSeek 开放平台上的模型名和 Claude Code 客户端下拉列表里显示的模型名不一致。Claude Code 的下拉列表默认显示的是官方模型名比如opus、sonnet、haiku你选择这些名字时客户端会在请求里带上对应的模型 ID。但国产模型不认这些 ID。解决方法是直接在ANTHROPIC_MODEL环境变量里写死 DeepSeek 的模型名deepseek-chat或者新建对话后输入/model deepseek-chat手动把模型名改成目标模型的真实 ID。这里的教训是不要依赖客户端界面里的选项要以服务商文档里写的模型名为准。7.3 输出断流 / 响应超时流式接口兼容性用deepseek-reasoner时我遇到过一个诡异现象模型思考了一会儿开始输出但输出到一半突然停住终端没有任何报错光标一直闪烁。后来发现是流式输出的兼容性问题。国产模型的推理模型在返回思考内容时协议字段和 Anthropic 标准格式有细微差异Claude Code 在解析时容易断流。网上有人通过设置超时时间缓解export API_TIMEOUT_MS600000但我的实际经验是换成非推理模型deepseek-chat之后这个问题基本消失。所以如果你接的是推理模型并且断流问题频繁我建议日常编码场景换用对话模型只在需要深度分析时临时切回推理模型。7.4 本地 Ollama 方案与更稳的兼容层工具除了云端 API还有人倾向于本地跑模型。Ollama 是最流行的本地模型运行工具装好后可以拉取通义千问的本地版本ollama pull qwen2.5-coder:14bOllama 提供的是 OpenAI 兼容接口默认地址http://localhost:11434/v1不是 Anthropic 格式所以不能像 DeepSeek 那样直接配ANTHROPIC_BASE_URL。你需要装一个转换层工具。目前社区里比较活跃的解决方案是claude-code-routernpm install -g claude-code-router它会把 Claude Code 发来的 Anthropic 格式请求转成 OpenAI 格式再转发给目标服务。配置文件里可以指定使用 DeepSeek、通义、Kimi也可以指定本地 Ollama。这类工具迭代非常快具体配置格式建议直接参考项目 README不要死记教程里的写法。另外如果你需要在 Anthropic 官方模型和多个国产模型之间来回切换可以试试 cc-switch 这个桌面管理工具。它本质上是把多组环境变量配置保存成配置项一键切换后自动重启 Claude Code。适合同时用多套模型的人但我个人建议新手先把单条链路跑通再考虑多配置切换的高阶玩法。本地模型方案最大的优势是数据不出机器离线也能用适合对隐私敏感或者网络不稳定的场景。代价是小参数模型写代码能力不如云端大模型大参数模型又需要很强的显卡显存。以 7B 参数模型为例实测下来能做一些代码补全和简单重构但让它完整实现一个带单元测试的功能模块会比较吃力。如果你只有普通办公电脑我建议把本地方案当成玩具玩生产力场景还是用云端 API 更靠谱。最后分享一点我个人的使用习惯。Claude Code 接国产模型这件事配置本身不难真正决定体验的是选对模型和用好上下文管理。日常写代码、跑测试、修 bug我用deepseek-chat速度快稳定性好遇到需要复杂推理或大范围代码审查的时候才临时切到推理模型。每次接手一个大项目之前我都会先让它完整读一遍 README 和目录结构再开始动手这样后面翻车概率小很多。希望这套配置流程能让你少走点弯路。