Claude Code 使用 API Key：配置、认证优先级与网关排错

更新于 2026-11-01 · fastaitoken.cyou

简答：Claude Code 使用 API Key，先区分两条路径：官方 Anthropic API 直连使用 ANTHROPIC_API_KEY；兼容网关通常由网关提供 Base URL 和令牌，可能使用 ANTHROPIC_AUTH_TOKEN。直连配置后运行 claude，再用 /status 验证；若电脑上同时存在订阅登录和环境变量，环境变量凭据可能优先并产生 API 用量费用。

定义：Claude Code 使用 API Key，是指通过环境变量或其他凭据机制向 Claude Code 提供 API 或网关认证信息，让命令行工具按对应账户和路由发起模型请求。

先选路径：官方 API 直连还是兼容网关

本文为第三方整理，不代表 Anthropic 官方。按 2026-11-01 检索到的 Claude Code 文档，API Key 配置前最重要的是先判断请求要发往哪里：如果直接调用 Anthropic API，使用 Claude Console 创建的 API Key；如果公司或团队通过兼容网关转发，请以网关管理员提供的 Base URL、令牌和模型要求为准。两条路径不要把变量混在一起。

Claude Code 两种接入路径对照

接入方式	主要变量	认证含义	计费或责任归属
Anthropic API 直连	`ANTHROPIC_API_KEY`	发送为 `X-Api-Key`，用于 Claude Console API Key	由该 API Key 关联的 API 账户承担用量
兼容 API 网关	`ANTHROPIC_BASE_URL` 加网关要求的认证变量	常见是 `ANTHROPIC_AUTH_TOKEN`，发送为 Bearer Token；具体以网关文档为准	由网关及其上游账户、团队规则决定
Claude 订阅登录	通过 `/login` 登录，不设置 API Key	使用订阅 OAuth 凭据	使用订阅对应的用量规则

Claude Code 官方认证文档明确区分了 ANTHROPIC_AUTH_TOKEN 与 ANTHROPIC_API_KEY：前者用于通过 Bearer Token 认证的网关或代理，后者用于直接访问 Anthropic API。查看官方认证优先级说明。

如果你只是要让 Claude Code 直接使用自己的 Anthropic API Key，先跳到下一节；如果你使用的是兼容网关，请先向网关提供方确认完整 Base URL、认证头、模型字段和是否要求 Anthropic 格式请求，不能仅凭一个 API Key 推断兼容性。

官方 API 直连：从创建 Key 到首次运行

确认账户入口：API Key 应在 Claude Console 创建，不是从普通聊天页面复制。官方帮助中心说明，Claude Console 用于创建 API Key、添加团队成员、设置账单和进行 API 调试。查看 Claude API 访问说明。
检查 Claude Code 是否已安装：在终端执行 claude --version。如果命令不存在，先按当前 Claude Code 安装文档选择适合系统的安装方式。
只在当前终端临时设置：首次测试建议使用临时变量，便于测试结束后清理，也不会把密钥长期留在 shell 配置文件中。
进入项目目录并启动：运行 cd 你的项目目录，再运行 claude。首次看到是否使用环境变量 Key 的确认提示时，选择与你的测试目标一致的选项。
在 Claude Code 内验证：输入 /status，确认当前使用的认证方式。官方文档说明，/status 可用于查看当前生效的认证来源。

官方 API 直连的临时配置命令

终端	配置命令	清理命令
macOS、Linux、WSL	`export ANTHROPIC_API_KEY='你的APIKey'`	`unset ANTHROPIC_API_KEY`
Windows CMD	`set ANTHROPIC_API_KEY=你的APIKey`	`set ANTHROPIC_API_KEY=`
Windows PowerShell	`$env:ANTHROPIC_API_KEY="你的APIKey"`	`Remove-Item Env:ANTHROPIC_API_KEY`

完整最小流程可以写成：

claude --version
export ANTHROPIC_API_KEY='你的APIKey'，Windows 按上表替换为对应命令
cd 你的项目目录
claude
在交互界面执行 /status

官方首次使用指南也给出了设置 ANTHROPIC_API_KEY 后运行 claude 的路径。查看官方首次使用流程。

三个变量怎么区分：API Key、Auth Token 与 Base URL

ANTHROPIC_API_KEY 是官方 API 直连的主要环境变量。Claude Code 会把它作为 X-Api-Key 认证头发送，适用于 Claude Console 创建的 API Key。

