先把结论放这儿Claude Code CLI 这个东西装起来一句话的事npm install -g anthropic-ai/claude-code但真正让它跑顺、少踩坑能聊的东西比你想的多得多。我最近在三四台不同系统上折腾它Windows 原生终端、WSL2、macOS 都过了一遍从claude 命令找不到到 PowerShell 脚本被拦、再到登录验证、权限模型几乎把热榜上能看到的坑都踩了个遍。这篇文章不搞教科书式的功能介绍直接把我踩过的坑和验证过的步骤完整过一遍目标是你看完能一次性跑通遇到问题也能自己定位。1. Claude Code CLI 的定位它跟网页里那个 Claude 不是一回事1.1 终端里的 Agent不是又一个聊天框很多人第一次听说 Claude Code会下意识以为它就是把 Claude 网页版塞进了终端里。这么理解其实偏差很大。Claude Code 是 Anthropic 官方出的agentic 编码工具它跑起来之后会主动去扫描你的项目目录、读文件、改代码、执行命令甚至自己调用 git 操作、跑测试脚本然后根据结果继续往下推进。换句话说它不只是在聊代码它是真的在你的代码库里干活。这也引出了它跟网页版最本质的区别网页版聊天框改不了你的文件Claude Code 能改。你在网页上让 Claude 写一段代码它给你贴出来复制粘贴是你的事在 Claude Code 里它自己就把文件改了跑命令把测试过了然后告诉你结果。这种能力非常爽但代价是——它需要权限而且权限管理这件事直接决定你是用得飞起还是被坑得体无完肤。1.2 安装前需要搞明白的几个基础概念在敲安装命令之前有几个概念建议先理清不然中途很容易卡壳Node.js 和 npm 的关系npm 是 Node.js 自带的包管理器Claude Code CLI 通过 npm 分发所以你的机器上必须有一个能用的 Node.js 环境。装完 Node.js 之后npm 会自动带上不需要单独装。全局安装 vs 项目安装npm install -g是全局安装装出来的claude命令在任何目录下都能直接用。只装到某个项目里的话换目录就找不到了所以 Claude Code 官方推荐全局安装。Anthropic 账号CLI 首次启动需要登录。它走的是 OAuth 登录流程会往浏览器里弹一个授权页登录后 CLI 会拿到凭证。账号需要订阅 Claude 的 Pro/Max 套餐或者开通 API 并绑定支付方式。这个是硬条件没有账号后面全白搭。PATH 环境变量装完claude命令提示找不到八成是 npm 全局 bin 目录没进 PATH。这个概念下面排障章节会反复提到。2. 动手安装之前的环境预检2.1 Node.js 版本太低会直接装不上Claude Code 对 Node.js 版本有要求18.0.0 以下基本装不上就算装上运行也会各种报错。我的建议是直接用 Node.js 20 LTS 或 22 LTS这两个版本最稳。别用太新的奇数版本也别用那种已经 EOL 的旧版。检查你机器上的 Node 版本终端里跑node -v npm -v如果提示node: command not found说明 Node.js 还没装或者装完没生效。新装的话直接去 Node.js 官网下 LTS 安装包Windows 和 macOS 都有图形化安装包一路默认就行。唯一要注意的是Windows 安装时确认勾选 Add to PATH这一步默认是勾上的但有人会手滑取消后面会特别难受。如果你平时用 nvmNode Version Manager管理多版本也建议切到 LTS 版本再用nvm install 22 nvm use 22这种操作不用我多解释。2.2 npm 镜像源装不动的头号原因很多人卡在第一步就是npm install半天不动或者在npm install时报各种网络错误。这大概率不是 Claude Code 的问题而是 npm 默认从官方源拉包网络路径不稳定。解决办法是换成国内镜像源最常见的是 npmmirror原淘宝镜像npm config set registry https://registry.npmmirror.com验证是否生效npm config get registry能看到https://registry.npmmirror.com就说明配好了。这个配置是全局的之后所有npm install都会走镜像拉包速度会快非常多。有一点需要提醒镜像源同步官方包偶尔有延迟。如果你安装时提示找不到anthropic-ai/claude-code这个包或者版本号很旧可以临时切回官方源装一次npm install -g anthropic-ai/claude-code --registryhttps://registry.npmjs.org装完再切回镜像源就行。这个技巧我实测过能解决镜像还没同步到最新版的尴尬。2.3 Windows 上先想清楚用 WSL2 还是原生 PowerShellWindows 用户安装前要先做一个选择直接在原生 PowerShell/cmd 里跑还是装一个 WSL2Windows Subsystem for Linux在 Linux 环境里跑。Claude Code 官方其实是推荐 WSL2 的原因很实际很多文件路径处理、Shell 命令兼容性问题在 WSL2 里天然不存在git、bash、各种脚本通信都正常。如果你有条件强烈建议在 WSL2 里装。启用 WSL2 之前Windows 上必须开启虚拟机平台功能这一步官方文档有提到下面排障章节会单独讲。如果不想用 WSL2在 Windows 原生 PowerShell 里也能跑但后面某些报错你会更容易遇到。另外无论走哪条路都把 PowerShell 执行策略先调好不然 npm 装完包也会被拦。这个也是高频报错我放到第 5 节详细拆。3. 从 npm install 到 claude 命令跑起来的完整流程3.1 全局安装 anthropic-ai/claude-code环境确认没问题之后装这个包就一条命令npm install -g anthropic-ai/claude-code注意包名带 scopeanthropic-ai/开头不是claude也不是claude-code。把这个-g去掉就成了项目级安装我不推荐后者原因前面说了全局安装才能保证任何目录下claude都好使。安装过程会有一段进度条装完后终端会提示已经把它安装到哪个目录。以 macOS 或 Linux 为例通常会出现在/usr/local/bin或者通过 nvm 安装时的~/.nvm/versions/node/xxx/bin目录下Windows 则通常是%APPDATA%\npm。这个路径后面要记一下排障时要用。3.2 验证安装并补全 PATH装完立刻验证claude --version能输出版本号类似1.0.x就说明安装成功。如果提示zsh: command not found: claude或者bash: claude: command not found基本就是 npm 全局 bin 目录不在 PATH 里。解决办法是把该目录加进 PATH。macOS/Linux 上如果你用的是 nvm检查echo $PATH里有没有 nvm 的 bin 路径如果是普通 Node.js 安装看看/usr/local/bin在不在 PATH 里。Windows 用户则去系统属性 - 环境变量里检查Path值是否包含%APPDATA%\npm。补完 PATH 后新开一个终端窗口再执行claude --version一般就通了。注意是新开当前窗口的环境变量是启动时读的不会自动刷新。3.3 首次启动登录与工作目录选择claude命令能跑起来之后进到你实际要干活的项目目录执行claude首次启动会进入登录流程。CLI 会输出一个验证码或者跳转链接并自动打开浏览器登录 Anthropic 账号、授权之后回到终端就能看到交互界面。授权凭证会保存在本机下次启动不需要重新登录。这里有两个实操上容易忽略的点进入哪个目录启动很关键。Claude Code 的工作范围默认就是启动时所在目录启动后再用/add-dir也能添加别的目录但最自然的用法还是先在项目根目录启动让它直接看到你的整个代码库。首次进交互界面会有个简单的欢迎引导。它会让你确认一些权限相关的选项不用急着全部允许可以先看明白每个选项再说。如果登录环节一直失败或者提示类似unfortunately, claude is not available to new users right now那大多是账号层面或者网络连通性方面的问题跟安装过程无关。确保你的网络能正常访问 Anthropic 官方服务再检查一下账号是否订阅了可用套餐然后重新跑一次登录。3.4 升级、卸载与重装Claude Code 更新频率不低隔一段时间就会出现新版本。升级命令npm update -g anthropic-ai/claude-code升级完同样可以用claude --version确认。如果你之前装过旧版升级后版本没变可以先claude --version看看再检查 npm 全局包里实际的版本npm list -g anthropic-ai/claude-code卸载也简单npm uninstall -g anthropic-ai/claude-code重装的话先卸再装或者直接再执行一次全局 install会覆盖旧版本。遇到诡异问题我一般直接卸载、清掉~/.claude下的配置文件再重装能解决九成灵异现象。4. 权限模型如何少点确认如何给完全访问权限4.1 Claude Code 为什么每步都要你确认第一次用 Claude Code 的人通常会有点不适应改个文件要确认跑个命令要确认开个网页预审内容也要确认。这不怪工具啰嗦因为它是一个真正的 agent下面这些动作它都可能主动发起读写项目里的文件在项目里执行任意 Shell 命令调用 git 做 commit、checkout 这类操作发起 HTTP 请求获取网页内容每一类操作都对应一个工具权限。Claude Code 默认的安全策略是先问再做这样 AI 如果理解错你的需求你还有机会在动手前拦下来。代价是频繁确认很打断心流。所以重点来了不是每次都手动确认而是通过配置把可信操作加入允许列表。4.2 用 settings.json 配置允许列表Claude Code 的权限配置放在 settings.json 里分全局和项目两级全局配置~/.claude/settings.json项目配置项目目录/.claude/settings.json项目配置优先级更高团队协作时可以把项目配置提交到 git 仓库保证所有人行为一致。一个简单的配置长这样{ permissions: { deny: [], allow: [ Read, Edit, Bash(git status), Bash(git log *), Bash(npm run build), Bash(npm run dev), WebFetch(domain:docs.anthropic.com) ] } }这里permissions.allow数组里每一条是一个权限规则。Read和Edit表示允许读取文件和编辑文件Bash(git status)表示只允许执行git status这条命令Bash(git log *)表示允许执行所有以git log开头的命令Bash(npm run build)单独放行构建命令。WebFetch(domain:example.com)表示允许抓取指定域名的网页。注意几点规则粒度可以很细。Bash(pwd)、Bash(ls)这种无副作用的命令建议直接放行Bash(rm *)、Bash(sudo *)这种高风险的一律不要加白名单。不带括号的Read、Edit表示整个工具全部放行适合低频但肯定安全的工具带参数的模式更精细可以按命令前缀或域名白名单来控。配置改完重开一个 Claude Code 会话生效或直接在交互界面里用/permissions命令重新加载。还有一个更常用的方式在交互界面里输入/permissions可以用菜单式操作把某条命令加入允许列表或者移除。比手改 JSON 直观适合不想记语法的场景。4.3 完全访问权限怎么给以及为什么我不建议你用热搜里有句话是claude code cli 如何给完全访问权限我也被问过很多次。确实有一个参数能实现这种效果启动时加claude --dangerously-skip-permissions加了之后所有确认动作都会被跳过Claude Code 拥有对当前工作目录的完全访问权限你说帮我搞定它就一路干到底。还有一种方式是用启动参数指定权限模式claude --permission-mode bypassPermissions效果类似。除了bypassPermissions官方还提供了几个折中模式权限模式行为说明适用场景默认default每条敏感操作逐一确认日常谨慎使用acceptEdits自动接受文件编辑但执行 Shell 命令仍需确认写代码多、跑命令少的场景plan只出方案不实际改文件和执行命令需求梳理、代码审查bypassPermissions跳过全部确认理解风险后临时使用我的态度很明确别在日常工作中用完全跳过确认的模式。我自己只在跑自动化脚本、批量重构这种明确知道边界的情况下用过--permission-mode acceptEdits即便是这样也遇到过它自作主张改错文件的情况。真要用完全访问权限务必满足几个前提工作目录有 git 且状态干净、改动能随时 revert、任务边界清晰。如果你就是觉得确认太烦优先用 settings.json 的 allow 列表把高频安全命令白名单化这是少点几次和不裸奔之间的最优解。4.4 VS Code 集成在编辑器里跑起来终端里用 Claude Code 已经很顺之后很多人还想在 VS Code 里直接呼出它。官方提供了 VS Code 扩展安装方式是在 VS Code 扩展面板里搜 Claude Code安装 Anthropic 官方出品的那一个。扩展本质上复用你本机已经装好的 CLI所以先保证claude --version在你的终端里能跑通再装扩展不然扩展会一直提示你找不到 CLI。用起来很简单在 VS Code 里按CtrlShiftP输入 Claude Code 就能看到相关命令。第一次使用会让你选择工作区并完成登录后续就相当于把 Claude Code 的交互面板嵌在编辑器里左边看代码、右边跟 agent 对话体验比纯终端好很多。搭配 VS Code 的源码管理面板Claude Code 改了什么文件、改了哪些行都一目了然出问题也能快速回退。5. 高频报错与排障实录5.1 command not found比你想象的多两个原因claude: command not found是我见过最多的报错但原因可能有三种Node.js 没装或版本过低node -v都打不出数字那就是最基础的环境没有。先把 Node.js LTS 装好再回过来装 Claude Code。npm 全局 bin 目录不在 PATH前面提过macOS/Linux 上确认/usr/local/bin或 nvm 的 bin 目录在PATHWindows 上确认%APPDATA%\npm在Path里。改完环境变量记得新开终端。全局安装时用了 sudo 导致权限归属混乱macOS/Linux 上如果npm install -g时用了sudo装出来的文件 root 所有后面升级、卸载都会报权限错误。不推荐用 sudo 装全局 npm 包更好的做法是给 npm 配置一个用户级全局目录或者直接用 nvm。排查时可以先用下面命令看 claude 到底装到哪了which claude如果输出一个路径说明它其实装了是启动 shell 的 PATH 不对如果什么都没输出那就是全局 bin 目录的问题按上面思路处理。5.2 PowerShell 禁止脚本的那句经典报错Windows 原生 PowerShell 用户特别容易撞见这段npm : 无法加载文件 D:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本这不是 Claude Code 的问题是 PowerShell 执行策略默认比较保守不允许加载.ps1脚本。修法是在 PowerShell 里执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserRemoteSigned的意思是本机创建的脚本可以运行从网上下载、需要远程签名的脚本必须经过签名。选CurrentUser作用域只对当前用户生效不会影响系统其他地方。执行后输入Y确认。之后重开 PowerShellnpm -v和claude --version应该都恢复正常了。如果仍然报错用管理员身份打开 PowerShell 再执行一次或者检查是不是有组策略强制覆盖了执行策略。这个修法不涉及任何安全降级属于 PowerShell 的标准配置Windows 很多工具都会要求这么做。5.3 Virtual Machine Platform 提示是什么意思Windows 上跑 Claude Code特别是配合 WSL2 或容器环境时可能会看到类似Claudes workspace requires the Virtual Machine Platform on Windows. Please enable it.这个提示是说系统缺少 Windows 的虚拟机平台可选功能而这正是 WSL2 运行的基础。启用方式是用管理员身份打开 PowerShell执行dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart然后再启用 WSL 功能dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart两条都执行成功后重启电脑。重启之后装 WSL 内核wsl --install装完再跑 Claude Code这个提示就应该消失了。如果你确定不用 WSL2也想不起来为什么要弹这个那多半是某个依赖工具比如 Docker Desktop要求开启它还是按上面步骤启用了比较省心。5.4 deprecated 警告到底要不要管npm 安装一堆依赖时有个警告出现频率极高npm warn deprecated node-domexception1.0.0: use your platforms native DOMException instead很多新手看到warn deprecated就紧张其实没必要。node-domexception这个包是很多底层依赖的间接依赖早期 Node.js 没有原生DOMException需要这个包来补齐现在的 Node.js 版本已经原生支持了所以 npm 提示这个包你可以不用了。它不影响 Claude Code 的正常安装和运行不用特意处理。整个 node_modules 依赖树里存在冗余、过期的包是非常常见的只要不是error级别的输出就继续往下走。真想让安装日志干净点可以等依赖维护方更新这不是你本地能改的。5.5 登录阶段的坑登录失败或claude启动后一直卡在授权页面有几个常见原因浏览器没自动弹出CLI 会打印一个链接手动复制到浏览器里访问即可。账户没有可用订阅Claude Code 需要 Pro/Max 订阅或 API 额度免费账号直接进不去。如果提示unfortunately, claude is not available to new users right now大概率是账号所处区域的可用性问题或新账号配额受限这种情况只能等待或者联系官方支持跟本地配置无关。网络无法访问 Anthropic 服务确认你的网络环境能正常访问 Anthropic 官方站点如果不行你需要处理的是基础网络连通性而不是丢给 Claude Code 背锅。排障时可以用一个很简单的办法确认登录凭证状态claude auth status如果显示未登录重新执行claude走一遍登录流程如果已登录但仍报错试试/logout后再登录相当于把会话重置一次。6. 常见问题速查表最后把高频问题收敛成一张速查表收藏起来比翻文档快多了。问题现象直接原因解决办法claude: command not foundnpm 全局 bin 不在 PATH或 Node.js 未安装确认 Node.js 已装将 npm 全局 bin 加入 PATH重开终端npm.ps1 禁止运行脚本PowerShell 执行策略限制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser无法将 npm 项识别为 cmdletNode.js 没装或 PATH 没配重装 Node.js 并勾选 Add to PATH或手动配置环境变量安装卡住、速度极慢npm 走官方源网络不稳定npm config set registry https://registry.npmmirror.comnode-domexception1.0.0deprecated 警告依赖树中的旧包无需处理不影响运行workspace requires the Virtual Machine PlatformWindows 未启用虚拟机平台按 5.3 节启用 VirtualMachinePlatform 并重启登录后claude仍提示无权限订阅层级不够或区域限制检查账号订阅状态联系官方支持claude --version版本不更新全局包未升级成功npm list -g anthropic-ai/claude-code查看实际版本后重新安装升级后配置丢失CLI 版本间配置格式变化备份~/.claude/settings.json更新后重新调整配置写在最后把这一整套流程跑下来我个人最大的感受是Claude Code CLI 的安装本身不难难的是理解它背后的运行机制——PATH 管着命令能不能被找到权限模型管着 agent 敢不敢动手Windows 的几个系统功能则管着底层环境通不通。我建议你第一次用的时候老老实实开默认模式感受一下它每一步的确认请求分别对应什么操作跑顺手了再针对性放行那些高频安全命令。这比一上来就bypassPermissions靠谱得多。另外有个小技巧分享给你如果你发现某个操作频繁被确认与其手动确认一百次不如把它整理进 settings.json 的 allow 列表里。整理完之后你用着爽项目团队其他人也能照着你这份配置走一举两得。等把权限这块玩明白了Claude Code 用起来的体验跟默认状态下完全是两个世界。