Windows 10上安装配置Claude Code：从环境准备到模型接入实战

2. 环境准备：先把Windows 10这台机器收拾利索

2.1 确认系统与终端状态

Claude Code本质是一个运行在终端里的命令行程序，在Windows 10上装它之前，先确认你本机的基础状态是否到位。我见过不少朋友一上来就敲 npm install -g @anthropic-ai/claude-code，结果卡在各种环境报错上，浪费大量时间。其实只要先把下面三样东西确认好，后面几乎是一路绿灯。

第一，操作系统版本。Windows 10的20H2及以上版本都能正常跑Claude Code，老版本（比如1809之前的）虽然理论上也能装，但终端组件和内置的OpenSSH版本可能比较旧，容易在连接远程仓库或执行某些命令时出幺蛾子。我的建议是尽量保持系统更新到最新补丁，尤其要确认PowerShell版本在5.1以上。你可以在PowerShell里输入 $PSVersionTable.PSVersion 查看，如果版本太低，建议直接装Windows Terminal并把默认Shell设为PowerShell 7，后面用起来会顺手很多。

第二，包管理器。Claude Code官方推荐用npm安装，但Windows 10自带的Node.js是缺位的，需要自己去装。这里有一个选择：装Node.js官方安装包（LTS版本）还是用winget？我个人的习惯是直接用Node.js官网的LTS安装包，因为安装过程会自动帮你配好PATH，省去后面手动设环境变量的步骤。如果你电脑上已经有Chocolatey或Scoop，也可以直接 choco install nodejs-lts 或 scoop install nodejs-lts，但新手我更推荐官网安装包，可视化界面点几下就完事，不容易出错。

第三，Git。Claude Code虽然不是一个Git工具，但它经常需要读取项目里的Git信息（比如当前分支、最近提交记录）来辅助理解代码上下文。Windows 10不自带Git，你需要去git官网下载安装。安装时注意选"Git from the command line and also from 3rd-party software"这个选项，确保Git能被命令行直接调用。装完可以在PowerShell里输入 git --version 验证。

2.2 安装Node.js并验证环境变量

Node.js的版本选择很有讲究。Claude Code官方要求Node.js版本不低于18.0.0，但实测我建议直接用20.x LTS版本，因为18在某些老版本上跑过一些依赖兼容问题，而20是当前稳定主流。你可以在官网下载页面找到"LTS"字样的版本下载，不要选"Current"版（那个是新特性试用版，稳定性差点）。

安装过程中有一个关键勾选项：在安装向导中，一定要把"Add to PATH"勾上。默认是勾选的，但有些朋友手滑取消了，装完发现 node 命令没法用，还得手动去补环境变量。安装完成后，重新打开一个PowerShell窗口（注意要重新打开，否则环境变量不会刷新），输入：

powershell复制node -v
npm -v

如果分别输出了类似 v20.x.x 和 10.x.x 的数字，说明Node环境和npm包管理器都已就绪。这一步极其重要，因为后面所有Claude Code的安装和升级都依赖npm。如果这里报错"node不是内部或外部命令"，多半是PATH没有配置好，需要手动去系统环境变量里把Node.js的安装目录（比如 C:\Program Files\nodejs\）加进去。

2.3 模型接入方案选型：官方API、第三方API还是本地模型

环境准备好之后，还有一个更重要的选择题：你到底要让Claude Code调用哪个模型？这个问题很多人装完了才想，结果发现卡在API Key配置上。我建议在安装之前就想清楚，因为不同的接入方式决定了你要做哪些环境变量配置。

第一种是官方API方式。直接在Anthropic控制台创建API Key，然后设置 ANTHROPIC_API_KEY 环境变量。官方API的模型能力最完整、最稳定，对新功能的跟进也最快，但需要海外网络环境，而且按使用量计费，价格不算便宜。

