前阵子帮一个朋友配置终端环境他问了我一句Claude Code到底怎么装装完之后能不能直接用国产模型我意识到这是个很多人都卡住的问题。Claude Code是Anthropic官方的终端编程助手在项目目录里敲一下就能读懂整个代码库、帮你改代码、跑命令、写提交说明用过之后确实很难回到纯手动改代码的状态。但从安装到真正跑起来中间有不少坑默认要海外账号登录流程也麻烦。这篇文章就把我从零到一跑通Claude Code详细安装的完整过程写出来重点放在阿里千问模型接入这个方案上整个链路在国内就能完成不需要海外账号也不需要额外折腾网络。适合第一次接触Claude Code、想在本地终端体验AI编程的开发者阅读也适合已经被登录流程劝退、想换个接入方式的老手。1. 为什么是Claude Code以及国内无忧的安装思路1.1 Claude Code到底能干什么很多人第一次听说Claude Code以为它只是一个套了终端壳的聊天机器人其实不是。它的核心能力是理解项目和操作项目。你在任意一个Git仓库目录下启动它它会自动扫描项目结构、读取关键文件的内容然后基于这些上下文回答你的问题、修改代码、执行命令。比如你可以直接说帮我看一下登录模块为什么一直报401它会定位相关文件、分析异常日志然后给出修改建议甚至主动帮你把代码改好。它和IDE里的AI插件最大的区别在于工作方式。IDE插件通常只把当前打开文件的片段喂给模型上下文非常有限而Claude Code天然以整个终端目录为工作单位可以按需读取任意文件还内置了Bash执行、文件编辑、代码搜索这些工具。换句话说它是站在你要对整个项目负责的角度来工作的而不只是针对当前光标这一行。这也是为什么很多已经习惯在终端里干活的人用过之后觉得回不去了——它把你从切编辑器、开插件、复制文件路径的琐碎操作里解放出来直接在命令行里完成定位问题—改代码—跑测试—提交的完整闭环。1.2 国内无忧的核心用千问替代默认模型问题在于Claude Code默认的认证方式是绑定Anthropic账号要么用海外手机号注册要么准备一张海外支付方式绑定的订阅卡这对很多人来说都是一道门槛。我自己刚上手时也被登录环节搞得焦头烂额。好消息是Claude Code的架构本身是客户端与服务端分离的。它本质上是一个会调度工具的对话程序真正负责推理的模型在API后面。而这个API端点是可以被环境变量覆盖的也就是说完全可以把模型请求指向阿里云百炼的Anthropic兼容接口用国内手机号注册、国内支付方式充值的阿里云账号来驱动同一个Claude Code客户端。这套方案我实际跑下来很稳核心配置只有三个环境变量后面会详细展开。先放一张对比表让你直观看到两种方式的差异对比项默认官方接入阿里千问模型接入账号要求海外手机号/邮箱国内手机号即可认证方式Anthropic OAuth登录DashScope API-Key充值方式海外支付方式支付宝/国内银行卡使用模型Claude系列模型千问系列如qwen-max计费模式订阅或按量按量计费余额随时充这也是为什么我把这个方式称为推荐方式-国内无忧它不是绕路而是直接用国内生态里成熟、稳定的服务把模型这一环替换掉。Claude Code还是那个Claude Code但驱动它的模型换成了千问。2. 装机前置把Node.js和终端环境备齐2.1 为什么非要有Node.js 18Claude Code是一个npm包这意味着你的电脑上必须先有Node.js运行时。很多人在这一步就卡住了常见的问题是版本太老。如果你用系统自带的旧版Node比如某些Linux发行版默认带的还是16甚至14那么在安装Claude Code时就会碰到依赖版本不匹配的错误或者装完之后一启动就报语法错误因为软件包内部用到了较新的JavaScript语法特性。我建议直接装Node.js 18以上的长期支持版本。检查你当前版本的命令很简单node -v如果输出类似v16.x.x或者干脆提示command not found那说明你的Node环境不满足要求需要重新安装。满足要求的话这一节可以直接跳过。2.2 nvm安装NodemacOS/Linux与Windows的差异macOS和Linux上我最推荐的方式是用nvmNode Version Manager来装Node。原因是nvm允许你在不同Node版本之间自由切换以后如果别的项目需要特定版本不会互相污染。安装nvm之后执行nvm install 22 nvm use 22这里我以22为例实际你可以选18、20、22这些仍在维护的版本。安装完成后用node -v确认版本号已经变成你选的版本。Windows用户则不太建议用nvmWindows版的nvm维护状态和使用体验都比较一般直接去官网下载Windows Installer安装包一路下一步就好。装完之后打开PowerShell同样用node -v验证。需要注意的是Windows上如果之前装过旧版Node建议先把旧版卸载干净再装新版不然PATH里可能有残留导致命令行里跑的还是旧版本。2.3 终端怎么选终端选择看起来是小事实际影响很大因为Claude Code的环境变量是从终端进程继承的。macOS用户直接用自带的Terminal就行追求更好的分屏和主题可以用iTerm2Windows用户建议用Windows Terminal加上PowerShell 7体验比老版cmd好很多。最方便的方案其实是VS Code的集成终端。因为大多数人的编程工作本身就在VS Code里进行直接在编辑器底部打开终端路径就是当前项目目录启动Claude Code之后它立刻就能感知到项目结构省去了手动cd的麻烦。集成终端继承的是你当前shell的环境变量所以后面配置的变量也能正常读到。3. Claude Code安装的两种推荐路径3.1 方式一全局安装全局安装是官方推荐的方式也是我最常用的方式。执行一条命令npm install -g anthropic-ai/claude-code安装过程中npm会把命令行工具链接到全局bin目录下装完之后你可以在任意目录直接使用claude命令。全局安装的好处非常明显不用考虑当前项目里用的是哪个版本系统里只有一个全局版本升级也方便。有的朋友会担心全局安装会不会权限不够尤其macOS和Linux上npm全局目录经常需要sudo权限。如果遇到EACCES: permission denied这样的报错先别急着用sudo npm install那会带来文件权限混乱的隐患。更好的做法是配置nvm之后用nvm自带的Node安装的npm通常会把全局目录放在用户目录下不需要sudo。这也是我坚持先用nvm装Node的原因之一。3.2 方式二项目内使用npx如果你只是想在一个项目里试一下不想动全局环境也可以直接npx anthropic-ai/claude-codenpx会在首次执行时把包下载到本地缓存然后运行。好处是版本隔离不同项目可以用不同版本坏处是首次启动明显更慢而且如果你记错了命令写法npx还可能提示你安装一个叫claude的无关包——这里务必留意别装错东西。我的建议是日常使用优先全局安装。因为Claude Code本身就是一个面向整个开发工作流的工具做成项目级依赖反而降低了它的灵活性。如果你是在帮别人维护某个固定项目、需要锁版本才考虑npx方式。3.3 验证、升级与卸载安装完成后第一件事是验证是否装好claude --version能输出版本号就说明安装成功。如果你执行这一步时提示找不到命令大概率是npm全局目录没有加入PATH回到上一节确认Node和npm的安装方式是否正确。后续升级非常简单npm update -g anthropic-ai/claude-code卸载则对应npm uninstall -g anthropic-ai/claude-code我个人的习惯是每隔一段时间主动升级一次因为这类工具功能迭代非常快新版本经常会加入重要的权限控制、模型调度优化。升级之后如果发现某些习惯的配置不生效记得看一眼官方更新说明很多旧的环境变量名在新版里会被统一规则化。4. 阿里千问模型接入实操从创建Key到第一句指令4.1 获取DashScope API-Key要接入千问模型你的请求需要经过阿里云百炼平台。流程是先在阿里云官网完成注册和实名认证然后进入百炼控制台开通模型服务最后在API-Key管理页面创建一个新的Key。创建Key时记得把生成的字符串完整复制下来它通常以sk-开头。这个Key只会在创建时完整显示一次页面刷新之后就看不到了所以稳妥的做法是立刻粘贴到本地一个临时文本里。当然这只是中转最终要放到环境变量里。这里的国内无忧体验非常明显注册只需要手机号实名认证用支付宝扫一下就好后续如果要充值支付宝直接搞定。整个过程不涉及任何海外服务也不依赖任何额外的网络配置。4.2 配置三个核心环境变量Claude Code通过环境变量来识别API端点、认证令牌和模型名。接入千问时核心配置如下环境变量推荐值作用ANTHROPIC_BASE_URLhttps://dashscope.aliyuncs.com/api/anthropic把请求指向百炼的Anthropic兼容接口ANTHROPIC_AUTH_TOKENsk-你的API-Key调用API时的认证凭证ANTHROPIC_MODELqwen-max指定主对话使用的千问模型此外我强烈建议再多配一个变量export ANTHROPIC_SMALL_FAST_MODELqwen-turbo这个变量控制的是Claude Code内部的一些轻量级任务比如生成标题、压缩上下文、快速分类等。这些任务不需要顶级模型用更小的模型既能降低成本又能加快响应速度。不配置这个变量的话有些版本会把所有请求都打到主模型上费用会明显偏高。需要特别说明的是Claude Code在请求时本来会发送Claude系列模型名比如claude-3-5-sonnet之类而百炼的Anthropic兼容端点会自动处理模型映射把请求路由到你通过ANTHROPIC_MODEL指定的千问模型上。所以这里你不需要手动去改什么模型映射表也不要去把模型名改成Claude系列直接写千问的名字就行。如果后续阿里云更新了接口或者推荐了新的模型名以百炼官方文档为准。4.3 不同shell的配置写法环境变量配置方法取决于你用的是哪种shell。macOS和Linux上最常见的两种是bash和zsh如果你用的是zsh把下面三行加到~/.zshrc文件末尾export ANTHROPIC_BASE_URLhttps://dashscope.aliyuncs.com/api/anthropic export ANTHROPIC_AUTH_TOKENsk-你的API-Key export ANTHROPIC_MODELqwen-max export ANTHROPIC_SMALL_FAST_MODELqwen-turbo加完之后执行source ~/.zshrc让它立即生效。bash用户则对应修改~/.bashrc操作完全一样。macOS上的一个常见坑是你明明在~/.zshrc里写了配置重新打开Terminal后却看不到环境变量。这是因为新建终端窗口默认跑的是login shell它优先加载~/.zprofile。解决办法是在~/.zprofile里加一行source ~/.zshrc保证配置一定会被读到。Windows PowerShell用户临时生效的写法是$env:ANTHROPIC_BASE_URLhttps://dashscope.aliyuncs.com/api/anthropic $env:ANTHROPIC_AUTH_TOKENsk-你的API-Key $env:ANTHROPIC_MODELqwen-max $env:ANTHROPIC_SMALL_FAST_MODELqwen-turbo如果要永久生效需要把这几行写进PowerShell的$PROFILE文件具体位置可以通过echo $PROFILE查看。Windows用户注意一点不要在旧版cmd窗口里配置这些变量因为Claude Code的终端交互在PowerShell下表现才正常。4.4 第一次运行确认走通千问模型配置完成后在任意项目目录下执行claude第一次启动可能会问你一些基础设置比如是否允许它读取目录、是否开启自更新按提示回答即可。接下来你就可以输入第一句指令了比如列出当前目录下的文件结构并告诉我这个项目是干什么的如果配置正确你会看到Claude Code开始扫描目录、调用工具然后给出回答。到这一步整个安装和接入就算真正跑通了。要确认请求确实走的是千问模型有两个办法。一是在百炼控制台查看调用记录能看到刚才那次请求的模型和token数量二是在Claude Code中输入/model它会显示当前会话使用的模型名正常情况下应该显示你配置的qwen-max而不是Claude系列的模型名。5. 踩坑实录启动失败后的完整排查链路5.1 报401认证错误问题几乎都在变量上Unauthorized或者Authentication Error是所有接入第三方API端点时最常见的报错。我的排查顺序是这样的先看环境变量是不是真的生效了在终端里执行echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_AUTH_TOKEN如果两个变量都正确输出接着确认Key本身没有过期可以临时用curl直接测一下接口连通性curl -X POST https://dashscope.aliyuncs.com/api/anthropic/v1/messages \ -H x-api-key: sk-你的API-Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:qwen-max,max_tokens:16,messages:[{role:user,content:hi}]}这里我特意用了x-api-key头来测试因为百炼兼容接口对认证头的兼容性比较灵活但本质上你只需要确认Key有效、网络能通。如果curl能返回正常结构说明问题一定出在Claude Code的环境变量传递上回到4.3节检查shell配置文件。5.2 报404模型不存在模型名和权限没对上Model Not Found这类错误第一反应是检查ANTHROPIC_MODEL里写的模型名是否准确。qwen-max是常见的模型名称但阿里云百炼偶尔会调整模型的命名比如区分qwen-max-latest这类带版本后缀的名字。如果你的账号是新开通的尤其要注意是不是需要在百炼控制台先申请对应模型的调用权限有些模型默认不开放。另一个可能性是端点路径不对。ANTHROPIC_BASE_URL的值必须精确到兼容接口的根路径如果你多加了一个/v1Claude Code拼接请求路径时就会变成/v1/v1/messages自然404。最稳妥的办法就是换成我上面给的值。5.3 每次启动都跳登录页环境变量被吞了很多人在配置完环境变量之后发现启动Claude Code依然弹官方的登录界面这说明Claude Code进程根本没读到你的API认证信息。出现这种情况九成是和shll加载顺序有关比如你写在了某个不会被当前终端加载的文件里。也有小概率是拼写问题ANTHROPIC_AUTH_TOKEN很容易和官方文档里的ANTHROPIC_API_KEY弄混两者都是合法变量名但你的环境里只需要设其中一个而且建议优先用ANTHROPIC_AUTH_TOKEN。还有一个容易忽略的点如果你在VS Code的集成终端里启动Claude Code但环境变量只配置在系统层而没有重新加载那么终端进程可能还保留着旧的环境。重启一次VS Code或者新建一个终端窗口通常就能解决。5.4 耗token太快、上下文爆掉百炼账单突然变高接入千问之后很多人的下一个焦虑是费用。Claude Code在对话过程中会频繁地把文件内容、工具返回结果塞进上下文一个稍大的项目跑半小时token消耗可能远超预期。我有一次只是让它重构一个小模块结果它自己读了一堆测试文件、历史提交记录账单一下多出不少。缓解手段有几个一是及时用/compact压缩上下文把早期对话的摘要替代原始内容二是减少直接问整个项目怎么样这类开放问题改为限定文件范围比如只读src/auth目录下的代码三是把ANTHROPIC_SMALL_FAST_MODEL配好让轻量任务走便宜的小模型。我把上面这四类问题汇总成一张表方便你对照排查现象最常见原因处理办法401认证失败ANTHROPIC_AUTH_TOKEN未生效或Key错误echo环境变量确认Key阅读4.2节404模型不存在模型名不准确或端点多加了/v1检查ANTHROPIC_MODEL核对BASE_URL登录界面反复出现环境变量没被终端进程读取source配置文件重启终端费用消耗过快大模型处理了所有轻量任务配置ANTHROPIC_SMALL_FAST_MODEL6. 让它真正好用常用配置、权限边界与效率技巧6.1 项目级配置与权限收紧Claude Code启动时会读取项目根目录下.claude文件夹里的配置文件其中最重要的是settings.json。通过它可以控制Claude Code在当前项目中能做什么、不能做什么。下面是我常用的一份配置{ permissions: { allow: [ Bash(git *), Read(**), Edit(**) ], deny: [ Bash(rm -rf *), Bash(sudo *) ] } }这里allow表示允许的操作Edit(**)表示允许编辑任意文件Read(**)表示允许读取任意文件。我一般会把git开头的命令直接放行因为让Claude做版本管理操作太顺手了但删除类和管理员权限的操作我会通过deny明确禁止避免它手滑执行危险命令。权限粒度是Claude Code非常有价值的设计它不搞一刀切。你完全可以让它在某些目录下只能读不能写或者只能执行特定的测试命令这在多人协作的项目里尤其有用。6.2 常用slash命令把下面这几个斜杠命令记住效率能提升一大截/clear清空当前会话开始新话题/compact压缩上下文减少token消耗/config打开配置界面可视化调整权限和模型/cost查看当前会话预估费用/init在项目里生成一份CLAUDE.md文件把项目背景写进去/init是我认为被低估的一个命令。生成的CLAUDE.md相当于给Claude Code的一份项目说明书你可以在里面写清楚项目的技术栈、目录约定、常见命令。之后每次启动它都会自动读这份文件相当于永久性的上下文开场白能显著减少你在对话里反复解释背景的次数。6.3 与git工作流配合接入千问之后我日常使用频率最高的场景其实是git。写完代码后让Claude Code自动生成规范的提交说明这是最直观的效率提升。操作很简单先执行git diff然后把输出结果粘贴给Claude Code让它分析变更内容并生成提交信息。更顺滑的方式是直接让Claude Code自己跑git命令因为在权限配置里已经允许了Bash(git *)它可以自己查看git diff、git status然后输出一段commit message你复制粘贴就可以提交了。我还经常让它帮我做代码审查。比如在合并之前跟它说检查一下当前分支相对主分支的改动找找潜在的边界问题和安全隐患它会逐文件逐段分析。这个过程用的是千问模型费用比你预期的低很多但得到的是一个廉价又耐心的reviewer。6.4 省token的几个实操心法最后分享几个我实际跑下来有效的省token技巧。第一把项目说明写进CLAUDE.md别在每一轮对话里重复描述背景模型一次会重新读token是一样的但你的时间省下来了。第二回答问题前主动限定范围比如只看这几个文件只排查最近的报错避免它把整个仓库都扫一遍。第三及时/compact尤其是一个会话持续很久、讨论了很多话题之后压缩摘要能显著降低后续请求的token量。第四定期用/cost检查会话开销心里有数才不会在某次月底看到账单时吓一跳。我在实际使用中发现接入千问模型的最大价值不在于省掉了海外账号的麻烦而在于你可以完全按自己的节奏控制成本。按量计费模式下日常小任务花不了几分钱真要大改代码的时候再放开让它充分发挥。这种丰俭由人的体验比固定订阅舒畅很多。折腾完整个安装和接入流程我最大的体会是工具链的选择其实是一个权衡问题。Claude Code的交互体验和工具调度能力留在本地终端里而模型能力用千问来提供两者结合之后日常开发的顺畅度提升非常明显。如果你也正在被默认登录流程拦住不妨按这篇文章的顺序从环境变量开始试一次跑通之后你会发现剩下的问题都只是怎么把它的能力用得更好了。