Claude Code API Key — 如何获取并完成配置

Claude Code 需要 API key 才能正常工作。无论你是第一次安装 Claude Code，还是准备从 Anthropic 官方直连迁移到更适合国内开发者的固定费率 Claude API gateway，核心流程都很简单：生成一个 key，配置两个环境变量，然后验证请求是否能成功到达 Claude。本教程会从注册、领取 $5 免费额度、配置 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY，到排查 401、404、429 等常见错误一步步讲清楚。对于想先试用免费claude api、了解 claude api价格，或者正在寻找 claude api中转、claude无限使用方案的开发者，这篇指南可以直接照着操作。

什么是 Claude Code API Key

Claude Code API key 是 Claude Code CLI 调用 Claude model provider 时使用的认证凭据。你可以把它理解成 Claude Code 和后端 API 服务之间的身份令牌：没有这个 key，Claude Code 发出的每一次请求都会因为无法认证而失败，通常表现为 authentication error、401 或 403。这个 key 本质上是一段字符串，一般会放进环境变量里，例如 ANTHROPIC_API_KEY，Claude Code 会把它作为 x-api-key header 发送；也可以使用 ANTHROPIC_AUTH_TOKEN，它会以 Bearer token 的形式发送。AI Prime Tech Unlimited 同时兼容这两种方式，所以你可以按现有 Claude Code、SDK 或自动化脚本的习惯来配置。

如果你使用 AI Prime Tech Unlimited 这类 Claude API gateway，而不是直接连 Anthropic 官方账号，那么 claude api密钥并不是从 Anthropic Console 生成，而是从 unlimited.aiprimetech.io 的 dashboard 生成。key 的格式可能和 Anthropic 官方略有不同，但在 Claude Code 里的配置逻辑完全一样：把 key 写入环境变量，把 base URL 指向 gateway，剩下的请求路径、messages API 调用、model 选择都由 Claude Code 和 SDK 自动处理。区别在于，你的用量会绑定到 gateway 账户的余额或订阅计划，而不是 Anthropic 官方账单。

很多开发者搜索 购买claude api 或 claude api中转，是因为想在本地、服务器、CI、Cursor、Cline、Aider 或 Claude Code 里稳定调用 Claude。对这类场景来说，一个 API key 可以同时在多台机器和多个 Claude Code session 中使用，例如你的 MacBook、Linux 服务器和办公电脑都可以配置同一个 key。不过，如果你把同一个 key 分享给整个团队，所有请求都会计入同一个账户的余额、限速和统计。团队使用时更建议每个开发者单独生成一个 key，这样 dashboard 里的用量追踪、风控和限流会更清晰，也方便在人员变动时单独 revoke 某个 key，而不影响其他人。

第一步：注册并生成你的 Key

打开 unlimited.aiprimetech.io 并创建账户。注册通常只需要邮箱和密码，完成邮箱确认后登录 dashboard。进入 API Keys 区域，点击 Generate New Key。建议给 key 起一个清晰的名称，例如 claude-code-laptop、work-desktop、cursor-home 或 ci-runner，这样以后你看到列表时就知道每个 key 用在哪里。如果某台设备丢失、某个项目不再维护，或者你怀疑 key 泄露，也可以快速定位并撤销对应 key。

生成 key 后请立刻复制并保存。出于安全考虑，大多数 dashboard 只会在生成时完整展示一次 API key，之后不会再次明文显示。你可以把它保存到 password manager、安全笔记，或者你们团队内部认可的 secret 管理工具中。不要把 key 直接写进代码仓库，也不要发到群聊、issue 或截图里。如果你不小心关闭页面或遗失 key，也不用担心，可以在 dashboard 重新生成一个新的 key，然后更新本机环境变量；旧 key 如果已经不再使用，最好立即 revoke，避免留下安全风险。

第二步：设置环境变量

