没在 Windows 上装过 Claude Code 的开发者第一次往往都会一头雾水——明明官方文档对着敲却总卡在奇怪的步骤上。好消息是Claude Code 官方已经支持 Windows 原生终端装起来并不复杂坏消息是它依赖的几个前置条件在 Windows 上都有各自的坑。这篇文章就直接从我实际在 Windows 上装、配、用 Claude Code 的过程出发把从环境准备到 VS Code 集成、再到调用本地模型和第三方 API 的完整链路讲清楚特指给准备在 Windows 上把 Claude Code 用起来、又不想在配置环节浪费太多时间的开发者。1. 安装前先解决 Terminal 和权限Windows 上最容易翻车的两件事很多人在 Windows 上装 Claude Code 失败其实不是安装命令本身的问题而是前置环境没理顺。这里的核心有两点终端选型和权限模式。1.1 为什么 Windows 比 Linux/macOS 多一些门槛Claude Code 本质是一个跑在终端里的命令行工具它最大的依赖是 Node.js 运行时安装方式也走 npm 全局包。Linux 和 macOS 上的终端默认都是 Unix 风格跟 Node 生态天然契合而 Windows 默认的 PowerShell 和 CMD 在处理字符编码、代理变量、符号链接、路径格式时会遇到很多“非 Unix 环境”特有的毛病。再加上很多人实际用的是 Windows 下的“子系统终端”或者第三方终端配置不一网上教程贴出来的命令就会出现水土不服的情况。我个人的建议是直接使用 Windows Terminal配合 PowerShell 7 或者 Windows PowerShell 5.1 都行尽量不要用 CMD。Windows Terminal 对现代终端交互的支持好得多Claude Code 的交互式界面在里面的渲染也正常不会出现光标错位、排版错乱这些问题。而且它支持多标签后面调试多个配置也很方便。如果你还没有 Windows Terminal去 Microsoft Store 搜一下就能装免费。装完以后把默认终端方案设成 Windows Terminal再顺手把默认配置文件设成 PowerShell这个操作非常基础但后面能省掉大量跟终端相关的诡异问题。1.2 权限模式别用“管理员身份运行”来装 Claude Code这是 Windows 上最容易被忽略的坑。很多开发者一遇到 npm 全局安装报权限错误第一反应就是右键“以管理员身份运行”终端然后执行安装。这样做短期内确实能装成功但会给后面埋雷。Claude Code 在启动时会尝试启动一个守护进程而这个守护进程的逻辑在 Windows 上有个已知限制从提升权限管理员的终端里启动时反而会报错。报错信息类似error: start the windows daemon from a non-elevated terminal; shared clients这个报错翻译过来就是请从一个非提升的终端启动 Windows 守护进程。意思很明确——别用管理员终端跑 Claude Code。但如果你当初是用管理员身份装的 npm 全局包全局目录的权限可能已经限制了普通终端对它的写入和访问导致你又不得不继续用管理员终端。这就形成了一个恶性循环。所以我建议的路径是普通权限终端安装 普通权限终端运行。具体来说安装时如果遇到EPERM这类权限报错优先去修 npm 的全局目录权限或调整 prefix而不是直接切管理员。后面我会讲到具体怎么处理。1.3 环境变量检查PATH 和代理配置决定你能不能启动检查完终端和权限还要确认 PATH 里能正确找到 Node 和 npm。打开任意终端输入node -v npm -v如果两个都能输出版本号说明基础运行时没问题。如果提示“node 不是内部或外部命令”那就是 Node.js 安装时没把路径写进系统 PATH此时要去检查环境变量设置或者重装 Node.js。另一个隐藏问题是代理变量。Windows 下的终端经常会因为系统代理环境变量设置不当导致 npm 网络请求卡住或超时。如果你平时用系统级代理建议在终端里确认一下npm config get proxy npm config get https-proxy如果显示的不是预期值可以通过npm config delete proxy和npm config delete https-proxy清除或者手动设置正确的代理地址。这里的处理完全取决于你自己的网络环境我只是提醒大家别忽略这一层。2. 环境准备的关键选型Node 版本、Git 和终端插件说完了终端和权限下面把环境准备部分的每个组件都说清楚。我踩过不少坑这里给出的版本组合是在 Windows 上测试过可以有效运行的方案。2.1 Node.js 选 LTS不要追新Claude Code 官方要求 Node.js 18 以上但我实际测试下来Node 20 LTS 是 Windows 上最稳妥的选择。Node 22 或者更新版本也能用但在部分 Windows 环境里会出现依赖编译上的小问题而且很多 npm 全局工具对最新 Node 版本的适配还没完全跟上。Node 18 虽然也能跑 Claude Code但版本偏老后续如果官方升级依赖可能会遇到不兼容。去 Node.js 官网下载 LTS 版本安装包安装时保持默认选项即可包括“Add to PATH”这些默认勾选。安装完成后重启一下终端再执行node -v确认版本。这里有个细节npm 的全局包安装目录默认是在 Node.js 安装目录下的node_modules和全局 bin 目录。如果你在安装 Node.js 时修改了安装路径全局包的路径会跟着变后续执行claude命令时如果提示找不到命令就要去检查这个全局目录有没有写进 PATH。2.2 Git for Windows必须装但不要装成“仅 Git Bash”Claude Code 在 Windows 上需要读取 Git 配置很多子命令在涉及版本库操作时也依赖 Git。所以 Git for Windows 是必须的。但注意不要只安装“Git Bash”模式要完整安装 Git for Windows并且在安装向导的“Adjusting your PATH”步骤里选择中间项Git from the command line and also from 3rd-party software这样 Git 才会进入 PATHClaude Code 无论在哪一个终端都能调用到 Git 命令。装完以后执行git --version验证。顺便配置一下全局 user.name 和 user.email因为 Claude Code 在操作代码库时可能会执行一些涉及提交信息的操作没有 Git 身份配置会报错。2.3 Windows Terminal 的配置细节字体、编码和滚动行为很多人觉得 Windows Terminal 装完就能用其实有几个小设置会影响 Claude Code 的体验。首先把默认字体设置成支持大量 Unicode 字符的字体比如 Cascadia Mono 或 JetBrains Mono这样 Claude Code 交互界面中的特殊字符才能正常显示。其次文本编码要设置成 UTF-8Windows Terminal 默认已经是 UTF-8但如果你之前改过代码页建议在 settings.json 里确认一下。最后重点讲一下滚动行为。Claude Code 输出信息很多有时上下文较长Windows Terminal 默认的“键盘滚动”模式可能让你在回看输出时觉得卡顿。建议把experimental.viewportWidth相关的设置忽略直接把行高和滚动行数调到舒适值。这些不是必需项但能让体验顺滑不少。我习惯在 Windows Terminal 的设置界面里搜 “line height”把行高调到 1.2 左右阅读长输出时眼睛会舒服很多。3. 正式安装npm 全局安装、认证和第一次交互前置环境准备好以后安装步骤本身非常简单核心就是一条 npm 命令。但安装完以后你还得处理认证和服务模式的问题这里才是真正的分水岭。3.1 全局安装命令与常见安装报错打开普通权限的终端执行npm install -g anthropic-ai/claude-code安装过程会拉取 npm 包及其依赖正常情况下一两分钟能完成。装完以后执行claude --version如果能输出版本号说明安装本体成功。如果你在执行安装时遇到权限类报错例如npm ERR! Error: EACCES: permission denied那就说明 npm 全局目录的权限有问题需要处理而不是强行用管理员。两个方案方案一修改 npm 全局目录到用户目录下推荐。执行npm config set prefix $HOME/npm-global然后把%USERPROFILE%\npm-global添加到 PATH重新打开终端后再安装。方案二手动给 Node.js 安装目录下的node_modules目录添加当前用户的写入权限。这个方法效率高但会改动 Node.js 安装路径的权限结构后续卸载或升级 Node 时可能会有遗留问题。我个人建议用方案一干净而且不碰系统目录。3.2 认证流程账号登录和订阅命中问题安装完以后在终端输入claude就会进入交互式界面。第一次使用需要认证。有两种方式第一种是官方账号登录启动claude后它会提示打开一个网页进行授权。登录你自己的 Claude 账号并同意授权回到终端就会自动完成认证。第二种是 API Key 认证。如果你有 Anthropic API 的 key也可以设置环境变量ANTHROPIC_API_KEY。这种方式更适合开发者调接口的场景但注意免费版账号可能没有 API 使用额度建议先确认自己的订阅状态。这里我要专门提一个热词相关的问题很多 Windows 用户遇到一个报错大意是“your organization has disabled claude subscription access for claude code”翻译过来是你的组织禁止了 Claude Code 的订阅访问。这种情况一般出现在用企业邮箱或团队账号登录时组织管理员在后台关闭了 Claude Code 的使用权限。如果你是个人使用更换个人账号邮箱登录就可以解决如果你是团队内部需要联系管理员开通权限。3.3 第一次启动基础交互模式与常用命令速览认证成功后再次输入claude进入对话界面。你会看到底部有一个输入框可以通过自然语言直接跟它交互。此时建议先试试最基础的能力让它解释当前目录下的代码让它帮你写一个脚本让它执行终端命令说到执行终端命令Claude Code 在 Windows 上的一个特色是它可以直接执行终端命令。在对话里输入类似“运行dir查看目录内容”的指令它会调起终端执行并返回结果。这里要注意Claude Code 在 Windows 上的命令执行能力受限于当前工作目录它并不会自动切换到你想要的分区或目录如果你让它执行cd D:\somefolder之后再执行其他命令有些场景下会失效。原因是会话的工作目录是固定的你最好直接在项目目录下打开终端再启动claude。另外一个常用命令是/status查看当前会话状态、token 用量和文件读取情况。在 Windows 上因为路径分隔符跟 Unix 不同偶尔会出现路径展示异常的小 bug但通常不影响使用。4. VS Code 集成与桌面版从纯终端到图形界面很多人用不惯纯终端交互希望能在 VS Code 里用 Claude Code或者直接用桌面版。这部分我把两种方式的差异讲清楚方便按需选型。4.1 在 VS Code 中配置 Claude CodeVS Code 里集成 Claude Code 主要有两条路。一条是安装官方提供的 Claude Code for VS Code 扩展另一条是直接把 Claude Code 跑在 VS Code 的集成终端里。先说官方扩展。在 VS Code 的扩展市场搜索 “Claude Code”找到 Anthropic 出品的扩展并安装。安装完成后侧边栏会多出 Claude 的面板入口你可以直接在里面发起对话也可以选中代码片段后在面板中提问甚至可以右键选择 “Explain this code” 之类的快捷操作。这个扩展本质上是包装了底层的 Claude Code 命令行工具所以要求你本机能正常执行claude命令。如果你不想装扩展第二个方法也很实用在 VS Code 底部打开集成终端直接在终端里运行claude这样既能看到代码上下文又能用终端交互方式操作。这个方式跟官方扩展互不冲突而且能完整保留 Claude Code 的命令行能力。关于配置在 VS Code 的 settings.json 里可以设置一些 Claude Code 相关项比如模型偏好、是否允许自动读取文件、输出语言等。我建议至少把“自动接受文件读取提示”关掉等熟悉后再打开避免它频繁读取无关文件消耗额度。4.2 桌面版的取舍Windows 上安装与使用体验Claude Code 桌面版目前也在推进 Windows 支持。如果你下载过桌面版安装包是完整的图形安装器装完以后会有一个独立的桌面应用登录独立于终端的 Claude Code 会话。我个人体验下来的看法是终端版是主力桌面版是补充。桌面版的主要优势是界面更好看、上下文管理和会话管理更直观适合平时不喜欢碰终端的同学。但它的一个重要缺点在于很多高级参数和第三方接入的灵活性不如终端版。比如后面要讲的本地模型接入多数方案优先支持的是终端版的 Claude Code桌面版有时候会忽略ANTHROPIC_BASE_URL环境变量。另外提醒一下如果你已经在终端版里完成过登录认证桌面版登录时依然需要独立认证一次两者不共享 token。首次登录时留意别搞混账号。4.3 本地模型接入调用 LM Studio 的完整配置很多被订阅门槛挡住的人会选择给 Claude Code 接入本地模型其中最常见的是 LM Studio。LM Studio 可以在 Windows 上直接下载安装装完以后加载一个兼容 Claude API 格式的本地模型比如Qwen系列或DeepSeek系列的量化版本然后启动本地服务。配置过程很简单。核心就是让 Claude Code 把 API 请求发送到 LM Studio 的本地地址。在终端里设置环境变量set ANTHROPIC_BASE_URLhttp://localhost:1234/v1 set ANTHROPIC_API_KEYlocal-not-needed set ANTHROPIC_MODELyour-model-nameWindows 的 PowerShell 语法是$env:ANTHROPIC_BASE_URLhttp://localhost:1234/v1。设置好以后重新启动claude它就会请求本地模型而不是云端。这里有个关键点LM Studio 的 API 兼容层默认监听端口 1234但这个端口可以改。如果你在 LM Studio 里改了端口上面环境变量的端口也要同步改。另外接入本地模型以后Claude Code 的部分高级功能如代码库分析、工具调用链可能受限于模型本身能力这是预期内的跟 Claude Code 本体无关。5. 第三方 API 接入的高级玩法C Switch、DeepSeek、Qwen、GLM 等模型的自由切换Claude Code 除了官方账号和本地模型还有一个很受大家关注的玩法通过第三方 API 兼容层把它接到其他模型供应商上。这里面最常被提到的是cc switch以及 DeepSeek、Qwen、GLM 这些模型。5.1 为什么需要第三方 API 接入官方的 Claude Code 默认调用 Anthropic 的云端 API这对国内用户和部分预算有限的个人开发者来说存在两个痛点一是网络延迟和服务可用性的不确定性二是模型调用成本。通过第三方 API 接入其他模型能用更低的价格换取类似的使用体验甚至在部分编程能力测试中DeepSeek V4、Qwen 和 GLM 的编码表现已经接近主流闭源模型。注意这个过程本质上是“把 Claude Code 当客户端把其他模型当服务端”核心逻辑还是通过环境变量去覆盖 Claude Code 默认的 API 端点和模型名称。5.2 cc switch 的安装与配置流程cc switch是一个社区工具专门用来切换 Claude Code 的模型供应商。它本质上是一个配置管理脚本可以让你在不同的 API 供应商之间一键切换避免每次手动改环境变量。这个工具在 Windows 上可以通过 npm 安装npm install -g cc-switch cc-switch运行后会进入一个交互式界面让你配置多个供应商。每个供应商需要填写名称比如deepseek或local-lmBase URL即 API 服务地址API Key你的第三方密钥模型名称比如deepseek-v4、qwen-max、glm-4或本地模型名称保存以后cc switch会把当前选中的供应商写入 Claude Code 的配置文件或环境变量中。切换时重新执行cc-switch选择目标配置项重启claude就能生效。这个工具的实际价值在于你不用手抄一长串环境变量而且可以在多个供应商之间来回切换适合那些想要对比不同模型在 Claude Code 中编程表现的开发者。5.3 手动配置第三方 API以 DeepSeek/Qwen/GLM 为例如果你不想安装 cc switch完全可以手动配置。仍是以环境变量为主。假设你要接入一个 OpenAI 兼容的 API比如 DeepSeek那么设置$env:ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic $env:ANTHROPIC_API_KEY你的key $env:ANTHROPIC_MODELdeepseek-v4这里的关键是ANTHROPIC_BASE_URL必须要指向一个兼容 Anthropic API 格式的端点。DeepSeek 官方提供了 Anthropic 兼容接口因此直接填官方地址即可Qwen 和 GLM 的第三方代理服务商可能各自提供不同的兼容地址需要去对应文档确认。有个很重要的提醒不是所有 OpenAI 风格接口都能被 Claude Code 直接调用。Claude Code 默认使用 Anthropic Messages API 格式请求如果供应商只提供 OpenAI 格式的/v1/chat/completions那是无法直接对接的必须在中间加一层转换服务。这个知识点导致很多人以为配了 Base URL 就能用结果一直报 404 或格式错误。所以在给 Claude Code 选择第三方 API 时一定要先确认提供商是否明确标注“Anthropic API 兼容”。5.4 第三方 API 的常见报错与参数微调实际测试中第三方 API 接入后最常见的报错是 401 和 404。401 代表 API Key 不正确或没有访问权限404 通常是 Base URL 路径不对这时要去对照供应商文档确认地址是否正确。还有一个容易被忽略的点ANTHROPIC_MODEL环境变量在有些版本里可能不会生效因为模型名称可能被写在配置文件中。遇到这种情况可以用claude config set model 模型名通过 Claude Code 的 config 命令设置模型。注意这里的模型名称必须以供应商支持的模型 ID 为准不能随便起。如果你的第三方 API 对并发有限制或者在长对话中容易中断可以调整 Claude Code 的请求重试参数。虽然官方没有直接暴露全部参数但通过设置环境变量CLAUDE_CODE_MAX_OUTPUT_TOKENS和CLAUDE_CODE_MAX_THINKING_TOKENS可以影响单次输出的 token 上限这能在一定程度上缓解大输出被中断的问题。6. Windows 上的踩坑记录守护进程、脚本闪退、杂项问题一次说清最后一部分我把 Windows 上使用 Claude Code 时最容易踩的坑集中列一下。这些内容来自我的实际踩坑和调研不见得每条你都会碰到但碰到了能少走很多弯路。6.1 守护进程报错请从非提升终端启动前面提到过的守护进程报错我再补充一下排查路径。如果你在启动claude时报error: start the windows daemon from a non-elevated terminal; shared clients先检查你的终端是不是管理员身份。如果是关掉管理员终端重新打开普通权限终端再启动。Windows Terminal 里可以在每个标签页标题栏上看到是否有“管理员”标识。如果你确实需要管理员权限做其他事情建议开两个终端一个管理员用来执行系统维护一个普通权限专门跑 Claude Code。这样分工明确不会互相干扰。6.2 脚本命令闪退与 .bat 脚本编码问题Windows 上还有一个很常见的问题是你把 Claude Code 的启动命令写进了一个.bat脚本双击执行时窗口一闪而过或者执行完 PowerShell 就会被强制关闭。原因多半是脚本编码问题或pause缺失。比如你在脚本里写了claude双击运行时如果 Claude Code 启动失败或因为已存在相同进程而退出窗口会立刻关闭。要排查问题脚本写这样echo off claude pause加上pause就能在退出前看到具体报错。另外.bat脚本里如果包含非 ASCII 字符比如中文注释必须另存为 ANSI 编码否则会出现乱码导致命令解析失败。6.3 端口占用惹的祸关闭或释放指定端口本地模型或第三方代理服务跑在固定端口上时Windows 经常出现端口被占用导致服务起不来的情况。如果你要释放某个端口比如 1234可以用netstat -ano | findstr :1234找到占用该端口的 PID然后taskkill /PID pid /F这个操作经常发生在 LM Studio 没有完全退出、残留了后台进程的场景中。另外Windows 更新后偶尔会出现端口被系统保留的情况虽然不常见但如果 netstat 查不到占用却依然提示端口冲突可以检查系统“排除端口范围”配置。6.4 环境变量在 PowerShell 与 CMD 中的差异Claude Code 在 Windows 上设置环境变量时PowerShell 和 CMD 的语法不一样。很多人从网上复制命令时没注意这个问题导致变量设置无效。简单区分PowerShell$env:ANTHROPIC_BASE_URLhttp://...查看用$env:ANTHROPIC_BASE_URLCMDset ANTHROPIC_BASE_URLhttp://...查看用echo %ANTHROPIC_BASE_URL%如果你在 PowerShell 里用了set命令PowerShell 会把set当成 alias 别名处理通常不会生效。我建议统一用 PowerShell并在启动claude前用$env:ANTHROPIC_BASE_URL检查变量是否真的设置上了这样排错成本最低。6.5 我个人的 Windows 配置模板与习惯最后分享一个我目前稳定使用的 Windows 配置组合作为参考系统Windows 11 专业版终端Windows Terminal PowerShell 7Node.js20 LTSGitGit for Windows 2.4x 以上Claude Codenpm 全局包普通权限运行本地模型LM Studio Qwen 量化模型端口 1234第三方 APIcc switch 管理多个供应商启动项目的推荐路径是先在项目目录下打开终端设置需要的环境变量再执行claude。不要用管理员终端也不要双击某个“一键启动脚本”直接跑除非你已经把脚本问题排查清楚。Windows 上装 Claude Code 本身只是开始真正的生产力发挥在于把它接到合适的模型和流程中去。如果你卡在安装第一步重点检查终端权限和 Node 环境如果你卡在模型接入重点检查 Base URL 和模型名是否正确。希望这篇折腾记录能给你省下不少时间。