ANTHROPIC_AUTH_TOKEN 是 Bearer Token 形式的认证变量。官方文档将它放在 ANTHROPIC_API_KEY 之前的认证优先级中，并说明它适用于使用 Bearer Token 认证的 LLM 网关或代理。它不是“把任意 API Key 改个变量名就一定能用”，必须确认网关确实要求这个认证方式。

ANTHROPIC_BASE_URL 用于把请求路由到自定义 API 端点。它描述的是请求地址，不是密钥；如果网关要求路径已经包含版本或兼容接口前缀，应以网关文档给出的完整 Base URL 为准，避免把路径重复拼接。

变量使用速查

变量	适用场景	不要做什么
`ANTHROPIC_API_KEY`	官方 Anthropic API 直连	不要默认把它当成所有兼容网关的认证变量
`ANTHROPIC_AUTH_TOKEN`	要求 Bearer Token 的网关或代理	不要在未确认网关认证头时盲目设置
`ANTHROPIC_BASE_URL`	自定义 API 端点或网关地址	不要把完整请求路径和 Base URL 重复拼接

Claude Code 官方网关文档还指出，网关会把开发者请求转发给上游模型提供方，开发者凭据与上游提供方凭据可以是两套不同凭据。因此，网关能否使用某个模型、是否兼容某个请求字段，应由网关自身文档和实际响应确认，不能仅根据 Claude Code 能启动就下结论。查看官方网关工作方式说明。

兼容网关的最小配置：只填已确认的字段

如果你接入的是兼容网关，先向服务提供方拿到四项信息：完整 Base URL、认证变量或请求头、模型标识、是否要求 Anthropic Messages 格式。本文不替任何具体网关补写未核实的地址、模型名或价格。

在 macOS、Linux 或 WSL 中，通用结构如下；尖括号内容必须替换为网关提供的实际值：

export ANTHROPIC_BASE_URL='https://你的网关域名/官方要求的路径'
export ANTHROPIC_AUTH_TOKEN='你的网关令牌'
claude
进入 Claude Code 后执行 /status

Windows PowerShell 的对应结构是：

$env:ANTHROPIC_BASE_URL="https://你的网关域名/官方要求的路径"
$env:ANTHROPIC_AUTH_TOKEN="你的网关令牌"
claude

Windows CMD 的对应结构是：

set ANTHROPIC_BASE_URL=https://你的网关域名/官方要求的路径
set ANTHROPIC_AUTH_TOKEN=你的网关令牌
claude

网关配置时不要同时保留一个不相关的 ANTHROPIC_API_KEY。根据官方认证优先级，ANTHROPIC_AUTH_TOKEN 高于 ANTHROPIC_API_KEY；但如果网关需要其他认证方式，仍应以网关文档为准。若只设置 ANTHROPIC_BASE_URL 而没有网关凭据，官方文档说明，已保存的订阅登录可能仍然是当前认证来源，计费和用量也可能继续归属于订阅会话。查看网关与订阅认证的边界。

成功判定不是“窗口能打开”，而是：Base URL 可达、认证方式与网关要求一致、模型标识被网关接受，并且 /status 显示的凭据来源符合预期。若其中一项没有官方或服务方文档支持，应标记为“需核实”。

认证冲突与报错排查：按凭据、地址、模型分流

仍然走订阅登录或出现费用归属疑问：先退出 Claude Code，检查当前终端是否设置了 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或网关相关变量，再重新启动并执行 /status。官方说明，环境变量凭据可能优先于订阅登录；设置 ANTHROPIC_API_KEY 时，API 请求可能按该 API 账户的按量规则计费。查看官方环境变量与计费提醒。
401 或无效凭据：确认变量名、Key 或 Token 是否完整，是否复制了多余空格；再确认直连使用的是 ANTHROPIC_API_KEY，网关是否要求 ANTHROPIC_AUTH_TOKEN。不要把“变量非空”当成“凭据有效”。
403、组织被禁用或权限不足：保存返回正文和请求时间，检查 API Console 或网关管理员提供的组织、Workspace、权限和 Key 状态。单凭 403 不能判断是余额、模型权限还是组织状态问题。
404：优先检查 ANTHROPIC_BASE_URL 是否多拼或少拼路径，以及网关是否要求 Anthropic 兼容路径。不要直接把 404 归因于 API Key。
429：检查 API 账户或网关的速率限制、并发限制和当前用量；具体限制值以对应账户或网关控制台为准，本文不代填未核实数字。
模型不支持：核对网关要求的模型标识和 Claude Code 当前发送的请求格式。模型名称不能凭印象填写，必须以服务方当前模型列表或实际响应为准。
超时或流式中断：先把问题分成三层：本机到 Base URL 的网络、网关到上游的转发、上游账户的响应。只有在直连请求能够复现时，才继续检查本地 API Key；兼容网关的上游故障不能仅凭 Claude Code 表现归因于 Key。

