文档
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
claudeANTHROPIC_BASE_URL 应为源站地址。Claude Code 会自行追加 /v1/messages——Anthropic 自家的验证代码片段为 curl "$ANTHROPIC_BASE_URL/v1/messages"——因此,如果值以 /v1 结尾,请求就会发送到 /v1/v1/messages 并返回 404。这是最常见的设置错误;其他问题请参阅 ANTHROPIC_BASE_URL 页面。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 页面。
sk-kn- 开头),并充值 $10 起——调用费用从该余额中扣除,失败的调用不会收费。随后,控制台会打开 Claude Code 设置页面。分步操作
- 在
/app/keys创建密钥并复制——它只会显示一次。 - 为当前会话导出上述变量,或将其写入
~/.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中,因为该文件会被提交到代码库。 - 运行
claude并打开 Status 选项卡。若某一行显示Auth token,即表示网关凭据已生效;若Login method行显示 claude.ai 账户,则说明变量未被读取。 - 如果你也登录了 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 均不可用;这篇排查指南说明了密钥的读取位置,以及如何同时保留两种配置。 - 对于 VS Code 扩展,应将变量放在 VS Code 自身用户设置中的
claudeCode.environmentVariables内——扩展会在启动前检查凭据,因此~/.claude/settings.json会传递给已启动的进程,却不会传递给该检查。
已于 2026年10月3日对照 Anthropic 的“将 Claude Code 连接到 LLM 网关” 检查。第三方设置会发生变化;如果这里的字段名称不再与你看到的内容一致,应以该页面为准,而不是本页。
调试客户端前先验证
一个请求即可确定故障来自端点、密钥还是配置文件。如果返回 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 的美元,格式为输入 / 输出。
| 模型 ID | Kunavo 输入 / 输出 | 它在 Claude Code 中的位置 |
|---|---|---|
claude-sonnet-5 | $1.40 / $7.00 | 默认工作模型——通过 /model 或 ANTHROPIC_ |
claude-opus-5-5 | $2.80 / $14.00 | 用于规划和架构级编辑 |
claude-haiku-4-5 | $0.70 / $3.50 | haiku 别名以及 Claude Code 自己发起的后台调用——使用 ANTHROPIC_ |
claude-fable-5-2 | $5.60 / $28.00 | 前沿层级,适用于值得按其费率付费的规划任务 |
常见问题
如何在没有 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 运行,不受影响。