文档

文档

ANTHROPIC_BASE_URL

用于将 Claude Code 和 Anthropic SDK 指向 api.anthropic.com 以外端点的环境变量 — 查看完整变量参考、各客户端配置方法,以及几乎所有故障都源于的两个常见问题。

ANTHROPIC_BASE_URL 用于告知 Anthropic SDK 和 Claude Code 将 API 请求发送到哪个主机,取代默认的 https://api.anthropic.com。请将其设为不含路径的源站地址 — 客户端会自行附加 /v1/messages — 并与 ANTHROPIC_AUTH_TOKEN 配合使用;该令牌会作为 Authorization: Bearer 请求头发送。

这就是“自带密钥”或“自定义 base URL”配置的全部内容:把 ANTHROPIC_BASE_URL 设为 Kunavo 的端点,把你的 Kunavo 密钥设为 ANTHROPIC_AUTH_TOKEN,请求就会以 Anthropic Messages 格式经由 Kunavo 到达 Claude。四个模型变量也都要固定,因为 sonnet 和 haiku 别名请求的是 Kunavo 不提供的模型,不固定就会返回 404。

~/.zshrc
# The origin only — no trailing /v1, no trailing slash.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Claude Code: pin all four model variables to models the endpoint serves.
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 Code 和 SDK 会在进程启动时读取这些变量,因此已运行的会话仍会使用旧端点。

不要在 ANTHROPIC_BASE_URL 中加入 /v1。 Anthropic 客户端会自行附加路径,因此 https://api.kunavo.com/v1 会生成发往 /v1/v1/messages 的请求,所有调用都会返回 404。OpenAI SDK 采用相反的约定,确实需要在 base_url 中加入 /v1 — 这种区别是这里最常见的配置错误。

所有变量及其用途

Claude Code 读取的完整变量列表见 Anthropic 的环境变量参考。将端点重定向时,以下变量最为重要。

变量值控制内容
ANTHROPIC_BASE_URLhttps://api.kunavo.com所有请求发送到的源站地址。不含路径,也不带末尾斜杠。
ANTHROPIC_AUTH_TOKENsk-kn-…作为 Authorization: Bearer 发送的凭据。网关需要使用此变量。
ANTHROPIC_API_KEYsk-ant-…作为 x-api-key 请求头发送的凭据,这是 api.anthropic.com 要求的格式。设置此变量或上方的令牌,两者择一,不要同时设置。
ANTHROPIC_MODELclaude-sonnet-5Claude Code 在对话中使用的主模型。
ANTHROPIC_DEFAULT_OPUS_MODELclaude-opus-5-5opus 别名背后的模型(/model opus)。Claude Code 自身的默认模型是最新的 Opus,因此请将其固定为端点提供的模型之一。Opus 5.5 需要 Claude Code v2.1.280 或更高版本。
ANTHROPIC_DEFAULT_SONNET_MODELclaude-sonnet-5sonnet 别名背后的模型(/model sonnet)。该别名默认请求 Sonnet 5.5,因此请将其固定为端点提供的某个 Sonnet 模型。
ANTHROPIC_DEFAULT_HAIKU_MODELclaude-haiku-4-5haiku 别名背后所使用的模型(/model haiku、指定 haiku 的子代理),也是 Claude Code 用于自身后台调用的模型。该别名从 v2.1.293 起会请求 Haiku 5.5,因此请将其固定到端点实际提供的 Haiku 模型。
模型名称必须是端点实际提供的模型。指向网关却保留该网关不支持的模型 ID,是第二常见的故障原因;此时会出现 404 model_not_found,而不是认证错误。Kunavo 的模型 ID 列于模型页面,也可通过 GET /v1/models 实时获取。

各客户端的配置方法

Claude Code

将导出命令放入 Claude Code 启动时使用的 shell 配置文件,然后打开新的终端。安装和工作流程都无需更改。

~/.zshrc
# ~/.zshrc (or ~/.bashrc) — applies to every Claude Code session.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Pin models this endpoint serves. Claude Code's default and its opus/sonnet
# aliases follow Anthropic's newest models, which may not be served here —
# unpinned, those calls 404.
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 Code 中运行 /status,确认当前会话使用的端点。分步说明(包括生成密钥的位置)请参见:在 Claude Code 中设置 API 密钥。

