实在没想到Claude Code装起来会和它用起来是两个世界。如果你已经看过一些演示视频大概率会觉得这工具就是打开终端敲一行命令、回车、开写代码全程丝滑。但真到自己动手装尤其你是Windows用户或者想把它接进DeepSeek、GLM这类模型跑起来你会在安装这一关先折腾掉一两个小时。这篇东西就是我实实在在踩完一圈坑之后的记录覆盖从环境准备到常见报错的完整排查思路也包含了我在macOS和Windows 11两套系统上的实际操作过程。Claude Code本质上是Anthropic官方推出的命令行编程助手不是网页聊天窗口也不是IDE插件而是一个跑在终端里的Agent能直接读你的项目结构、改文件、执行命令并且和你多轮对话。这篇安装记录适合谁看想从零装Claude Code但被各种权限、路径、网络报错劝退的新手想在VSCode里配置Claude Code插件的开发人员以及打算把Claude Code切换到DeepSeek、GLM等模型上用的朋友。我会尽量把每一步为什么这么走讲清楚方便你举一反三。1. 装之前先搞清三件基础事1.1 你装的到底是哪个Claude Code先说个特别容易混淆的点Claude Code官方其实有几种形态安装方式完全不一样。最常见的是CLI命令行版就是用npm全局安装的那个包依赖Node.js环境日常用法是在项目目录下敲claude启动。这也是网上绝大多数教程讲的东西。还有一类是桌面版desktop独立安装包带图形界面适合不想碰终端的人。但如果你是想在开发流程里用我个人的建议是优先用CLI版因为你迟早要在VSCode终端里调它CLI版和终端工作流结合得最自然。第三个是VSCode扩展插件。这个不是独立安装包而是在编辑器里装插件本质上插件还是会去调用你本地的CLI命令。所以就算你只打算用VSCode插件前面CLI版本的安装和配置也逃不掉。我踩过的坑就是一开始贪心把CLI版和桌面版都装了结果两边配置文件互相干扰登录的API Key还指向不同账户最后把桌面版卸载才恢复正常。如果你不是特别需要图形界面别两头都装。1.2 本地环境自查清单Claude Code官方推荐的安装方式是npm全局安装所以Node.js环境是硬前提。这里说的Node.js版本网上很多教程写的是16以上就行但我实际测试下来旧版本在Windows上容易触发奇怪的权限问题在macOS上倒还好。我建议直接装LTS版本我当时用的是20.x一直很稳定。装完之后在终端里跑一下命令确认node -v npm -v如果看到node: command not found或者npm: command not found那说明Node.js根本没装好先去Node官网装LTS版本装完再往下走。另外还要确认你的终端工具Windows上我推荐用Windows Terminal而不是老式cmdmacOS上直接用系统自带的Terminal或者iTerm2都行。Claude Code的交互界面有一些彩色输出和快捷键绑定终端太老会出现显示错乱。1.3 为什么强烈推荐先建一个干净目录测试安装Claude Code之后的第一件事我建议不要直接在你现有的重要项目里跑而是先建一个只有几个临时文件的测试目录。原因有两条第一Claude Code启动后会扫描项目文件如果你的项目很大依赖目录几百MB首次索引会巨慢看起来就像卡死了第二它会读取项目里的配置文件如果你之前配过别的AI工具里面可能有残留的环境变量或权限设置会干扰Claude Code的正常工作。我当时就是在公司一个几万文件的大型前端项目里直接启动结果等了快两分钟才进入对话界面我还以为装坏了。后来发现是它要遍历node_modules里的文件处理得很吃力。在干净目录里跑通基础流程再切到真实项目会从容很多。2. 两种主流安装方式与我的选择2.1 npm全局安装最省心但路径坑最深Claude Code的官方推荐安装命令非常简单npm install -g anthropic-ai/claude-code装完之后运行claude --version如果能看到版本号说明基础安装成功。npm全局安装的好处是升级方便以后想更新就再跑一遍同样的命令。坏处是它在Windows上有路径问题。我遇到的典型报错是这样的安装过程没有任何提示但运行claude的时候终端提示“claude不是内部或外部命令”。查了半天发现npm把全局包安装到了一个路径但那个路径没有加入系统的PATH环境变量。解决方式如下。先查一下npm的全局安装目录npm config get prefix我机器上返回的是C:\Users\你的用户名\AppData\Roaming\npm。你把这个目录加到系统PATH里然后重新开一个终端窗口验证。macOS和Linux用户一般不会有这个问题因为安装路径通常在/usr/local/bin或者/opt/homebrew/bin系统默认都会识别。2.2 原生安装脚本macOS和Linux用户多了一个选择如果你用的是macOS或者Linux还可以用官方原生安装脚本curl -fsSL https://claude.ai/install.sh | bash这个脚本会把Claude Code装到~/.local/bin目录下并且在.bashrc或.zshrc里自动添加PATH配置。这个方式对不熟悉npm的人来说更友好但是有个坑如果你用了特定的shell配置管理工具脚本自动改的PATH配置可能不生效或者被覆盖。我遇到过的情况是安装脚本显示成功但新开的终端还是找不到claude命令最后手动把export PATH$HOME/.local/bin:$PATH加到.zshrc里才解决。两个方式我最后都试了一遍Windows上只能用npm方式macOS上我个人倾向于npm方式因为和包管理统一以后卸载也方便。2.3 安装后的首次登录与确认安装完成之后运行claude会出现欢迎界面然后要求你登录Anthropic账户或输入API Key。这里有个细节有的教程会让你用claude login命令有的让你直接运行claude进入交互式登录。两种都可以但如果你打算后续切换成DeepSeek或GLM这样的第三方模型这一步的登录其实可以跳过。因为当你配置了自定义的Base URL和API Key之后Claude Code不会再走Anthropic官方认证。我第一次安装时以为必须登录官方账号才能用白白浪费了一个多小时配置API Key。我建议的首次验证步骤是这样的先直接运行claude如果能看到版本信息和交互提示说明程序本体没问题此时再考虑登录或配置第三方模型。3. 踩坑实录Windows和macOS的权限问题排查3.1 Windows上PowerShell执行策略拦截Windows用户装完Claude Code最常见的第二个报错不是找不到命令而是权限拦截。运行claude的时候PowerShell弹出错误无法加载文件因为在此系统上禁止运行脚本这是因为PowerShell默认的执行策略是Restricted不允许运行本地脚本。解决方法是在PowerShell里修改执行策略Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这里解释一下为什么用RemoteSigned而不是Unrestricted。RemoteSigned的意思是本地创建的脚本可以运行但从网络上下载的脚本必须有数字签名。Claude Code安装后生成的启动脚本恰好是本地创建的这个策略足够让Claude Code跑起来同时你又不会因为放宽限制引入太多安全风险。如果你所在的团队有统一安全策略改之前最好先问一下管理员。我当时就在这一步卡了很久因为报错信息看起来和Claude Code本身没关系我还以为安装包有问题。3.2 macOS上command not found的修复思路macOS上首次安装后最常遇到的是终端提示zsh: command not found: claude。如果你用的是npm全局安装先确认npm的前缀目录。Apple Silicon芯片的Mac上npm默认路径通常是/opt/homebrew/binIntel芯片的Mac一般是/usr/local/bin。直接用下面命令查看which claude npm config get prefix如果which claude没有输出但安装目录里确实有claude文件那就手动把对应的bin目录加到PATH里。编辑~/.zshrc加入export PATH$PATH:/opt/homebrew/bin然后执行source ~/.zshrc再验证claude --version。这里补充一句如果你用的是curl -fsSL https://claude.ai/install.sh | bash方式安装的路径可能是~/.local/bin要加的路径就不一样了。建议两种方式都别来回混用不然你会在PATH配置里看到一堆重复路径后面找问题更难。3.3 终端弹出“unable to connect to anthropic services fail”接下来是很多新用户会被吓到的一个报错我装的时候也不止一次碰到报错大概是welcome to claude code v2.1.272 unable to connect to anthropic services注意这个报错跟版本号本身没关系本质是启动时Claude Code尝试连接Anthropic服务但连接失败了。排查思路按顺序来先检查网络连通性。在终端里直接跑curl -I https://api.anthropic.com如果有响应说明网络正常如果超时或者连接失败那就是网络环境的事。这种时候先确认你的网络能不能正常访问海外服务我不展开说具体操作但你可以先试试换一个网络环境再启动Claude Code。再检查环境变量。如果你之前配过其他AI工具可能已经设置了ANTHROPIC_BASE_URL或者ANTHROPIC_API_KEY这会覆盖Claude Code的默认连接配置。我遇到过的情况是历史遗留了一个错误的ANTHROPIC_BASE_URLClaude Code一直尝试连那个地址当然连不上。检查一下echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY如果发现有值确认一下是不是自己刚配的不是的话先unset掉unset ANTHROPIC_BASE_URL unset ANTHROPIC_API_KEY最后是清缓存重试。Claude Code的登录状态和临时文件会缓存在当前用户的目录下如果你升级了版本旧缓存可能和服务端的新协议对不上。删除~/.claude目录再重新登录注意这会清掉你的会话记录和配置操作前先备份里面的settings.json。3.4 “给完全访问权限”到底要不要给我在安装过程中不止一个教程提示要给Claude Code“完全访问权限”Windows上是管理员权限macOS上是在“系统设置-隐私与安全性-完全磁盘访问权限”里勾选。这个操作的目的是让Claude Code能读取和修改你磁盘上的任意文件包括那些被系统保护起来的目录。如果你只在一个项目目录里使用我建议不要给完全访问权限用项目级授权就够了。Claude Code会在首次使用时请求权限你只允许它访问当前目录即可。我给完全访问权限之后遇到的麻烦是它在读取到系统目录的时候会尝试生成一些辅助文件偶尔会触发系统安全提示烦得很。后来我把权限收回只保留项目目录的访问权反而更安静。但有一种情况值得给完全访问权限你想让它跨多个目录操作比如前端项目在/Users/yourname/projects/web后端在/Users/yourname/projects/api如果只在其中一个目录启动Claude Code默认不太容易直接读写另一个目录。这时候给完全访问权限才能无阻碍操作。结论是单项目用不用给多项目串联、需要它自由整理文件的可以给但要清楚这意味着Claude Code能读你机器上几乎所有文件按需取舍吧。4. 接入DeepSeek、GLM等多模型配置实操4.1 为什么越来越多的人把Claude Code接到第三方模型上Claude Code默认依赖Anthropic官方服务但对不少用户来说官方API的额度管理或者网络条件并不友好所以社区里开始流行把它转向国内能直接访问的兼容模型服务比如DeepSeek和GLM。严格说Claude Code的模型接入并不复杂它本身就是通过一个Base URL来调用API你把Base URL换掉再把API Key换成对应平台的Key它就走了完全不同的模型服务。这种设计本来是为了支持企业自定义网关的现在被大量个人用户用来接第三方模型。我测试下来的体验是DeepSeek和GLM在代码生成质量上跟官方模型还是有差距但胜在访问稳定、成本低作为日常辅助开发其实是够用的。4.2 环境变量接入方式的完整步骤配置第三方模型最常规的方式是设置两个环境变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。以DeepSeek为例常见配置是export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_API_KEY你的DeepSeek API Key以GLM智谱为例常见配置是export ANTHROPIC_BASE_URLhttps://open.bigmodel.cn/api/anthropic export ANTHROPIC_API_KEY你的GLM API Key这里有几个细节容易踩坑第一Base URL末尾不要多加一个斜杠。有的平台文档里给的地址末尾带了/你直接复制过来启动的时候会拼出一个双斜杠的完整地址Claude Code可能解析失败。我当时就在DeepSeek地址末尾多留了一个斜杠折腾了好一会儿。第二API Key一定要设置到当前终端会话里。如果你在一个终端里设置了环境变量在另一个终端里启动claude是读取不到那个变量的会走默认的官方配置。我建议把配置写进~/.zshrc或者Windows的用户环境变量里这样每次打开终端都自动生效。第三切换回官方模型时记得移除这两个环境变量。我见过有人配完DeepSeek之后忘了清除环境变量结果过了半年再看Claude Code一直在调DeepSeek还以为是官方模型。4.3 用工具管理多套配置的偷懒办法如果你有多个模型配置频繁切换手动改环境变量实在太累。社区里有一个小工具叫cc switch专门用来管理Claude Code的模型配置。用法很简单先设置好不同配置之后切换就一条命令。这类工具的原理其实就是改环境变量或者改Claude Code配置文件里的模型指向本质不复杂但能避免反复输入长串命令。我自己习惯写一个更简单的shell脚本放在/usr/local/bin/cc-model里面就是一个多选菜单对应不同模型的export命令执行完直接启动claude。如果你和我一样经常白天用DeepSeek、晚上切GLM建议也花十分钟做个类似的切换脚本。4.4 VSCode里如何同时配置DeepSeek和GLMVSCode插件本身有独立的配置入口。打开VSCode设置搜索claude-code你会看到Claude Code: Base Url和Claude Code: Api Key之类的选项。直接填上对应模型的地址和Key插件就会走你填的模型。如果你想在VSCode里切换多个模型又不想每次去设置里改可以在项目根目录放一个.env文件在插件启动时自动加载。不同项目用不同模型这个方式最干净。我试过在全局设置里配一个模型再在某个项目里用.env覆盖实现不同项目走不同模型的方案效果稳定。唯一要注意的是.env文件别提交到Git仓库里面是你的API Key。5. 和编辑器配合使用的几个关键细节5.1 VSCode插件装完之后识别不到CLI怎么办VSCode里安装Claude Code插件过程本身不复杂扩展市场搜索“Claude Code”直接安装重启编辑器就能看到侧边栏入口。但有一个问题很多新用户会撞上插件提示找不到claude命令。原因一般是插件自己去PATH里找claude但因为VSCode的启动方式比较特殊它读取的PATH可能是从图形界面继承的和你在终端里看到的PATH不完全一样。尤其macOS上从Dock启动VSCode经常读不到~/.zshrc里的配置。解决办法是在VSCode的settings.json里手动指定CLI路径{ claude-code.path: /Users/你的用户名/.local/bin/claude }Windows上就写成对应的npm路径比如{ claude-code.path: C:\\Users\\你的用户名\\AppData\\Roaming\\npm\\claude.cmd }设置完之后重启VSCode插件就能正常调起CLI了。5.2 避开每次都要手动确认的烦人操作Claude Code在默认情况下每次要执行命令或者修改文件之前都会弹出确认提示。这对谨慎的用户是好功能但如果你只是让它快速跑一轮代码修改这个确认会很打断节奏。Claude Code有个权限系统你可以提前声明允许某些操作然后它会自动执行。比如你信任它修改当前项目里的文件可以先设置claude --allowedTools Read, Edit, Bash或者直接在对话里输入权限声明指令。还有一个参数是--dangerously-skip-permissions用了它会完全跳过所有确认跑起来非常流畅但代价是它做什么你都不会提前被询问。我个人的建议是在你完全信任的独立测试项目里可以用在核心业务项目里别开。除了这个Claude Code还支持自定义常用命令你可以在配置里把经常执行的操作固化成快捷指令之后一个回车就能执行减少重复输入。5.3 日常开发里最顺手的几个用法装好之后我实际用得最多的场景是这样几个一是让Claude Code修bug。给它一段报错信息它能直接查相关代码并给出修改方案如果你开了文件修改权限它甚至会直接改好代码你只需review diff。二是让它重构代码。比如“把这个文件里的函数拆成几个可复用的模块”它对中小型代码库的理解能力相当在线。三是让它写测试用例。新建一个测试文件然后把被测函数的逻辑告诉它通常几秒钟就能生成一套可以跑的测试代码。如果你有多个模型配置我的经验是简单问题、快速生成类任务用DeepSeek就很够用复杂的架构设计、跨文件逻辑梳理还是切到官方模型或者GLM大模型效果好一点。6. 报错问题速查表与卸载重装6.1 把常见报错整理成一张表安装期间我前前后后遇到了十来种报错有些是配置问题有些是环境问题整理成表格的话方便你按图索骥。报错现象根本原因解决方法claude不是内部或外部命令npm全局目录不在PATH里把npm prefix目录加入系统PATH禁止运行脚本PowerShell执行策略限制Set-ExecutionPolicy -Scope CurrentUser RemoteSignedzsh: command not found: claudePATH未包含安装目录手动在.zshrc加export PATH$PATH:安装目录unable to connect to anthropic services网络不通或历史环境变量残留检查网络连通unset无关的ANTHROPIC_BASE_URLVSCode插件报错找不到claude图形界面PATH和终端PATH不一致在settings.json里手动指定claude-code.path切换了Base URL之后一直失败地址末尾多了斜杠或拼写错误检查完整URL去掉末尾斜杠登录后会话很快失效旧缓存和新协议不兼容备份settings.json后删除~/.claude目录重新登录这张表不完全覆盖所有情况但覆盖了90%的新手问题。如果你遇到的报错不在这里面先确认你用的是最新版本再考虑清缓存重装。6.2 从零卸载重装的完整流程如果实在折腾不下去或者版本升级后出现诡异行为果断重装。先卸载npm uninstall -g anthropic-ai/claude-code然后删除缓存目录rm -rf ~/.claudeWindows上目录路径是C:\Users\你的用户名\.claude。然后重新安装npm install -g anthropic-ai/claude-code这个顺序很重要先卸载再删缓存避免安装的时候读到了损坏的旧配置。我遇到过一次版本升级后一直无法连接服务重装也没用后来发现是没有删缓存旧配置始终在干扰新版本。安装完成之后最好用claude --version验证版本号是你刚装的版本再进行登录或模型配置。6.3 Win11原生终端和WSL环境的选择建议如果你用的是Windows 11在原生PowerShell里安装运行Claude Code虽然可行但偶尔会碰到奇奇怪怪的问题比如路径解析和权限判断。我的建议是如果你的项目不是必须跑在Windows原生环境里可以试试WSLWindows Subsystem for Linux。在WSL里安装Claude Code的体验和原生Linux几乎一样而且macOS和Linux上的大多数教程直接适用报错更少。我自己的使用习惯是业务项目放在WSL里用Claude Code跑起来非常流畅偶尔要在原生Windows环境处理文件权限相关的测试才切回PowerShell。最后再分享一个小经验Claude Code这个工具安装本身并不复杂但正因为它的启动流程涉及Node环境、网络连接、权限设置、模型配置这几层任何一层出了小问题都可能让你误以为是我装错了。如果你能把“定位问题”的思路拆开——先确认程序本体能启动再确认网络能连通再确认API配置正确最后才考虑是否重装——那么你能省下的时间远比照着各种帖子瞎试要多得多。我自己之所以把全过程记录下来就是希望后来者能少走一段我走过的弯路。