第二种是第三方兼容API方式。现在国内外不少模型服务商提供了Anthropic兼容接口，你只需要把 ANTHROPIC_BASE_URL 指向它们的地址，设置对应的API Key和模型名，就能让Claude Code跑在DeepSeek、混元、MiniMax等模型上。这个方案对国内用户特别友好，网络稳定、价格更低，而且模型能力也不弱。我身边很多同事就是这么接的，成本控制得很好。

第三种是本地模型方式。通过Ollama等工具在本地运行开源模型（比如Qwen2.5、DeepSeek-R1蒸馏版），然后把Claude Code指向本地的 http://localhost:11434 地址。这种方式完全免费、数据不外泄，但受限于本机硬件，模型参数量不能太大，代码理解能力比云端模型要差一些，适合简单任务或者对隐私要求极高的场景。

这三种方案怎么选？我给的参考标准很简单：如果你是按量付费、追求最强代码能力，选官方API；如果你在国内网络环境下想要稳定、便宜的方案，首选第三方兼容API；如果你要处理敏感代码、不能出内网，那只能选本地模型。下面这篇博文会重点讲官方API和第三方兼容API的配置，本地模型作为备选方案也会简单提一下。

3. 安装Claude Code：从npm全局安装到首次启动

3.1 npm全局安装的完整命令与权限避坑

环境就绪后，安装Claude Code本身非常简单，在PowerShell里执行：

powershell复制npm install -g @anthropic-ai/claude-code

这条命令会从npm仓库下载Claude Code包并全局安装。等待过程中，npm会输出一长串下载进度，这里不需要任何干预。安装完成后，输入：

powershell复制claude --version

如果输出了版本号（比如 1.0.x），说明安装成功。但这里有一个Windows非常典型的坑：如果你在安装时看到类似 EACCES: permission denied 的报错，说明当前用户对npm全局目录没有写权限。Node.js官方安装包在Windows上一般不会出现这个问题，但如果你的Node是用某些包管理器装的，或者公司电脑有权限管控，就可能碰到。解决办法有两个，一是用管理员身份重新打开PowerShell再执行安装命令，二是配置npm的全局目录到当前用户目录下（npm config set prefix "$env:APPDATA\npm"），后者的好处是以后升级包不需要再切管理员身份。

另外我还要提一个更现代的安装方式。Claude Code也提供了原生安装脚本，可以在官方文档里找到对应的命令。原生安装的优势是不依赖npm，安装速度更快，且升级也简单。但考虑到大多数教程和社区经验都以npm方式为主，新手用npm方式出了问题时更容易搜索到解决方案，所以我仍然建议从npm方式入门。

3.2 首次启动：登录认证还是直接配置API Key

安装完成后，直接在终端输入 claude 进入交互界面。首次启动时，Claude Code会询问你是要登录Anthropic账号还是使用API Key。这里有两种选择，对应不同的使用方式。

如果你选择登录账号的方式，程序会生成一个一次性登录码，并打开浏览器让你完成授权。登录成功后，Claude Code会把会话令牌保存在本地，后面直接就能用。这个方式的优点是认证简单，不需要自己管理API Key，但副作用是它主要用于Anthropic订阅用户，不适合第三方API或本地模型。

如果你选择API Key方式（这也是大多数人的选择），首次启动时它会提示你设置 ANTHROPIC_API_KEY 环境变量。在PowerShell里设置环境变量的方式比较特殊，用以下命令：

powershell复制$env:ANTHROPIC_API_KEY="sk-ant-xxx"

但这里要特别提醒：$env: 方式设置的环境变量只在当前这个终端窗口有效，一旦关掉窗口就没了。为了持久化，应该用下面的命令：

powershell复制setx ANTHROPIC_API_KEY "sk-ant-xxx"

setx 会把变量写入用户级环境变量，下次打开任何终端窗口都会自动生效。不过注意，setx 写入后当前窗口仍读不到新值，需要重新开一个终端窗口才行。我第一次用的时候在这里卡了一下，设置完发现还是报没找到API Key，后来才意识到是要重开窗口，这个细节很多教程都没提。