Claude Code 主要读取两个环境变量来完成 gateway 配置：ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY。ANTHROPIC_BASE_URL 应该设置为 gateway 的根域名，不要带任何路径后缀。这里最常见的错误是把它写成 https://claudeapikey.dev/v1。Anthropic SDK 会自动在 base URL 后面拼接 /v1/messages，如果你手动加了 /v1，最终请求路径就会变成 /v1/v1/messages，通常会返回 404。正确写法是只保留根地址：https://claudeapikey.dev。

在 Linux 或 macOS 上，你可以把环境变量写进 shell profile，例如 ~/.bashrc、~/.zshrc 或 ~/.profile。常见配置是 export ANTHROPIC_BASE_URL="https://claudeapikey.dev"，再加上 export ANTHROPIC_API_KEY="your-key-here"。保存后需要 source 对应文件，或者重新打开一个 terminal session，让环境变量真正加载到当前 shell。Windows 用户可以通过 Settings > System > Advanced system settings > Environment Variables 设置系统环境变量，也可以把它们写进 PowerShell 的 $PROFILE。无论使用哪种方式，重点都是确保 Claude Code 启动时能读取到这两个变量。

如果你有多个项目，或者不同项目需要使用不同的 Claude API provider，可以在项目根目录创建 .env 文件，并写入同样的变量。Claude Code 会从当前工作目录加载 .env，而且项目级 .env 通常比系统级环境变量更适合做 per-project 配置。例如某个项目使用 AI Prime Tech Unlimited 的 claude api中转，另一个项目走公司内部 proxy，你就可以通过不同 .env 隔离配置。需要特别注意的是，.env 里包含 claude api密钥，必须加入 .gitignore，避免误提交到 GitHub、GitLab 或内部仓库。一旦 key 被提交到公开仓库，即使很快删除，也应当立即 revoke 并重新生成。

第三步：验证连接是否成功

设置好环境变量后，打开一个新的 terminal session，然后启动 Claude Code。你可以输入一个简单请求，例如 Hello, confirm you can respond. 如果 Claude 正常回复，说明整条链路已经跑通：API key 有效，ANTHROPIC_BASE_URL 指向正确，AI Prime Tech Unlimited gateway 能够接收请求并成功路由到 Claude model。对于第一次配置的用户，这一步非常重要，因为它能确认问题不在 Claude Code、shell 环境变量、网络代理或 key 本身。

如果验证失败，请先看错误码。401 或 403 通常表示 API key 无效、过期、复制错误，或者使用了已经 revoke 的 key。建议回到 dashboard 重新生成或复制 key，并确认环境变量里没有多余空格、引号错误或换行。404 几乎总是 base URL 写错，尤其是误加 /v1、路径重复，或者末尾带了不必要的 path。connection refused、timeout 或 DNS 相关错误，则更可能是网络、VPN、代理、防火墙、公司网络策略或本地 DNS 配置导致。

你也可以绕过 Claude Code，用 curl 直接验证 gateway。示例命令是 curl -H 'Authorization: Bearer YOUR_KEY' https://claudeapikey.dev/v1/models，或者使用 x-api-key header。如果 key 有效，接口会返回当前可用 model 列表。这个方法很适合定位问题：如果 curl 能成功，但 Claude Code 失败，那通常说明问题在环境变量加载、shell profile、Claude Code 启动上下文或项目 .env；如果 curl 也失败，那就应优先检查 key、余额、base URL 和网络。很多国内开发者在搭建 claude api中转时，最容易忽略的就是 terminal 没有重新打开，导致 Claude Code 仍在使用旧环境。

第四步：配置 Model 偏好

默认情况下，Claude Code 会根据内置规则为不同层级选择 model，例如 Sonnet、Opus、Haiku 等。大多数日常 coding 场景，Sonnet 已经足够快且成本合适；复杂架构分析、长上下文推理、疑难 bug 排查时，可以切换到 Opus。你也可以通过额外的环境变量覆盖默认 model，包括 ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 和 ANTHROPIC_DEFAULT_FABLE_MODEL。这些值必须写成 gateway 支持的精确 model identifier。

