最近后台留言被同一个问题刷屏了Claude Code到底怎么装装完之后怎么把它接到DeepSeek、Qwen这些国产大模型上我一个人回复不过来干脆把整条链路重新跑了一遍从零开始把每个步骤、每个坑都记下来整理成这篇完整的安装教程看完你就能自己动手配置。Claude Code是Anthropic推出的命令行AI编程助手直接在终端里跟你对话能读项目文件、改代码、跑测试交互起来比网页版顺手得多。它的亮点是Agent式工作流你给它一个任务它能自己规划、调工具、反复验证而不是像聊天框那样一问一答。但很多人卡在第一步官方账号有使用门槛订阅和额度劝退了一大批人。于是“Claude Code 国产大模型”就成了最省钱、最容易上手的方案——不需要官方订阅直接把Claude Code的请求指向国内模型服务就行。这篇教程面向纯零基础不管你是Windows、macOS还是Linux从装Node.js开始一直到VSCode里跑起来国产模型我都会一步一步拆开讲。全程不讲废话只讲能落地的操作。1. 安装前的三个关键认知1.1 Claude Code解决了什么问题先把这个工具是什么说清楚。Claude Code是一个跑在终端里的AI编程助手核心能力是“代理式执行”你描述需求它会拆解成任务列表、读取项目文件、修改代码、执行命令验证结果。比如你说“帮我修一下登录接口的Bug”它会先看相关文件、复现问题、改代码、跑测试而不是只吐一段代码让你自己贴。这个体验跟IDE侧边栏开个聊天框完全不同。它更像你身边坐了一个能直接动键盘的同事。加上Anthropic在长上下文和代码理解上确实强所以最近热度非常高。不过官方版本需要Claude账号或API Key这两个都有付费要求而且部分地区在注册、支付环节就有门槛。这也是为什么“Claude Code接国产模型”这个需求突然变得很旺盛——本质上是用Claude Code这个好用的“壳”去调用DeepSeek、Qwen这些国内模型服务。1.2 为什么选择国产大模型国产模型这几年进步非常快DeepSeek的推理能力、Qwen的代码能力、Kimi的长文本能力各有各的强项。价格上比Anthropic官方API便宜一大截DeepSeek甚至还经常搞活动送额度。更关键的是很多开发者的数据敏感要求不能出内网那本地Ollama跑Qwen系列就是最优解。对比维度官方Claude CodeClaude Code 国产模型账号门槛需要官方订阅或API Key注册国内模型平台即可费用按量付费或订阅成本高便宜很多部分有免费额度数据流向数据发往官方服务器发往所选模型服务商或完全本地模型能力Claude系列DeepSeek、Qwen、Kimi等配置难度开箱即用需要改配置本教程全程覆盖还有很多人纠结Codex和Claude Code怎么选。我的看法是Codex深度绑定OpenAI生态如果你主力模型是GPT系列选Codex顺手但你如果已经决定用DeepSeek/Qwen那Codex接入国产模型的路径反而没有Claude Code这么成熟社区工具也少一些。所以这篇文章直接围绕Claude Code展开。1.3 前置环境准备清单安装之前先检查三样东西Node.js、终端工具、Git。Claude Code是基于Node.js开发的安装它最标准的方式就是通过npm全局安装所以Node.js必须是装好的。要求是Node.js 18以上最好用20或22的LTS版本。检查命令node -v npm -v如果提示“node不是内部或外部命令”说明没装或者没配环境变量去Node.js官网下载LTS版安装包一路默认下一步就行。Windows下安装包会自动把node和npm写进PATH装完记得重开终端。Git不是必须的但Claude Code在分析Git仓库、生成提交信息时会用到建议一并装上。macOS自带gitWindows到官网下Git for WindowsLinux用包管理器一行搞定。终端方面Windows强烈建议用Windows TerminalmacOS用自带的Terminal或iTerm2都行Linux随便。2. Claude Code本体安装从命令行到VSCode2.1 用npm全局安装环境准备好了安装本体其实就一条命令npm install -g anthropic-ai/claude-code这条命令会从npm仓库拉取Claude Code并安装到全局目录。安装过程可能有点慢取决于网络但通常一两分钟能完成。装完运行claude --version能输出版本号比如1.0.x说明本体装好了。Windows用户经常在第一步就翻车最常见的报错是PowerShell里执行命令时提示无法加载文件 ... 因为在此系统上禁止运行脚本这是Windows默认的脚本执行策略限制不是Claude Code的问题。解决办法是以管理员身份打开PowerShell把当前用户的执行策略改成允许本地脚本运行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser改完重开终端再执行claude --version问题就解决了。2.2 在VSCode里配置Claude Code命令行工具装好之后很多人习惯在VSCode里用。其实不需要额外装插件直接在VSCode的终端里输入claude就能启动它会以对话界面出现在终端里。但我更推荐用VSCode里的Claude Code插件。在扩展市场搜“Claude Code”就能找到安装后左侧会出现专属入口AI对话会在侧边栏或者独立编辑器窗口里展示看代码、改代码都比纯终端舒服。需要注意一点插件本质还是调用你本地的Claude Code命令行。所以如果命令行版本没装好插件也会报“claude not found”。装完插件第一件事还是在VSCode终端里跑一下claude --version确认环境正常。如果你更习惯JetBrains系列的IDEIDEA、PyCharm这些思路一样先在终端装好Claude Code再在IDE的终端面板里调用。它在本质上就是一个终端应用跟IDE绑定不深这也算它的灵活性。2.3 首次启动与登录方式选择在终端输入claude首次启动会引导你登录。通常有两个选项OAuth浏览器登录跳转浏览器用你的Claude账号授权API Key登录填写你的Anthropic API Key这里先提醒一句如果走官方登录商业授权和付费额度都要确认好登录失败最常见的原因就是账号没有有效的Claude计划或API额度。具体排查方法我在第5章会详细讲。如果你现在的目标就是接入国产大模型那官方登录这步可以先跳过。下一步会一次性把配置讲清楚。3. 接入国产大模型三种主流方案实测对比3.1 方案A用CC Switch做一键切换CC Switch是社区里非常流行的Claude Code配置管理工具专门解决“多套API配置来回切换麻烦”的问题。它本质上是帮你写Claude Code的环境变量和配置文件并提供图形界面。对新手最友好强烈推荐。安装CC Switch很简单去它的官方仓库的Releases页面下载对应系统的安装包Windows下载exemacOS下载dmg双击安装即可。安装完打开核心操作就三步点击“ 新增Provider”填写API地址和密钥如果你用国产云模型填对应平台的Base URL和API Key如果你用Ollama本地模型地址填本机的服务地址保存后点击“切换”或“激活”CC Switch会把配置写入Claude Code的配置文件切换完重新打开claude它就会把请求发到你选的那个模型服务上。不需要动任何代码文件也不用手动记环境变量。我实测下来这套流程对完全没接触过命令行配置的人来说是最不容易出错的。需要注意CC Switch本身不负责“模型协议转换”。如果Claude Code和模型服务之间的API格式不一致它不一定能帮你解决。很多国产云模型是OpenAI兼容格式而Claude Code原生用Anthropic格式这一层转换需要靠底层网关或兼容层完成。这也是为什么在选云模型方案前最好先确认对方是否提供Anthropic兼容端点或者使用带转换能力的网关工具。3.2 方案BOllama跑本地模型彻底免费且隐私如果你想要免费、离线、数据不出本机那就用Ollama这套方案。Ollama是一个本地大模型运行工具装好后可以直接把Qwen、DeepSeek这些开源模型拉到本地跑。安装分三步到Ollama官网下载对应系统的安装包装完启动服务拉取一个代码模型比如Qwen2.5系列ollama pull qwen2.5-coder:14b确认服务在跑ollama serve然后在CC Switch里新增Provider类型选Ollama或手动填本地地址模型名填你刚拉取的那个。这里有个细节Ollama本地服务默认不做鉴权但API地址要求必须填一个密钥占位符随便填一串字符就行不能留空。本地方案最需要注意的是硬件。一个14B的模型跑起来至少要16GB内存想速度快还得有一块够劲的显卡。如果显存不够推理速度会非常慢体验大打折扣。我建议先拉一个小模型试水比如7B或者8B的参数版本能跑通了再上大模型。3.3 方案C手动配置环境变量最透明可控除了工具CLI本身也提供了手动配置的方式适合喜欢“一切尽在掌握”的开发者。核心就三个环境变量环境变量作用示例值ANTHROPIC_BASE_URL指定API服务地址http://127.0.0.1:11434ANTHROPIC_AUTH_TOKEN鉴权Token或密钥占位符随意字符串或真实API KeyANTHROPIC_MODEL指定要用的模型名qwen2.5-coder:14b临时生效的写法Windows PowerShell$env:ANTHROPIC_BASE_URLhttp://127.0.0.1:11434 $env:ANTHROPIC_AUTH_TOKENollama $env:ANTHROPIC_MODELqwen2.5-coder:14b claudemacOS / Linux的写法export ANTHROPIC_BASE_URLhttp://127.0.0.1:11434 export ANTHROPIC_AUTH_TOKENollama export ANTHROPIC_MODELqwen2.5-coder:14b claude这样做的好处是灵活脚本化之后可以一键切换。坏处是如果你对接的是OpenAI兼容格式的云API那么光设这三个变量还不够中间需要加一层协议转换。社区里有不少开源的协议网关可以做这件事功能就是把OpenAI格式的请求翻译成Anthropic格式。所以方案C更适合“服务端已经支持Anthropic格式”的场景比如新版Ollama或某些国内服务商提供的兼容接口。3.4 三种方案怎么选直接给结论场景推荐方案纯新手、想快速跑通方案ACC Switch免费、离线、数据安全方案BOllama喜欢命令行、要脚本化方案C环境变量云模型APIDeepSeek等方案A 确认兼容层或使用支持Anthropic格式的网关我个人实际测试下来OllamaQwen的组合在普通开发机上表现不错日常代码补全、简单重构完全够用。云API模型能力强不少但会涉及协议转换层配置复杂度稍高。4. 配置细节参数、文件与边界4.1 三个环境变量到底在做什么其实把环境变量理解成“给Claude Code指路”就够了。ANTHROPIC_BASE_URL是告诉它“往哪个地址发请求”ANTHROPIC_AUTH_TOKEN是“进门要刷的门卡”ANTHROPIC_MODEL是“到了之后找哪个人办事”。官方默认的Base URL指向Anthropic服务器我们改了它请求就发到了本地Ollama或者国内模型服务。有个很常见的误区以为只要改了Base URLClaude Code就能直接调用任何OpenAI格式的API。实际上Claude Code发出去的请求体遵循Anthropic Messages API格式字段名、请求结构和OpenAI格式差异很大。所以如果没有协议转换层光改Base URL往往会得到一堆奇怪的报错比如400或404。这一点在选型时务必记住。4.2 settings.json与.claude目录Claude Code支持通过配置文件固化这些设置不用每次开终端都敲环境变量。全局配置文件在Windows:C:\Users\你的用户名\.claude\settings.jsonmacOS/Linux:~/.claude/settings.json也可以在项目根目录建一个.claude/settings.json只对这个项目生效。一个典型内容{ env: { ANTHROPIC_BASE_URL: http://127.0.0.1:11434, ANTHROPIC_AUTH_TOKEN: ollama, ANTHROPIC_MODEL: qwen2.5-coder:14b }, permissions: { allow: [Bash(npm run *), Read(~/*), Edit(~/*)] } }注意配置文件不要提交到Git仓库尤其是包含真实API Key的情况。建议在.gitignore里加上.claude/settings.json或者用独立的settings.local.json管理密钥。4.3 省Token的几个实用技巧模型能力强成本也跟着上。接入云API之后省Token就是省钱。我总结几个最有效的办法对话中发送/compact压缩历史上下文对话太长时这个命令能把之前的摘要化释放上下文空间用小模型处理简单任务比如代码补全用7B/8B模型复杂重构再切换到强模型启动时加上--max-turns限制单次任务的循环轮数避免它在简单问题上反复纠缠关闭不必要的日志输出减少工具调用产生的额外token消耗这些技巧在Claude Code里都有对应的命令和参数具体详情可以在启动后输入/help查看。实测下来最有效的是养成“长对话定期compact”的习惯有时候能省掉接近三分之一的token。5. 高频问题排查安装与运行实录5.1 PowerShell提示禁止运行脚本正如第2章提过的这是新人最常见的问题。完整报错通常是claude : 无法加载文件 C:\Users\xxx\AppData\Roaming\npm\claude.ps1因为在此系统上禁止运行脚本。原因就是PowerShell执行策略默认是Restricted。解决方案Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser执行后会提示确认输入Y。改完重开终端即可。如果还是不行用管理员身份打开PowerShell再执行一次或者检查Node.js是否安装正确。5.2 登录返回403登录时报403先别慌按顺序排查检查账号状态是否有有效的Claude订阅或API账户是否成功充值并创建了Key。403最常见的根因就是账号权限不对检查系统时间系统时间偏差太大OAuth签名校验会失败清理本地缓存后重试删除~/.claude目录下的.credentials.json缓存文件再重新运行claude登录更换登录方式如果浏览器登录一直403改为用API Key方式登录如果以上都试过仍然不行而且你本来就不需要官方账号那完全可以走第3章的国产模型方案直接使用不需要走官方登录这条链路。5.3 中文乱码Windows下中文输出变成乱码绝大多数是编码问题。解决办法很简单chcp 65001这会把当前终端代码页切换到UTF-8。更彻底的做法是控制面板 - 区域 - 管理 - 更改系统区域设置勾选“Beta: 使用Unicode UTF-8提供全球语言支持”重启后生效。如果你用Windows Terminal还可以在设置里把默认字体改成“Cascadia Mono”显示中文更舒服。macOS和Linux下基本不会遇到乱码如果有检查终端的字符编码设置是否为UTF-8。5.4 卡在登录界面或闪退启动后一直卡在登录界面大概率是之前的身份缓存冲突。先退出终端删除~/.claude下的凭据缓存文件再重新启动。如果一启动就闪退八成是Node.js版本不兼容确认版本在18以上最好升级到20。5.5 常见问题快速对照表问题原因快速解决提示禁止运行脚本PowerShell执行策略执行Set-ExecutionPolicy命令node/npm不是内部命令Node未装或未配PATH装LTS版并重开终端登录403账号额度/权限查账号状态、清缓存、换API Key中文乱码终端代码页不对chcp 65001卡登录界面身份缓存冲突删~/.claude/.credentials.json连接本地模型404API格式或版本不兼容更新Ollama/使用兼容层回复速度太慢本地模型太大/显存不足换小参数模型或改云API最后再分享一个我自己的习惯我会在项目根目录放一个switch-to-local.sh或者switch-to-local.ps1脚本里面写好几组不同模型的环境变量想用哪个模型就执行哪个脚本比每次手敲变量省心很多。这个玩法配合CC Switch其实也一样只不过我对手动脚本有偏爱。踩了几轮坑之后我的心得是如果你是第一次接触Claude Code先把Ollama小模型这套跑通确认整个链路没问题再换更强大的云模型。别看网上那些测评贴很热闹真正本地跑起来、改几行代码、让它完成一个真实的改Bug任务你对它的理解会上一个台阶。希望这篇教程能帮你省下我在最初踩坑时浪费的那些时间。