文档

文档

Claude Agent SDK

Agent SDK 没有 base URL 选项——它会启动 Claude Code CLI,并将整个环境交给它。这就是路由的切入点,只需两个变量即可完成配置。

在 SDK 中搜索 base_url 选项一无所获,这并非文档遗漏——这个选项并不存在。SDK 会将 Claude Code CLI 作为子进程运行,而读取 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 的正是 CLI。设置这两个变量后,代理发出的每个调用都会经过路由,无需修改代理代码。

# The SDK has no base_url option. The CLI it spawns reads these, and the
# SDK passes the parent environment straight through — so exporting them
# before your program starts is enough.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Pin models Kunavo serves: the CLI's default and its opus/sonnet aliases
# follow Anthropic's newest models, and the sonnet alias asks for Sonnet 5.5,
# which Kunavo does not serve — unpinned, those requests 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

python my_agent.py
端点应为服务根地址——https://api.kunavo.com,不要带 /v1。Anthropic 客户端会自行追加 /v1/messages。这个规则在其他所有 Anthropic 兼容客户端中也同样适用,很多人会在这里出错;ANTHROPIC_BASE_URL 页面对此有详细说明。
本页讲的是 Claude Agent SDK(截至 2026-10-22 为 TypeScript 0.3.x 和 Python 0.2.x),它运行的是 Claude Code CLI。2026-10-21 发布的 Anthropic API SDK 新大版本(Python 2.0、TypeScript 1.0)是另一个包;它们在网关背后带来的变化见 ANTHROPIC_BASE_URL 页面。

为什么环境变量会传递给 CLI

这里值得用一段话说明,因为这关系到它究竟是一个可能失效的技巧,还是可以依赖的、已有文档记录的特性。Python SDK 的子进程传输会将父进程的 os.environ 作为子进程环境,只移除一个键——CLAUDECODE,以免子进程误以为自己正在 Claude Code 会话中运行——随后合并 CLAUDE_CODE_ENTRYPOINT,再合并 ClaudeAgentOptions.env,最后加入 SDK 版本。

由此可得两点,其中第二点最容易被弄错。Shell 中的所有环境变量都会传递给 CLI,因此导出这两个变量即可生效。此外,options.env 会合并到继承的环境之上,因此显式传入的值会优先生效,不会被旧的导出值覆盖。代码见 subprocess_cli.py。

显式设置方式,以及何时应坚持使用它

在自己的机器上导出变量没有问题,但在其他环境中就不可靠了:代理使用哪个端点取决于进程的启动方式;一旦它在调度器、容器或未加载个人配置的 CI 作业中运行,就会出问题。在 options 对象中传入 env,便能将路由配置纳入程序本身。

my_agent.py
import asyncio

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

# The explicit form. options.env is merged ON TOP of the inherited
# environment, so this wins over whatever the shell happens to hold —
# which is what you want in anything that is not your own laptop.
options = ClaudeAgentOptions(
    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",
    },
)


async def main():
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Summarise the open TODOs in this repo")
        async for message in client.receive_response():
            print(message)


asyncio.run(main())

在 TypeScript SDK 中,options.env 会替换 CLI 的环境,而不是合并进去(见其类型文档,SDK 0.3.308),所以要先把 process.env 展开放进去。以下代码已于 2026-10-22 在 Node 22 上使用 SDK 0.3.308 经本地 Kunavo 构建运行通过:

my_agent.mts
import { query } from "@anthropic-ai/claude-agent-sdk";

// options.env REPLACES the CLI's environment in the TypeScript SDK (it is
// merged on top in Python), so spread process.env to keep PATH and HOME.
const env = {
  ...process.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",
};

for await (const message of query({
  prompt: "Summarise the open TODOs in this repo",
  options: { env },
})) {
  if (message.type === "result") console.log(message.subtype, message.result);
}

