最近后台收到最多的私信，不是“Claude Code怎么用”，而是“Claude Code装好了，但怎么直连国产大模型”。说实话这个需求太真实了。Claude Code是Anthropic推出的命令行AI编程助手，能在终端里直接帮你读代码、改文件、跑命令，还能多文件联动修改，属于目前Agent型编程工具里体验非常靠前的一档。但它默认配置的是官方服务，很多人既没有现成的官方账号，又想体验这套工作流，于是绕不开一个问题：怎么把它的请求切到国产大模型服务上。
这篇教程不会跟你扯一堆理论，就按我自己的实际安装过程，从零开始讲清楚三件事：怎么把Claude Code装好、怎么在VS Code里跑起来、怎么用cc switch或者环境变量直连到DeepSeek、智谱这些国产模型的接口，最后再把装完最容易踩的坑逐个拆给你看。适合完全没接触过Node.js、对命令行有点发怵的新手，也适合已经装上但一直没把模型切换明白的老手。
1. 先搞清楚：Claude Code到底是什么，为什么非要直连国产大模型
1.1 一句话认识Claude Code
Claude Code是一个跑在终端里的AI编程助手，官方定位是“agentic coding tool”，翻译成人话就是：它不是一个只会聊天给代码片段的对话机器人，而是一个能真的在你的项目目录里干活的“实习生”。
你给它一个任务，比如“帮我修复登录接口的鉴权漏洞”，它会自己读项目结构、打开相关文件、搜索关键函数、修改代码、跑测试，甚至能自己执行命令来看结果。整个过程不是一次问答，而是一连串有上下文记忆的工具调用。你可以随时打断、纠正方向，也可以让它一次改完多个文件后再统一 review 改动。
这套工作流和传统IDE里的AI补全完全是两个物种。Copilot类工具是“你写代码时自动补全”，Claude Code这类Agent工具是“你把活交给它，它自己折腾”。后者更像是在用人，前者像是在用键盘。
经常有人拿Codex和Claude Code做比较。Codex是OpenAI出的同类产品，两款工具的整体思路很像，但落地细节差异挺大。我用过一段时间Codex，又切回Claude Code，体感上的差别我整理了一张表：
| 对比维度 | Claude Code | Codex |
|---|---|---|
| 交互方式 | 终端交互+VS Code插件 | 终端交互+IDE面板 |
| 上下文管理 | CLAUDE.md记忆+自动压缩 | 对话历史+手动换session |
| 工具调用生态 | MCP协议，扩展丰富 | 内置沙箱+少量插件 |
| 多文件修改能力 | 强，一次能改十几个文件 | 中等，适合单文件级任务 |
| 模型可选范围 | 官方模型+第三方API都能接 | 主要绑定自家模型 |
| 适合人群 | 想深度掌控代码改动的人 | 习惯IDE一站式体验的人 |
不是说谁一定比谁强，而是Claude Code在“命令行+脚本化”这条路上走得更深，而且它最吸引我的一点是：模型层可以替换。官方模型表现固然好，但并不是所有人都有合适的官方账号，也不是所有场景都需要用最贵的模型。能把请求切到国产模型，等于把一台高性能跑车换上了适配国内路况的发动机，该跑还是能跑。
1.2 直连国产大模型的三个理由
第一个理由最实在：省事。很多人没有官方账号，或者不愿意折腾账号体系，但DeepSeek、智谱这些平台的账号注册非常简单，手机号验证一下就行，实名流程也顺，充值门槛低。把Claude Code改造成“国产模型启动器”，等于省掉了最麻烦的一环。
第二个理由是性价比。国产模型的API定价整体比官方低不少，日常做代码补全、单文件改动、读代码解释逻辑这类任务，用国产模型的输出质量完全够用。对于个人开发者、自由职业者来说，这是个非常务实的方案。
第三个理由是数据合规。不少项目代码有保密要求，代码不能传到境外服务。用国产模型服务商或者本地Ollama，数据面在国内或直接在本地，很多团队才敢放心用。这也是我为什么在后面的方案里特意讲了Ollama本地部署这条线。
1.3 直连之前，你需要理解的一个核心概念
Claude Code本身只是个“壳”，真正干活的是背后的大模型。Claude Code通过一个叫Anthropic API协议的接口跟模型对话。只要某个模型服务能提供兼容这个协议的接口，Claude Code就能用，不管背后跑的是哪个厂商的模型。
这就是“直连国产大模型”的底层原理：不修改Claude Code本身，而是把它请求的API地址换掉，再填上一个国产模型服务商给的密钥，它就会去找国产模型要答案。整个过程不需要破解什么、不需要改动程序文件，只是改配置而已。理解这一点，后面所有操作就都顺理成章了。
2. 安装前的硬性准备：环境、版本、账号一个都不能少
2.1 确认Node.js环境
Claude Code是用npm安装的，所以电脑上必须先有Node.js。很多新手在这一步就卡住了，因为根本不知道自己装没装过。打开终端（Windows上用PowerShell，macOS上用终端，Linux看你自己的发行版），输入下面这条命令：
node -v如果看到类似v20.11.0这样的输出，说明Node.js已装好，可以跳过这一步。如果提示node: 未找到命令或者无法识别“node”，那就需要先去Node.js官网下载LTS版本安装。注意一定选LTS（长期支持版），不要选手贱的Current尝鲜版，稳定压倒一切。
安装完成后关掉终端重新打开一次，再跑node -v和npm -v确认都正常。npm是Node.js自带的包管理器，Claude Code就是靠它装的。两个命令都能输出版本号，环境这关才算过。
2.2 准备好三样东西
环境就绪后，正式开工前再确认三样东西：
- 一个终端工具。Windows用户推荐直接用VS Code里的集成终端，或者Windows Terminal。老旧的cmd不建议，显示和交互都太折磨人。
- 一个国产模型的API Key。去DeepSeek开放平台、智谱开放平台这类网站注册账号，创建一个API Key。创建的时候会要求充值，按量付费，充个几十块就能用很久。API Key是一串
sk-开头的字符串，创建后复制保存好，很多平台只显示一次。 - 一个干净的测试项目目录。别在系统盘根目录或者桌面乱试，建一个空的测试文件夹，后面安装和启动都在这个目录里操作，避免权限混乱。
2.3 Windows用户特别要看的注意事项
如果你用的是Windows，有两个坑在安装前就要知道：
第一个是PowerShell执行策略。Windows默认可能会限制运行npm全局安装的脚本，后面安装时会报“无法加载文件，因为在此系统上禁止运行脚本”之类的错。解决办法是在PowerShell里先执行一遍：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser执行后如果提示是否更改执行策略，输入Y回车就行。这一步的含义是“允许运行本地脚本和已签名的远程脚本”，是官方认可的安全操作，不是关闭系统防护。
第二个坑是路径问题。npm全局安装的软件，默认会装到一个npm目录下，如果这个目录不在系统PATH里，装完之后输入claude会提示找不到命令。遇到这种情况，不要慌，先执行npm config get prefix看看全局目录在哪，然后把这个目录加到系统环境变量PATH里。不同机器路径不一样，这里就不写死命令了，加到PATH这个操作网上一搜一大把。
3. 完整安装实录：从npm到第一条命令
3.1 安装Claude Code本体
环境准备好之后，安装过程其实就一条命令。打开终端，执行：
npm install -g @anthropic-ai/claude-code-g参数表示全局安装，装完之后系统里任何目录都能直接调用claude命令。安装过程可能会有点慢，取决于网络状况，看到一堆进度条滚动是正常的，别中途Ctrl+C把进程掐了。
安装完成后，没有任何提示也不要慌，先验证一下版本：
claude --version如果输出了类似1.0.x的版本号，说明本体已经装好。没输出版本号也别急着放弃，看第2.3节的路径问题排查一下。
提示：如果你之前装过旧版本，升级方式同样简单，重新执行一遍上面的安装命令即可，npm会自动覆盖旧版本。
3.2 第一次启动：认识交互界面
安装完成后，在测试目录里输入：
claude第一次启动会要求你登录或授权。如果你已经决定用国产模型，这一步可以先不登录。按Ctrl+C退出启动流程，先把模型切换配置好再回来，不然Claude Code会一直纠缠官方账号的事。
如果选择先体验默认流程，它会尝试打开浏览器让你登录官方账号。等你把模型切到国产API之后，这个过程就不需要了，Claude Code会直接跳过登录环节。
启动成功后的界面是一个交互式终端，底部有个输入框，顶部显示当前对话的上下文信息。你可以在里面直接输入自然语言指令，比如“列出当前目录的文件结构并解释每个文件的用途”。输入/help可以查看所有内置命令，输入/clear可以清空当前对话上下文，输入/quit或按两次Ctrl+C退出。
3.3 VS Code插件安装与界面认识
很多人在终端里用不惯，更喜欢在编辑器里操作。VS Code下有两个常用选择：
第一个是直接在VS Code的集成终端里运行claude命令。打开VS Code，按Ctrl+~呼出集成终端，输入claude启动，这样Claude Code就嵌在编辑器里了，左边看代码、右边跑AI，天然无缝。
第二个是安装官方Claude Code扩展。打开VS Code扩展市场，搜索“Claude Code”，认准Anthropic官方发布的那个，点击安装。装完之后左侧边栏会出现Claude Code的图标，点击可打开面板，在面板里直接输入指令控制Claude Code。这个扩展实质上是给终端版的Claude Code包了一层图形界面，方便跟踪对话历史和查看文件改动，但底层还是同一套东西。
我用得最多的是第一种方式，理由很简单：集成终端里可以直接看到Claude Code执行命令的过程和输出，随时可以Ctrl+C打断，更直观。
4. 核心环节：直连国产大模型的三种配置方案
4.1 方案一：cc switch图形化切换供应商
cc switch是一个专门为Claude Code设计的管理工具，全程图形化操作，对新手非常友好。它的作用是帮你管理多个API供应商配置，想用哪家就一键切换，不用每次手动改环境变量。
安装cc switch同样走npm：
npm install -g cc-switch安装完成后，在终端执行：
cc-switch它会打开一个图形界面，界面上列出了Anthropic官方、DeepSeek、智谱等预设供应商。点击“添加供应商”，填三样信息：供应商名称、API地址、API密钥。以DeepSeek为例：
- 名称：随便填，自己能认出来就行
- API地址：
https://api.deepseek.com/anthropic - API密钥：你从DeepSeek平台创建的
sk-开头的串
填完点保存，然后在列表里点击“切换”按钮，cc switch会帮你把配置写入Claude Code的配置文件（一般位于用户目录下的~/.claude/settings.json），同时清掉旧的登录态。切换完成后再启动claude，就不会再要求登录官方账号了。
cc switch适合喜欢点鼠标的人，也适合需要在多个服务商之间来回切换的场景。比如你今天想用DeepSeek写业务代码，明天想试试智谱的模型，用cc switch两秒钟就能切过去，性价比非常高。
4.2 方案二：环境变量直连（推荐，最稳）
不装任何额外工具，直接通过环境变量把Claude Code的请求地址指到国产模型服务商。这是最干净、最可控、出问题最好排查的方案，也是我自己长期在用的方式。
Claude Code启动时会读两个关键环境变量：ANTHROPIC_BASE_URL指定API地址，ANTHROPIC_AUTH_TOKEN指定密钥。设置好这两个变量，Claude Code就会把请求发到对应的国产模型服务上。
以DeepSeek为例，在macOS或Linux的终端里执行：
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_AUTH_TOKEN="你的API密钥"但这样设置只在当前终端窗口有效，关掉窗口就没了。想永久生效，macOS/Linux用户把这两行追加到shell配置文件末尾——zsh用户写~/.zshrc，bash用户写~/.bashrc：
echo 'export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"' >> ~/.zshrc echo 'export ANTHROPIC_AUTH_TOKEN="你的API密钥"' >> ~/.zshrc source ~/.zshrcWindows PowerShell用户可以用下面的命令设置用户级环境变量：
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.deepseek.com/anthropic", "User") [Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "你的API密钥", "User")设置完关掉终端重新打开，让环境变量生效。然后进入测试目录，直接输入claude，如果没再要求登录、并能正常响应你的问题，说明直连成功。
这里有一个可能需要调整的点：模型名。Claude Code默认请求的模型是claude-sonnet-4或类似的Claude系列模型名，而国产模型服务的兼容层通常会自动把这类模型名映射到自家的模型上，比如DeepSeek会映射到deepseek-chat。如果服务商没有做自动映射，你还需要再设置一个ANTHROPIC_MODEL环境变量来指定模型名，具体名字看服务商文档。
我把目前主流的几家平台端点整理了一张表，方便你对照：
| 服务商 | Anthropic兼容API地址 | 说明 |
|---|---|---|
| DeepSeek | https://api.deepseek.com/anthropic | 官方提供了兼容层，效果不错 |
| 智谱 | https://open.bigmodel.cn/api/anthropic | 需在开放平台开通服务后使用 |
| 其他平台 | 以各平台最新文档为准 | 各家接口变动较快，建议直接看开放平台 |
注意：API地址一定以你所用服务商的官方文档为准，如果页面提示地址变了，以最新文档为主。各家更新频繁，表格只能作为启动线索。
4.3 方案三：Ollama本地模型接入（完全离线）
如果你的代码完全不能出内网，或者不想花API的钱，可以用Ollama在本地跑一个开源模型，再把Claude Code指到本地服务上。这条链路一共三步。
第一步，安装Ollama并从拉取一个模型。到Ollama官网下载对应系统的安装包，装好后在终端执行：
ollama pull qwen2.5-coder:14b这个命令会从模型仓库拉取一个阿里的代码模型到本地，14b量化版本大概需要8-10GB磁盘空间，普通开发机跑起来没问题。
第二步，需要一个本地转换层。Claude Code说的是Anthropic协议，而Ollama原生提供的是OpenAI兼容协议，两者不能直接对话。这里需要用LiteLLM做一个本地接驳：
pip install litellm litellm --model ollama/qwen2.5-coder:14b --port 4000LiteLLM会在本地4000端口起一个服务，这个服务能听懂Anthropic协议的请求，再转成Ollama能理解的格式发给本地模型。执行成功后终端会显示服务已启动。
第三步，把Claude Code指到本地：
export ANTHROPIC_BASE_URL="http://localhost:4000" export ANTHROPIC_AUTH_TOKEN="sk-local"然后启动claude，它就会跟本地模型对话。本地模型的响应速度取决于你的电脑配置，尤其是内存和显存。实测下来，14b量级的代码模型在生成常规业务代码时质量不错，但跟顶级商用模型相比，在复杂架构设计、多文件联调这种高难度任务上还是有差距。这条方案的最大优势是私有、免费、不断网也能用，适合有数据安全要求的团队。
5. 实操避坑：装完必踩的这些问题我全踩过
5.1 PowerShell安装报错：执行策略与命令找不到
Windows下最常见的报错就是PowerShell拒绝运行npm全局脚本。报错信息长这样：
无法加载文件 ...因为在此系统上禁止运行脚本解决办法就是前面2.3节提到的，先执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser。注意一定要带-Scope CurrentUser，只对当前用户生效，不需要管理员权限，也最安全。
还有一种常见情况是安装没报错，但执行claude提示“无法识别”。这种就是npm全局目录没进PATH。用npm config get prefix查到全局目录后，把它加到系统环境变量PATH里，然后重新打开终端。这一步做完，绝大多数“命令找不到”的问题都能解决。
5.2 登录403、会话失效怎么办
如果你切到国产模型后，Claude Code仍然报403，先按顺序排查三件事：
第一，确认环境变量有没有正确加载。在终端里执行echo $env:ANTHROPIC_BASE_URL（Windows）或echo $ANTHROPIC_BASE_URL（macOS/Linux），看输出是否是你填的API地址。如果输出为空，说明环境变量没设上，回到4.2节重新设置。
第二，确认API Key有没有填对。有些平台创建的Key有有效期，过期了也会报403。去平台后台看一眼Key状态，不行就删掉重建一个，重新设置环境变量再试。
第三，确认系统时间是否准确。API请求的签名机制对客户端时间很敏感，系统时间偏差超过几分钟就会鉴权失败。把系统时间同步一下，一般能解决。
还有一个不稳定因素：Claude Code升级后，旧版缓存的登录凭据可能和新版本冲突，导致请求走到了旧的认证逻辑上。这种情况下，删掉用户目录下的~/.claude缓存文件夹里和凭据相关的文件再重试。删之前备份一下settings.json，因为你的供应商配置在里面。
5.3 终端乱码、中文提示异常
Windows终端跑Claude Code，常见问题是中文显示成乱码。这不是Claude Code的问题，而是终端编码没切到UTF-8。在PowerShell里执行：
chcp 65001把代码页切成UTF-8后，乱码问题一般就消失了。如果每次打开终端都要手动切，可以在终端设置里把默认编码改成UTF-8。Windows Terminal的话，在设置里的“配置文件->外观->字体”里把字体改成“Cascadia Mono”或“Consolas”，并把编码设为UTF-8，能根治。
macOS和Linux上如果出现乱码，通常是终端字体不支持中文，换个支持CJK字符的字体即可，比如“JetBrains Mono”或“Sarasa Term SC”。
5.4 桌面端卡在登录账号界面怎么办
很多人装的Claude Code桌面版会遇到一个尴尬情况：打开后一直卡在登录账号界面，怎么点都没反应。这个问题的根源是桌面端默认逻辑强制要求官方登录，而你既没有官方账号，也走不通官方认证流程。
有两个解法。最快的解法是：不用桌面端登录流程，直接用命令行版配合环境变量。桌面端和命令行版本质上是同一个引擎，命令行版只要设好ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN，就能跳过登录直接干活。登录界面不是必须走完的流程，只是一个身份验证环节，既然你的模型服务商已经提供了密钥，那就没必要再验证官方身份。
第二个解法是清理桌面端的本地凭据缓存。在Windows上找到%APPDATA%\Claude目录，macOS上找~/Library/Application Support/Claude，把里面跟登录账号相关的缓存文件删掉，重启应用，有时能闯过登录卡的界面。
提醒：桌面端版本迭代很快，不同版本的设置界面可能不一样。如果你用的桌面版一直搞不定，直接退回命令行版是最省心的选择，核心功能一点不少。
6. 从会用到用好：几个能帮你省时间的配置技巧
6.1 CLAUDE.md：让Claude Code记住项目规矩
Claude Code支持一个叫CLAUDE.md的记忆文件。你可以在项目根目录下创建一个CLAUDE.md，里面写清楚这个项目的技术栈、目录结构、代码规范、注意事项。Claude Code每次启动时都会自动读取这个文件，相当于给AI一份“项目说明书”。
我的习惯是开头写一段项目简介，然后列一下技术栈和关键依赖，再写清楚代码风格约定（比如“缩进用2个空格”“组件命名用大驼峰”“禁止直接修改数据库迁移文件”）。有了这份文件，Claude Code的修改会更贴合项目风格，不会动不动给你生成一堆风格跑偏的代码。
6.2 控制token消耗的几个开关
很多人担心用起来烧钱，其实Claude Code有几个内置机制可以控制消耗。
第一个是上下文压缩。对话时间长了，历史记录会越积越多，token消耗直线上升。可以手动输入/compact把上下文压缩成精华摘要，大幅减少后续请求的token用量。
第二个是会话管理。当一个任务结束后，输入/clear清空上下文，别让上一轮的代码讨论影响到下一轮任务。每次只聚焦一个目标，既省token，回答质量也更高。
第三个是让Claude Code“少说多做”。在指令里明确要求“不要解释，直接给代码”或者“只输出修改后的完整文件”，能省掉大段废话。实测下来，同样的任务，明确约束输出格式和不约束相比，token能差出30%以上。
如果你想知道上一轮到底烧了多少token，可以在启动Claude Code时带上统计参数，或者使用/status查看当前会话的信息。心里有数，才能不乱花。
6.3 接入MCP扩展能力
MCP是Claude Code的扩展协议，相当于给AI装上了一堆“新感官”。默认情况下Claude Code只能读你项目里的文件、执行终端命令，但通过MCP，它能直接查数据库、读网页、调内部接口，信息获取能力一下子就打开了。
举个例子，我想让Claude Code直接查数据库的表结构来帮我写查询语句，可以这样加一个PostgreSQL的MCP服务：
claude mcp add my-db -- npx @modelcontextprotocol/server-postgres "postgresql://user:pass@localhost:5432/mydb"加完之后，Claude Code就拥有了连接这个数据库的能力。你在对话里说“看看users表里有哪些字段”，它会自己连数据库去查，而不是瞎猜。MCP生态现在发展很快，GitHub、数据库、浏览器、文件系统都有现成的server，装的时候先想清楚自己需要什么，别一口气全装上，配置太多反而拖慢响应速度。
6.4 让Claude Code帮你写提交信息
这个技巧是我最近才养成的习惯。写完代码后，在Claude Code里输入：
git diff 看一下改动，帮我生成一条符合 conventional commits 规范的提交信息它会自动读取改动内容，生成一条格式规范、描述准确的commit message。比我自己手写快多了，而且保持了提交历史的整洁。项目里commit信息杂乱无章的团队，可以试试这个用法，成本极低，收益立竿见影。
7. 最后想说的大实话
用了大半年的Claude Code，又折腾了一堆国产模型接入方案，我的体会是：工具永远是次要的，思路才是主要的。Claude Code这套交互逻辑，真正改变的不是“谁在写代码”，而是“写代码这件事怎么被拆解”。你把一个模糊的需求描述清楚，它帮你拆成一步步可执行的任务，这个过程逼着你把问题想明白，这比AI帮你写多少行代码都有价值。
具体的接入方案上，我的建议很简单：想省心就用cc switch，想稳定可控就用环境变量直连，代码敏感就上Ollama本地模型。不用迷信某一个方案，换着用，找到适合自己节奏的就是最好的。
最后再分享一个小技巧：新版Claude Code迭代很快，隔三差五就有大版本更新。如果在你使用过程中出现了“明明配置都对，但突然不能用了”的情况，先别急着怀疑密钥，先执行一遍npm install -g @anthropic-ai/claude-code把它升到最新版，再试试。我遇到过好几次“新版本API变动导致旧配置失效”的情况，升级之后问题就自动消失了。保持工具版本更新这个习惯，能帮你省掉大量无谓的排查时间。