对大多数开发者来说，设置 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5 和 ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6 就足够了。Claude Code 默认会在多数交互中使用 Sonnet，因为它在速度、代码能力和成本之间比较均衡；当你通过 /model 命令切换，或者 plan mode 需要更强推理能力时，再使用 Opus。AI Prime Tech Unlimited 支持当前主流 Claude model 版本，因此你可以根据实际任务选择更适合的 model，而不需要频繁修改应用代码。

建议同时启用 gateway model discovery：设置 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1。这样 Claude Code 会向 gateway 查询可用 models，而不是只依赖本地硬编码列表，减少 model not found 的概率。你还可以设置 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1，避免非必要 telemetry 请求发送到 gateway，从而减少日志噪音，并略微降低请求延迟。对于追求 claude无限使用、claude无限额度体验的开发者，合理选择默认 model 也很关键：日常任务用 Sonnet，关键任务再切 Opus，既能保持响应速度，又能更高效地利用账户计划。

常见认证错误排查

最常见的问题是环境变量没有真正加载。你在 ~/.bashrc 或 ~/.zshrc 写入 export 之后，当前已经打开的 terminal 不会自动获得新变量，必须执行 source ~/.bashrc、source ~/.zshrc，或者重新打开 terminal。Windows 上有时需要彻底重启 terminal 应用，而不只是新建一个 tab。你可以用 echo $ANTHROPIC_BASE_URL 和 echo $ANTHROPIC_API_KEY 检查 bash/zsh 环境，也可以在 PowerShell 中使用 echo $env:ANTHROPIC_BASE_URL。检查时不要把完整 API key 截图或发给别人，只确认它是否存在即可。

如果连接有效但出现 model not found，通常是 model identifier 与 gateway 支持的名称不一致。Model ID 区分大小写，也和版本强相关。请以 dashboard 或 /v1/models 返回的名称为准。常见错误包括使用旧名称 claude-3-opus，而不是当前支持的 claude-opus-4-6；或者在环境变量值前后多打了空格；又或者复制时带上了中文引号。遇到这种情况，不要盲目怀疑 API key，先用 curl 请求 /v1/models 获取准确列表，再更新 ANTHROPIC_DEFAULT_SONNET_MODEL 或 ANTHROPIC_DEFAULT_OPUS_MODEL。

# 添加到 ~/.bashrc 或 ~/.zshrc：
export ANTHROPIC_BASE_URL="https://claudeapikey.dev"
export ANTHROPIC_API_KEY="your-key-from-dashboard"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# 验证连接：
# $ source ~/.bashrc && claude
# 或者直接测试 gateway：
# $ curl -H "x-api-key: $ANTHROPIC_API_KEY" https://claudeapikey.dev/v1/models

FAQ

Claude Code 和其他工具需要不同的 key 吗？
不需要。同一个 API key 可以用于 Claude Code、Cursor、Cline、Aider，以及任何兼容 Anthropic Messages API 或 OpenAI-compatible endpoint 的工具。一个 claude api密钥 可以同时服务多个开发工具。

ANTHROPIC_BASE_URL 需要包含 /v1 吗？
不需要。只设置根地址：https://claudeapikey.dev。Anthropic SDK 会自动追加 /v1/messages。如果你手动加入 /v1，路径会重复并导致 404。

免费额度用完后会发生什么？
Claude Code 通常会返回 rate limit、insufficient balance 或类似错误。你可以在 dashboard 充值 pay-as-you-go，也可以升级到 unlimited plan，例如 1 天 $9 或 1 周 $39，获得固定费率访问，不再按 token 单独计费。

同一个 key 可以在多台机器上使用吗？
可以。同一个 key 能同时在多台设备和多个 Claude Code session 中使用，所有用量都会计入同一账户余额和限速。团队使用时建议每位开发者单独生成 key，方便统计和管理。