返回指南
集成·2026年7月26日·更新于 2026年11月14日·阅读约 8 分钟

Claude Code API 密钥——在哪里获取、放在哪里,以及为什么错误的变量会静默失败

Claude Code 接受订阅登录或 API 密钥,而设置完成后两者的行为差异很大。下面说明各自的来源、确切承载它的变量,以及大多数 401 错误背后的请求头不匹配问题。

最后审核于 。

Claude Code 有两种不同的身份验证方式,而你所需的方式决定了其他所有配置。claude.ai 订阅登录会覆盖 Pro 或 Max 方案内的使用。API 密钥按 token 计费,不受方案限额限制。本指南介绍在哪里获取密钥、准确放置位置、两个凭据变量,以及为什么选错变量会导致静默失败;还会说明成功运行后如何控制账单。

你真的需要密钥吗?

情况使用方式
你拥有 Claude Pro / Max,且使用量在限额内订阅登录——无需密钥
没有订阅,或在任务中途达到限额API 密钥,按 token 计费
希望获得更低的每 token 费率来自网关的 API 密钥
需要按席位归属统计的团队使用每位开发者一个 API 密钥

开始前需要知道:设置密钥会暂停你的订阅。凭据变量处于活动状态时,Claude Code 会使用它,而不是已保存的 claude.ai 登录;方案限额将不再适用,使用费用会计入密钥所有者。取消设置后,Claude Code 会恢复使用订阅。

选项 1——Anthropic 第一方密钥

  1. 登录 console.anthropic.com(该账户与 claude.ai 分开)。
  2. 在 Billing 下添加余额。API 采用预付费方式,与任何订阅分开——Pro 方案不会为其付费。
  3. 在 API Keys 下创建密钥。它以 sk-ant- 开头,并且只显示一次。
anthropic-key.sh
export ANTHROPIC_API_KEY=sk-ant-...
# Then approve it once, interactively:
#   /config  ->  Use custom API key
claude

注意代码片段中的第二步。ANTHROPIC_API_KEY 会在 x-api-key 标头中发送,并且 Claude Code 使用它前需要一次性交互式批准。如果该提示曾被拒绝,之后密钥会被忽略,完全不会再次提示——看起来就像没有读取变量一样。请在 /config → Use custom API key 下重新启用。

选项 2——每 token 成本更低的密钥

Claude Code 原生读取 ANTHROPIC_BASE_URL,因此可连接到任何提供 Anthropic Messages API 的端点——无需插件、代理或修改过的二进制文件。这是网关支持的路径,也是以更低费率运行相同 Claude 模型的方式:

~/.zshrc
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

ANTHROPIC_BASE_URL 仅指定源站地址,Claude Code 会自行追加 /v1/messages。请保留模型配置行:Claude Code 的内置默认模型及其 opus 别名都会解析为最新的 Opus;如果 Kunavo 尚未提供该模型,首次请求就会返回 404。opus 配置行将模型固定为 Claude Opus 5.5,这需要 Claude Code v2.1.280 或更高版本(如果使用旧版本,请运行 claude update)。sonnet 别名请求的是 Sonnet 5.5,而 Kunavo 不提供该模型,因此如果未设置 ANTHROPIC_DEFAULT_SONNET_MODEL,/model sonnet、opusplan 的执行阶段以及设置为 sonnet 的子代理都会返回 404。注册并充值 $10 后,在控制台中创建 sk-kn- 密钥。无月费,余额永不过期。

模型Kunavo 每 1M 输入 / 输出适用场景
claude-sonnet-5$1.40 / $7.00日常编码
claude-opus-5-5$2.80 / $14.00复杂重构、计划模式
claude-haiku-4-5$0.70 / $3.50后台任务

这比主线模型的列表价低约 30%。完整费率请参阅 Claude API 定价指南;Claude Code 定价会将此路径与 Pro 和 Max 方案费用进行比较;包括按任务路由模型以及网关背后会发生哪些变化在内的完整设置,请参阅 Claude Code 路由器指南。如果尚未安装 CLI,请从安装 Claude Code开始。

密钥实际放置的位置

两个变量对应两个不同的 HTTP 标头。密钥放在服务器不读取的标头中时会以 401 失败:

变量标头使用场景
ANTHROPIC_AUTH_TOKENAuthorization: BearerBearer token 密钥;立即生效
ANTHROPIC_API_KEYx-api-keyAnthropic Console 密钥;需要一次性批准
apiKeyHelper两者轮换或由保管库保存的凭据

如果你不确定手中的密钥属于哪种类型,请从 ANTHROPIC_AUTH_TOKEN 开始,它无需批准步骤。在 Kunavo 上,任一变量都能让 Claude Code 发现模型列表,因为 /v1/models 会从任一标头读取密钥。

Shell 导出与设置文件

Shell 导出只对当前终端及其子进程生效。从 Dock 启动的编辑器看不到它,后台智能体也看不到。对于任何永久配置,请改用 ~/.claude/settings.json 的 env 区块——密钥相同,并且适用于 Claude Code 运行的所有位置。不要将密钥放入项目的 .claude/settings.json;该文件会提交并与所有克隆仓库的人共享。

运行 /status 以确认当前使用的凭据。若出现命名你变量的 Auth token 或 API key 行,表示密钥处于活动状态;若出现命名 claude.ai 账户的 Login method 行,表示密钥未生效。

无需编辑文件即可轮换密钥

如果凭据按计划过期,或来自保管库,请将 apiKeyHelper 指向一个会输出当前密钥的命令:

~/bin/get-key.sh
#!/bin/bash
# Any command that prints the current key to stdout works.
vault kv get -field=api_key secret/claude-code

在设置文件中以 "apiKeyHelper": "~/bin/get-key.sh" 引用它。Claude Code 会将输出缓存五分钟,并在 401 时重新运行;使用 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 调整该时间。该值会在两个标头中发送,因此两种方式都能使用。

让账单保持可预测

智能体式编码非常耗费 token——每一步都会重新发送系统提示词、任务历史和最新文件上下文。以下四点的重要性高于其他任何因素:

  1. 保留 Haiku 这一行。如果没有 ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5,Claude Code 的 haiku别名会请求 Kunavo 未提供的模型 ID(v2.1.293 起为 Haiku 5.5),因此 /model haiku和指定为 haiku 的子代理都会返回 404。同一行会将 Claude Code 自行生成的摘要和标题从主模型转移出去;如Claude Code 工作流的费用所列,任务派生越多,节省越明显。
  2. 同两个变量也会路由 Agent SDK。 它本身没有 base URL 选项——它会启动此 CLI 并直接传递你的环境变量,因此Agent SDK 程序完全按照上述配置进行路由。
  3. 开始新任务,而不是无限延长一个任务。 每一步都会重新发送上下文,因此长会话的成本呈平方级增长。主模型应使用哪个层级,会在 Opus、Sonnet 与 Haiku 对比中按每个已完成任务的成本,而不是每个 token 的成本进行分析。
  4. 让提示词缓存发挥作用。 缓存输入按输入费率的 10% 计费,而原生 Messages API 路径会原样传递 cache_control(详情)。
  5. 在控制台中为编辑器设置单独的密钥并配置支出上限,然后一周后检查使用量。按密钥设置的限额可将失控循环变成有上限的循环。

故障排除

症状修复方法
401 无效或无法识别的 token密钥放在了错误的标头中——在两个变量之间切换。也可能是密钥已被撤销;请重新生成。
变量已设置,但 Claude Code 仍要求你登录在首次设置前就能读取的位置进行设置:shell 导出或 ~/.claude/settings.json。项目级设置文件只有在信任提示之后才会生效。
ANTHROPIC_API_KEY 被忽略且没有提示此前已拒绝。/config → Use custom API key。
启动警告指出两个凭据来源密钥和已保存的登录同时处于活动状态。运行 /logout 以使用密钥,或取消设置变量以使用登录。
会话中途余额耗尽充值;请参阅 余额不足。

常见问题

Claude Code 需要 API 密钥吗?

不一定。Claude Code 支持两种身份验证方式:claude.ai 订阅登录(Pro 或 Max),在该方案限额内覆盖使用;或按 token 计费的 API 密钥。以下情况需要密钥:没有订阅、经常达到订阅限额,或希望通过其他端点路由 Claude Code。

在哪里获取 Claude Code 的 API 密钥?

如需第一方密钥,请登录 console.anthropic.com,在 Billing 下添加余额,然后在 API Keys 下创建密钥——它以 sk-ant- 开头,并且只显示一次。Claude Code 也接受任何提供 Anthropic Messages API 的端点所发放的密钥,Kunavo 等网关就是如此;这种密钥应在网关自己的控制台中创建。

应在哪里将 API 密钥填入 Claude Code?

可以放在环境变量中,或放在 ~/.claude/settings.json 的 env 区块中。Bearer token 密钥使用 ANTHROPIC_AUTH_TOKEN,x-api-key 密钥使用 ANTHROPIC_API_KEY——二者会通过不同的 HTTP 标头发送,密钥放错位置会以 401 失败。相比 shell 导出,设置文件更合适,因为它也能作用于编辑器和后台智能体。

为什么我的 ANTHROPIC_API_KEY 被忽略了?

ANTHROPIC_API_KEY 需要在交互式会话中进行一次性批准;如果该提示曾被拒绝,之后密钥会被忽略,且不再显示提示。请在 /config 下通过 'Use custom API key' 选项重新启用,或改用 ANTHROPIC_AUTH_TOKEN,后者无需批准步骤即可立即生效。

可以在 Claude Code 中使用更便宜的 API 密钥吗?

可以。Claude Code 会读取 ANTHROPIC_BASE_URL,因此任何提供 Anthropic Messages API 的端点都无需额外软件即可使用。将其指向 Kunavo,即可低于 Anthropic 列表价运行相同的 Claude 模型;采用按需付费方式,从 $10 充值开始,无月费且余额永不过期。

Claude Code API 密钥和我的 claude.ai 登录是同一个吗?

不是。它们是独立的系统,计费也彼此独立——console.anthropic.com 发放 API 密钥,claude.ai 处理订阅。Pro 方案不会为 API 使用付费。

可以用一个密钥同时访问 Claude 和 GPT 吗?

在 Kunavo 上可以——同一个 sk-kn- 密钥可服务于 目录中的所有模型。Claude Code 本身只支持 Anthropic Messages API,因此在 Claude Code 中你会使用 Claude 模型;其他工具可以使用同一个密钥访问其余模型。

持有密钥需要付费吗?

不需要。Kunavo 采用按需付费,从 $10 充值开始,无月费且余额永不过期——你支付的是 token 使用费,而不是密钥持有费。

通常如何获取 Anthropic API 的 API 密钥?

如需了解非 Claude Code 场景,包括 SDK 设置和密钥管理,请参阅 Claude API 密钥文档。