文档

文档

Claude Code

Claude Code 会将任何 Anthropic 格式端点视为网关。只需两个变量即可将它指向 Kunavo,另外三个变量可固定 Kunavo 提供的模型;无需改动安装,每个会话都按 token 从余额中扣费,而非使用订阅。

两个环境变量 — ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN — 无需改变安装即可让 Claude Code 使用按量付费。

# One terminal session
export ANTHROPIC_BASE_URL=https://api.kunavo.com   # origin, no /v1
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Pin models Kunavo serves. Claude Code's default and its opus/sonnet aliases
# follow Anthropic's newest models; the sonnet alias asks for Sonnet 5.5,
# which Kunavo does not serve — unpinned, /model sonnet 404s.
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

claude
ANTHROPIC_BASE_URL 应为源站地址。Claude Code 会自行追加 /v1/messages——Anthropic 自家的验证代码片段为 curl "$ANTHROPIC_BASE_URL/v1/messages"——因此,如果值以 /v1 结尾,请求就会发送到 /v1/v1/messages 并返回 404。这是最常见的设置错误;其他问题请参阅 ANTHROPIC_BASE_URL 页面。
固定指定模型。Claude Code 内置的默认值是最新的 Opus(截至 2026 年 9 月为 Opus 5.5,参见 Anthropic 的模型配置文档),而 Kunavo 尚未提供的模型会在首次请求时返回 404。sonnet别名请求 Sonnet 5.5,haiku别名请求 Haiku 5.5(从 v2.1.293 起);Kunavo 都不提供这两个模型,因此如果不固定模型,/model sonnet、/model haiku以及设为这些别名的子代理都会返回 404。ANTHROPIC_MODEL设置会话模型;ANTHROPIC_DEFAULT_OPUS_MODEL负责/model opus(Opus 5.5 需要 Claude Code v2.1.280 或更高版本),ANTHROPIC_DEFAULT_SONNET_MODEL负责/model sonnet,而 ANTHROPIC_DEFAULT_HAIKU_MODEL负责/model haiku以及后台调用。GET /v1/models中的任意 ID 都可以使用。
使用 ANTHROPIC_AUTH_TOKEN,不要使用 ANTHROPIC_API_KEY。这两个变量会选择请求头:AUTH_TOKEN 会发送 Authorization: Bearer,API_KEY 会发送 x-api-key。Kunavo 两种都能读取,但 API_KEY 需要在交互式会话中通过一次性审批提示后才能生效,而 AUTH_TOKEN 不需要。

以下是会改变自定义 ANTHROPIC_BASE_URL 背后行为的 Claude Code 版本,摘自其 CHANGELOG,日期为各版本在 npm 上的发布日期:

  • 2.1.299(npm,2026-10-14):Claude Code 自己发往 Anthropic 的请求(功能开关、启动、fast mode、个人资料和反馈)不再携带你为第三方网关设置的密钥;经自定义 base URL 的流式响应现在等待数据最长 300 秒,而不是 180 秒。
  • 2.1.304(npm,2026-10-19):在自定义 base URL 背后,工具搜索默认开启;网关返回 400 或 422 时,会在不使用工具搜索的情况下重试。
  • 2.1.305(npm,2026-10-20):修复了 2.1.304 的一个回归问题:在 Vertex、Bedrock 等提供方上端点或网关拒绝工具搜索时,以及在禁用了 ToolSearch 或未把它列入 --tools 的网关后面,所有请求都会失败。现在 Claude Code 会在不使用工具搜索的情况下重试。

请使用 2.1.305 或更高版本:2.1.299 是第一个不再把网关密钥发往 Anthropic 自己端点的版本,2.1.305 是第一个在禁用 ToolSearch 或 --tools 中未包含它时也能自行恢复的版本。

Agent SDK 运行的是同一个 CLI;每个 SDK 版本内置哪个 Claude Code,见 Agent SDK 页面。

不想手动编辑环境变量?CC Switch 可以将 Kunavo 保存为 Claude Code 提供方——服务根地址和 Bearer 密钥与上文相同;逐字段设置说明见 CC Switch 页面。
还没有密钥?创建 Kunavo 账户,创建一个密钥(以 sk-kn- 开头),并充值 $10 起——调用费用从该余额中扣除,失败的调用不会收费。随后,控制台会打开 Claude Code 设置页面。