3.3 WSL与原生Windows：两种运行方式的取舍

在Windows 10上运行Claude Code，除了直接装在原生的PowerShell/CMD环境里，还有一种非常流行的方式是装到WSL（适用于Linux的Windows子系统）里面。这两种方式哪个好，我客观对比一下。

原生Windows方式，也就是本文前面讲的方式，安装简单、路径直接，文件操作都在Windows文件系统里，和Windows生态的兼容性最好。但它有一个短板：Claude Code在Windows原生环境下，某些辅助工具（比如Python脚本、Shell命令）的执行可能受限，因为Windows的进程模型和类Unix系统有差异。

WSL方式则是在Windows 10里跑一个真正的Linux环境，再在Linux环境里装Claude Code。这样做的好处是兼容性最接近Linux生产服务器，很多依赖Shell命令的开发流程可以无缝跑通。坏处是需要额外安装WSL（在管理员PowerShell里执行 wsl --install），而且WSL里的文件系统和Windows文件系统之间的流转还是有层隔膜的，路径映射偶尔让人抓狂。

我个人目前的实际选择是：日常简单任务用原生Windows方式，跑在PowerShell里；遇到需要大量Shell脚本或部署类任务时，切到WSL环境里用。如果你只想装一套，且主要做日常代码编辑、解释、重构，那原生Windows方式足够用了；如果你要做的任务涉及Docker、Linux命令行工具、云原生部署演练，那直接上WSL，别犹豫。

4. 模型接入实战：把Claude Code指向你想要的模型

4.1 官方API密钥配置与验证

配置官方API密钥的过程其实很简单。先到Anthropic官网的控制台里创建一个API Key，创建完之后，把那段以 sk-ant- 开头的密钥复制出来。然后在PowerShell里用 setx 命令持久化设置：

powershell复制setx ANTHROPIC_API_KEY "sk-ant-你的密钥"

设置完成后，重开终端，输入 claude 启动，然后随便说一句"你好，帮我介绍一下你自己"。如果它正常回复了，说明官方API这条路已经通了。这时候你可以进一步测试代码能力，比如让它写一个Python快速排序函数，看看回复质量和速度。

有一点要提醒大家：官方API是按token计费的，输入和输出都算钱。如果你只是日常小项目使用，费用通常不高，但如果让Claude Code批量处理大量文件、或者让它反复修改同一个大型项目，账单可能让你肉疼。建议在官网账户里设置好消费上限（Spend Limit），防止某次大任务不小心跑出天价账单。我身边就有人一晚上跑了20多美元的用量，第二天收到邮件才知道，设置了消费上限才能安心。

4.2 第三方兼容API接入：以DeepSeek为例

国内用户更关心的其实是怎么让Claude Code用上国产模型，毕竟访问Anthropic官方API的延迟和稳定性问题让人头疼。好在Claude Code在设计上预留了环境变量的"后门"，通过 ANTHROPIC_BASE_URL 可以把请求转发到任意兼容Anthropic接口的服务商。

以DeepSeek为例，配置过程分三步。第一步，去DeepSeek开放平台注册账号并创建API Key。第二步，设置三个环境变量：

powershell复制setx ANTHROPIC_BASE_URL "https://api.deepseek.com/anthropic"
setx ANTHROPIC_AUTH_TOKEN "你的DeepSeek密钥"
setx ANTHROPIC_MODEL "deepseek-chat"

注意这里我用了 ANTHROPIC_AUTH_TOKEN 而不是 ANTHROPIC_API_KEY，DeepSeek这套兼容接口的鉴权头偶有差异。如果你按网上一些老教程设置完后总是报401，可以试试把API Key放在 ANTHROPIC_AUTH_TOKEN 里。另外 DEEPSEEK_API_KEY 是DeepSeek官方接入时用的变量，但Claude Code不一定读它。第三步，重开终端，启动 claude，随便聊一句验证是否通。