如果问题发生在订阅认证，官方建议可以先使用 /logout 重新登录；如果 API Key 与订阅同时存在，则先清理环境变量，再重新打开终端验证。查看官方订阅认证切换说明。

永久配置与密钥安全：能临时就不要长期写入

官方文档提供了把 ANTHROPIC_API_KEY 写入 ~/.zshrc、~/.bash_profile 或 Windows 用户环境变量的方式，但永久配置会增加忘记清理、误用账户和泄露的风险。首次测试优先使用当前终端临时变量；长期使用时，至少记录变量写入位置，并在切回订阅或更换网关时同步删除。

不要用 echo $ANTHROPIC_API_KEY 输出完整密钥到录屏、终端日志或 CI 日志。更安全的本地非泄露检查可以只判断是否非空：

macOS/Linux：test -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY 已设置" || echo "未设置"
PowerShell：if ($env:ANTHROPIC_API_KEY) { "已设置" } else { "未设置" }
CMD：if defined ANTHROPIC_API_KEY (echo 已设置) else (echo 未设置)

如果密钥已经出现在 Git、截图、工单、聊天记录或第三方工具中，不要只删除本地文件，应在对应控制台撤销旧 Key、创建新 Key，并检查日志与用量。官方安全建议还包括使用加密 Secret、把 .env 加入忽略文件、区分开发与生产 Key，以及定期检查 Logs 和 Usage。查看官方 API Key 安全建议。

三分钟自查清单

路径：我是在调用官方 Anthropic API，还是在调用兼容网关？
变量：直连是否使用 ANTHROPIC_API_KEY，网关是否明确要求 ANTHROPIC_AUTH_TOKEN？
地址：ANTHROPIC_BASE_URL 是否来自当前网关文档，是否重复拼接路径？
版本：是否先运行 claude --version，并按当前安装文档操作？
验证：是否启动后执行 /status，确认实际生效的认证来源？
计费：是否知道当前请求会归属于 API 账户、网关上游账户或订阅会话？
安全：是否避免在命令历史、源代码、配置文件和日志中暴露完整密钥？

常见问题

Claude Code 可以直接使用 Anthropic API Key 吗？

可以。先在 Claude Console 创建 API Key，在当前终端设置 ANTHROPIC_API_KEY，进入项目目录运行 claude，再执行 /status 检查当前认证来源。

ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 有什么区别？

官方文档将 ANTHROPIC_API_KEY 用于直接访问 Anthropic API，并以 X-Api-Key 发送；ANTHROPIC_AUTH_TOKEN 用于要求 Bearer Token 的网关或代理。不能只因为变量名不同就推断某个网关一定兼容。

为什么设置 API Key 后，Claude Code 还会提示登录？

可能是环境变量未进入当前终端、变量名错误、Key 未获批准，或者存在多个认证来源。先运行 /status，再检查当前终端变量，必要时执行 /logout 并重新启动。

只设置 ANTHROPIC_BASE_URL 可以接入兼容网关吗？

不能直接保证。Base URL 只负责路由；网关还可能要求 ANTHROPIC_AUTH_TOKEN、特定请求格式或其他认证。官方文档说明，只设置 Base URL 时，已保存的订阅登录可能仍是当前认证来源。

如何安全检查 API Key 是否存在？

不要直接 echo 输出完整密钥。可以使用 test -n、PowerShell 的 if 或 CMD 的 if defined，只显示“已设置”或“未设置”，并避免把真实 Key 写入 Git、日志和截图。

API Key 泄露后删除本地变量就够了吗？

不够。应在对应 API 控制台撤销旧 Key、创建新 Key，并检查 Git 历史、日志、截图、工单和第三方工具中的泄露位置。

参考资料

Run Claude Code through a gateway：网关、Base URL 与计费边界（code.claude.com）
Manage API key environment variables in Claude Code：环境变量设置与清理（support.claude.com）
Your first day in Claude Code：安装、设置 API Key 与首次运行（support.claude.com）
How can I access the Claude API?：Claude Console、API Key 与账单入口（support.claude.com）
API key best practices：密钥保存、用量监控与轮换（support.claude.com）
code.claude.com（code.claude.com）
support.claude.com（support.claude.com）