我最早注意到claude code是在一个技术社群里看到有人贴了一段终端录屏AI自己读完了整个项目结构改了十几个文件跑完测试还顺手把commit信息写得清清楚楚。当时的第一反应是“这玩意儿怎么跟以前的聊天机器人完全不是一个物种”。后来我专门抽出几天时间从安装到日常使用把claude code在Mac、Ubuntu、VS Code里的玩法都过了一遍也踩了不少坑这篇文章就是一次完整的实操复盘。claude code本质上是一个跑在你本地终端里的AI编程代理它不只是跟你对话而是能直接读取代码仓库、修改文件、执行命令、运行测试。适合谁用我觉得三类人最合适一是每天跟终端打交道的后端和全栈工程师二是想把AI真正嵌进开发流程而不是只在网页里问问题的独立开发者三是团队里负责技术基建、想给全员配一套统一AI工具链的人。文章后面会覆盖安装、升级、VS Code接入以及我最推荐的玩法——通过cc switch把DeepSeek、Qwen、GLM这些第三方模型接进来还有一系列高频报错的排查记录。1. Claude Code到底是什么——它和普通Chat类工具不一样在哪1.1 它不是一个聊天窗口而是一个“能动手的实习生”很多人第一次用这类工具时会下意识把它当成ChatGPT那种问答框。实际上claude code的工作方式完全不一样它启动后直接以你的项目目录为上下文可以看到整个仓库的代码结构、文件内容、Git历史然后通过一个对话式的终端界面跟你协作。你跟它说“帮我看看这个接口为什么超时”它不是给你一段泛泛而谈的分析而是直接定位相关文件、打印日志、甚至在你允许的情况下修改代码。这种体验上的差异源于它的底层设计。普通聊天工具是“你问我答”数据是一次性的每次对话都要手动贴代码。claude code则是一个常驻在你本地的“代理进程”它有自己的工具调用能力——读文件、写文件、执行Shell命令、跑测试、调用外部API。你可以把它理解成一个刚入职的实习生你交代任务它去查资料、动手做、给你看结果遇到不确定的地方会反过来问你。这种模式的最大好处是它解决的是“修改代码”这个完整闭环而不是只帮你“生成一段代码片段”。我在实际项目里测过一个典型场景一个老旧的Java服务里有个接口响应超时我让claude code排查它会先去读pom.xml确认依赖版本再去看Controller和Service层的调用链然后用arthas或者直接改日志级别去定位耗时点最后给出修改建议甚至能把改动直接写到文件里。这一套流程下来基本就是初级工程师半天的工作量压缩到了十几分钟。1.2 两条运行路径官方账号登录 vs 第三方API接入claude code的认证方式有两种这也是很多新手第一时间搞不清楚的地方。第一种是用Anthropic官方账号直接登录安装完成后在终端里执行claude会弹出一个浏览器授权页面登录后 Claude Code 就用账号里绑定的套餐额度来计费。这种方式胜在原生、稳定模型用的是Claude系列本身体验最完整包括长上下文、工具调用、代码库索引这些能力都是满血状态。前提是你有一个可用的Anthropic账号。第二种是用API Key的方式。Claude Code读取环境变量ANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKEN把请求发送到指定的接口地址。官方文档允许通过ANTHROPIC_BASE_URL这个变量改变API端点。这一条非常关键它意味着claude code并不是只能连Anthropic官方服务——你完全可以把它的请求转发到任何兼容接口上这就给国内开发者打开了一条非常实用的路通过第三方API服务把DeepSeek、Qwen、GLM这些国产模型接进来既绕开了账号限制成本也更可控还能用上自己熟悉和更经济的模型。我个人的建议是如果你只是想快速体验claude code的能力优先想办法搞定官方账号如果是想长期在项目里用、并且希望灵活切换不同模型那直接研究第三方API接入性价比会高很多。这也是后面第3章要重点展开的内容。2. 安装与升级Mac、Ubuntu、VS Code环境全流程2.1 安装前的环境检查Node.js版本是个隐藏坑claude code的安装方式非常简单本质就是一个npm全局包。但“简单”不代表没坑我碰到的最典型问题就是Node.js版本太低。官方要求Node.js 18以上如果你还在用Node 16安装过程中会直接报错或者装完了运行claude时提示缺少某些API。检查环境的第一步node -v npm -v如果版本低于要求建议直接用nvm升级到当前最新的LTS版本比如Node 20。这里多说一句我遇到过有人为了一个旧项目把系统Node锁在14然后跑claude code装不上这不是工具的问题是环境太旧了。claude code本身依赖了不少现代JavaScript特性低版本Node跑不起来很正常。macOS和Ubuntu在环境准备上基本一样唯一的差别是如果你的Ubuntu是精简安装可能还需要先装一下build-essential之类的编译工具——虽然claude code本身不用编译但npm某些依赖在安装时会尝试构建原生模块缺了gcc会报错。提前装好可以省掉一半的幺蛾子sudo apt update sudo apt install -y build-essential curl git2.2 npm全局安装与权限问题的处理环境准备好之后安装命令就一行npm install -g anthropic-ai/claude-code安装完成后验证claude --version如果这里报command not found通常不是没装上而是npm的全局bin目录不在你的PATH里。npm会提示你全局安装路径比如/usr/local/bin或者~/.npm-global/bin把对应目录加到shell配置文件里就行。我在Linux服务器上遇到过另一个很经典的问题用普通用户执行npm install -g时报EACCES权限错误。网络上一堆教程会直接让你sudo npm install -g我不是很推荐这么做因为用sudo装全局包会把包的属主变成root后面你再用普通用户去执行claude它想写配置目录~/.claude时反而会出现权限混乱。更稳妥的做法是配置npm的全局目录到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH然后重新安装。这样既不用动root权限后续升级也不会出幺蛾子。2.3 升级到最新版本的正确姿势claude code的迭代速度很快官方基本上每隔一两周就会发新版本修复bug、加新功能。升级的方式有两种。一是用工具自带的更新命令claude update这个命令会检查最新版本并自动更新。二是直接走npmnpm install -g anthropic-ai/claude-codelatest我的经验是如果只是日常用偶尔执行一次claude update就够了如果遇到bug先去官方GitHub的Release页面看看最新版本和更新日志再决定要不要升。还有一个细节升级之后最好检查一下配置是否兼容尤其是如果你用了第3章介绍的cc switch这类第三方配置工具新版本可能会改变settings.json的读取逻辑。我自己就遇到过一次升级后第三方模型全部失效的情况——其实不是模型的锅是新版读取配置的路径变了重新切一下Provider就好了。3. 把Claude Code接到DeepSeek、Qwen、GLMcc switch实战3.1 为什么要做模型切换以及可行的技术路径先聊个现实问题claude code默认依赖Anthropic的账号体系和API对于没有官方账号的开发者来说门槛确实不低。但工具本身留了一个很聪明的口子——ANTHROPIC_BASE_URL环境变量。只要把这个地址指向任何兼容Anthropic消息格式的API端点claude code就能跑起来不需要登录官方账号。这就带来两条技术路径第一条用第三方服务商直接提供的Anthropic兼容接口。现在国内一些模型厂商和第三方API平台已经做了兼容层你只需要把BASE_URL指向它填入对应的API Key就能用上DeepSeek、通义千问、智谱GLM这些模型。比如DeepSeek官方就提供了/anthropic后缀的兼容端点专门给这类工具用。第二条通过一个本地转换层。很多模型只提供OpenAI格式的接口而claude code默认发的是Anthropic格式的请求。这时候可以在本地起一个“路由转换器”把Anthropic格式转成OpenAI格式再转发给目标模型。社区里已经有成熟方案了它的做法是把BASE_URL指向本地端口由这个服务去调度不同的模型。两条路各有利弊兼容接口简单直接但模型选择可能有限本地路由灵活什么模型都能接但多一层服务就多一个排查点。3.2 cc switch的安装与Provider配置cc switch是我目前用过最顺手的模型切换工具。它本质上是一个桌面端管理面板专门用来管理claude code的配置核心功能就是帮你维护多套Provider配置想用哪个模型一键切换不需要每次手动改环境变量。安装方式npm install -g cc-switch装完直接执行cc-switch启动面板。首次打开会让你选择配置目录默认是~/.claude点保存就行。它主要做了三件事读取和修改~/.claude/settings.json管理ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN提供可视化的Provider增删改查。新增一个Provider很简单。以DeepSeek为例在面板里点新增名称填DeepSeekAPI地址填https://api.deepseek.com/anthropicAPI Key填你在DeepSeek开放平台申请的密钥。然后点切换cc switch会立即把当前配置写入settings.json并生效。这个时候你再打开终端跑claude你会发现它根本没有要求登录而是直接连上了DeepSeek的接口。Qwen和GLM的配置方式完全一样。通义千问这边如果你用的是兼容接口就填对应的BASE_URL如果暂时没有也可以走本地转换层填localhost地址。智谱GLM的开放平台也提供了兼容端点配置方法大同小异。核心就是一个确认厂商给你的是什么格式的接口再把地址和Key填进cc switch。3.3 核心原理BASE_URL与Token如何接管请求这一步值得停下来稍微拆一下理解了原理你才能自己排错。claude code启动时会按优先级读取几个配置来源环境变量、项目目录下的配置文件、用户目录~/.claude/settings.json。其中最关键的两个变量是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。前者决定“请求发到哪”后者决定“用什么身份发”。当你通过cc switch切换Provider时它就是在改写settings.json里这两个值。举个例子配置DeepSeek后settings.json里大致是这样{ env: { ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN: sk-xxxxxxxx } }claude code每次调用模型都会向https://api.deepseek.com/anthropic这个地址发请求并带上你的Token作为认证凭证。厂商收到请求后如果它内部做过格式转换就会把Anthropic的请求翻译成自己模型的输入再把模型的输出转成Anthropic格式返回。这里有个坑你要注意不是所有厂商都叫它BASE_URL有的叫“API地址”有的叫“Endpoint”本质都是同一个东西。还有的厂商要求URL里带具体路径比如DeepSeek就是https://api.deepseek.com/anthropic如果你漏掉了/anthropic后缀会得到404或者路由不存在。3.4 “不登录也能跑”的Harness模式很多人在社区里问过一个问题claude code这个主程序社区里常叫它harness能不能不登录官方账号直接跑第三方模型答案是能但这里有两种理解。第一种理解是“完全跳过登录流程”。当settings.json里已经配置了ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN时claude code启动时不会再要求你做浏览器授权因为它已经有明确的API端点和身份凭证了直接进入对话界面。这就是所谓的不登录模式。我日常就是这么用的配合cc switch切换模型体验跟在官方模式下没有区别。第二种理解是“不配置任何凭证裸跑”。这个我劝你别试因为claude code必须有一个可用的API端点才能发起模型请求。如果什么都不配它会默认连官方地址而官方接口没有Key是直接拒绝的。所以“不登录”的正确姿势不是啥都不填而是填好第三方端点。有一点要提醒第三方模型接入后工具调用能力取决于模型本身。Claude模型的指令遵循能力和工具调用稳定切换到DeepSeek或Qwen后函数调用参数有时候会变形导致claude code修改文件失败。这不是工具坏了而是模型差异。我的做法是在切换模型后先让它跑一个简单的“读文件再写文件”的任务试一下工具调用链路确认通畅再上大任务。4. VS Code里配置Claude Code插件、权限、命令执行4.1 安装插件和启动方式VS Code接入claude code有两种方式。一种是最简单的——直接在项目终端里跑claude跟独立终端完全一样另一种更推荐的——安装官方扩展“Claude Code for VS Code”把对话面板集成到编辑器侧边栏可以直接框选代码发给它它也能直接读取当前打开的文件上下文。安装插件分两步。先在VS Code扩展市场搜索“Claude Code”安装官方扩展然后在项目里打开终端执行claude登录初始化。插件本身只是个前端壳真正干活的还是CLI所以CLI没装好的话插件只是个空壳。插件启动后侧边栏会多出一个对话面板。这时如果你已经配置好第三方API面板里直接就能用如果是官方登录模式第一次会要求授权。两种模式下插件和CLI共享同一套配置所以你在cc switch里切了模型插件的模型也跟着变。4.2 插件配置项逐个解释很多新手拿到插件直接开用没注意右下角的小齿轮里那堆配置项。我建议先把几个关键项搞清楚否则容易出安全事故。第一项是Permission Mode也就是权限模式。默认是最安全的“每次都问”AI想执行命令或修改文件时需要你手动确认。如果你想让它全自动跑可以改成“自动接受”但要谨慎这个模式下AI误删文件你连拦的机会都没有。第二项是Allowed Tools这是个工具白名单。你可以限制AI只能读文件或者只能改特定目录下的文件不能碰git、不能执行rm。我给团队培训时推荐的标准配置是默认拦截所有写操作和删除操作只放行读操作和测试命令。第三项是Model设置。这里不只是选模型还要配合你的Provider。比如你通过兼容接口接的是DeepSeek的deepseek-chat在Model里填对应的模型名如果填错了请求会直接被服务端拒绝。cc switch切模型时也会顺带改这个参数所以一般情况下你不需要手动动它。另外还有几个不那么显眼的配置比如“自动摘要上下文”“日志级别”默认就行不需要折腾。日志级别建议保持在info出了bug可以看输出排查。4.3 让Claude Code直接执行终端命令的正确姿势claude code最强的地方之一就是能直接执行终端命令这也是它区别于普通代码生成器的分水岭。在对话里跟它说“帮我把测试跑一下”它不会让你自己复制命令去跑而是自己开一个子进程执行pytest或者npm test然后把输出抓回来分析如果失败了它还会尝试修复再跑。这个能力要在VS Code插件里用好有几个关键动作。第一明确工作目录。claude code的所有命令都基于你打开的那个项目根目录执行所以在插件里使用前先确认VS Code打开的是正确项目否则它可能在错误目录里乱动文件。第二允许Tool执行权限。第一次它会弹一个确认框问你是否允许执行Shell命令最好选“允许并且以后不再询问”否则每执行一条命令都弹窗体验会很破碎。第三危险命令要白名单管控。我明确禁止它直接跑git push和rm -rf这两个命令一出错就是灾难。我举个实际项目里的例子。有一次重构一个Python服务我把需求发给claude code它自动执行了grep定位代码、用sed改了三个文件、跑了单测、发现一个case失败后又回头修了逻辑整个过程中我只在它执行git commit前点了一次确认。这种体验放到一年前是想都不敢想的。前提是你把权限配置好别让它裸奔。5. 高频问题与排查记录从报错到解决5.1 安装类的报错EACCES、找不到claude命令我整理了这段时间碰到频率最高的几个安装期问题直接做成速查表报错现象根本原因解决办法EACCES: permission deniednpm全局目录无写权限配置npm prefix到用户目录避免用sudocommand not found: claudenpm全局bin目录不在PATH找到npm prefix路径并加入.bashrc/.zshrc提示Node版本过低本机Node低于18用nvm升级Node到20再重装安装时卡住不动网络或npm源不稳定换用国内npm镜像比如npmmirror这里面最容易被忽视的是PATH问题。很多人报command not found第一反应是重装其实只要检查一下echo $PATH里有没有npm的全局目录就行。npm install -g完成后会明确打印它把包安装到了哪个目录比如/usr/local/bin或~/.npm-global/bin对着加进去下次开终端就生效了。5.2 第三方API接入类报错401、404、模型不存在接入DeepSeek、Qwen、GLM这一类第三方模型时报错主要集中在三类第一类401 Unauthorized。这个基本就是Token问题要么Key填错了要么Key没有开启对应模型的权限。去API平台检查一下Key是否有效以及账户余额是不是欠费了。我遇到过几次其实都是因为复制Key时带了多余的换行符。第二类404 Not Found。这个大概率是BASE_URL的路径不对。你用cc switch配置时Endpoint不是随便填的——DeepSeek要带/anthropic后缀别的平台要看文档确认具体路径。填错路径服务端直接把请求路由丢了。第三类“model not found”或者“invalid model”。这是模型名不匹配。claude code默认请求的是claude系列模型当你换了Provider必须把模型名改成目标模型支持的名称比如DeepSeek的deepseek-chat、Qwen的qwen3-coder。cc switch在切换Provider时会自动处理这个映射所以我的建议是不要手动改模型名直接用工具切减少出错概率。另外还有一个容易被忽略的点如果你用的是OpenAI格式的接口而不是Anthropic兼容接口那光改BASE_URL是跑不通的格式不一样。这种情况必须上转换层或者换一个支持Anthropic格式的兼容端点。5.3 使用体验类问题上下文超限、修改不生效、误删文件用久了之后真正的困扰反而不是安装和报错而是使用层面的问题。上下文超限是最常见的。claude code会把整个项目文件读进上下文当仓库很大时很容易顶到模型的上下文上限。表现就是AI开始“失忆”忘记它几分钟前刚改过什么或者回答质量急剧下降。我的对策是大型仓库先用.gitignore把无关目录排除掉必要的时候在对话里告诉它“忽略static目录和docs目录”减少噪音另外尽量把一个大的重构任务拆成几个小的子任务每个任务结束后让它总结一下状态。修改不生效是另一个高频问题。有时候AI说“已经改好了”但你打开文件发现根本没变或者git diff看不到变化。这个一般是两次请求之间产生了竞态或者是AI只是想改但被权限拦下了没告诉你。排查方法很简单让它重新读一遍目标文件开头确认内容和预期一致再用git status看文件是不是真的被改了。如果都没问题那就是工具调用链路有bug重试一下或者更新版本。最严重的是误删问题。我自己有一次让AI清理项目里的冗余文件它把build目录当成临时文件删了。虽然不影响源码但也够吓人的。从此之后我的规则是涉及delete操作一律走确认模式不允许AI直接执行rm命令。你可以在claude code的配置里把风险工具单独设成“每次确认”把读写类工具设成“自动允许”这样既保留效率又兜住底线。这个安全习惯我是真心建议每个用这类工具的人都养成。最后再分享一个我自己的使用习惯。现在我在项目里把claude code当成“结对编程的默认搭子”但每次大改之前一定先让它输出一个执行计划我确认后再放手让它干活。刚开始用的时候总是急着想看到结果后来踩过几次坑才明白工具越强越需要在“让它干什么”和“让它不干什么”上把好关。这个平衡找到了你会发现它的生产力提升是实打实的。