1. Windows 下 Claude Code 终端安装到底卡在哪

Claude Code 是 Anthropic 推出的终端 AI 编码助手，能在 PowerShell 里直接读写项目文件、跑命令、改代码。它适合习惯命令行、想让 AI 直接操作本地仓库的开发者。但 Windows 用户第一次装它，十有八九会撞上三类问题：安装脚本跑完却提示claude不是内部或外部命令、PowerShell 报执行策略禁止运行脚本、以及装好了却连不上 API 一直转圈。

我实测下来，这些报错基本都指向同一个根因——环境变量没写对，或者 API 通道没配通。前者是 PATH 没生效，后者是没把请求指向一个稳定的接入地址。这篇就按「装二进制 → 配 PATH → 写 settings.json → 验证连通」的完整链路走一遍，每一步都给可复制的命令和配置片段，最后再集中排一遍最常见的坑。

需要先说明一点：Claude Code 本身是个客户端，它需要一个能响应 Anthropic 接口格式的服务端。官方账号是一种选择，但很多人更希望用一个统一的 Key 来管理调用、方便切换模型和查看用量。下面配置里我会用 TaoToken 作为统一接入层来演示，它的接口地址是https://taotoken.net/api，兼容 Anthropic 的消息格式，配置方式和官方一致，只是把 base_url 和 key 换掉即可。

2. 装之前先把 TaoToken 的 Key 和地址准备好

在动 PowerShell 之前，先把接入信息拿到手，不然后面 settings.json 没法填。打开浏览器进 TaoToken 官网，注册登录后进控制台，在 API Keys 页面创建一个新 Key。这个 Key 就是后面所有请求的凭证，格式通常是一串以sk-开头的字符串，创建后只显示一次，记得先复制存好。

创建 Key 的入口在控制台的 API Keys 页，模型对话入口可以用来先在网页上试一下通道是否正常，确认能出结果再去配终端，能省掉不少「到底是网络问题还是配置问题」的纠结。

拿到两样东西就够了：一个是 API Key，一个是接口基地址https://taotoken.net/api。注意这个地址不带任何查询参数，settings.json 里填的就是它。如果你后面想换模型或者看用量，回控制台操作即可，终端这边不用改。

提示：Key 属于敏感凭证，别直接提交到 Git 仓库。settings.json 如果放在项目目录里，记得加进 .gitignore。

3. 安装 Claude Code 并处理 PowerShell 执行策略

Claude Code 在 Windows 上推荐用原生安装脚本，它会拉取二进制并放到用户目录下。先确认系统是 Windows 10 1809 及以上，然后打开 PowerShell。第一步不是直接跑安装命令，而是先看执行策略，因为默认策略可能禁止运行远程脚本。

在 PowerShell 里执行：

Get-ExecutionPolicy

如果返回Restricted，安装脚本会被拦。把它改成当前用户级别的 RemoteSigned，这个改动不需要管理员权限，也只影响你自己：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

改完再确认一次，返回RemoteSigned就对了。接着跑官方安装脚本：

irm https://claude.ai/install.ps1 | iex

脚本会下载二进制并解压到类似C:\Users\你的用户名\.local\bin的目录。跑完如果看到Claude Code successfully installed!，说明文件已经落地。但这时候别急着敲claude，因为那个目录大概率还没进 PATH，直接敲会报「无法将 claude 项识别为 cmdlet」。

安装脚本有时会贴心地打印一段黄色提示，告诉你某个路径不在 PATH 里，让你手动加。这段提示别忽略，它就是下一步要解决的问题。

4. 把安装目录写进 PATH 环境变量

PATH 的作用是让系统在终端里输入claude时，知道去哪些目录找这个可执行文件。没配 PATH，你就只能每次输入完整绝对路径，非常麻烦。配置方式有两种，图形界面和命令行，我建议先用命令行快速搞定，出问题再用图形界面核对。

先确认二进制到底在哪。安装脚本一般会放在用户目录下的.local\bin，用这条命令查：

Get-ChildItem "$env:USERPROFILE\.local\bin" | Select-Object Name

看到claude.exe或类似文件，说明路径就是$env:USERPROFILE\.local\bin。把它追加到当前用户的 PATH（用户变量，不需要管理员权限）：

