用 Claude Code 的两个环境变量，把 Claude Agent SDK 跑在 Router One 上

安装 Python SDK 并设置凭证

使用 Python 3.10 或更新版本，安装 claude-agent-sdk；wheel 包自带原生 Claude Code 可执行文件，不需要单独安装 Claude Code。若 pip 装到的是源码包而不是平台 wheel（官方文档以 ARM64 Windows 为例），按官方方式原生安装 Claude Code，SDK 会从 PATH 找到它。TypeScript 包是 @anthropic-ai/claude-agent-sdk，需要 Node.js 18 或更新版本。下面是 macOS/Linux 的 shell 示例，运行前替换两个占位符：Router One Key，以及当前目录中详情页列出 POST /v1/messages 的 Claude 系列模型的精确 ID。ROUTER_ONE_* 是本示例定义的变量名，代码读取后把 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 交给引擎；像 Claude Code 指南那样直接导出这两个变量同样有效，因为 Python SDK 会把 env 合并到继承的环境之上。SDK 不会自动读取 .env 文件，运行 Python 文件时要沿用同一环境。

python -m pip install claude-agent-sdk
export ROUTER_ONE_API_KEY="sk-your-router-one-key"
export ROUTER_ONE_MODEL_ID="<exact-model-id-from-/models>"

把 Claude Agent SDK 配置到 Router One base URL

保存为 claude_agent_sdk_router_one.py，运行 python claude_agent_sdk_router_one.py。query() 以子进程方式启动随包附带的 Claude Code 引擎，并逐条产出它的消息。env 选项合并到继承的环境之上：ANTHROPIC_BASE_URL 填不带 /v1 的主机根地址 https://api.router.one，因为引擎会自己拼上 /v1/messages；ANTHROPIC_AUTH_TOKEN 以 Authorization: Bearer 头携带你的 Router One Key，于是每一轮模型调用都是发往网关的 Anthropic Messages 请求。ANTHROPIC_API_KEY 不需要设置，示例刻意没有写它。model= 把目录里的模型 ID 原样传给引擎的 --model 参数；不设 model 时会回退到 Claude Code 的默认别名，别名解析出的是内置默认 ID，未必是目录里的条目。max_turns=3 限制工具调用的往返轮数。permission_mode 保持未设置且没有提供 can_use_tool 回调，模型即便请求工具也会被拒绝而不是执行，所以首次运行只有模型请求。循环打印每条 AssistantMessage 里的 TextBlock，最后打印 ResultMessage 的 subtype 和 num_turns。

import asyncio
import os

from claude_agent_sdk import (
    AssistantMessage,
    ClaudeAgentOptions,
    ResultMessage,
    TextBlock,
    query,
)

options = ClaudeAgentOptions(
    model=os.environ["ROUTER_ONE_MODEL_ID"],
    env={
        "ANTHROPIC_BASE_URL": "https://api.router.one",
        "ANTHROPIC_AUTH_TOKEN": os.environ["ROUTER_ONE_API_KEY"],
    },
    max_turns=3,
)


async def main() -> None:
    prompt = "Reply with one short greeting."
    async for message in query(prompt=prompt, options=options):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print(f"{message.subtype}: {message.num_turns} turn(s)")


asyncio.run(main())

哪些选项决定网关收到什么

ClaudeAgentOptions 的大多数字段只影响引擎在本地做什么，下表是会改变 Router One 收到的请求的几个；TypeScript 侧是 Options 对象上同名的驼峰字段，其中一个在两套 SDK 里行为不同。

给一次 query 设预算，并在 Logs 里逐轮核账

一次 query() 调用是一串 Messages 请求：每轮至少一次，引擎拉起 subagent 时更多，再加上 Claude Code 引擎文档里写明的后台请求。max_turns 限制的是工具调用轮数而不是花费；max_budget_usd 比较的是按公示价算出的估算值，官方文档明确说它可能与实际账单偏离，不能据此做财务决策。给这个 Agent 单独建一把设了 maxSpend 的 Router One Key，然后到 Dashboard → Logs 看这次运行：按该 Key 和精确模型过滤，把 Trace 对到运行的时间窗和 ResultMessage 的 num_turns，失败的 Trace 保留 request_id。结果里的 total_cost_usd 是 SDK 的估算，网关每条 Trace 记录的费用才是实际扣费。Router One 只提供并记录模型请求：工具执行、hooks、权限检查、会话和 subagent 都在 SDK 里、在你的机器或容器上运行。

Claude Agent SDK 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Claude Agent SDK 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

Claude Agent SDK 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

在 trace 里验证 Claude Agent SDK 的调用

先在 Claude Agent SDK 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

常见问题