1. Windows 原生跑 Claude Code 到底卡在哪
Claude Code 是 Anthropic 推出的终端代理式编程工具，简单说就是你把需求用自然语言丢给它，它自己读文件、改代码、跑命令，像一个坐在你终端里的结对程序员。它最适合谁？适合已经在用 VS Code、习惯命令行、想让 AI 直接动项目文件而不是只聊天的开发者。问题在于，它官方只发 macOS 和 Linux 版本，Windows 用户双击安装包这条路根本走不通。
我一开始也以为装个 Node.js 就完事，结果npm install -g @anthropic-ai/claude-code在 PowerShell 里能装上，一运行claude就报平台不支持。原因不复杂：Claude Code 内部依赖一堆 Unix 风格的进程管理和路径处理，Windows 的 cmd/PowerShell 语义对不上。所以 Windows 用户真正要解决的不是"怎么装"，而是"怎么在 Windows 上造一个它认的 Linux 环境"。
这就是 WSL 出场的地方。WSL 全称 Windows Subsystem for Linux，是微软官方功能，让你在 Windows 里直接跑一个真 Linux 内核，不用开虚拟机、不用双系统。它和虚拟机的区别是：虚拟机是整台假电脑，WSL 是 Windows 和 Linux 共享内核的轻量层，启动快、占内存小、文件互通。对 Claude Code 来说，WSL 里的 Ubuntu 就是一个标准 Linux 环境，它检测平台时完全认。
整条路径我拆成四段：WSL 装好并迁到 D 盘省 C 盘空间、WSL 里装 Node.js 和 Claude Code、配置认证信息跑通第一个项目、用 JupyterLab 补上代码树视图。每一步我都会给可复制的命令和配置，最后附一张报错对照表。你跟着做，能在自己机器上复现每一步的验证结果。
需要提前说清楚一点：Claude Code 本身要连 Anthropic 的模型服务，直连对国内用户不友好，所以本文用 TaoToken 这类兼容 Anthropic 接口的服务来做接入层，把 Base URL 和 Key 换成可用的地址即可。下面所有配置里的地址都以 TaoToken 为例，你照着替换就能跑。
2. WSL 环境准备与 D 盘迁移避坑指南
这一节解决"环境从零到能用"。如果你机器上已经有 WSL 和 Ubuntu，可以跳到 2.3 直接看迁移。先说清楚为什么建议迁到 D 盘：WSL 默认把整个 Linux 文件系统塞在 C 盘用户目录下，一个 Ubuntu 实例加上后面装的 Node、Python、Jupyter，轻松吃掉十几个 G。C 盘红了之后 Windows 更新都费劲，所以迁盘不是可选项，是必做项。
2.1 启用 WSL 与虚拟机平台
以管理员身份打开 PowerShell（Win + X 选"终端(管理员)"或"Windows PowerShell(管理员)"），依次执行两条启用命令：
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart两条都返回"操作成功完成"后重启电脑。重启后在管理员 PowerShell 里把默认版本设为 WSL 2：
wsl --set-default-version 2WSL 2 用真正的 Linux 内核，性能比 WSL 1 高一个量级，Claude Code 这种要频繁读写文件的工具必须用 2。如果提示需要更新内核，去微软官方文档下载wsl_update_x64.msi装上再执行上面这条。
2.2 安装 Ubuntu 发行版
打开 Microsoft Store 搜 Ubuntu，选 22.04 LTS 或 24.04 LTS 都行，点安装。装完从开始菜单启动一次，首次会要求设用户名和密码，这个用户名后面wsl -l -v会用到，记牢。设完你就进了一个真 Linux shell，uname -a能看到 Linux 内核版本。
2.3 导出、注销、导入到 D 盘
先在 D 盘建好目录结构，用文件资源管理器建或者 PowerShell 建都行：
mkdir D:\WSL\images mkdir D:\WSL\instances然后确认发行版确切名称：
wsl -l -v输出里 NAME 列就是名字，比如Ubuntu-22.04。接着导出成 tar 包：
wsl --export Ubuntu-22.04 D:\WSL\images\ubuntu.tar导出可能要几分钟，完成后D:\WSL\images\ubuntu.tar就是整个系统的备份。确认文件存在且大小正常后，注销 C 盘上的原实例：
wsl --unregister Ubuntu-22.04这一步会删掉 C 盘上的原实例，所以务必先确认导出成功。注销后再wsl -l -v会发现列表里没它了，C 盘空间也回来了。最后从 tar 包导入到 D 盘：
wsl --import Ubuntu-22.04 D:\WSL\instances\Ubuntu D:\WSL\images\ubuntu.tar导入完成后wsl -l -v里 Ubuntu 又回来了，但它的虚拟硬盘ext4.vhdx现在位于D:\WSL\instances\Ubuntu。你可以去那个目录确认文件确实在 D 盘。注意导入后的实例默认以 root 登录，想恢复原来的普通用户，可以在实例里执行ubuntu config --default-user 你的用户名，或者直接在/etc/wsl.conf里配[user] default=你的用户名。
2.4 一键启动脚本
每次开 PowerShell 敲wsl -d Ubuntu-22.04太烦，写个 bat 双击启动。新建toggle-wsl.bat，内容如下：
@echo off title WSL Toggle for Ubuntu-22.04 set DISTRO_NAME=Ubuntu-22.04 echo Checking status of %DISTRO_NAME%... wsl -l -v | findstr "%DISTRO_NAME%" | findstr "Running" > nul if %errorlevel% == 0 ( echo %DISTRO_NAME% is running. Shutting down... wsl --terminate %DISTRO_NAME% ) else ( echo %DISTRO_NAME% is stopped. Starting... start wsl.exe -d %DISTRO_NAME% ) echo Operation complete. pause双击它，如果 WSL 没跑就新开一个窗口进去，如果已经在跑就关掉，省得你手动敲命令。这个脚本我放在 D 盘根目录，用起来很顺手。
3. Node.js 与 Claude Code 安装配置全流程
环境有了，接下来在 WSL 里装运行时和 Claude Code 本体。这一节的所有命令都在 Ubuntu 终端里执行，不是 PowerShell。
3.1 安装 Node.js LTS
Claude Code 是 npm 包，需要 Node.js 18 以上。用 NodeSource 的源装 LTS 版本最省事：
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo bash - sudo apt-get install -y nodejs node --version npm --versionnode --version输出v20.x或更高就对了。如果卡在下载，换清华镜像源重试。
3.2 安装 Claude Code
npm install -g @anthropic-ai/claude-code claude --version能打印出版本号说明装好了。如果报权限错误，别用sudo npm install -g，那会把包装到 root 目录导致后面找不到，正确做法是配 npm 全局目录到用户目录，或者用 nvm 管理 Node。
3.3 配置认证：Base URL + Key + Model ID 三件套
Claude Code 通过环境变量读认证信息。核心是三个：ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、以及模型 ID。用 TaoToken 的话，Base URL 填https://taotoken.net/api，Key 去控制台生成。你可以临时 export，也可以写进 shell 配置文件持久化。
临时方式（当前终端有效）：
export ANTHROPIC_BASE_URL=https://taotoken.net/api export ANTHROPIC_AUTH_TOKEN=sk-你的Key claude持久化方式，写进~/.bashrc：
echo 'export ANTHROPIC_BASE_URL=https://taotoken.net/api' >> ~/.bashrc echo 'export ANTHROPIC_AUTH_TOKEN=sk-你的Key' >> ~/.bashrc source ~/.bashrc如果你更习惯用配置文件而不是环境变量，Claude Code 支持~/.claude/settings.json，可以写成这样：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }这个文件路径是~/.claude/settings.json，注意~在 WSL 里是/home/你的用户名。三件套里 Base URL 决定请求打到哪，Key 决定身份，Model ID 决定用哪个模型，缺一个都会报错。Model ID 具体填什么以你所用服务的模型列表为准，TaoToken 控制台里能看到可用模型名。
3.4 首次启动的交互流程
第一次运行claude会走几个引导：选主题（随便选，后面能改）、确认安全须知、选默认 Terminal 配置、信任当前工作目录。全部回车确认即可。进入交互界面后，你就能用自然语言让它读代码、改文件、跑测试了。
4. 验证请求与 JupyterLab 代码树实战
配置完不验证等于没配。这一节先给最小验证命令，再把 JupyterLab 接上，解决终端里看不到项目树的问题。
4.1 最小验证：确认请求真的通了
在任意目录执行：
claude -p "用一句话说明当前目录下有哪些文件"-p是单次执行模式，不进入交互界面，直接打印结果。如果返回了文件列表描述，说明 Base URL、Key、模型三件套全部生效。如果报 401，说明 Key 不对；如果报连接失败，说明 Base URL 写错或网络不通。这一步过了，后面才有意义。
4.2 装 JupyterLab 补上代码树视图
Claude Code 是纯终端工具，看整个项目结构不如 VS Code 直观。用 JupyterLab 可以变相解决：它左侧有文件树，右侧能开终端跑 Claude Code，等于把两者拼在一起。
先装 pip 和 JupyterLab：
sudo apt install python3-pip -y pip install jupyterlab -i https://pypi.tuna.tsinghua.edu.cn/simple/进到你的项目目录，比如项目在 Windows 的F:\work\code\AIcode\zhongyao_mcp_gradio，在 WSL 里对应路径是/mnt/f/work/code/AIcode/zhongyao_mcp_gradio。cd 进去后启动：
jupyter lab --allow-root --no-browser --port 8888浏览器打开http://localhost:8888，左侧就是树状文件结构，和 VS Code 的资源管理器很像。在 JupyterLab 里新建一个 Terminal，在里面 export 那两个环境变量再跑claude，你就能一边看代码树一边让 Claude Code 分析项目。
4.3 实测：让 Claude Code 分析一个真实项目
我在 JupyterLab 的终端里对那个 gradio 项目执行：
claude -p "分析这个项目的主要功能、入口文件和依赖，用中文分点说明"它会自己列目录、读关键文件、给出结论，全程不需要我手动指定读哪个文件。实测下来它对 Python 项目的结构理解挺准，能指出入口脚本和核心模块。你也可以进交互模式，让它改某个函数再跑测试，验证它真的能操作文件。
5. 常见报错对照与排查手册
这一节把踩过的坑列成表，你遇到报错直接对号入座。所有报错都来自真实终端输出。
| 报错关键字 | 触发场景 | 原因 | 解决 |
|---|---|---|---|
401 Unauthorized | 执行 claude 后请求被拒 | Key 错误或过期 | 重新生成 Key，确认ANTHROPIC_AUTH_TOKEN无多余空格 |
local proxy failed/ 连接超时 | 请求发不出去 | Base URL 写错或网络不通 | 确认ANTHROPIC_BASE_URL=https://taotoken.net/api，末尾不要带斜杠 |
reading 'choices'相关报错 | 返回体解析失败 | 接口返回格式不匹配，多为 Base URL 指向了非 Anthropic 兼容端点 | 换成兼容 Anthropic 协议的地址，确认服务支持/v1/messages |
OAuth/ 登录跳转失败 | 首次启动走 OAuth | 环境变量没生效，走了默认登录 | 确认 export 在当前 shell 生效，或写进 settings.json |
command not found: claude | 装完找不到命令 | npm 全局 bin 不在 PATH | npm config get prefix看路径，把它加进 PATH |
EACCES permission denied | npm 安装报错 | 用了 sudo 或全局目录权限不对 | 改用 nvm 或配用户级 npm prefix，别 sudo |
WSL 2 requires an update | 启动 WSL 报错 | 内核组件没装 | 装wsl_update_x64.msi后wsl --set-default-version 2 |
Platform not supported | 在 PowerShell 直接跑 claude | 没进 WSL | 必须在 WSL 的 Ubuntu 终端里运行 |
重点说两个高频的。第一个是 401，九成是 Key 复制时带了换行或空格，用echo $ANTHROPIC_AUTH_TOKEN检查一下。第二个是reading 'choices'，这个报错通常意味着请求打到了一个返回 OpenAI 格式的端点，而 Claude Code 期望 Anthropic 的/v1/messages格式，所以 Base URL 一定要用兼容 Anthropic 协议的地址。
如果你用 CC Switch 或 Cline 这类工具管理多套配置，记住三件套必须成对出现：Base URL、Key、Model ID 一个都不能少，只填两个照样报错。Codex 的auth.json和 Claude Code 的settings.json是两套东西，别混用。
6. 把 Claude Code 接进日常开发流
跑通之后，我把它固定成了几个用法。一是claude -p做单次任务，比如"把这个目录下所有 print 改成 logging"，不进交互直接出结果，适合脚本化。二是进交互模式做多轮重构，它会记住上下文，改完一个文件接着改下一个。三是配合 JupyterLab，左边看树右边跑命令，分析陌生项目特别快。
Key 和 Base URL 建议写进~/.claude/settings.json而不是每次 export，这样换终端也不用重配。模型 ID 按需切换，写复杂逻辑用强模型，改格式用快模型，成本能压下来。WSL 实例记得定期wsl --export备份一次，迁盘或重装都不慌。
如果你还没生成 Key，去 TaoToken 控制台建一个，然后照着第 3 节的 settings.json 填进去就能跑。接入文档里有各语言的调用示例，遇到协议细节可以对照。想让 Claude Code 长期挂在项目里做 Agent 式开发，Coding Plan 那条线更适合持续用；只是偶尔验证模型效果，用模型对话页面直接试就行。
