Windows Claude Code 配置 API Key：安装、验证与错误排查
简答：Windows 配置 Claude Code API Key，最短流程是：安装 Claude Code，选择 PowerShell 或 CMD 设置 ANTHROPIC_API_KEY，重新打开终端后运行 claude，再用 /status 检查认证方式。若接入兼容网关，再按接口方要求配置 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL；不要把真实密钥写进项目或提交到 Git。
定义：Windows Claude Code 配置 API Key，是通过环境变量或用户级 settings.json 为 Claude Code 提供认证信息，并在启动后确认实际使用的认证方式。
先照做：Windows 安装与 API Key 配置对照表
本文是第三方 AI API 接入指南，不是 Claude Code 官方页面。Claude Code 官方文档列出的 Windows 支持范围包括 Windows 10 1809 及以上版本，原生 Windows 可使用 PowerShell 或 CMD；WSL 则使用 Linux shell。官方安装说明还提醒，不同终端要使用对应命令，否则会出现命令解析错误。
| 使用场景 | 认证变量 | 是否需要 Base URL | 建议配置方式 |
|---|---|---|---|
| 官方 Anthropic API | ANTHROPIC_API_KEY | 通常不需要自行修改 | 先用当前终端临时配置，确认可用后再决定是否持久化 |
| Anthropic 兼容网关 | 常见为 ANTHROPIC_AUTH_TOKEN，以接口方文档为准 | 通常需要 ANTHROPIC_BASE_URL | 使用网关提供的 Base URL、模型和认证说明，不要照抄其他服务地址 |
| Claude 订阅或组织登录 | 不依赖 API Key | 不应随意改写 | 运行 claude 后按提示使用 /login |
- 打开 PowerShell 或 CMD。
- 安装 Claude Code：PowerShell 使用
irm https://claude.ai/install.ps1 | iex；CMD 使用curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd。 - 关闭当前窗口，重新打开终端，然后运行
claude --version。 - 根据接口类型设置变量，再运行
claude。 - 进入 Claude Code 后运行
/status，确认认证来源和设置文件。
安装命令、Windows 版本要求和 claude --version 验证方式以 Claude Code 官方安装文档为准。示例中的密钥、地址和模型均为占位内容，必须替换为你自己的有效值。
PowerShell、CMD 和 WSL 怎么配置
PowerShell：当前窗口临时配置
临时配置只影响当前 PowerShell 窗口，适合首次验证，关闭窗口后不会继续保留该会话变量：
$env:ANTHROPIC_API_KEY="替换为你的真实 API Key"
如果使用兼容网关，变量名称和地址必须以网关文档为准。常见写法可以是：
$env:ANTHROPIC_AUTH_TOKEN="替换为你的 Token"
$env:ANTHROPIC_BASE_URL="https://你的接口地址"
claude
CMD：当前窗口临时配置
CMD 不使用 PowerShell 的 $env: 语法：
set ANTHROPIC_API_KEY=替换为你的真实 API Key
claude
兼容网关示例：
set ANTHROPIC_AUTH_TOKEN=替换为你的 Token
set ANTHROPIC_BASE_URL=https://你的接口地址
claude
WSL：这是另一套环境
如果你在 WSL 中运行 Claude Code，Windows PowerShell 或 CMD 中设置的变量不一定会自动出现在 WSL 里。应在 WSL 终端单独设置：
export ANTHROPIC_API_KEY="替换为你的真实 API Key"
claude
不要把 Windows 原生终端和 WSL 当成同一个 shell 排查。先在实际运行 claude 的窗口中执行变量检查，再决定是否写入对应的 shell 配置文件。
官方帮助中心给出了 Windows CMD、PowerShell 查看和临时设置 ANTHROPIC_API_KEY 的命令，并明确说明环境变量 API Key 会优先于已登录的订阅认证。查看官方 API Key 环境变量说明
永久配置：环境变量还是 settings.json
永久配置有两种思路：Windows 用户环境变量适合让多个终端和工具读取；settings.json 适合把 Claude Code 自己的环境配置集中管理。官方文档说明，变量可以放在 shell 中，也可以放在设置文件的 env 对象中。环境变量官方参考指出，用户级文件会作用于本机上的每个项目。
方式一：Windows 用户环境变量
- 打开“系统属性”中的“高级”选项卡。
- 进入“环境变量”，在“用户变量”下点击“新建”。
- 变量名填写
ANTHROPIC_API_KEY。 - 变量值填写真实 Key，不要带多余引号或空格。
- 确认保存，关闭已经打开的 PowerShell、CMD、VS Code 和 Claude Code 窗口。
- 重新打开终端，检查变量是否能被当前 shell 读取。
PowerShell 检查：echo $env:ANTHROPIC_API_KEY；CMD 检查：echo %ANTHROPIC_API_KEY%。检查时不要把输出截图或粘贴到公开位置。
方式二：用户级 settings.json
Windows 下，~/.claude 对应 %USERPROFILE%\.claude，用户级配置文件通常是 %USERPROFILE%\.claude\settings.json。官方设置文件说明明确列出 Windows 路径映射，并说明设置文件必须是严格 JSON。
只有配置官方 API 时，可使用以下脱敏结构：
{
"env": {
"ANTHROPIC_API_KEY": "替换为你的真实 API Key"
}
}
如果是兼容网关，应根据对方文档选择变量，示例结构如下：
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "替换为你的 Token",
"ANTHROPIC_BASE_URL": "https://你的接口地址"
}
}
已有 settings.json 时，只在原有 JSON 中合并 env 字段，不要直接覆盖整个文件；文件不能使用注释，不能留下多余逗号，也不要把真实 Key 提交到 Git。官方文档还说明，项目级 .claude/settings.json 可能被提交给团队，因此个人密钥不应放在那里。
配置成功的判定与首次调用
- 先运行
claude --version，确认命令可找到。 - 再运行
claude，观察是否进入交互界面。 - 在 Claude Code 中运行
/status，确认当前是 API Key、订阅登录还是其他认证方式。 - 如果使用官方 API，确认 API Key 来自正确的 Console 账户；如果使用兼容网关，确认 Base URL、Token 和模型名称来自同一接口说明。
- 在项目目录中执行一次低风险请求，例如让 Claude Code 只读取项目结构并输出简短总结。
成功不等于“终端没有报错”这么简单：至少应同时满足命令可启动、认证方式符合预期、请求能返回文本。官方帮助中心建议使用 /status 检查当前认证方法；官方设置文档也说明，/status 可以显示已加载的设置来源。认证冲突和 /status 说明 设置来源检查说明
401、403、404、429 和启动失败怎么分流
| 现象 | 优先检查 | 处理方法 |
|---|---|---|
| 401 或认证失败 | 变量名、Key 是否失效、是否多了引号或空格 | 在当前运行 Claude Code 的终端重新检查变量，并确认官方 API 使用 ANTHROPIC_API_KEY，兼容网关是否要求 ANTHROPIC_AUTH_TOKEN。 |
| 403 或无权限 | 账户权限、项目权限、网关访问策略 | 不要反复更换命令；回到 Key 所属平台核对权限和可用范围，必要时联系管理员。 |
| 404 或找不到模型、路径 | ANTHROPIC_BASE_URL 是否错误，模型是否被接口支持 | 不要擅自拼接或删除路径，按接口提供方的 Base URL 和模型列表说明核对。 |
| 429 | 限流、余额或账户用量限制 | 先停止连续重试，检查账户用量和响应中的限流提示；只有明确属于临时限流时，才按服务方给出的等待时间重试。 |
| claude 不是命令 | 安装是否完成、PATH 是否刷新 | 关闭终端并重新打开；仍失败时按官方 PATH 排查入口检查安装目录。 |
| PowerShell 禁止运行脚本 | 执行策略或终端类型 | 先确认你确实在 PowerShell，再参考官方安装故障排查，不要把 PowerShell 命令粘贴到 CMD。 |
如果出现登录提示，不一定代表 API Key 没生效。Claude Code 支持订阅登录、Console 登录、API Key 以及云平台认证；当环境变量存在时，官方文档提示它可能优先于订阅认证，并带来 API 用量计费。先用 /status 判断当前认证来源，再决定保留哪一种方式。
密钥安全与 Windows 配置自查清单
- 不要公开真实 Key：不要把 Key 放进 Git、截图、Issue、聊天记录、项目级共享配置或公开日志。
- 不要混用认证方式：如果准备使用 Claude 订阅，先检查并移除不需要的
ANTHROPIC_API_KEY；官方帮助中心明确提醒，环境变量 Key 可能优先于订阅。 - 不要照抄接口地址：
ANTHROPIC_BASE_URL只填写你实际使用的兼容接口地址，具体是否包含版本路径、模型名或其他前缀，必须以该接口文档为准。 - 不要把两个 shell 混在一起：PowerShell 的
$env:、CMD 的set、WSL 的export不能互换。 - 修改后重启相关程序：改完 Windows 用户变量后，重新打开终端、编辑器和 Claude Code；否则旧进程可能仍使用旧环境。
- JSON 先校验：如果使用
settings.json，检查双引号、逗号和大括号，并用/status或claude doctor确认配置是否被读取。
如果你不确定自己到底在使用哪一种认证，最稳妥的顺序是：退出 Claude Code，检查当前终端变量，清理不需要的变量，再重新启动并运行 /status。这样比反复重装客户端更容易定位问题。
常见问题 FAQ
Windows 上应该用 ANTHROPIC_API_KEY 还是 ANTHROPIC_AUTH_TOKEN？
官方 Anthropic API 的标准变量是 ANTHROPIC_API_KEY，官方文档说明它会作为 API Key 发送；ANTHROPIC_AUTH_TOKEN 用于自定义 Authorization 头，值会以 Bearer 方式发送。连接兼容网关时，应以网关文档要求的变量为准，不要因为变量名相似就同时设置两者。
配置了 API Key，为什么 Claude Code 仍然提示登录？
可能是变量没有设置在当前终端、变量名拼写错误、终端没有重启，或者你使用的是另一种认证流程。先运行对应 shell 的变量检查命令，再启动 claude，进入后运行 /status。如果 Key 已设置但同时存在订阅登录，Claude Code 可能提示你确认认证方式。
ANTHROPIC_BASE_URL 应该填写什么？
只有在使用代理、兼容网关或其他自定义 API 端点时，才按接口提供方说明设置 ANTHROPIC_BASE_URL。不要直接假定必须加 /v1，也不要把完整请求路径、模型名或示例域名当成 Base URL；具体格式无法仅凭 Claude Code 官方变量名推断。
settings.json 已经有内容，能不能直接替换成 API Key 示例？
不建议直接覆盖。应保留原有字段，在顶层合并 env 对象；如果原文件已有 env，就在其中增加或修改对应变量。配置文件必须是严格 JSON，保存后用 /status 检查来源，出现格式错误时再用 claude doctor 排查。
Windows CMD 和 PowerShell 的配置命令为什么不能通用？
因为它们是不同的 shell 语法。PowerShell 使用 $env:变量名=值，CMD 使用 set 变量名=值；WSL 则使用 Linux 风格的 export。请先看命令提示符，再选择对应写法。
常见问题
Windows 上应该用 ANTHROPIC_API_KEY 还是 ANTHROPIC_AUTH_TOKEN？
官方 Anthropic API 使用 ANTHROPIC_API_KEY；ANTHROPIC_AUTH_TOKEN 用于自定义 Authorization 头，兼容网关应以接口文档要求为准。
配置 API Key 后为什么仍提示登录？
先检查当前终端是否真的读到了变量，再进入 Claude Code 使用 /status 查看认证来源；终端未重启、变量名错误或订阅登录冲突都可能导致误判。
ANTHROPIC_BASE_URL 应该填写什么？
仅在使用代理或兼容网关时按接口方文档填写。不要擅自添加 /v1、完整请求路径或模型名，具体格式以当前接口说明为准。
settings.json 已有内容，能否直接替换？
不要直接覆盖，应保留原字段并合并 env 对象；严格 JSON 不允许注释和多余逗号，保存后用 /status 检查。
CMD、PowerShell 和 WSL 的命令能混用吗？
不能。PowerShell 使用 $env:，CMD 使用 set，WSL 使用 export；请在实际运行 claude 的终端中配置和验证。
相关阅读
- 继续看 Claude Code 接入 Anthropic 兼容 API 的完整配置与排错
- 如果你还在使用 Cursor，可参考自有 API Key 配置方法
- 查看 Cursor API Key 设置范围与常见错误
- 浏览更多 AI API 配置与错误排查文章
参考资料
- Claude Code 官方安装与 Windows 设置文档（code.claude.com）
- Claude 官方帮助：管理 Claude Code API Key 环境变量（support.claude.com）
- Claude Code 官方环境变量参考（code.claude.com）
- Claude Code 官方设置文件与优先级说明（code.claude.com）