分步操作

  1. 在 /app/keys 创建密钥并复制——它只会显示一次。
  2. 决定路由配置放在哪里:本地开发时使用导出的变量,无人值守运行时使用 ClaudeAgentOptions(env=…)。
  3. 将 ANTHROPIC_BASE_URL 设为 https://api.kunavo.com,并将 ANTHROPIC_AUTH_TOKEN 设为你的 sk-kn-… 密钥。
  4. 将ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL和ANTHROPIC_DEFAULT_SONNET_MODEL设置为已提供的 ID:CLI 内置的默认模型以及其opus和sonnet别名会跟随 Anthropic 的最新模型;而 Kunavo 未提供的模型——sonnet别名所请求的 Sonnet 5.5——会返回 404。
  5. 同时将 ANTHROPIC_DEFAULT_HAIKU_MODEL设为 claude-haiku-4-5:若不设置,CLI 的 haiku别名会请求 Kunavo 未提供的模型 ID(v2.1.293 起为 Haiku 5.5),因此设为 model: haiku 的子代理会返回 404。同一行设置还会让 CLI 自行发起的后台子任务使用最便宜的档位。
  6. 运行程序。代理代码无需任何改动。

SDK 运行的是哪个 Claude Code

每个 SDK 版本都自带一个 Claude Code 二进制文件:TypeScript SDK 0.3.N 带的是 Claude Code 2.1.N(见其 package.json 中的 claudeCodeVersion),Python SDK 则在其变更日志中写明所附带的 CLI(0.2.166 带 2.1.299,0.2.169 带 2.1.305)。Claude Code CHANGELOG 中有三项变更在网关背后很重要:

  • 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 会在不使用工具搜索的情况下重试。

所以请使用 TypeScript SDK 0.3.305 或更高版本,或 Python SDK 0.2.169 或更高版本。在 2026-10-22 用 Claude Code 2.1.308 检查时,sonnet 别名仍然请求 Kunavo 不提供的模型,所以上面固定的四个模型变量要保留。

一个 agent 回合按什么计费

CLI 发出的每个请求都会依次发送系统提示和工具定义、到目前为止的对话,以及新增的内容。从一个会话的第二个请求起,大部分输入都是缓存读取,在 Claude Sonnet 5 上按输入单价的 0.1× 计费;新增部分会以 1.25× 写入缓存;输出(含思考)按输出单价计费。一个提示可能产生多个请求,每次工具往返一个。要估算一个会话的费用,把它的输入、其中的缓存部分和输出填进 Claude token 成本计算器。

不同子任务应使用哪个层级

代理会将任务分发出去——你提出的一项请求会变成多次计费往返调用——因此,层级映射在这里比在聊天应用中更重要。费率以每 1M 个 token 的美元价格表示,按输入 / 输出列出,数据实时读取自目录。

模型 IDKunavo 输入 / 输出适用场景
claude-haiku-4-5$0.70 / $3.50CLI 自动生成的后台子任务——频繁、自动,且很容易多花钱
claude-sonnet-5$1.40 / $7.00代理实际推理时的常用默认层级
claude-opus-5$3.50 / $17.50仅当较便宜的层级需要尝试多次才能完成任务时使用
关于最后一行的计算——较便宜的层级表现要差多少才不再划算——请参阅 Opus 与 Sonnet 与 Haiku。如果代理在无人值守的情况下运行,相关费用说明见 在无需许可提示的情况下运行。

调试 SDK 前先验证

只需一次请求,就能判断故障出在密钥、端点还是 SDK。如果返回 200,说明同一凭据也适用于 SDK 启动的 CLI;如果仍有问题,原因就在变量的设置方式,而不是变量值本身。

# Settles whether a failure is the key, the endpoint, or the SDK.
# 200 here means the same credential works for the CLI the SDK spawns.
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-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

参考资料

