★ FEATURED ARTICLE 最近我身边聊AI编程的人十个里有八个都在讨论Claude Code。这个藏在终端里的AI编程助手短短几个月就成了不少开发者的主力工具。但真正到上手那一步很多人会卡在两个地方一是环境装不干净各种报错劝退新手二是装完之后不知道怎么接模型尤其是想走“直连国产大模型”这条路时网上信息零零散散翻半天也没个完整流程。这篇教程就是来填这个坑的。我会从最基础的环境准备讲起把Git、Node.js、npm换源、安装Claude Code、配置环境变量、对接国产大模型API一直到首次运行和常见报错排查一条龙走通。不扯高深原理只讲能直接抄作业的操作争取让零基础的朋友照着敲也能跑起来。1. 为什么是Claude Code为什么要直连国产模型1.1 先搞明白它在终端里到底做了什么Claude Code是Anthropic出品的命令行AI编程工具。你可以把它理解成一个“住在终端里的AI工程师”——你在项目目录里启动它它能看到你的代码文件、git提交记录、目录结构然后根据你的指令直接读写文件、执行命令、跑测试而不是像网页版聊天机器人那样只能给一段代码让你自己贴。这种工作方式的区别很关键。传统AI辅助编程是“人问AI答”你复制粘贴、来回切换窗口Claude Code是“你说需求它动手”它自己改文件、自己跑命令验证你把关结果就行。很多人说用完之后回不去了就是因为这个交互模式效率高出一大截。不过它的官方定位是配合Anthropic自家模型使用所以默认配置下需要能访问官方服务。这个时候就轮到“国产大模型直连”出场了——通过给Claude Code设置几个环境变量把它请求的API地址指向兼容协议的国产模型服务商就能用国内可直接访问的模型服务来跑这个强大的编程工具响应速度快、网络稳定、成本也友好得多。1.2 直连国产模型到底在解决什么问题直连国产大模型这件事表面看只是改了个API地址深层解决的是三个实际问题。第一个是网络环境的现实问题。官方服务在国内访问不稳定很多朋友装了也没法顺畅用这是最直接的门槛。第二个是账密体系的割裂问题。用官方服务需要注册并登录Anthropic账号而大多数人更习惯用自己已有的国产模型平台账号API Key一填就能跑。第三个是成本问题。国产大模型的API定价普遍更亲民加上Claude Code这种工具在运行时会反复调用模型token消耗量比想象中大用国产服务能省不少钱。所以直连国产模型不是“退而求其次”而是针对国内开发者场景的一次合理适配。现在DeepSeek、通义千问、智谱等厂商都提供了兼容Anthropic协议的接入端点Claude Code生态本身也在逐渐开放这条路越来越成熟。1.3 你需要的前置基础写这篇教程我默认你是零基础但这些前置条件需要先列清楚一台Windows 10/11、macOS或者主流Linux发行版电脑系统的命令行能正常打开能正常访问国内网络整个流程都用不到任何特殊工具在国产模型开放平台注册过账号或者愿意花五分钟注册一个后面会一步步讲有一个你想让AI帮你搞定的项目文件夹哪怕是个空文件夹都行。如果你以前完全没碰过命令行也不用慌。全文只会用到几个固定命令我会把每条命令的作用、为什么敲、敲完会发生什么都讲清楚。你不需要理解编程只需要愿意跟着敲。2. 环境准备装好Git、Node.js是零基础第一关Claude Code虽然只是个命令行工具但它运行在Node.js环境里又依赖Git来做代码操作和上下文理解。所以安装它之前得先把这两个基础环境搞定。很多人装Claude Code失败八成是卡在这一步。2.1 Git安装与全局配置Git是干什么的简单说它是一个版本管理工具用来记录代码文件的每一次修改。Claude Code在工作时会读取git状态比如“你改过哪些文件”“当前分支是什么”“最近的提交信息”然后根据这些信息理解项目现状。所以Git必须装而且要装干净。Windows用户直接去Git官网git-scm.com下载Windows版本下载完双击安装包一路Next即可。唯一要注意的是安装过程中有一个“Adjusting your PATH environment”的选项默认选“Git from the command line and also from 3rd-party software”就好这样Claude Code才才能在命令行里正常调用到Git。安装完成后打开一个新的PowerShell窗口输入git --version能看到类似git version 2.45.0这样的输出说明Git装好了。接下来配置用户名和邮箱这是Git提交代码时的身份标识Claude Code在自动创建提交时也会用到git config --global user.name 你的昵称 git config --global user.email 你的邮箱macOS用户更简单装上Xcode Command Line Tools后系统自带Git。也可以直接用Homebrew安装brew install git。Linux用户用发行版自带的包管理器Ubuntu/Debian执行sudo apt install gitCentOS/RHEL执行sudo yum install git。2.2 Node.js与npm的安装Node.js是JavaScript的运行环境npm是它自带的包管理器。Claude Code本身就是用npm发布的安装命令就是npm install -g anthropic-ai/claude-code所以Node.js环境是硬前提。去Node.js官网nodejs.org下载LTS版本安装包。所谓LTS就是长期支持版稳定性和兼容性最好适合大多数场景。Windows安装包同样是一路Next它会自动把node和npm加入系统PATH。macOS用户也可以下载官网pkg包或者用Homebrew执行brew install node。Linux用户优先用NodeSource源或者nvm安装这里不展开跟着官网文档走即可。装完后打开新的命令行窗口验证node -v npm -v分别能看到node和npm的版本号就说明环境没问题。这里有个坑要提醒安装Node.js之后如果执行命令提示“node不是内部或外部命令”多半是安装时PATH没勾选或者装完没有开新窗口导致环境变量没刷新。重启一下命令行通常能解决。2.3 npm换源安装速度快速起飞npm默认的官方源在国外国内安装包时经常慢到怀疑人生甚至直接超时失败。这一步很关键——把npm源切换到国内镜像安装速度会快非常多。在命令行里执行npm config set registry https://registry.npmmirror.com这就是把npm的下载源指向国内镜像。设置完之后可以用npm config get registry确认一下看到https://registry.npmmirror.com/就说明换源成功。做完这件事Claude Code安装的前置环境就彻底齐了。到这里你已经完成了整个流程里最枯燥、最容易报错的部分。接下来才是见证奇迹的时刻。3. 安装Claude Code一条npm命令背后的细节环境准备好之后正式安装Claude Code其实就一条命令的事。但这条命令背后的细节和它可能踩的坑值得单独拿出来讲一讲。3.1 全局安装命令与参数解析在命令行里执行这条命令npm install -g anthropic-ai/claude-code拆解一下这条命令的含义。-g是--global的缩写表示全局安装也就是不装到某个具体项目里而是装到系统全局环境这样你在任何目录下都能直接使用claude这个命令。anthropic-ai/claude-code是包名npm会去你刚才配置的镜像源里找到这个包并下载安装。执行过程中你会看到滚动输出的进度条和文件列表这是npm在下载和安装依赖耐心等它跑完。正常情况下最后会出现类似added 1 package in 5s的输出就代表装好了。我在真实环境里实测换源之后整个安装过程几十秒就能完成。如果没换源可能卡在等待下载上半天没反应所以前面那个步骤千万别省。3.2 验证安装claude --version的玄机安装完成后验证是否成功claude --version如果输出一个版本号比如0.2.x或者更高的版本号说明Claude Code已经成功安装并可以被命令行找到了。如果提示“claude不是内部或外部命令”“claude: command not found”说明npm的全局安装目录不在系统PATH里。Windows用户需要检查npm的全局前缀路径可以用npm config get prefix查出来然后把%APPDATA%\npm通常是这个路径加到系统环境变量的PATH里。macOS/Linux用户则常见于没有用nvm装Node导致的权限问题把npm全局目录软链到/usr/local/bin或者直接改用nvm重装Node再来一次都能解决。3.3 升级与卸载npm的日常维护Claude Code迭代很快隔段时间就会有新版本。升级方式很简单npm update -g anthropic-ai/claude-code或者直接重新执行安装命令npm会自动覆盖成最新版。卸载则执行npm uninstall -g anthropic-ai/claude-code这里顺便提一句如果你之前装过旧版本启动新版本时终端可能会提示需要迁移配置或重新初始化按提示操作就好不会影响你已有的项目文件。4. 直连国产大模型环境变量配置是核心Claude Code装好之后直接运行它默认会去连Anthropic官方服务这时候就需要登录账号或者配置官方API Key。而我们要做的“直连国产大模型”核心就是在这一步动手脚——通过设置几个环境变量让Claude Code把请求发到国产模型服务商那里去。4.1 原理拆解Claude Code怎么找到模型先理解背后逻辑。Claude Code在设计时就留了后门它不是一个写死模型的客户端而是通过环境变量来决定“请求发到哪里、用哪个身份认证、选哪个模型”。它主要读取这4个环境变量环境变量作用示例值ANTHROPIC_BASE_URLAPI请求的基础地址决定请求发往哪里https://api.deepseek.com/anthropicANTHROPIC_AUTH_TOKEN认证令牌相当于API Keysk-xxxxxxxxANTHROPIC_MODEL主模型处理核心对话和任务deepseek-chatANTHROPIC_SMALL_FAST_MODEL轻量模型处理标题生成、意图识别等后台小任务deepseek-chat把BASE_URL指向一个“兼容Anthropic协议”的API端点把AUTH_TOKEN换成你的国产模型平台KeyClaude Code就会乖乖去请求国产模型。这就是整个过程最关键的认知。现在有些国产模型服务商比如DeepSeek已经官方提供Anthropic协议兼容端点配置起来最省心。另外一些服务商可能只提供OpenAI兼容格式的接口这种情况下要么等官方适配要么通过一个转换网关把Anthropic协议翻译成OpenAI协议再转发。后者稍微麻烦一些但技术上是通的适合爱折腾的朋友。4.2 以DeepSeek为例三步拿到API Key并完成配置DeepSeek是目前配置最丝滑的国产模型之一我拿它当例子完整走一遍。第一步打开DeepSeek开放平台platform.deepseek.com注册并登录账号。进入控制台后找到“API Keys”页面点击创建新的API Key系统会生成一串以sk-开头的密钥。这个密钥只显示一次一定要立刻复制保存好。第二步确认你打算使用的模型名称。DeepSeek目前主要提供两个模型deepseek-chat对应DeepSeek-V3系列擅长日常编码和对话deepseek-reasoner对应推理增强模型适合复杂逻辑推理。作为Claude Code的主模型一般选deepseek-chat就够了后台轻量任务同样用deepseek-chat省钱又稳定。第三步把API Key和模型名配置到环境变量里。这个操作在不同系统上写法不一样下一节详细展开。4.3 Windows/macOS/Linux三平台环境变量配置Windows用户打开PowerShell逐条执行下面四条命令setx ANTHROPIC_BASE_URL https://api.deepseek.com/anthropic setx ANTHROPIC_AUTH_TOKEN 你的DeepSeek API Key setx ANTHROPIC_MODEL deepseek-chat setx ANTHROPIC_SMALL_FAST_MODEL deepseek-chatsetx命令会把变量永久写入用户环境变量。注意执行完之后必须关闭当前终端窗口重新打开一个新的环境变量才会生效。这是很多新手忘了的一步。macOS和Linux用户以zsh为例把下面几行追加到~/.zshrc文件末尾echo export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic ~/.zshrc echo export ANTHROPIC_AUTH_TOKEN你的DeepSeek API Key ~/.zshrc echo export ANTHROPIC_MODELdeepseek-chat ~/.zshrc echo export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat ~/.zshrc source ~/.zshrc最后一行source ~/.zshrc是让配置立即生效。如果你用的是bash把.zshrc换成.bashrc或.bash_profile即可。配置完之后可以在终端执行echo $ANTHROPIC_BASE_URL查看是否输出正确地址。4.4 用cc-switch做配置管家环境变量这种方式虽然直接但有个痛点是切换模型厂商时得反复改环境变量、重启终端。如果你有多个模型账号来回用推荐试试cc-switch这个开源工具。cc-switch是一个专门管理Claude Code配置的桌面端工具界面简洁你可以在里面预置好DeepSeek、通义千问、智谱等多个供应商的API地址和Key需要哪个点一下就能切换。它本质上就是替你读写环境变量和配置文件省去了手工改的麻烦。对零基础用户来说我更推荐这种方式先在cc-switch里配置好你要用的国产模型然后启动Claude Code时它会自动继承你的配置不用手动碰环境变量不容易出错。配置完眼花了也可以随时回来看一眼当前用的是哪个供应商。5. 首次运行与高频操作环境变量配好之后终于可以启动Claude Code了。这一节讲首次运行会遇到什么、怎么和它对话、怎么控制它的权限。5.1 第一次启动时的完整流程打开命令行进入一个准备让AI干活的项目目录cd D:\my-project claude第一次运行可能会看到初始化提示。由于我们已经配置了国产模型的AUTH_TOKEN正常情况下它会直接用环境变量里的凭据认证不会弹出官方账号登录流程。启动成功后终端会进入一个类似聊天界面的交互模式光标处出现符号等待你输入指令。建议第一次启动后先输一句简单的话测试连通性比如你好请告诉我你当前使用的是哪个模型如果模型正确响应说明整条链路已经打通可以开始干活了。如果报错别急下一节常见问题速查表会列出绝大多数情况的解法。5.2 最常用的交互命令Claude Code虽然叫“Code”但交互方式更像终端版聊天助手。日常用下来这几个命令出现频率最高输入普通文字直接给指令或提需求比如“帮我把这个项目的README写出来”/help查看帮助菜单里面有全部支持的命令/clear清空当前会话历史重新开始/compact压缩上下文。当对话太长、token消耗膨胀时压缩之后能省钱也能保持响应速度/cost查看当前会话大概消耗了多少token和费用/model查看或切换当前模型/init让Claude Code扫描项目结构并生成初始化文档方便它快速了解项目按CtrlC两次或输入CtrlD退出程序实际体验下来/compact和/cost是最实用的两个命令。Claude Code这种工具用起来token消耗比网页对话快得多因为这些操作背后都是多次模型调用养成看消耗的习惯能帮你省不少钱。5.3 权限控制让它改文件之前先问过你Claude Code之所以强大是因为它能直接改文件、执行命令。但也正因为如此权限控制必须心里有数。默认情况下Claude Code要写文件、执行命令之前都会弹出确认提示要求你按键同意。比如它想修改index.js终端会显示类似“Do you want to edit this file? (y/n)”的提示你按y允许按n拒绝。这个机制是保护项目安全的第一道防线建议新手保持默认不要盲目放权。如果你觉得反复确认太烦可以按ShiftTab在权限模式之间切换。它会变成一个允许自动接受部分操作的模式效率更高但风险也随之增加。我个人建议只在信任的项目和明确的改动类型上用自动接受模式涉及生产环境、删除操作、批量修改时一律手动确认。6. 踩坑记录与排查速查这一节把我在实操中遇到过的、以及在社区里被问烂了的典型问题整理成一份速查表。遇到问题先按图索骥大概率能自己解决。6.1 安装阶段的高频报错报错信息原因解决办法无法加载文件xxx.ps1因为在此系统中禁止运行脚本PowerShell执行策略限制以管理员身份运行PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser选Y确认npm ERR! EACCES permission denied全局目录没有写权限Windows用管理员终端重试macOS/Linux用nvm装Node后再试不要用sudo硬扛claude不是内部或外部命令npm全局目录不在PATH执行npm config get prefix找到全局路径把它加到系统PATHnpm install超时或卡住下载源是官方源网络缓慢执行npm config set registry https://registry.npmmirror.com换源后重装这里重点说一下PowerShell执行策略的问题这是Windows新手最常碰到的一道坎。Claude Code安装包本身是一个npm包但运行它的辅助脚本有时会被PowerShell的默认安全策略拦下来。不是脚本有问题而是系统策略太严格。按表格里的命令放宽策略后就正常了。6.2 调用阶段的高频报错报错信息原因解决办法401 UnauthorizedAPI Key没配置或填错重新检查ANTHROPIC_AUTH_TOKEN确认key没复制漏字符404 Not FoundBASE_URL指向的端点不正确确认ANTHROPIC_BASE_URL是否包含兼容协议的具体路径model not found / 模型不存在ANTHROPIC_MODEL填写的模型名不对去模型平台查一下可用模型列表填准确的模型标识符请求超时或连续失败网络波动或服务商限流检查网络换时段重试或者看看是否触发了平台的并发限制Error: 401 authentication_error用了没有权限的子账号在模型平台检查账号余额和API权限状态有个排错技巧可以分享配置完之后先在浏览器地址栏直接访问ANTHROPIC_BASE_URL如果API端点本身是通的一般会返回一个错误信息或JSON而不是打不开页面。这个动作能帮你快速判断问题出在网络层还是配置层。6.3 使用体验优化与省钱技巧Claude Code跑起来容易跑得舒服、跑得省钱需要一点技巧。第一善用轻量模型。把ANTHROPIC_SMALL_FAST_MODEL设成和主模型一致或更便宜的模型因为它只干标题生成、意图识别这类小活不需要动用好模型。这一步立省不少token。第二定期压缩上下文。对话越长每次请求携带的历史消息越多token消耗直线上升。感觉对话有点长了就执行/compact让Claude Code把之前的内容浓缩成摘要再继续效果和成本都友好很多。第三把需求描述清楚。Claude Code执行任务改文件时指令越清晰试错循环越少也就越省钱。比如“把readme.md里第二节改成三步安装说明”比“帮我改一下readme”消耗小得多。第四用好/init和项目配置文件。在项目里维护好.claude/目录下的配置文件把权限规则、忽略文件预先设定好可以让Claude Code少一些无谓的确认和扫描运行效率更高。我从自己的使用经验来看Claude Code配合国产模型这套组合最大的价值还不只是“能跑”而是把AI编程助手的门槛降到了国内开发者抬手就能够到的位置。不需要折腾账号不需要复杂的网络环境注册一个国产模型API填几个环境变量一个高效的终端编程助手就上线了。最后再分享一个小技巧如果你在多个项目之间流转建议每个项目启动Claude Code之前先用git status看一眼当前分支和改动情况让工作区保持干净。Claude Code在工作时会大量依赖git状态来理解你改了什么一个清晰的git工作区能让它的判断准确很多也能减少一些莫名其妙的误操作。这个习惯坚持下来体验提升不是一点半点。
阅读完成 · 觉得有帮助？
