Claude Code 国内 API Key：获取、配置与最小请求验证
简答：Claude Code 没有一个通用的“国内 API Key”。个人开发者应先选择官方 API、云平台身份认证或 Anthropic 兼容网关，再取得对应的 Key、Base URL、模型 ID 和请求协议；如果这四项中有一项未确认，不要直接配置。最快的验证方法是：先用脱敏环境变量发送一次最小 Messages API 请求，再启动 Claude Code。
定义：Claude Code 国内 API Key，是用于让 Claude Code 连接官方 API、云平台或兼容网关的具体认证凭证，不是跨平台通用的公共密钥。
30 秒速查：先决定接入路径，再获取 Key
本文是第三方接入指南，不代表任何服务商官网。搜索“Claude Code 国内 API Key”的用户，首先要区分“Key 从哪里来”和“网络是否能连通”这两个问题；官方 API、云平台和兼容网关的凭证、地址、模型目录及计费主体并不相同。
| 路径 | 适合谁 | Key 或凭证来源 | 需要先确认 | 费用与稳定性 |
|---|---|---|---|---|
| 官方 Claude API | 个人开发、脚本和服务端调用 | Claude Console 的 API keys 页面 | 账号权限、账单或余额、所在网络能否访问官方 API | 由官方平台计费；具体价格、限额和可用性以控制台及官方文档为准 |
| 云平台托管接口 | 已有企业云账号、需要 IAM 或组织权限的团队 | 对应云平台的身份凭证或授权机制 | 区域、模型访问资格、角色权限和请求格式 | 由对应云平台计费；不能直接套用官方 API 的价格或权限结论 |
| Anthropic 兼容网关 | 已有网关账户，或需要统一路由和内部管理的团队 | 网关控制台或管理员提供的 Key | 完整 Base URL、认证变量、模型 ID、是否支持 Messages API 和流式 | 由网关或上游平台计费；本文不对任何具体网关的价格、稳定性或可用性作保证 |
立即执行的决策路径：个人用户先确认能否使用官方 Console 和官方 API；企业用户先确认云平台的区域与权限；选择兼容网关时，必须在配置前拿到完整 Base URL、Key 变量、模型 ID 和协议说明。大陆网络环境下是否能访问某个域名、是否存在代理或 TLS 问题，需要在你的实际网络中单独核验，不能仅凭“国内 API”这一说法判断可用。
官方 API Key：获取入口、认证头和订阅区别
官方文档显示，Claude API 的 Key 在 Claude Console 的 API keys 页面创建。创建时可以设置名称、有效期、关联账号和工作区范围；完整 Key 只在创建后显示一次，丢失后需要重新创建。具体入口和字段以官方 API Key 文档当前页面为准。
- 登录 Claude Console，打开 API keys 页面。
- 点击创建 Key，选择 Key 类型、有效期、关联账号和工作区范围。
- 复制完整 Key，并放入环境变量或密钥管理工具。
- 确认账号具备 API 使用权限，并按照控制台提示完成账单或余额设置。
- 先发送一次最小 API 请求，再启动 Claude Code。
Claude 应用订阅与 API Key 不是同一件事。订阅用于登录和使用对应的 Claude 产品；API Key 用于程序调用 API，API 用量和计费由 API 平台的账号、工作区或项目设置决定。不要因为已经有 Claude 应用订阅，就推断自己已经拥有可用的 API Key。
官方 API 当前要求请求包含认证、版本和内容类型等请求头。官方 API 概览列出：Authorization: Bearer <token>，或仍可使用兼容的 x-api-key；同时需要 anthropic-version 和 content-type: application/json。具体请求路径为 POST /v1/messages，详见官方 API 概览与官方 HTTP API 参考。
先跑最小请求：把 Key、地址、模型和协议分开验证
最小请求只适用于官方 API，或明确声明兼容 Anthropic Messages API 的网关。不要把下面的官方地址、模型 ID 或请求头直接套到未提供兼容说明的服务上。模型值必须替换为当前控制台或接口文档列出的实际模型 ID；本文不绑定一个未经你当前平台确认的模型名称。
macOS、Linux、WSL：curl 非 2xx 时先保留响应正文
先设置变量：export ANTHROPIC_API_KEY="你的真实Key"、export ANTHROPIC_BASE_URL="https://api.anthropic.com"、export ANTHROPIC_MODEL="控制台列出的模型ID"。然后执行：curl --silent --show-error --write-out "\nHTTP_STATUS:%{http_code}\n" --request POST "$ANTHROPIC_BASE_URL/v1/messages" --header "Authorization: Bearer $ANTHROPIC_API_KEY" --header "anthropic-version: 2026-10-21" --header "content-type: application/json" --data "{\"model\":\"$ANTHROPIC_MODEL\",\"max_tokens\":32,\"messages\":[{\"role\":\"user\",\"content\":\"只回复：连接测试成功\"}]}"。如果平台要求 x-api-key，应删除或替换认证头，但只能按该平台文档执行。
Windows PowerShell：检查状态码和响应内容
先设置变量：$env:ANTHROPIC_API_KEY = "你的真实Key"、$env:ANTHROPIC_BASE_URL = "https://api.anthropic.com"、$env:ANTHROPIC_MODEL = "控制台列出的模型ID"。再执行：$headers = @{ Authorization = "Bearer $env:ANTHROPIC_API_KEY"; "anthropic-version" = "2026-10-21"; "content-type" = "application/json" }; $body = @{ model = $env:ANTHROPIC_MODEL; max_tokens = 32; messages = @(@{ role = "user"; content = "只回复：连接测试成功" }) } | ConvertTo-Json -Depth 5; try { $r = Invoke-WebRequest -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" -Method Post -Headers $headers -Body $body -ErrorAction Stop; "HTTP_STATUS:$($r.StatusCode)"; $r.Content } catch { if ($_.Exception.Response) { "HTTP_STATUS:$([int]$_.Exception.Response.StatusCode)" }; $_.ErrorDetails.Message } 。
成功判据：收到 HTTP 2xx，并且响应正文能看到模型返回内容。claude --version只能证明客户端命令可执行；它不能证明 API Key、Base URL 或模型 ID 有效。最小请求返回的状态码和正文，才适合区分网络、鉴权、路径和模型问题。
官方 API 版本会变化，当前页面示例使用的版本号应以官方 API 版本文档为准。兼容网关可能要求不同的版本头、路径或认证头，不能把官方示例视为所有网关的固定规则。
兼容网关配置：四项参数必须向服务方逐项核实
如果你选择兼容接口，先向服务方索取下表中的完整信息。只拿到一个 Key、但没有地址和模型列表时，当前资料不足以完成可靠配置。
| 参数 | 作用 | 必须核对的内容 |
|---|---|---|
| API Key 或 Token | 请求鉴权凭证 | 使用 ANTHROPIC_API_KEY 还是 ANTHROPIC_AUTH_TOKEN，是否发送为 Bearer Token，是否有有效期 |
| Base URL | 请求根地址 | 是否包含版本路径、是否应保留或删除 /v1、是否支持 HTTPS |
| 模型 ID | 接口识别的模型字符串 | 完整大小写、当前是否可用、是否需要网关映射 |
| 协议与流式 | 决定请求体和返回解析方式 | 是否兼容 Anthropic Messages API、是否支持 SSE、是否有请求体大小或超时限制 |
Anthropic 的网关配置文档说明，静态网关凭证可以通过 ANTHROPIC_AUTH_TOKEN 配置，并作为 Authorization 头发送；apiKeyHelper 的优先级低于 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY。这条规则只说明当前 Claude Code 官方文档中的配置行为，不代表任意网关都接受相同变量。详情见官方 LLM Gateway 配置文档。
配置兼容网关时，可以先按服务方文档设置：export ANTHROPIC_AUTH_TOKEN="网关提供的Key"、export ANTHROPIC_BASE_URL="服务方提供的完整Base URL"、export ANTHROPIC_MODEL="控制台显示的模型ID"。如果服务方明确要求 ANTHROPIC_API_KEY，先清理旧的 ANTHROPIC_AUTH_TOKEN，再只保留一套凭证。
Claude Code 配置：Shell、PowerShell 与 settings.json
Shell 临时配置适合首次验证，关闭终端后变量通常不会保留。macOS、Linux 或 WSL 可使用：export ANTHROPIC_AUTH_TOKEN="网关Key"、export ANTHROPIC_BASE_URL="完整Base URL"、export ANTHROPIC_MODEL="实际模型ID"、claude doctor、claude -p "只回复：连接测试成功"。
Windows PowerShell 可使用：$env:ANTHROPIC_AUTH_TOKEN = "网关Key"、$env:ANTHROPIC_BASE_URL = "完整Base URL"、$env:ANTHROPIC_MODEL = "实际模型ID"、claude doctor、claude -p "只回复：连接测试成功"。
为了检查变量是否存在但不打印完整密钥，Shell 可执行：if [ -n "$ANTHROPIC_API_KEY" ]; then echo "ANTHROPIC_API_KEY=已设置"; else echo "ANTHROPIC_API_KEY=未设置"; fi; if [ -n "$ANTHROPIC_AUTH_TOKEN" ]; then echo "ANTHROPIC_AUTH_TOKEN=已设置"; else echo "ANTHROPIC_AUTH_TOKEN=未设置"; fi; printf 'BASE_URL=%s\nMODEL=%s\n' "$ANTHROPIC_BASE_URL" "$ANTHROPIC_MODEL"。PowerShell 可执行：@("ANTHROPIC_API_KEY","ANTHROPIC_AUTH_TOKEN","ANTHROPIC_BASE_URL","ANTHROPIC_MODEL") | ForEach-Object { $v = [Environment]::GetEnvironmentVariable($_); if ($_ -match "KEY|TOKEN") { if ([string]::IsNullOrEmpty($v)) { "$_=未设置" } else { "$_=已设置" } } else { "$_=$v" } }。
当前 Claude Code 文档列出的设置文件包括用户级 ~/.claude/settings.json、项目共享的 .claude/settings.json 和项目本地的 .claude/settings.local.json；Windows 的用户目录对应 %USERPROFILE%\.claude。用户级设置适合个人默认配置，项目共享设置适合团队非敏感配置，项目本地设置适合个人覆盖项。详见Claude Code 设置文件与优先级文档。
推荐不要把真实 Key 写入项目文件。可以只在项目设置中保存非敏感变量或模型选择，例如：{"env":{"ANTHROPIC_BASE_URL":"服务方提供的Base URL","ANTHROPIC_MODEL":"控制台列出的模型ID"},"model":"控制台列出的模型ID"}。其中 model 是 Claude Code 的模型设置，ANTHROPIC_MODEL 是环境变量覆盖方式；具体支持情况和优先级以当前设置文档为准。保存后，在 Claude Code 内运行 /status 查看已加载的设置来源，运行 claude doctor 检查被拒绝或无效的配置。
国内用户先核对的 5 项条件
- 域名和 TLS：确认 Base URL 能解析，HTTPS 证书有效，且当前网络没有拦截或改写请求。
- 完整路径：确认服务方要求的是根地址、包含
/v1的地址，还是另一个专用路由，不要自行拼接。 - 认证方式：确认使用 Bearer Token、
x-api-key或其他方式，并确认 Claude Code 发出的请求头与网关要求一致。 - 模型目录：从当前控制台或接口文档复制完整模型 ID，不根据名称猜测能力、上下文长度、工具调用或视觉支持。
- 计费和限制：确认计费主体、输入输出 token 口径、速率、并发、余额或预算限制；查不到的信息应标记为“未核实”。
这五项只能说明“是否具备开始验证的条件”，不能保证特定网关一定可用。具体服务的价格、状态、稳定性、隐私政策和日志保留规则，需要以该服务当前公开文档、控制台或可复现响应为准。
按层排查 401、403、404、429、超时和流式中断
| 现象 | 可能原因 | 建议动作 |
|---|---|---|
| 无法解析域名或拒绝连接 | DNS、网络、端口或代理问题 | 先检查域名解析、HTTPS 握手和本机代理，不要先修改模型 ID |
| 401 | 官方文档列出的常见原因包括 Key 格式错误、被撤销或过期 | 检查当前终端实际生效的变量、Key 是否完整、是否已禁用或过期 |
| 403 | 可能涉及组织、工作区、账号或模型权限 | 查看响应正文和控制台权限，不要只根据状态码下结论 |
| 404 | 可能是地址、路径、工作区或模型不存在 | 逐字符核对 Base URL、请求路径和模型列表 |
| 429 | 可能是速率、并发、额度或上游限制 | 读取响应正文和 Retry-After，降低并发并检查额度 |
| 请求超时 | DNS、TLS、代理、服务端处理或读取超时 | 先发送最小非流式请求，再分别检查网络与服务端超时 |
| 非流式成功、流式中断 | 网关或反向代理未正确转发 SSE，或读取超时过短 | 确认网关支持流式，检查代理缓冲和读取超时配置 |
上表是通用诊断，不代表任意服务商固定返回规则。官方错误文档明确说明，401 通常与 Key 状态有关，但其他 4xx 仍需结合错误类型、响应正文、请求编号和控制台日志判断。可参考官方 Claude API 错误说明。
API Key 安全与费用控制清单
- 不要把 Key 写入前端代码、公开仓库、Issue、截图、聊天记录或未经脱敏的日志。
- 个人开发优先使用短有效期 Key；团队或生产环境按项目、工作区或服务账号分开管理。
- 把请求时间、模型 ID、状态码和用量记录下来，但对 Key、Authorization 和完整响应中的敏感内容脱敏。
- 发现 Key 泄露后，立即在控制台禁用或删除并创建新 Key；只修改本地环境变量并不能让旧 Key 失效。
- 为脚本设置预算、速率、并发和重试上限，避免循环调用或错误重试造成异常消耗。
- 不要把 Claude 应用订阅、云平台凭证和兼容网关 Key 混为一谈；它们的认证主体、计费和权限边界可能不同。
截至 2026-11-06，本文没有核实任何具体兼容网关的价格、状态、可用模型或服务承诺；配置前请以对应控制台和公开文档为准。
常见问题
Claude Code 有一个通用的国内 API Key 吗？
没有。Key 属于具体平台、组织或兼容网关，不能在所有 Claude Code 环境通用。你需要先确定使用官方 API、云平台还是兼容网关，再获取对应凭证和配置参数。
Claude 应用订阅可以直接当 API Key 使用吗？
不能直接这样理解。应用订阅和 API Key 是不同的认证与计费路径；API Key 需要在 Claude Console 或对应云平台、兼容网关中单独取得。
ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 应该用哪个？
以当前接入方文档为准。官方 API 文档使用 ANTHROPIC_API_KEY；官方网关配置示例使用 ANTHROPIC_AUTH_TOKEN，并说明静态值作为 Authorization 头发送。排查时不要同时设置两个不同凭证，先清理旧变量，再按文档保留一套。
Base URL 要不要加 /v1？
不能统一回答。官方 Messages API 的请求路径是 /v1/messages，但兼容网关可能要求根地址、版本路径或其他路由。必须按服务方给出的完整 Base URL 配置，不能凭经验追加或删除 /v1。
如何确认当前终端到底用了哪个 API Key？
不要打印完整密钥。Shell 或 PowerShell 只检查变量是否为空，并单独打印 Base URL 和模型 ID；然后用最小 curl 或 Invoke-WebRequest 请求查看 HTTP 状态码和响应正文。
为什么 Claude Code 能启动，但请求仍然报 401 或 404？
claude --version 和 claude doctor 主要用于确认客户端与环境，不能单独证明远端请求成功。应使用最小请求逐项检查当前生效的 Key、Base URL、请求路径、认证头和模型 ID。
可以根据模型名称判断它支持工具调用、视觉或长上下文吗？
不可以。模型能力必须以当前平台模型列表和接口文档为准，名称相似不代表协议、上下文长度或工具调用能力一致。
相关阅读
参考资料
- Claude Platform Docs：Get your Claude API key（platform.claude.com）
- Claude Platform Docs：Authentication（platform.claude.com）
- Claude Platform Docs：API overview（platform.claude.com）
- Claude Platform Docs：HTTP API reference（platform.claude.com）
- Claude Platform Docs：Versions（platform.claude.com）
- Anthropic：LLM gateway configuration
- Claude Code Docs：Settings files and precedence（code.claude.com）
- Claude Platform Docs：Claude API errors（platform.claude.com）