该 SDK 在 anthropics/claude-agent-sdk-python 开源。本文描述的环境行为来自它自己的子进程传输代码,读取于 2026-09-04。TypeScript SDK 的架构相同——它驱动 CLI,而不是调用 API——其类型文档(0.3.308,读取于 2026-10-22)写明 options.env 会替换 CLI 的环境,而不是合并进去。Kunavo 这一侧是 Messages API,以同样方式路由的其他客户端见 集成中心。

常见问题

Claude Agent SDK 可以使用自定义基础 URL 吗?

可以,但不能通过 SDK 选项设置——它没有 base_url 参数,因此在 README 中搜索该参数也不会找到任何结果。SDK 会将 Claude Code CLI 作为子进程运行,而读取 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 的正是 CLI。在程序运行环境中设置这两个变量,就能路由该智能体发起的所有调用,无需修改智能体代码。

SDK 如何将环境变量传递给 CLI?

它会继承整个父环境,但恰好会过滤掉一个键。在 Python SDK 的子进程传输中,子进程环境按以下顺序构建:从父进程的 os.environ 中移除 CLAUDECODE,然后合并 CLAUDE_CODE_ENTRYPOINT,再合并 ClaudeAgentOptions.env,最后合并 SDK 版本信息。由此可知两点:shell 中的所有环境变量都会传递给 CLI;由于 options.env 是在 shell 环境之上合并的,因此其值优先。

我应该使用环境变量,还是使用 ClaudeAgentOptions(env=...)?

在自己的笔记本电脑以外的场景中,请使用 options.env。依赖当前 shell 环境意味着智能体的端点取决于进程的启动方式;如果进程在不包含个人配置的调度器、容器或 CI 作业中运行,第一次就可能出错。通过 options 对象显式传递 env,可使路由成为程序自身的属性,而不依赖运行环境;它会在继承的环境变量之上合并,因此也会覆盖过时的导出变量。

Agent SDK 需要单独的 Anthropic 账户吗?

它需要的是 Claude Code CLI 接受的凭据,但不一定要是 Anthropic 官方凭据。由于路由通过 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 完成,因此只要端点提供 Anthropic Messages API 即可——在 Kunavo 上,只需使用一个 sk-kn- 密钥访问 https://api.kunavo.com,费用从预付余额中按 token 扣除,而非按套餐计费。

Agent SDK 程序应该使用哪些模型?

根据子任务匹配模型档位,因为一个代理可能会派生出多个任务。每百万 token 价格为 $0.70 / $3.50 的 Claude Haiku 4.5适合处理 CLI 自行生成的后台工作;每百万 token 价格为 $1.40 / $7.00 的 Claude Sonnet 5是实用的默认选择;每百万 token 价格为 $3.50 / $17.50 的 Claude Opus 5仅适合较便宜档位需要多次尝试的任务。无论如何,都要将 ANTHROPIC_DEFAULT_HAIKU_MODEL 与路由变量一并设置:否则 CLI 的 haiku 别名会请求 Kunavo 未提供的模型 ID,导致设为 model: haiku 的子代理返回 404;设置后,这些后台工作会由 Haiku 而非主模型处理。

TypeScript Agent SDK 的工作方式也一样吗?

是的。它的架构相同——SDK 驱动 Claude Code CLI,而不是直接调用 API——所以读取路由变量的同样是 CLI。显式写法有一个区别要注意:在 TypeScript SDK 中,options.env 会替换 CLI 的环境,而不是合并进去,所以要先把 process.env 展开放进去。本页的 TypeScript 示例已于 2026-10-22 使用 SDK 0.3.308 在本地 Kunavo 构建上运行通过。

为什么 SDK 会从环境变量中滤除 CLAUDECODE?

这样,SDK 启动的 CLI 就不会误以为自己运行在 Claude Code 父会话中。它是从继承的环境中移除的唯一键;在这里,它的重要性仅在于说明其他环境变量会被完整传递——包括本页依赖的两个路由变量。