用Claude Agent SDK构建CLI工具：把settings改到TaoToken

1. 为什么 CLI 场景下要把 Claude Agent SDK 的 settings 改到 TaoToken用 Claude Agent SDK 搭 CLI 工具最容易被忽略的一步不是写 query 循环而是把 settings 里的 endpoint 和鉴权通道改对。默认情况下SDK 会去读环境变量里的ANTHROPIC_API_KEY并请求官方地址。你在本地跑没问题一旦要把 CLI 交给团队、塞进 CI、或者让多个项目共用一套 Key就会遇到三个现实问题Key 散落在每台机器上、额度无法统一看、换模型要改代码。TaoToken 在这里扮演的角色是统一 Key/API 通道。你只需要在 settings 里把 base URL 指向https://taotoken.net/api把 Key 换成 TaoToken 控制台里生成的那一串SDK 的其余调用逻辑完全不用动。CLI 工具本身还是你写的那个 CLIquery() 还是 query()ClaudeSDKClient 还是 ClaudeSDKClient变的只是它把请求发到哪里、用哪把钥匙。我试过在一个内部部署助手项目里做这件事最直观的收益是新同事拉下代码后只要在 settings 里填一次 Key不用再问“官方 Key 在哪”。对 CLI 这种要被反复分发、在管道和 CI 里跑的工具来说配置集中化比什么都重要。这一篇就围绕“把 settings 改到 TaoToken”这件事给你可复制的 settings 片段、query 和 ClaudeSDKClient 两种调用示例以及跑起来后怎么验证请求真的成功了。适合已经在用 Claude Agent SDK 写 CLI、但还没把通道统一起来的开发者。2. TaoToken 前置准备Key、Base URL 与 settings 读取顺序在动 settings 之前先把三样东西确认清楚否则后面排错会绕远路。第一是 Key。去 TaoToken 控制台生成一个 API Key形如sk-...。这个 Key 就是你要写进 settings 或环境变量的凭证。生成入口在控制台的 API Keys 页面建议给 CLI 单独建一个 Key方便按工具维度看用量。第二是 Base URL。TaoToken 的 API 地址是https://taotoken.net/api。注意这里不要带任何查询参数SDK 会自己在后面拼/v1/messages之类的路径。很多人排错时发现 404就是因为把带 UTM 的官网地址误当成了 API 地址填进去。第三是 settings 的读取顺序这是最容易踩坑的地方。Claude Agent SDK 的配置来源大致有这么几层优先级从高到低来源说明适合场景代码里显式传入的 options直接写在 ClaudeAgentOptions 里临时调试、单次覆盖项目级 settings 文件项目根目录下的配置文件团队共享、随代码走用户级 settings用户主目录下的配置个人机器全局默认环境变量ANTHROPIC_API_KEY、ANTHROPIC_BASE_URLCI、容器关键点在于如果你在代码里硬编码了api_key它会盖过 settings 文件如果你只在 settings 文件里写环境变量又可能反过来干扰。所以统一通道时最稳的做法是“只留一处真源”。我一般推荐把 Base URL 和 Key 都放进项目级 settings代码里不写死环境变量在 CI 里再覆盖。这里要提醒一句TaoToken 是合规的 API 通道服务你把它当成一个标准的 Anthropic 兼容 endpoint 来用就行不需要任何额外网络配置。settings 里填的就是一个普通的 HTTPS 地址。准备好 Key 和 Base URL 后先别急着写 CLI 主逻辑下一步我们直接把 settings 片段落地。3. 可复制配置settings 片段与 ClaudeAgentOptions 写法这一节是全文的核心给你能直接抄的配置。分两部分settings 文件片段以及代码里 ClaudeAgentOptions 的写法。先看项目级 settings。Claude Agent SDK 支持从项目读取配置常见做法是在项目根目录放一个 settings 文件。下面是一个可复制的 JSON 片段路径按你项目实际结构调整{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5 }, permissions: { allow: [Read, Glob, Grep, Bash], deny: [] } }如果你更习惯用 TOML 风格管理等价写法如下[env] ANTHROPIC_BASE_URL https://taotoken.net/api ANTHROPIC_API_KEY sk-你的TaoToken密钥 ANTHROPIC_MODEL claude-sonnet-4-5 [permissions] allow [Read, Glob, Grep, Bash] deny []注意ANTHROPIC_BASE_URL结尾不要带斜杠也不要带/v1。SDK 内部会自己拼接版本路径你多写一层就会变成/api/v1/v1/messages直接 404。再看代码侧。如果你不想依赖 settings 文件或者想在 CLI 启动时动态注入可以直接在 ClaudeAgentOptions 里写。下面这段是 query() 场景的最小配置import anyio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage async def main(): options ClaudeAgentOptions( cwd., allowed_tools[Read, Glob, Grep, Bash], env{ ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5, }, ) async for message in query(prompt读取当前目录结构并解释项目用途, optionsoptions): if isinstance(message, ResultMessage): print(message.result) anyio.run(main)这里有个细节env字段传入的变量会注入到 SDK 子进程的环境里优先级高于用户级 settings但低于你显式写在 options 顶层的api_key。所以如果你既写了env又写了顶层api_key以顶层为准。统一通道时建议二选一别两处都写否则排查起来很痛苦。三件套对照一下避免漏项配置项值写在哪Base URLhttps://taotoken.net/apisettings 的 env 或 options.envAPI Keysk-...同上建议只留一处Model ID如claude-sonnet-4-5同上或运行时按参数覆盖把这三样填对通道就通了。接下来写调用示例验证它真的能跑。4. query 与 ClaudeSDKClient 调用示例CLI 主循环怎么写配置对了接下来是 CLI 的主循环。Claude Agent SDK 给你两个入口query() 适合一次性任务ClaudeSDKClient 适合多轮对话和细粒度控制。CLI 工具通常两者都会用到——简单子命令走 query交互式会话走 ClaudeSDKClient。先看 query() 版本适合mycli ask ...这种一问一答import sys import anyio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage async def run_once(prompt: str): options ClaudeAgentOptions( cwd., allowed_tools[Read, Glob, Grep, Bash], env{ ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5, }, max_turns20, ) async for message in query(promptprompt, optionsoptions): if isinstance(message, ResultMessage): print(message.result) def main(): prompt .join(sys.argv[1:]) or 你能帮我什么 anyio.run(run_once, prompt) if __name__ __main__: main()跑起来就是python mycli.py 解释这个仓库的入口文件。query() 会在内部管理对话、工具调度和多轮推理你只负责把最终 ResultMessage 打出来。再看 ClaudeSDKClient 版本适合需要流式输出、中断、多轮上下文的交互式 CLIimport anyio from claude_agent_sdk import ( ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock, ResultMessage, ) async def interactive(): options ClaudeAgentOptions( cwd., allowed_tools[Read, Glob, Grep, Bash], env{ ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5, }, permission_modedefault, max_turns20, ) async with ClaudeSDKClient(optionsoptions) as client: await client.query(解释认证模块的实现) async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(block.text, end, flushTrue) elif isinstance(message, ResultMessage): print(f\n完成 (停止原因: {message.stop_reason})) anyio.run(interactive)两者的区别值得说清楚query() 每次调用是独立的不保留会话历史ClaudeSDKClient 维护会话你可以在同一个 client 上多次query()上下文会累积。CLI 里如果要做“连续追问”用后者如果每个子命令都是独立任务用前者更省心。如果你还要挂自定义 MCP 工具比如一个部署工具写法是在 options 里加mcp_serversfrom claude_agent_sdk import tool, create_sdk_mcp_server tool(check_service_health, 检查服务健康状态, {service: str}) async def check_service_health(args): service args[service] return {content: [{type: text, text: f{service} 状态正常}]} server create_sdk_mcp_server(ops-tools, tools[check_service_health]) options ClaudeAgentOptions( cwd., allowed_tools[Read, Bash, mcp__ops-tools__check_service_health], mcp_servers{ops: server}, env{ ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5, }, )注意 MCP 工具在 allowed_tools 里的命名格式是mcp__server名__tool名写错了工具就不会被调用模型会一直说“我没有这个工具”。5. 常见报错排查401、local proxy failed、reading choices、OAuth配置和代码都写好了跑起来却报错这是最耗时间的阶段。下面按真实报错逐条对照。401 Unauthorized。最常见的原因是 Key 没生效或写错位置。先确认你填的是 TaoToken 控制台生成的 Key不是官方 Key再确认它写在 settings 的env.ANTHROPIC_API_KEY或 options 的env里而不是散落在别处。如果同时存在环境变量和 settings环境变量可能盖过 settings用echo $ANTHROPIC_API_KEY看一眼当前 shell 里有没有残留旧值。还有一种情况是 Key 前后带了空格或换行复制时很容易带上建议用引号包住。local proxy failed / connection refused。这个报错通常意味着 SDK 尝试连接的地址不对。检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/多了斜杠或https://taotoken.net/api/v1多了版本号。正确值就是https://taotoken.net/api。另外确认你的机器能正常访问这个 HTTPS 地址用curl -I https://taotoken.net/api看返回头即可不需要任何额外网络配置。reading choices / 响应解析失败。这类报错往往出现在模型 ID 写错的时候。比如你填了一个 TaoToken 通道不支持的模型名服务端返回的结构和 SDK 预期不一致解析就炸了。对照控制台里可用的模型列表把ANTHROPIC_MODEL改成受支持的值比如claude-sonnet-4-5。如果你在 CLI 里做了模型参数透传也要检查用户传进来的值有没有被原样塞进 options。OAuth / authentication_error。如果你之前用过 Claude Code 的登录态本地可能残留了 OAuth 凭证SDK 会优先走那套流程导致和你的 Key 冲突。排查方法是清掉相关的本地凭证缓存或者显式在 options 里传api_key让它盖过 OAuth。CLI 工具面向团队分发时建议直接禁用 OAuth 路径统一走 Key避免每个人机器状态不一样。把这几类报错对照完基本能覆盖 90% 的接入问题。剩下的边角情况多半是 settings 读取顺序没理清回到第 2 节那张优先级表再对一遍。6. 验证请求成功与后续接入路径配置写完不算完得有一个明确的动作证明请求真的走通了 TaoToken。我一般用三步验证。第一步最小连通性测试。写一个只发一句话、不带任何工具的脚本import anyio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage async def ping(): options ClaudeAgentOptions( env{ ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5, }, ) async for message in query(prompt回复通道正常, optionsoptions): if isinstance(message, ResultMessage): print(RESULT:, message.result) anyio.run(ping)跑出来打印RESULT: 通道正常之类的文本说明 Base URL、Key、Model 三件套都对了。如果这一步就报 401回到第 5 节。第二步带工具的验证。把allowed_tools[Read]加上prompt 改成“读取当前目录下的 README 并总结”。如果模型能调用 Read 工具并返回文件内容摘要说明工具调度链路也通了。这一步能顺带验证 MCP 配置有没有写错命名。第三步去 TaoToken 控制台看用量。请求成功后控制台的调用记录里应该能看到刚才这几次请求模型、时间、token 数都对得上。这是最硬的证据——本地打印可能是缓存控制台记录不会骗人。三步都过你的 CLI 工具就算正式接上 TaoToken 通道了。后续如果要做长期编码或 Agent 类任务可以了解 Coding Plan如果只是想快速验证某个模型的表现直接用模型对话页面试接入过程中遇到文档细节问题接入文档里有完整的参数说明。Key 的管理和轮换在 API Keys 页面建议给不同 CLI 工具分配不同 Key方便按工具看用量。最后说个实用技巧把 Base URL 和 Model ID 做成 CLI 的启动参数或环境变量覆盖项Key 只从 settings 读。这样团队成员换模型不用改代码而你也不用担心 Key 被写进 git。CLI 工具的价值在于可组合、可分发配置设计上多留一层覆盖后面会省很多事。