1. 从单体 Agent 到微服务我为什么开始拆 Subagent如果你正在做 AI Agent 开发大概率遇到过这种场景一个主流程里塞了十几个工具调用既要它做复杂推理又要它顺手把 3000 行日志总结成三句话、把一段 HTML 抽成 JSON、把用户上传的合同里“退款条款”找出来。结果就是主模型上下文越来越长token 账单越来越吓人而且它还会在长上下文里“走神”——前面说过的约束后面就忘了。OpenRouter 推出的openrouter:subagent工具本质上就是给这种“单体 Agent”开了一刀让一个强模型当 Orchestrator编排者把那些机械、独立、I/O 密集型的子任务下放给一个更便宜、更快的子模型去干。子模型看不到主模型的历史对话只能看到主模型显式传过去的task_description干完活把结果吐回来。这个隔离机制非常关键它让每个子任务变成一个干净的工作单元不会污染主模型的上下文。这像什么像后端从单体应用拆成微服务。主脑负责决策和编排Subagent 负责单一职责的执行。你可以给“总结专员”配一个便宜模型给“爬虫专员”配一个带 web_search 的子模型各司其职成本和质量都能控。但这里有个现实问题多 Subagent 编排意味着你要管理多个模型通道、多套 Key、多个 Base URL。如果每个子模型都去单独申请 Key、单独配环境变量调试成本会迅速吃掉你省下来的 token 钱。所以这篇我会结合 TaoToken 统一 Key/API 通道把“Subagent 微服务化”从概念落到可复制的配置和验证动作上。TaoToken 官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 端点是 https://taotoken.net/api 一个 Key 走多个模型正好适配这种“主脑 多个廉价双手”的架构。下面我会按“先讲清机制 → 配好统一通道 → 写可复制配置 → 验证调用链 → 排错”的顺序来你可以跟着一步步搭出一个可观测的 Agent 微服务化原型。2. TaoToken 统一 Key 通道多 Subagent 编排的前置准备在拆 Subagent 之前先解决“通道”问题。多智能体编排最烦的不是写 prompt而是模型接入层主模型用一家、子模型用另一家、搜索工具再挂一家Key 散落在.env、settings.json、auth.json里换一个模型就要改一处配置。TaoToken 的思路是提供一个统一的 OpenAI 兼容入口你用同一个 Key、同一个 Base URL就能在多个模型之间切换。这对 Subagent 场景特别合适因为主脑和子模型本来就是不同模型统一通道能让配置收敛到一处。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来形如sk-...的字符串。这个 Key 就是你后面所有模型调用的凭证。注意不要把它提交到 Git建议放环境变量或本地配置文件。拿到 Key 后记下两个地址Base URLhttps://taotoken.net/api注意不要加 UTM 参数这是给程序调用的模型对话调试页https://taotoken.net/model-chat 用来快速验证某个模型 ID 是否可用如果你用的是 Claude Code 这类编码 AgentTaoToken 也提供了对应的接入文档https://taotoken.net/doc 。里面会说明 Base URL、Key、Model ID 三件套怎么填。对于本文的 Subagent 场景我们主要用 OpenAI 兼容的/v1/chat/completions接口所以任何支持自定义 Base URL 的 SDK 都能接。这里有个容易踩的坑很多人把官网首页地址https://taotoken.net/?utm_source...直接填进代码的 Base URL结果请求 404 或返回 HTML。代码里必须用https://taotoken.net/api带 UTM 的是给浏览器访问的推广链接不是 API 端点。这个区别在排错章节我会再强调一次。配置方式我推荐用环境变量跨语言通用export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用 Cline、CC Switch 这类工具它们通常有图形化的模型配置面板填三件套即可Base URL 填https://taotoken.net/apiAPI Key 填你的sk-...Model ID 填具体模型名比如anthropic/claude-opus-4.8或z-ai/glm-5.2。Cline 的 MCP 配置里如果要用到模型也是同样的三件套逻辑别只填 Key 忘了 Base URL。前置准备做完你应该有一个可用的 Key、一个统一的 Base URL、以及至少两个模型 ID一个强模型当主脑一个便宜模型当 Subagent。接下来进入可复制配置环节。3. 可复制配置Subagent 编排的 JSON 与 settings 片段这一节给你可以直接抄的配置。Subagent 的核心是在主模型请求的tools数组里加一个openrouter:subagent工具并指定子模型。下面是一个完整的最小可用请求体主脑用 Claude Opus子模型用 GLM{ model: anthropic/claude-opus-4.8, messages: [ { role: user, content: 审计这次发布总结变更日志列出破坏性更新并起草一份发布公告。 } ], tools: [ { type: openrouter:subagent, parameters: { model: z-ai/glm-5.2, instructions: 你是一个快速、专注的执行者。严格按照任务描述完成不要展开无关内容。 } } ] }如果你想让子模型自己带工具比如联网搜索可以这样写{ tools: [ { type: openrouter:subagent, parameters: { model: z-ai/glm-5.2, instructions: 你是一个专注的信息提取员只返回结构化结果。, tools: [ { type: openrouter:web_search } ] } } ] }子模型会在内部跑自己的“思考-行动”循环最后只把最终结果返回给主模型。主模型看不到子模型的中间步骤这样上下文就不会被污染。如果你用 Python 的 OpenAI SDK 走 TaoToken 通道配置长这样import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) resp client.chat.completions.create( modelanthropic/claude-opus-4.8, messages[ {role: user, content: 把这份 2000 行日志总结成 5 条关键事件并抽取成 JSON。} ], tools[ { type: openrouter:subagent, parameters: { model: z-ai/glm-5.2, instructions: 你是日志分析专员只输出 JSON。 } } ], ) print(resp.choices[0].message.content)如果你用 Cline 或 CC Switch它们的配置文件通常是 JSON 或 TOML。以 Cline 的settings.json为例模型配置部分要写全三件套{ apiProvider: openai, openAiBaseUrl: https://taotoken.net/api, openAiApiKey: sk-你的Key, openAiModelId: anthropic/claude-opus-4.8 }Codex 的auth.json也是类似逻辑Base URL 指向https://taotoken.net/apiKey 填进去Model ID 填具体模型。记住Base URL、Key、Model ID 三件套缺一不可只填 Key 会报 401只填 Base URL 会报模型不存在。配置写好后先别急着跑复杂编排用一个小任务验证通道是否通。下一节讲验证动作。4. 验证请求与成功结果确认调用链真的跑通了配置写完第一步不是直接上生产任务而是发一个最小请求确认主模型能调起 Subagent、子模型能返回结果。我建议用 curl 先打一发排除 SDK 层的干扰curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: anthropic/claude-opus-4.8, messages: [ {role: user, content: 请把这句话总结成三个关键词OpenRouter Subagent 让主模型把机械任务下放给便宜子模型实现隔离执行和成本控制。} ], tools: [ { type: openrouter:subagent, parameters: { model: z-ai/glm-5.2, instructions: 你是关键词提取专员只返回三个关键词。 } } ] }成功的话你会看到返回的choices[0].message.content里有三个关键词同时usage字段会显示 token 消耗。注意观察主模型的 token 消耗应该只包含它自己的推理部分子模型的消耗会单独计费。如果你在 TaoToken 的 consolehttps://taotoken.net/console 里看用量能看到不同模型的调用分开统计这正是 Subagent 成本可控的证据。如果返回里出现tool_calls字段说明主模型决定调用 Subagent这是正常流程。有些模型会先返回一个 tool_call然后你需要把工具结果回传再拿最终回复。OpenRouter 的 Subagent 是服务端执行的所以通常你直接拿到最终结果不需要自己回传。但如果你用的是自建编排就要处理这个两段式流程。验证通过后可以做一个更接近真实的编排测试让主模型处理一个长文档任务观察它是否把“总结”和“抽取 JSON”拆给 Subagent。你可以故意在 prompt 里写“先总结再抽取字段”然后看返回结构。实测下来主模型会倾向于把这两个 I/O 密集型步骤委派出去自己只做最终整合。还有一个验证点子模型的隔离性。你可以在主模型的对话历史里放一段“暗号”然后让 Subagent 去回答一个需要暗号的问题。如果 Subagent 答不出来说明隔离生效了——它确实看不到主模型的历史上下文。这个测试能帮你确认架构符合预期。调用链跑通后你就有底气上多 Subagent 编排了。但真实项目里报错是常态下一节把我踩过的坑列出来。5. 常见报错排查401、local proxy failed 与 choices 读取失败多 Subagent 编排的报错八成集中在通道配置和响应解析上。下面按真实报错逐个拆。401 Unauthorized最常见。原因通常是 Key 没填对、Key 过期、或者把官网首页地址当成了 Base URL。检查顺序先确认Authorization: Bearer sk-...里的 Key 是从 https://taotoken.net/api-keys 复制的完整字符串没有多余空格再确认 Base URL 是https://taotoken.net/api不是带 UTM 的推广链接。如果你用 Cline 或 CC Switch检查settings.json里的openAiApiKey和openAiBaseUrl是否都填了。只填 Key 不填 Base URL请求会打到默认的 OpenAI 端点自然 401。local proxy failed / connection refused这个报错通常出现在你本地配了代理但代理没启动或者环境变量HTTP_PROXY指向了一个不存在的端口。先检查你的 shell 里有没有残留的代理环境变量env | grep -i proxy如果有临时清掉再试unset HTTP_PROXY HTTPS_PROXY ALL_PROXY另外如果你在 Docker 或 WSL 里跑localhost可能指向容器内部而不是宿主机Base URL 要用宿主机的可达地址。这个和 Subagent 本身无关但会伪装成“通道不通”。reading choices of undefined这个报错说明你拿到的响应体里没有choices字段通常是请求失败返回了错误 JSON但你的代码直接去读resp.choices[0]。修复方式是先打印完整响应import json print(json.dumps(resp.model_dump(), ensure_asciiFalse, indent2))你会看到实际返回的是{error: {...}}。常见原因模型 ID 写错比如把z-ai/glm-5.2写成glm-5.2、tools 数组格式不对、或者子模型不支持某个工具类型。对照 TaoToken 的模型列表确认 Model ID 拼写。OAuth / auth.json 相关报错如果你用 Codex 或 Claude Code它们可能走 OAuth 流程而不是纯 API Key。这时候要确认auth.json里的配置是否指向了正确的 Base URL。Claude Code 的接入文档在 https://taotoken.net/doc 里面有完整的配置说明。如果你在 Claude Code 里做 Subagent 编排确保主模型和子模型的 Model ID 都在 TaoToken 支持的列表里。子模型不返回结果 / 一直转圈可能是子模型 ID 不可用或者instructions太长导致子模型超时。先用 https://taotoken.net/model-chat 单独测一下子模型能不能正常对话。如果单独测能通但编排时不返回检查tools数组的嵌套层级是否正确——openrouter:subagent的parameters里再套tools层级别写错。排错的核心思路是先隔离通道问题用 curl 直打再隔离模型问题用 model-chat 单测最后查编排逻辑打印完整响应。三步走下来大部分报错都能定位。6. 把 Subagent 用起来从原型到长期编码 Agent验证和排错都过了最后说怎么把它用进真实项目。Subagent 最适合的场景是“主脑做决策双手做苦力”。比如你在做一个代码审查 Agent主模型负责判断这次改动有没有架构风险Subagent 负责把 diff 总结成结构化清单、把相关测试用例抽出来、把日志里的错误聚类。这些子任务逻辑简单但 token 消耗大交给便宜模型正合适。如果你要长期跑编码 Agent比如让它在 CI 里自动审查 PR建议用 Coding Plan 这类长期方案来管理调用配额入口在 https://taotoken.net/coding-plan 。它比按次调用更适合高频、持续的 Agent 场景。配合统一 Key 通道主脑和多个 Subagent 的模型切换都在一处配置维护成本低很多。实际落地时我建议先从一个 Subagent 开始别一上来就拆五个。选一个最耗 token 的机械任务把它委派出去观察成本和质量变化。确认收益后再逐步增加 Subagent 的种类。每个 Subagent 的instructions要写清楚职责边界比如“只返回 JSON不要解释”这样主模型整合结果时更省心。另外Subagent 的隔离性是把双刃剑它不会污染主上下文但也意味着你不能指望它“记得”之前的对话。所以每个子任务都要自包含把必要的输入显式传进去。这一点在写task_description时要特别注意。最后别忘了可观测性。TaoToken 的 console 能看到不同模型的调用量和 token 消耗你可以据此判断哪些任务真的被委派出去了、省了多少钱。如果发现主模型还是自己干了所有活可能是instructions不够明确或者任务本身需要强推理不适合下放。多调几次你会找到适合自己项目的拆分粒度。