1. 为什么 Windows 上装 Claude 工具链总卡在第一步如果你最近在 Windows 上折腾 Claude 相关工具大概率经历过这样的循环装完 Node.js 发现版本不对配好 Git 又卡在 PowerShell 执行策略好不容易把 CLI 装上一跑就报local proxy failed或者401。我前后在 Win10 和 Win11 两台机器上各走了一遍完整流程把能踩的坑基本踩全了这篇就把从零到能发出一条成功请求的路径完整记下来。先说清楚这套流程适合谁手上是 Windows 10/11想用 Claude Code 这类命令行工具做代码辅助或者想通过 API 方式接入 Claude 模型做对话和 Agent 任务的人。不需要你提前懂 Node.js但需要你能照着敲命令、看报错。整个过程分四块环境准备Node.js Git PowerShell、CLI 安装、API 接入配置、连通性验证。每一块我都会给出可复制的命令和配置片段以及我实际遇到的报错和对应处理方式。核心检索词先摆出来Claude 在 Windows 上的安装本质是「Node.js 运行时 Git 版本管理 PowerShell 终端 API 网关」四件套的协同。缺任何一环后面都会以各种奇怪的报错形式还回来。比如 Node.js 版本低于 18npm 装包时直接给你EBADENGINEPowerShell 执行策略是 Restricted任何.ps1脚本都跑不起来Git 没装某些 CLI 的依赖拉取会静默失败。这些我在下面都会逐个拆开。我试过最省事的路径其实是先把环境版本对齐再动 CLI 和 API顺序反了会浪费大量时间在排查上。下面按这个顺序来。2. 环境准备Node.js、Git、PowerShell 三件套的版本对齐2.1 Node.js 装哪个版本、怎么验证Claude 相关 CLI 工具目前普遍要求 Node.js 18 以上实测 20 LTS 最稳。去 Node.js 官网下载 Windows Installer.msi选 20.x LTS 版本。安装时注意勾选「Add to PATH」否则后面 PowerShell 里敲node会提示找不到命令。装完打开 PowerShell验证node -v npm -v正常输出类似v20.11.1 10.2.4如果node -v报「无法将 node 项识别为 cmdlet」说明 PATH 没生效。两个处理方式一是重开一个 PowerShell 窗口环境变量刷新需要新会话二是手动把 Node.js 安装目录加进系统 PATH。我遇到过装完立刻验证失败、重开窗口就好了的情况别急着重装。Node.js 版本过低会怎样如果你装的是 16.x后面npm install -g某个包时会出现npm ERR! code EBADENGINE npm ERR! engine Unsupported engine npm ERR! required: {node:18.0.0}看到EBADENGINE基本就是版本问题升级 Node.js 即可。2.2 Git 的安装与最小配置Git 在 Windows 上建议用官方 Installer安装过程中有一堆选项默认一路下一步问题不大但有两个地方注意一是「Adjusting your PATH environment」选「Git from the command line and also from 3rd-party software」这样 PowerShell 里能直接用git二是换行符处理选「Checkout as-is, commit Unix-style line endings」避免跨平台协作时的换行符噪音。装完验证git --version输出git version 2.44.0.windows.1之类即可。再配一下基础身份某些工具会读取git config --global user.name your-name git config --global user.email youexample.comGit 没装或没进 PATH 时部分 CLI 在拉取依赖或做版本检查时会报git: command not found或静默卡住。这个坑不明显但排查起来费时间建议一开始就装好。2.3 PowerShell 执行策略那个让脚本跑不起来的开关Windows 默认的 PowerShell 执行策略是Restricted意思是任何.ps1脚本都不让跑。很多安装脚本和 CLI 的初始化逻辑依赖 PowerShell 脚本所以这一步必须处理。先看当前策略Get-ExecutionPolicy如果输出Restricted改成RemoteSignedSet-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSignedRemoteSigned的含义是本地写的脚本可以直接跑从网络下载的脚本需要签名。对开发场景够用也比直接设Unrestricted安全。改完再Get-ExecutionPolicy确认输出RemoteSigned。这一步不做的话后面跑某些安装脚本会直接报无法加载文件 xxx.ps1因为在此系统上禁止运行脚本。看到这个报错回来改执行策略就行。三件套齐了之后建议再确认一下 npm 的全局安装目录在 PATH 里npm config get prefix输出的路径应该在你的系统 PATH 中。如果不是全局装的 CLI 命令会找不到。这个后面接入部分还会用到。3. 可复制配置CLI 安装与 API 接入的完整片段3.1 安装 Claude Code CLI环境就绪后用 npm 全局安装npm install -g anthropic-ai/claude-code装完验证claude --version能输出版本号就说明 CLI 本体装好了。如果报claude 不是内部或外部命令回到上一步检查npm config get prefix的路径是否在 PATH 里。3.2 API 接入配置Base URL Key Model ID 三件套CLI 装好只是壳真正让它能跑起来的是 API 接入配置。这里我用的是 TaoToken 的接入方式它提供兼容的 API 网关配置逻辑对 Claude Code 这类工具是通用的。先拿 Key访问 API Keys 页面创建密钥地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。创建后复制那串sk-开头的密钥只显示一次存好。然后配置环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个变量。在 PowerShell 里临时设置当前会话有效$env:ANTHROPIC_BASE_URL https://taotoken.net/api $env:ANTHROPIC_API_KEY sk-你的密钥如果要持久化写进用户环境变量[Environment]::SetEnvironmentVariable(ANTHROPIC_BASE_URL, https://taotoken.net/api, User) [Environment]::SetEnvironmentVariable(ANTHROPIC_API_KEY, sk-你的密钥, User)持久化后需要重开 PowerShell 才生效。如果你用的是带配置文件的方式比如某些工具读settings.json配置片段长这样{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }Model ID 这块要注意不同工具对模型名的写法要求不一样有的要完整 ID有的接受别名。如果跑起来报模型不存在先确认你填的 Model ID 在网关支持的列表里。TaoToken 的模型列表可以在模型对话页面查到https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。三件套对照表配置项作用示例值Base URLAPI 请求地址https://taotoken.net/apiAPI Key身份认证sk-xxxxxxxxModel ID指定模型claude-sonnet-4-20250514这三个缺一不可。只配了 Key 没配 Base URL请求会打到默认地址然后超时Base URL 配了但 Key 无效直接 401Model ID 写错报模型不存在或reading choices之类的解析错误。3.3 关于 OAuth 登录那条路很多人第一反应是走claude login的 OAuth 流程但在国内网络环境下这条路经常卡在跳转登录页那一步最后拿到一个oauth/authorize链接却打不开。如果你也卡在这里直接放弃 OAuth改用上面的 API Key 方式接入省时间。OAuth 那条路对网络环境要求高而 API Key 方式只要 Base URL 可达就能跑。4. 验证请求从发一条消息到确认链路通配置完别急着上复杂任务先用最小请求验证链路。最直接的方式是用 curl 打一个对话请求curl -X POST https://taotoken.net/api/v1/messages -H Content-Type: application/json -H x-api-key: sk-你的密钥 -H anthropic-version: 2023-06-01 -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: 说一句你好}] }正常返回是一段 JSON包含content数组和模型回复的文本。看到这个就说明 Base URL、Key、Model ID 三件套都对了。如果 curl 不方便也可以直接在 CLI 里跑一个简单任务claude 用一句话解释什么是递归CLI 会走你配置的环境变量把请求发到网关然后流式输出结果。第一次跑通看到文字一个个蹦出来的时候前面折腾环境的烦躁基本就消了。验证阶段我建议按这个顺序排查先确认$env:ANTHROPIC_BASE_URL和$env:ANTHROPIC_API_KEY在当前会话里确实有值echo $env:ANTHROPIC_BASE_URL再用 curl 打一次最后才用 CLI。这样出问题能快速定位是配置层还是工具层。成功的结果长这样curl 返回 200 加 JSON bodyCLI 能流式输出中文回复。如果 curl 通了但 CLI 不通问题在 CLI 的配置读取上如果 curl 就不通问题在环境变量或网络层。5. 本篇常见报错排查401、local proxy failed、reading choices这一节把我实际遇到和收集到的报错逐个拆开。401 Unauthorized最常见。原因通常是 Key 无效、Key 没带上、或者 Base URL 和 Key 不匹配比如 Key 是 A 平台的Base URL 填了 B 平台。排查echo $env:ANTHROPIC_API_KEY确认 Key 有值且没多余空格确认 Base URL 是https://taotoken.net/api而不是别的重新生成一个 Key 再试。注意 Key 只在创建时显示一次复制时别漏字符。local proxy failed / connection refused这个报错通常出现在你本地配了代理但代理没起来或者工具尝试走一个不存在的本地端口。处理方式是检查环境变量里有没有残留的HTTP_PROXY/HTTPS_PROXY指向本地端口有的话清掉Remove-Item Env:HTTP_PROXY -ErrorAction SilentlyContinue Remove-Item Env:HTTPS_PROXY -ErrorAction SilentlyContinue然后重开 PowerShell 再试。这个报错和网络环境有关但根因往往是本地代理配置残留不是网关的问题。reading choices / 解析响应失败这个报错说明请求发出去了、也收到了响应但响应格式不是工具预期的结构。常见原因是 Model ID 填错网关返回了一个错误 JSON工具尝试按正常响应解析就崩了。排查确认 Model ID 拼写正确用 curl 单独打一次看返回的原始 JSON 是什么如果是错误信息按错误提示改。OAuth 相关报错authorize 链接打不开、callback 失败前面说过直接放弃 OAuth 走 API Key。如果你已经卡在 OAuth 流程里清掉相关缓存再重新用 API Key 配置。EBADENGINENode.js 版本过低升级到 18 以上。无法加载 ps1 脚本PowerShell 执行策略问题回到 2.3 改RemoteSigned。claude 不是内部或外部命令npm 全局目录不在 PATH检查npm config get prefix。排查的核心思路是分层环境层Node/Git/PowerShell→ 安装层CLI 是否装上→ 配置层三件套是否正确→ 网络层Base URL 是否可达。从下往上逐层确认比盲目重装高效得多。6. 长期使用建议与接入入口跑通之后如果你打算长期用 Claude 做编码或 Agent 任务建议关注 Coding Plan 这类方案比按量计费更适合高频使用场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 里面有各工具的详细配置说明。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 可以看用量和余额。最后给一个实用技巧把环境变量写进 PowerShell 的 profile 文件这样每次开窗口自动加载不用重复设置。profile 路径用$PROFILE查看把$env:ANTHROPIC_BASE_URL和$env:ANTHROPIC_API_KEY两行加进去即可。但注意 Key 写在 profile 里是明文机器多人用的场景要谨慎。整套流程走下来最耗时的其实不是配置本身而是被各种报错带偏方向。记住分层排查的思路环境对了、三件套对了剩下的就是一条 curl 的事。