我实测下来，DeepSeek接入Claude Code后，代码理解能力在通用场景下表现不错，尤其是中文注释、文档生成、代码解释这类任务，输出质量很稳定。不过要注意的是，第三方模型兼容层偶尔会有小bug，比如工具调用格式不一致、上下文长度限制不同等，如果遇到诡异报错，可以先在DeepSeek的官网浏览器对话里验证一下是不是模型本身的问题。

4.3 本地模型接入：Ollama方案补全

如果你不想花钱，也想让Claude Code跑起来，本地模型是目前最合适的方案。先安装Ollama并拉取一个编码能力还行的模型，比如 qwen2.5-coder 或 deepseek-coder。Ollama默认监听 http://localhost:11434，所以环境变量这样配：

powershell复制setx ANTHROPIC_BASE_URL "http://localhost:11434"
setx ANTHROPIC_AUTH_TOKEN "ollama"

这里解释一下为什么认证令牌可以随便填：Ollama本地服务默认不校验鉴权，令牌填什么都能通过。但也正因为如此，不要在公网环境暴露Ollama端口，否则任何人都能调用你的本地模型。启动Claude Code后，它会尝试通过Anthropic协议访问本地模型，但这里有个现实问题：Claude Code使用的是Anthropic的Messages API格式，而Ollama使用OpenAI格式，两者并不直接兼容。所以实际使用中，要么给Ollama加一个Anthropic兼容层（社区有相关代理工具），要么接受偶尔的格式错误。简单说，本地模型这条路属于"能跑，但不是开箱即用"，适合愿意折腾的朋友。

4.4 多模型切换：用脚本管理环境变量

既然模型配置本质就是环境变量，那自然而然就会遇到多模型切换的需求。比如我白天用DeepSeek跑日常任务，偶尔用官方API跑复杂项目，怎么快速切换？

我的做法是准备两个PowerShell脚本，一个 use-deepseek.ps1，一个 use-anthropic.ps1。每个脚本里用 setx 设置对应的一组环境变量。切换时，只需要运行对应脚本，然后重开终端启动 claude 就行。虽然得重开终端这一步有点烦，但胜在省心、不会串配置。

如果你更懒，也可以在 claude 命令启动时临时指定环境变量：

powershell复制$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
$env:ANTHROPIC_MODEL="deepseek-chat"
claude

这样只影响当前窗口，不会污染全局配置。我的使用体验是：临时变量适合想快速试一下某个模型好不好用，setx 持久化适合确定日常主用哪套方案。搞清楚这套逻辑，你在不同模型之间来回切就能游刃有余。

5. Claude Code日常使用实操：从命令到权限管理

5.1 核心斜杠命令速查

模型配通之后，接下来就是真正用起来。Claude Code的交互界面完全基于终端，所有功能都通过斜杠命令触发。下面这组命令是我每天用得最多的，按使用频率排序：

• /help：查看所有可用命令列表。新手进来第一件事先敲这个，快速了解功能全貌。
• /clear：清空当前对话上下文。Claude Code的上下文有长度限制，聊久了会变慢或报错，遇到这种情况就 /clear，开个新话题。
• /compact：压缩当前对话的上下文。它会把历史对话总结成摘要再继续，比直接 /clear 强在保留了关键信息，适合长任务中途不想丢记忆的场景。
• /init：在项目根目录生成 CLAUDE.md 文件。这是Claude Code项目记忆的关键，我会在下面专门讲。
• /login 和 /logout：重新登录或退出当前账号。切换账号时用得到。
• /cost：查看当前会话的token消耗和费用估算。对于按量付费用户，这是个救命命令，我几乎每天都会看一眼。
• /review：让Claude Code检查你当前代码的改动，给出评审意见。这个功能在自我代码审查阶段很好用。

这些命令在交互界面直接输入即可，程序会自动识别。如果某个命令没反应，先确认是不是命令拼写问题，或者当前模型是否支持该功能。第三方兼容模型有时会对部分命令支持不完整，比如 /review 依赖工具调用能力，模型能力弱的时候可能会返回奇怪的错误。