Anthropic SDK(Python / TypeScript)

SDK 会读取相同的环境变量,也可以将这两项设置传给构造函数 — 适用于一个进程需要连接多个端点的情况。

anthropic_sdk.py
from anthropic import Anthropic

# The Anthropic SDK appends /v1/messages, so pass the origin — not .../v1.
client = Anthropic(
    base_url="https://api.kunavo.com",
    auth_token="sk-kn-...",          # sets the Authorization: Bearer header
)

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=512,
    messages=[{"role": "user", "content": "Say hi"}],
)
print(msg.content[0].text)

OpenAI SDK — 另一种约定

如果代码已经使用 OpenAI 格式,则完全不需要 ANTHROPIC_BASE_URL。将 base_url 指向 OpenAI 兼容路径 — 这次需要包含 /v1 — 即可通过 /v1/chat/completions 调用相同的 Claude 模型。

openai_sdk.py
from openai import OpenAI

# The OpenAI SDK is the other convention: it wants the /v1 in the base_url.
client = OpenAI(
    api_key="sk-kn-...",
    base_url="https://api.kunavo.com/v1",
)

r = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Say hi"}],
)
print(r.choices[0].message.content)

Cline、Roo Code、Kilo Code、Cursor

编辑器智能体通常会在自己的界面中提供相同的两项设置,而不是通过环境变量设置:"base URL" 或 "custom endpoint" 字段,以及 API key 字段。规则不变 — Anthropic 风格的提供方填写不带 /v1 的源站地址,并在 API key 字段中填写密钥。各客户端的操作指南:Cline、Roo Code、Kilo Code。

确认配置生效

一次 curl 请求即可同时验证 base URL 和凭据。返回 200 并带有 JSON 响应体,说明两者都正确。

# 200 and a JSON body means the base URL and the token are both right.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

# In Claude Code, /status shows the endpoint the session is actually using.

故障排查

症状原因修复方法
每个请求都返回 404/v1 被加在 ANTHROPIC_BASE_URL 末尾只设置源站地址。客户端会附加 /v1/messages。
401 / invalid x-api-key端点使用 Bearer 令牌认证时,凭据却设置为了 ANTHROPIC_API_KEY改用 ANTHROPIC_AUTH_TOKEN — 查看完整区别
仍在访问 api.anthropic.com在会话启动后才导出变量,或将变量设在该 shell 不会读取的配置文件中打开一个新终端;在启动客户端的同一个 shell 中,用 echo $ANTHROPIC_BASE_URL 确认。
404 model_not_found端点不提供该模型 ID将 ANTHROPIC_MODEL 设为 GET /v1/models 中的一个 ID
/model sonnet、/model haiku 或子代理返回 404该别名请求的是端点不提供的模型固定 ANTHROPIC_DEFAULT_SONNET_MODEL 和 ANTHROPIC_DEFAULT_HAIKU_MODEL,另外两个模型变量也一并固定
更新 Claude Code 后所有请求都失败2.1.304 版在自定义 base URL 后默认开启了工具搜索;遇到 400 或 422 时会在不使用工具搜索的情况下重试,但在禁用 ToolSearch 或 --tools 中未包含它时,所有请求都会失败更新到 2.1.305 或更高版本,它会在不使用工具搜索的情况下重试
Claude Code 提示余额过低请求已到达端点,费用记在密钥名下,而非订阅名下这是预期行为 — 充值,或取消设置该令牌以恢复使用套餐。请参见余额不足

版本说明