$claudePath = "$env:USERPROFILE\.local\bin" [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$claudePath", "User")

这条命令只改用户变量，不动系统变量，安全且可逆。执行完当前窗口不会立刻生效，必须关掉 PowerShell 重新开一个。重开后验证：

claude --help

能打印出帮助信息就说明 PATH 通了。如果还是找不到，用图形界面核对一遍：按 Win 键搜「环境变量」，进「编辑系统环境变量」→「环境变量」，在上方用户变量里选中 Path，点编辑，确认C:\Users\你的用户名\.local\bin这一行在列表里。缺了就新建一行补上，一路确定。

注意：用户变量只对当前登录账户生效，系统变量对所有用户生效但需要管理员权限。个人开发机改用户变量就够了，别去动系统变量，避免影响其他软件。

5. 写 settings.json 把请求指向统一接入地址

PATH 通了只是能启动，真正让它干活还得配 API 通道。Claude Code 读取配置的位置在用户目录下的.claude文件夹，主配置文件是settings.json。如果目录不存在先建：

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude"

然后创建或编辑settings.json，填入下面这段骨架。核心是把 base_url 指向 TaoToken 的接口地址，并用环境变量引用 Key，避免明文写死在文件里：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }

三个字段的作用分别是：ANTHROPIC_BASE_URL决定请求发往哪里，这里填 TaoToken 的接口地址；ANTHROPIC_AUTH_TOKEN是鉴权凭证，把sk-你的Key换成第 2 步创建的那串；ANTHROPIC_MODEL指定默认模型，按你账号里可用的模型名填。

如果你不想把 Key 明文写在 json 里，可以改成从系统环境变量读取。先在 PowerShell 里设一个用户级环境变量：

[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-你的Key", "User")

然后 settings.json 里把ANTHROPIC_AUTH_TOKEN那行删掉，Claude Code 会自动从环境变量取。这样配置文件可以放心提交或分享，Key 留在系统里。改完记得重开终端让环境变量生效。

6. 验证 API 通道是否真的连通

配置写完，最怕的是「看起来都对但就是不通」。别急着开项目，先用一个最小请求验证通道。重开 PowerShell，进任意一个空目录，直接启动：

claude

首次启动它会读 settings.json，如果配置正确，会进入交互界面。随便问一句让它读当前目录，比如输入「列出当前目录的文件」，如果它能返回结果，说明从终端到 TaoToken 再到模型的整条链路是通的。

想更直接地验证接口，可以用 curl 打一发消息请求，绕开客户端看服务端返回：

curl.exe https://taotoken.net/api/v1/messages ` -H "x-api-key: sk-你的Key" ` -H "anthropic-version: 2023-06-01" ` -H "content-type: application/json" ` -d '{\"model\":\"claude-sonnet-4-20250514\",\"max_tokens\":64,\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}'

返回里带content字段和一段文本，就证明 Key 和地址都没问题。如果返回 401，是 Key 错了或没生效；返回 404，多半是 base_url 写错，检查有没有多写或少写/api；返回超时，则是网络层的问题，往下看排错部分。

7. 本篇常见报错逐个排查

报错一：claude : 无法将“claude”项识别为 cmdlet这是 PATH 没生效。先确认二进制目录存在，再确认 PATH 里有这一行，最后务必重开终端。三个条件缺一不可，尤其是重开这一步，很多人改完就在原窗口试，永远不生效。

报错二：无法加载文件，因为在此系统上禁止运行脚本执行策略拦的。回到第 3 步，用Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned改掉，别用管理员全局改，没必要。

报错三：启动后一直转圈或提示连接失败先确认 settings.json 里的ANTHROPIC_BASE_URL是https://taotoken.net/api，没有多余斜杠或路径。再用第 6 步的 curl 单独测接口，把客户端和服务端问题分开定位。如果 curl 通而客户端不通，多半是 settings.json 格式错了，用 JSON 校验工具过一遍，注意别多逗号。

报错四：返回 401 未授权Key 错了、过期了，或者环境变量没生效。去控制台重新生成一个 Key，确认复制时没带空格。如果用环境变量方式，重开终端再试。

报错五：模型名报错model not foundANTHROPIC_MODEL填的模型名在你账号下不可用。回控制台看可用模型列表，换成存在的那个。模型名区分大小写和版本号，别凭记忆手敲。

报错六：改了 settings.json 但行为没变Claude Code 启动时读配置，改完要退出重进。另外确认改的是用户目录下的.claude\settings.json，不是项目里的其他同名文件，项目级配置会覆盖用户级。

8. 配好之后怎么继续往下走

到这一步，终端能启动、接口能通、模型能回话，基础链路就算跑通了。接下来按你的使用场景分流：如果只是想验证模型对话效果，直接进模型对话页面在网页上试更省事；如果打算长期用 Claude Code 写代码、跑 Agent 任务，建议去了解一下 Coding Plan，它针对高频编码场景做了额度优化，比按次调用更划算；如果还要接其他工具或自己写脚本调接口，去 API Keys 页面管理 Key，接入文档里有各语言的调用示例。

配置这件事，一次配好后面就省心了。真正容易反复踩的其实就两个点：PATH 改完没重开终端，以及 base_url 多写或少写了路径。把这两条记住，剩下的报错基本都能自己定位。