5.2 权限模式：让Claude Code自由干活还是事事请示

Claude Code的一个核心设计是它可以直接修改你的代码文件。因此在交互界面里，有一个权限模式的概念需要理解清楚。

默认情况下，Claude Code每执行一个文件修改操作前，都会弹出一个确认提示，让你选择"允许"、"拒绝"还是"始终允许这个文件"。这种模式最安全，适合刚开始接触的用户，避免AI误改代码。但如果你已经充分信任Claude Code，每天要让它批量处理很多文件、每一个都确认实在太烦，就可以用到权限模式切换。

在 /config 菜单里，你可以设置权限策略。常用的选项包括：

• 默认模式（每次确认）：适合新手和重要项目。
• acceptEdits 模式：允许所有文件编辑操作，不再逐一确认。适合有版本控制兜底的中低风险项目。
• plan 模式：只让Claude Code分析、提方案，不实际改文件。适合先让它给出重构思路，自己再动手。

我个人建议：只要你的项目已经用Git管理（能随时回滚），就可以大胆开启 acceptEdits 模式，效率提升非常明显。但如果项目还没有纳入版本控制，或者你只是跑实验代码，建议保持默认确认模式。

另外有一个细节，CLAUDE.md 里可以写 permissions 指令，比如：

markdown复制permissions:
  deny: ["*.pem", "*.key"]

这样Claude Code就会主动避开私钥等敏感文件，这对于安全性要求高的项目非常有用。

5.3 CLAUDE.md：把项目规范和背景写进记忆里

CLAUDE.md 是Claude Code的灵魂文件。简单说，它就是一个纯文本文件，放在项目根目录，里面写项目说明、代码规范、常用命令、架构信息等。每次Claude Code启动后，它会自动读取这个文件，把里面的内容当作"项目背景"来理解。这等于给AI装了一份项目说明书。

我举个例子。假设你有一个Python后端项目，CLAUDE.md可以这样写：

markdown复制# 项目名称：用户服务
## 技术栈
- Python 3.11 + FastAPI
- PostgreSQL 15
- Redis 7

## 常用命令
- 启动：uvicorn app.main:app --reload
- 测试：pytest tests/
- 格式化：ruff check .

## 编码规范
- 使用类型注解
- 业务代码放在 app/services/
- 数据库操作必须走SQLAlchemy，禁止手写裸SQL
- 所有错误统一抛 BusinessError，由全局异常处理器兜底

## 架构说明
- 路由层只做参数校验，不写业务逻辑
- 所有外部接口调用必须经 app/clients/ 下的封装

有了这份CLAUDE.md，Claude Code在帮你写新接口或修改业务时，会自然遵循项目的技术栈和编码规范，生成代码风格高度一致。这比每次对话时口头描述项目背景要高效得多，因为口头描述往往会遗漏细节，而CLAUDE.md则被完整加载到上下文里。

在项目的开发过程中，CLAUDE.md也会慢慢更新。当Claude Code发现项目里某个约定值得沉淀时，它会主动提醒你补充进CLAUDE.md。你也可以定期手动整理，让这个文件始终跟上项目演进的节奏。

5.4 VS Code + PowerShell：本地开发组合拳

Claude Code本身是纯终端工具，但大多数人的日常开发还是在VS Code里完成。这两者怎么配合？

