1. Windows 下 Claude Code 安装卡点复盘PowerShell 与 npm 环境检查很多人第一次在 Windows 上装 Claude Code卡住的地方往往不是命令本身而是 PowerShell 的执行策略、npm 全局路径、Node 版本这三件事。我试过在一台全新 Win11 机器上从零走一遍结果前 20 分钟全耗在环境上真正敲安装命令只花了 30 秒。所以这一节先把环境检查讲透后面配置 MCP 才不会莫名其妙报错。Claude Code 是什么简单说它是 Anthropic 推出的终端 AI 编程助手能在命令行里读你的项目、改代码、跑命令。适合谁适合习惯在终端里干活、又想让 AI 直接操作文件系统的开发者。它和 VS Code 插件配合时终端和编辑器共享同一份用户级配置这也是后面 MCP 配置能双端同步的原因。先确认 Node 和 npm 是否就位。打开 PowerShell普通权限即可安装全局包时再考虑管理员逐条执行node -v npm -v where.exe node where.exe npm正常应该看到类似v20.11.0和10.2.4的版本号。如果node能出版本但npm报「无法将 npm 项识别为 cmdlet」说明 npm 的全局路径没进 PATH。用where.exe npm看它到底在哪通常在C:\Program Files\nodejs\或用户目录下的AppData\Roaming\npm。把缺失的那条路径手动加进系统环境变量 PATH重启 PowerShell 再验证。接着检查 PowerShell 执行策略。默认的 Restricted 会拦住 npm 生成的.ps1脚本表现为安装到一半报「无法加载文件因为在此系统上禁止运行脚本」。查看当前策略Get-ExecutionPolicy -List如果 CurrentUser 是 Undefined 或 Restricted改成 RemoteSigned 就够了不需要动 MachinePolicySet-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned这一步只影响当前用户安全边界可控。改完再Get-ExecutionPolicy -Scope CurrentUser确认返回 RemoteSigned。还有一个容易被忽略的点npm 全局安装目录是否有写权限。如果你之前用管理员装过 Node普通用户跑npm install -g会报 EPERM。先看全局前缀npm config get prefix如果指向C:\Program Files\nodejs普通用户大概率写不进去。两个选择一是安装时用管理员 PowerShell二是把 prefix 改到用户目录比如npm config set prefix $env:APPDATA\npm然后把该目录加进 PATH。我个人倾向后者后续升级包不用每次提权。环境这三项过了再进入安装环节。命令本身很短npm install -g anthropic-ai/claude-code claude --versionclaude --version能打印版本号说明终端侧装好了。如果这一步报网络类错误先别急着怀疑配置多半是 npm registry 或网络链路问题可以临时切到国内镜像验证npm config get registry npm config set registry https://registry.npmmirror.com装完想切回官方源再npm config set registry https://registry.npmjs.org。registry 只是下载包的地址和后面模型调用是两回事别混为一谈。这一节的排查顺序建议固定下来Node/npm 是否存在 → PATH 是否完整 → 执行策略是否放行 → 全局目录是否可写 → registry 是否可达。五步走完90% 的「装不上」都能定位。下一节讲怎么把模型接入配好让claude真正能对话。2. TaoToken 前置配置Base URL、API Key 与 Model ID 三件套终端装好只是壳真正让它干活的是背后的模型接口。Claude Code 默认指向官方服务国内直连经常超时而且账号登录环节对国内用户不友好。更省事的做法是换成兼容 Anthropic 协议的接入方式把 Base URL、API Key、Model ID 这三件套配好终端和 VS Code 插件会自动读取同一份用户级配置。TaoToken 在这里扮演的是统一接入层它提供兼容的 API 端点你拿到一个 Key就能在 Claude Code、Cline、Codex 等多个工具里复用。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 。注意 API 地址不带查询参数配置里填的就是这个干净路径。先说清楚三件套各自填什么配置项作用填写位置Base URL请求发往哪个端点环境变量或 settings 文件API Key身份凭证环境变量别写进代码仓库Model ID调用哪个模型环境变量或配置字段Claude Code 读取配置有两种方式环境变量和用户目录下的 settings 文件。环境变量优先级高适合临时切换settings 文件适合长期固定。Windows 下设置用户级环境变量setx ANTHROPIC_BASE_URL https://taotoken.net/api setx ANTHROPIC_AUTH_TOKEN 你的APIKey setx ANTHROPIC_MODEL 你的ModelIDsetx写入的是持久变量但当前这个 PowerShell 会话不会立刻生效需要关掉重开。想在当前会话立即验证用$env:语法$env:ANTHROPIC_BASE_URL https://taotoken.net/api $env:ANTHROPIC_AUTH_TOKEN 你的APIKey $env:ANTHROPIC_MODEL 你的ModelID两种方式可以叠加先用$env:在当前窗口测试确认通了再用setx固化。这样调试时改起来快不用反复开关终端。如果你更习惯用配置文件Claude Code 的用户级 settings 在C:\Users\你的用户名\.claude\settings.json。注意是.claude目录下的settings.json不是根目录的.claude.json这两个文件容易搞混。写入如下 JSON{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的APIKey, ANTHROPIC_MODEL: 你的ModelID } }保存后重启终端。VS Code 里的 Claude Code 插件会读取同一份用户级配置所以不需要在插件里重复填一遍。这一点很关键很多人以为插件要单独配结果两边不一致排查半天。关于 Model ID填什么取决于你在 TaoToken 控制台里开通了哪些模型。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsole_configutm_campaignrewrite 在模型列表里能看到可用的 ID。Key 的创建在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapikeys_configutm_campaignrewrite 新建后复制一次页面刷新就不再显示完整 Key记得当场存好。安全提醒API Key 等同于账号凭证不要提交到 Git不要贴在公开 issue 里。如果不小心泄露立刻去控制台吊销重建。环境变量方式比写死在代码里安全因为不会随仓库分发。配完这三件套先别急着上 MCP。用一条最小请求验证模型通道是否打通确认没问题再叠加更复杂的配置这样出问题时排查范围小。下一节给出可直接复制的完整配置片段和验证命令。3. 可复制配置settings.json 与 MCP 接入片段这一节把配置落到文件层面给出可以直接复制的片段。核心原则是模型接入走 settings.jsonMCP 服务器走claude mcp add命令或对应的配置文件两者互不干扰。先确认 settings 文件路径。在 PowerShell 里执行echo $env:USERPROFILE假设输出C:\Users\tao那么 settings 文件就是C:\Users\tao\.claude\settings.json。如果.claude目录不存在手动建一个New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.claude然后用记事本或 VS Code 打开 settings.json写入完整配置{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-替换成你的Key, ANTHROPIC_MODEL: 替换成你的ModelID }, permissions: { allow: [], deny: [] } }permissions字段可以先留空后续按需加白名单。JSON 对格式敏感末尾不能有多余逗号引号必须是英文半角。写完用 PowerShell 校验一下语法Get-Content $env:USERPROFILE\.claude\settings.json -Raw | ConvertFrom-Json没报错就说明 JSON 合法。这一步能提前拦住「配置写了但不生效」里最常见的一类问题——格式错误导致整个文件被忽略。接下来配 MCP。MCP 是 Model Context Protocol让 AI 能调用外部工具和数据源。以 Context7 为例它能拉取框架的最新官方文档减少生成过时 API 的概率。用命令行添加claude mcp add -s user context7 npx upstash/context7-mcp-s user表示写入用户级配置终端和 VS Code 插件共享。执行成功会提示Added stdio MCP server context7。查看已注册的 MCP 列表claude mcp list如果命令报claude不是可识别命令说明全局安装的 bin 目录没进 PATH回到第一节检查npm config get prefix并把该目录加进 PATH。MCP 的配置最终也会落到用户级文件里。Windows 下通常在C:\Users\你的用户名\.claude.json或.claude目录下的相关配置中。用记事本打开可以看到类似结构{ mcpServers: { context7: { command: npx, args: [upstash/context7-mcp] } } }如果你更想手动编辑而不是用命令可以照着这个结构加。但手动改完要确保 JSON 合法否则整个 MCP 列表都会加载失败。我建议优先用claude mcp add它帮你处理了转义和路径问题。对于 Cline 这类 VS Code 插件MCP 配置走的是插件自己的 settings。以 Cline 为例在 VS Code 设置里搜索 Cline MCP或直接编辑其配置文件填入{ mcpServers: { context7: { command: npx, args: [upstash/context7-mcp], disabled: false } } }注意 Cline 的配置结构和 Claude Code 不完全一样别直接复制粘贴。关键是command和args两个字段要对。如果你用 Codex它的凭证文件在C:\Users\你的用户名\.codex\auth.json结构大致是{ OPENAI_API_KEY: 你的Key, base_url: https://taotoken.net/api }Codex 的字段名和 Claude Code 不同别混用。三件套在 Codex 里对应的是OPENAI_API_KEY、base_url和模型参数。配置写完统一重启终端和 VS Code。重启这个动作不能省因为环境变量和配置文件都是启动时读取的。下一节给出逐项验证的操作步骤确认每一层都真的生效了。4. 逐项验证从 claude --version 到 MCP 请求成功配置写完不代表生效得一层层验证。这一节按从底到顶的顺序给出验证命令和预期结果任何一层不过就停在那里排查别往下走。第一层终端命令是否可用claude --version预期输出类似1.0.x的版本号。报「无法识别」就回第一节查 PATH。第二层环境变量是否被读取。在 PowerShell 里打印echo $env:ANTHROPIC_BASE_URL echo $env:ANTHROPIC_MODEL如果为空说明setx后没重开终端或者 settings.json 没被加载。注意ANTHROPIC_AUTH_TOKEN不要直接 echo 到屏幕避免泄露可以只确认长度$env:ANTHROPIC_AUTH_TOKEN.Length返回一个大于 0 的数字即可。第三层模型通道是否打通。用一条最小对话请求验证claude -p 回复两个字通了-p是 print 模式发一次请求就退出适合脚本化验证。预期返回「通了」或类似简短回复。如果报 401说明 Key 无效或没被读到如果报连接超时检查 Base URL 是否写成了带路径的完整地址如果报 model not found说明 Model ID 填错了去控制台核对。第四层MCP 是否注册成功claude mcp list预期看到context7在列表里状态正常。如果列表为空说明claude mcp add没写进用户级配置检查是否漏了-s user。第五层MCP 是否真的能被调用。在交互模式里问一个需要查文档的问题claude进入交互后输入「用 Context7 查一下 Vue 3 最新的组合式 API 写法」。如果 MCP 生效它会去拉取文档再回答。这一步能验证 MCP 服务器进程是否真的能启动。npx upstash/context7-mcp首次运行会下载包网络慢的话会卡一会儿耐心等或先手动跑一次npx upstash/context7-mcp --help预热。第六层VS Code 插件是否同步。打开 VS Code确认 Claude Code 插件已安装并启用。在插件面板里看它是否读取到了用户级配置。最直接的验证是在 VS Code 里发起一次对话问同样的问题看返回是否和终端一致。如果终端通、插件不通多半是插件版本旧或没重启更新插件并重启 VS Code。验证过程中建议开一个单独的 PowerShell 窗口专门看日志。Claude Code 的详细日志可以通过环境变量打开$env:ANTHROPIC_LOG debug claude -p testdebug 日志会打印请求地址、模型名、响应状态排查 401 和超时特别有用。验证完记得关掉不然日志量很大。六层全过说明从安装到 MCP 的链路完整可用。任何一层失败先解决那一层不要跳步。下一节汇总常见报错和对应处理。5. 常见报错排查401、local proxy failed 与 reading choices这一节按报错原文归类给出定位思路。报错信息是排查的起点别只看「失败了」三个字把完整错误贴出来对照。401 Unauthorized。这是最常见的。含义是凭证没被接受。可能原因有三个Key 拼写错误、Key 已失效、Key 没被正确读取。先在 PowerShell 里确认环境变量存在echo $env:ANTHROPIC_AUTH_TOKEN.Length如果长度是 0说明没读到。检查是不是写进了 settings.json 但 JSON 格式错误导致整个文件被忽略。用ConvertFrom-Json校验。如果长度正常但仍 401去控制台确认 Key 状态必要时重建。注意 Key 只在创建时显示一次复制时别多带空格或换行。local proxy failed。这个报错通常出现在有本地网络工具介入时。含义是请求发不到目标端点。先确认 Base URL 是否写对echo $env:ANTHROPIC_BASE_URL应该是https://taotoken.net/api不要带尾部斜杠不要带多余路径。如果 URL 对但仍失败检查是否有其他工具占用了系统网络设置。临时清空相关环境变量再试Remove-Item Env:HTTP_PROXY -ErrorAction SilentlyContinue Remove-Item Env:HTTPS_PROXY -ErrorAction SilentlyContinue然后重新发请求。如果清空后通了说明是网络工具配置冲突需要调整工具规则而不是改 Claude Code 配置。reading choices 相关报错。这类错误通常表现为解析响应失败比如Cannot read properties of undefined (reading choices)。含义是返回的数据结构不符合预期。常见原因是 Base URL 指向了不兼容的端点或者 Model ID 填了一个该端点不支持的模型。先确认 Base URL 是兼容 Anthropic 协议的地址再核对 Model ID 是否在控制台的可用列表里。如果用的是 OpenAI 兼容端点却填了 Anthropic 专用字段也会出这个错。OAuth 相关报错。如果看到 OAuth 或登录跳转失败说明 Claude Code 在尝试走官方账号登录流程。国内环境下这个流程经常走不通。解决办法是确保ANTHROPIC_AUTH_TOKEN已设置让它走 Key 认证而不是 OAuth。检查环境变量优先级环境变量高于配置文件如果两处都配了且不一致以环境变量为准。MCP 服务器启动失败。报错通常是MCP server context7 failed to start。先手动跑一次命令看真实错误npx upstash/context7-mcp --help如果这一步就报错说明是 npx 或包本身的问题和 Claude Code 无关。常见原因是 npx 缓存损坏清一下npm cache clean --force再重试。如果--help正常但 Claude Code 里启动失败检查claude mcp list里的配置是否和手动命令一致。VS Code 插件看不到配置。终端通了但插件不通先确认插件版本。旧版插件可能不读取用户级 settings。更新到最新版然后完全退出 VS Code 再打开不是关窗口而是从任务栏退出进程。如果还不行在 VS Code 的输出面板里选 Claude Code 频道看日志通常会提示它读了哪个配置文件。排查时有个通用技巧把问题范围缩小到单层。先确认终端能通再确认 MCP 能列出来再确认插件能读配置。每层单独验证不要同时改多个地方否则不知道是哪个改动生效了。6. 长期使用建议与接入入口配置跑通之后日常使用还有几个习惯能省事。第一把常用的 MCP 服务器固定下来别频繁增删每次改动都重启验证。第二API Key 定期轮换尤其是多人共用一台机器时。第三settings.json 纳入个人 dotfiles 管理换机器时直接同步但 Key 用环境变量注入不要把明文写进仓库。如果你主要在终端里做长期编码任务或者想让 AI 跑多步 Agent 流程可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcodingplan_ctautm_campaignrewrite 。它适合需要稳定调用、按周期使用的场景。想先快速试一下模型对话效果不装任何工具可以直接用网页版https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchat_ctautm_campaignrewrite 。在浏览器里发一条消息确认 Key 和模型可用再回到终端配置能少走弯路。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc_ctautm_campaignrewrite 里面有各工具的完整配置示例包括 Claude Code、Cline、Codex 的字段对照。遇到字段名不确定时以文档为准别靠猜。Key 管理入口再放一次https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapikeys_ctautm_campaignrewrite 。创建、吊销、查看用量都在这里。控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsole_ctautm_campaignrewrite 能看到模型列表和调用统计Model ID 以控制台显示的为准。最后提醒一个实操细节每次改完配置用claude -p test发一条最小请求确认通道还在再开始正式干活。这个习惯能让你在配置漂移时第一时间发现而不是写到一半才报错。