文档
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。
# 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 会在进程启动时读取这些变量,因此已运行的会话仍会使用旧端点。
https://api.kunavo.com/v1 会生成发往 /v1/v1/messages 的请求,所有调用都会返回 404。OpenAI SDK 采用相反的约定,确实需要在 base_url 中加入 /v1 — 这种区别是这里最常见的配置错误。所有变量及其用途
Claude Code 读取的完整变量列表见 Anthropic 的环境变量参考。将端点重定向时,以下变量最为重要。
| 变量 | 值 | 控制内容 |
|---|---|---|
ANTHROPIC_ | https://api. | 所有请求发送到的源站地址。不含路径,也不带末尾斜杠。 |
ANTHROPIC_ | sk-kn-… | 作为 Authorization: Bearer 发送的凭据。网关需要使用此变量。 |
ANTHROPIC_ | sk-ant-… | 作为 x-api-key 请求头发送的凭据,这是 api. |
ANTHROPIC_ | claude-sonnet-5 | Claude Code 在对话中使用的主模型。 |
ANTHROPIC_ | claude-opus-5-5 | opus 别名背后的模型(/ |
ANTHROPIC_ | claude-sonnet-5 | sonnet 别名背后的模型(/ |
ANTHROPIC_ | claude-haiku-4-5 | haiku 别名背后所使用的模型(/ |
GET /v1/models 实时获取。各客户端的配置方法
Claude Code
将导出命令放入 Claude Code 启动时使用的 shell 配置文件,然后打开新的终端。安装和工作流程都无需更改。
# ~/.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 会读取相同的环境变量,也可以将这两项设置传给构造函数 — 适用于一个进程需要连接多个端点的情况。
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 模型。
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_ 末尾 | 只设置源站地址。客户端会附加 /v1/ |
| 401 / invalid x-api-key | 端点使用 Bearer 令牌认证时,凭据却设置为了 ANTHROPIC_ | 改用 ANTHROPIC_ — 查看完整区别 |
| 仍在访问 api. | 在会话启动后才导出变量,或将变量设在该 shell 不会读取的配置文件中 | 打开一个新终端;在启动客户端的同一个 shell 中,用 echo $ANTHROPIC_ |
| 404 model_ | 端点不提供该模型 ID | 将 ANTHROPIC_ 设为 GET /v1/models 中的一个 ID |
| /model sonnet、/ | 该别名请求的是端点不提供的模型 | 固定 ANTHROPIC_ |
| 更新 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 就会恢复使用该套餐。