最简单是直接在VS Code里打开终端面板（快捷键 Ctrl+`），在终端里启动 claude，一边写代码一边和AI对话。这样文件编辑、代码查看、AI对话都在一个窗口内完成，省去来回切换应用的麻烦。VS Code的终端支持多标签，你甚至可以同时开一个终端跑项目、一个终端跑Claude Code。

如果你想要更沉浸式的体验，可以在VS Code里装一个支持对话AI的插件，但目前最稳定的方式还是终端。我自己长期的组合方式是：左侧是VS Code编辑器看代码，底部终端面板里跑Claude Code，需要修改文件时，Claude Code会直接落在磁盘上，回到编辑器里按 Ctrl+Z 或者用Git diff查看改动，整个工作流非常顺畅。

6. 常见问题与排查技巧实录

6.1 高频报错速查表

这一节我把自己踩过、也帮朋友排查过的常见报错整理成了一张速查表，碰到问题可以先对着表排查。

这里面最有意思的是 529 错误，这是Anthropic官方API的"服务器过载"标志。高峰期经常碰见，不是你配置的问题，纯属对方服务压力大。网上有不少人问"为什么我的Claude Code突然报529"，其实就是高峰期请求被限流了。等几分钟再次尝试，一般就能恢复。如果你频繁遇到529，反过来也说明该考虑切换到第三方兼容API了。

6.2 Windows 10特有坑点：执行策略与路径空格

在Windows 10上使用Claude Code，还有一些环境带来的坑值得单独说。

PowerShell执行策略是第一个常见的拦路虎。某些精简版系统或公司域控电脑，PowerShell默认执行策略是 Restricted，运行任何脚本都会被拦截。Claude Code安装脚本如果被拦截，你可能会看到类似"无法加载文件...因为在此系统上禁止运行脚本"的提示。解决办法是以管理员身份打开PowerShell，执行：

powershell复制Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

这条命令允许本地脚本运行，远程下载的脚本必须签名。对开发机来说，这是安全性和便利性比较平衡的策略。

第二个坑是路径空格。Windows的用户目录可能就是 C:\Users\张三，中间有中文或空格。某些底层依赖在解析这种路径时会出错。如果安装或运行Claude Code时遇到莫名奇妙的路径错误，可以先试试把项目放到一个纯英文路径下，比如 C:\dev\myproject，看问题是否消失。我遇到过几次，把项目从桌面挪到 D:\projects 后问题就没了。

第三个坑是杀毒软件或Windows Defender实时扫描。npm安装包时会生成大量小文件，实时扫描可能会导致安装速度奇慢或偶尔文件被隔离。如果安装过程中卡住，可以临时把项目目录加入Defender白名单，装完后再恢复。

6.3 模型不识别与工具调用异常：先分清是模型问题还是配置问题

最近社区里关于 "model not recognized" 的讨论特别多，很多人遇到这种情况的第一反应是重装Claude Code，但我建议先做两个诊断动作。

第一，看版本。这个报错最常见的原因是Claude Code版本太旧，不认最新发布的模型名。解决办法很简单，升级Claude Code版本即可。npm方式升级命令是：

powershell复制npm update -g @anthropic-ai/claude-code

升级完再看一眼 claude --version 确认是新版本。

第二，看模型名。如果你在环境变量里设置了 ANTHROPIC_MODEL，要确认这个名字在对应服务商那边真实存在。比如某个热词里的 deepseek-v4-pro，如果你用的是DeepSeek官方API，它可能不认识这个名字，你需要去他们平台的文档里查准确的模型标识符。同理，你设置成了OpenAI或Ollama本地模型名，也可能因为命名不一致导致Claude Code不认。

工具调用异常（比如Claude Code说"我不能执行这个操作"）则多半是模型能力问题。第三方兼容模型中，偏弱的模型在工具调用场景下确实表现不稳，会出现该调工具时不调、不该调时瞎调的情况。遇到这类问题，可以换能力更强的模型版本，或者降低任务复杂度，把一个大任务拆成多个小对话来执行。

最后再分享一个我的使用习惯。在Windows 10上跑Claude Code，我一般保持系统、Node.js、Claude Code三者的版本都处于较新状态，每过一两个月就统一升一次级。表面上看这增加了维护成本，但实际能避免大量"旧版本不支持新特性"的隐性坑。多数报错，要么是配置问题，要么是版本问题，把这两块管好了，你就已经超过80%的使用者了。