Anthropic API SDK,2026-10-21。Python SDK 2.0.0 和 TypeScript SDK 1.0.0 会发送 anthropic-version: 2026-10-21,并把 API 密钥放在 Authorization: Bearer 中,而不是 X-Api-Key。Kunavo 从这两种请求头中的任意一种读取密钥,所以这次升级在 Kunavo 这边无需任何改动。在该 API 版本下,带有 temperature、top_p 或 top_k 的请求会被以 400 拒绝(Anthropic 的API 版本 2026-10-21 迁移指南,读取于 2026-10-22),新版 SDK 也不再把它们作为参数接受:Python SDK 2.1.0 会抛出 TypeError。无论客户端声明哪个版本,Kunavo 都以 API 版本 2023-06-01 调用模型,因此仍然带有 temperature 的请求(例如通过 extra_body 传入)不会被拒绝:支持该参数的模型会收到它;不支持的模型,Kunavo 会将其丢弃,并在 X-Kunavo-Dropped-Params 响应头中注明。已于 2026-10-22 使用 Python SDK 2.1.0 和 TypeScript SDK 1.1.0 对本地 Kunavo 构建进行验证。

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

  • 2.1.285(npm,2026-09-29):自定义 base URL 背后的会话会使用支持 1M 上下文窗口的模型的该窗口(Opus 4.7 及以后、Sonnet 5 及以后、Fable);如果网关在 200K token 处截止,用 /autocompact 200k 把上限改回来。
  • 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 中未包含它时也能自行恢复的版本。

这对 Pro 或 Max 订阅的影响

设置凭据变量后,Claude Code 会按密钥而非已登录的订阅计费:套餐限额不再适用,使用费用会记在密钥所有者名下。订阅本身不受影响 — 移除该变量并打开新的终端后,Claude Code 就会恢复使用该套餐。两者不会合并计费,相关费用计算方法见 Claude Code 价格。

下一篇

常见问题

什么是 ANTHROPIC_BASE_URL?

ANTHROPIC_BASE_URL 是一个环境变量,用于告知 Anthropic SDK 和 Claude Code 将 API 请求发送到哪个主机,而不是默认的 https://api.anthropic.com。请将其设为不含路径的源站地址 — 客户端会自行附加 /v1/messages — 并与 ANTHROPIC_AUTH_TOKEN 配合使用;该令牌会作为 Authorization: Bearer 请求头发送。任何兼容 Anthropic 的端点都可使用;在 Kunavo 上,该值为 https://api.kunavo.com。

ANTHROPIC_BASE_URL 应包含 /v1 吗?

不应包含。ANTHROPIC_BASE_URL 只填写源站地址 — https://api.kunavo.com,而不是 https://api.kunavo.com/v1 — 因为 Anthropic SDK 和 Claude Code 会自行附加 /v1/messages 路径。加入 /v1 会导致请求发往 /v1/v1/messages,并返回 404。OpenAI SDK 则采用相反的约定,base_url 中需要包含 /v1,因此同一个网关会根据所用客户端以两种不同方式填写。

ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 有什么区别?

ANTHROPIC_AUTH_TOKEN 会通过 Authorization: Bearer 请求头发送凭据,而 ANTHROPIC_API_KEY 会通过 api.anthropic.com 要求的 x-api-key 请求头发送凭据。使用 Bearer 令牌进行身份验证的网关需要 ANTHROPIC_AUTH_TOKEN;更改 ANTHROPIC_BASE_URL 后出现 401,最常见的原因就是设置了 ANTHROPIC_API_KEY。设置其中一个即可,不要同时设置两者 — 两者都存在时,具体行为取决于客户端版本。

如何在 Claude Code 中设置自定义 base URL?

在 Claude Code 启动时使用的 shell 配置文件(~/.zshrc 或 ~/.bashrc)中导出 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN,然后打开新的终端以载入这些变量。Claude Code 会在启动时读取它们,因此已运行的会话仍会使用旧端点。在 Claude Code 中运行 /status,确认当前会话使用的端点。

设置 ANTHROPIC_BASE_URL 会停用我的 Claude Pro 或 Max 订阅吗?

设置 ANTHROPIC_AUTH_TOKEN 等凭据变量后,Claude Code 会按密钥而非已登录的订阅计费,因此 Pro 和 Max 套餐限额不再适用,使用费用会记在密钥所有者名下。订阅本身不受影响,也不会被取消 — 移除该变量并打开新的终端后,Claude Code 就会恢复使用该套餐。