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 与虚拟机平台以管理员身份打开 PowerShellWin 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 2wsl --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 shelluname -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_NAMEUbuntu-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 LTSClaude 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 Codenpm 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/apiKey 去控制台生成。你可以临时 export也可以写进 shell 配置文件持久化。临时方式当前终端有效export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的Key claude持久化方式写进~/.bashrcecho export ANTHROPIC_BASE_URLhttps://taotoken.net/api ~/.bashrc echo export ANTHROPIC_AUTH_TOKENsk-你的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 和 JupyterLabsudo 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_URLhttps://taotoken.net/api末尾不要带斜杠reading choices相关报错返回体解析失败接口返回格式不匹配多为 Base URL 指向了非 Anthropic 兼容端点换成兼容 Anthropic 协议的地址确认服务支持/v1/messagesOAuth/ 登录跳转失败首次启动走 OAuth环境变量没生效走了默认登录确认 export 在当前 shell 生效或写进 settings.jsoncommand not found: claude装完找不到命令npm 全局 bin 不在 PATHnpm config get prefix看路径把它加进 PATHEACCES permission deniednpm 安装报错用了 sudo 或全局目录权限不对改用 nvm 或配用户级 npm prefix别 sudoWSL 2 requires an update启动 WSL 报错内核组件没装装wsl_update_x64.msi后wsl --set-default-version 2Platform 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 那条线更适合持续用只是偶尔验证模型效果用模型对话页面直接试就行。