分步操作

  1. 在 /app/keys 创建密钥并复制——它只会显示一次。
  2. 为当前会话导出上述变量,或将其写入 ~/.claude/settings.json 的 env 块中:{"env":{"ANTHROPIC_BASE_URL":"https://api.kunavo.com","ANTHROPIC_AUTH_TOKEN":"sk-kn-...","ANTHROPIC_MODEL":"claude-sonnet-5","ANTHROPIC_DEFAULT_OPUS_MODEL":"claude-opus-5-5","ANTHROPIC_DEFAULT_SONNET_MODEL":"claude-sonnet-5","ANTHROPIC_DEFAULT_HAIKU_MODEL":"claude-haiku-4-5"}}。Anthropic 的文档明确指出,凭据不应放在项目的 .claude/settings.json 中,因为该文件会被提交到代码库。
  3. 运行 claude 并打开 Status 选项卡。若某一行显示 Auth token,即表示网关凭据已生效;若 Login method 行显示 claude.ai 账户,则说明变量未被读取。
  4. 如果你也登录了 claude.ai,Claude Code 启动时会打印 claude.ai connectors are disabled because ANTHROPIC_API_KEY or another auth source is set。使用网关密钥时这是正常现象:请求会使用 Kunavo 密钥运行,而该会话中的 claude.ai 连接器、Remote Control 和 /schedule 均不可用;这篇排查指南说明了密钥的读取位置,以及如何同时保留两种配置。
  5. 对于 VS Code 扩展,应将变量放在 VS Code 自身用户设置中的 claudeCode.environmentVariables 内——扩展会在启动前检查凭据,因此 ~/.claude/settings.json 会传递给已启动的进程,却不会传递给该检查。

已于 2026年10月3日对照 Anthropic 的“将 Claude Code 连接到 LLM 网关” 检查。第三方设置会发生变化;如果这里的字段名称不再与你看到的内容一致,应以该页面为准,而不是本页。

这是简要版本。完整教程——包括模型选择、真实会话成本和失败模式——见 Claude Code API 密钥指南。

调试客户端前先验证

一个请求即可确定故障来自端点、密钥还是配置文件。如果返回 JSON,则相同的基础 URL 和密钥可以在 Claude Code 中使用。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

字段中应填写哪个模型 ID

每个文本模型都可通过模型 ID 访问——实时列表见 GET /v1/models,包含价格的目录见模型页面。费率单位为每 1M token 的美元,格式为输入 / 输出。

模型 IDKunavo 输入 / 输出它在 Claude Code 中的位置
claude-sonnet-5$1.40 / $7.00默认工作模型——通过 /model 或 ANTHROPIC_MODEL 设置
claude-opus-5-5$2.80 / $14.00用于规划和架构级编辑
claude-haiku-4-5$0.70 / $3.50haiku 别名以及 Claude Code 自己发起的后台调用——使用 ANTHROPIC_DEFAULT_HAIKU_MODEL 固定指定模型
claude-fable-5-2$5.60 / $28.00前沿层级,适用于值得按其费率付费的规划任务
计费方式是从预付余额中按 token 扣费,无月费——参见 计费。对于重复上下文——这正是编辑器或聊天客户端发送内容的大部分——提示缓存对账单的影响大于模型选择。

常见问题

如何在没有 Claude 订阅的情况下使用 Claude Code?

将 ANTHROPIC_BASE_URL 设为 Anthropic 格式的端点,并将 ANTHROPIC_AUTH_TOKEN 设为该端点的密钥;同时将 ANTHROPIC_MODEL 固定为端点实际提供的模型——Claude Code 的内置默认值可能不在其中。这样,Claude Code 会向该端点进行身份验证,而不是连接 claude.ai;使用费用由该凭据的所有者按 token 计费,而非计入订阅套餐。Anthropic 将此模式称为网关模式;已保存的 claude.ai 登录信息仍留在磁盘上,但不会使用,取消设置这些变量后便会恢复使用。

ANTHROPIC_BASE_URL 应包含 /v1 吗?

不用。Claude Code 会自行追加路由路径,因此变量应填写源站地址——https://api.kunavo.com,而不是 https://api.kunavo.com/v1。Anthropic 自家的验证命令是 curl "$ANTHROPIC_BASE_URL/v1/messages",可以直接看出拼接方式。如果基础 URL 已以 /v1 结尾,请求会发送到 /v1/v1/messages 并返回 404。

ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 有什么区别?

它们会将凭据放在不同的 HTTP 请求头中:ANTHROPIC_AUTH_TOKEN 会发送 Authorization: Bearer,ANTHROPIC_API_KEY 会发送 x-api-key。如果将密钥放入错误的变量,它会通过端点不读取的请求头发送,导致请求以 401 失败。如果网关文档写的是“Bearer 令牌”,请使用 ANTHROPIC_AUTH_TOKEN;如果写的是“API 密钥”或“x-api-key”,请使用 ANTHROPIC_API_KEY。

使用自定义基础 URL 时,Claude Code 哪些功能会停止工作?

Remote Control 和语音听写都需要 claude.ai 身份;设置了网关凭据时,两者都不可用。只要 ANTHROPIC_BASE_URL 指向非 Anthropic 主机,Remote Control 还会被禁用。/schedule 和你在 claude.ai 添加的连接器也无法使用:只有在使用 claude.ai 登录凭据时,Claude Code 才会加载 claude.ai 连接器。因此,如果你也登录了 claude.ai,启动时会显示:“claude.ai connectors are disabled because ANTHROPIC_API_KEY or another auth source is set”。快速模式可用性检查也会直接访问 api.anthropic.com,而不会遵循基础 URL。核心循环中的所有内容——智能体、工具、子智能体以及你自行添加到 Claude Code 的 MCP 服务器——都通过 Messages API 运行,不受影响。