1. 多 Agent 协作的真实痛点为什么你的 SubAgent 总是“各干各的”很多人第一次接触 Agent 编排脑子里想的都是“主 Agent 派活、子 Agent 干活、最后汇总”这么一条顺滑流水线。真跑起来才发现SubAgent 要么收不到足够上下文要么拿到的 prompt 里塞了一堆无关历史要么几个子任务互相踩文件最后主 Agent 汇总时发现结果对不上。问题不在模型能力而在创建方式、上下文传递边界和调度策略这三件事没拆清楚。我先把概念对齐一下避免后面看代码时混淆。Tool 是扳手被调用一次做一件事SKILL 是工具箱里面装着若干工具和使用说明被动响应Agent 是工匠拿到目标后自己规划路径、选工具、验证结果、决定什么时候停。SubAgent 就是主 Agent 临时请来的另一个工匠它有自己独立的 Agent Loop但只拿到主 Agent 精选过的那部分信息。这套机制能解决什么举个最典型的场景你让主 Agent“全面审查这个项目”它会把任务拆成结构分析、安全审查、性能审查、规范检查四条线分别 spawn 四个 Explore 类型 SubAgent 并行跑谁先完成谁先回传主 Agent 边等边整合甚至根据某个子结果动态再开一个新 SubAgent 去深挖。整个过程不需要你手动编排但前提是底层模型通道得稳、得能同时扛住多个并发请求。适合谁看已经会用 Claude Code 或类似 Agent 框架、想搞明白 SubAgent 背后到底怎么调度的人以及正在搭多模型协作链路、被“上下文丢失”和“并发限流”折腾过的开发者。下面我会从创建、上下文传递、调度三个层面拆开讲并且用 TaoToken 的统一 Key 通道把多模型接入这一段跑通让你有一条能直接复制的链路。2. TaoToken 统一 Key 通道多模型接入的前置准备多 Agent 系统里最容易被忽略的坑是每个 SubAgent 可能要用不同模型。Explore 类型做只读搜索用便宜快的模型就够Plan 类型做方案设计得用推理强的安全审查可能想换个模型交叉验证。如果每个模型都单独配一套 Key、单独改一遍 Base URL配置管理会迅速失控。TaoToken 的价值就在这里一个 Key、一个 Base URL通过 Model ID 切换背后调用的模型Agent 和 SubAgent 共用同一条通道。先明确三个必须对齐的参数后面所有配置都围绕它们参数值说明Base URLhttps://taotoken.net/api所有请求的统一入口不要加 UTMAPI Key在控制台创建一个 Key 通吃多模型Model ID按需填写决定这次请求实际走哪个模型获取 Key 的路径很直接打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建完先别急着往 Agent 里塞用模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 发一条消息验证 Key 是活的这一步能省掉后面大量“到底是 Key 错还是配置错”的排查时间。为什么强调“统一通道”对多 Agent 特别重要因为 SubAgent 是动态创建的数量不确定、类型不确定。如果每个 SubAgent 都要独立鉴权、独立配 endpoint主 Agent 在 spawn 的时候就得把鉴权信息也一起传下去这既增加了 prompt 的复杂度也把密钥暴露在了上下文里。统一通道之后SubAgent 只需要知道自己该用哪个 Model ID鉴权由运行环境统一处理。这里有个设计上的取舍值得说清楚TaoToken 是合规的 API 聚合通道不是让你绕过什么限制它的定位是帮你把多模型调用收敛到一个入口方便计费、方便切换、方便在 Agent 编排里做模型路由。你把它理解成“模型调用的统一网关”就行。配置层面我建议把 Base URL 和 Key 放在环境变量里不要硬编码进 Agent 配置。原因后面排障章节会讲——当 SubAgent 在隔离环境比如 git worktree里运行时环境变量是最可靠的传递方式。先执行export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYsk-你的Key验证环境变量生效echo $TAOTOKEN_BASE_URL echo $TAOTOKEN_API_KEY | head -c 8第二条只打印前 8 位避免 Key 完整出现在终端历史里。这一步做完前置准备就算齐了接下来进入真正可复制的配置环节。3. 可复制配置Agent 与 SubAgent 的创建模板这一节给三份能直接用的配置片段一份是 Agent 运行时的 settings 配置一份是 SubAgent 的创建调用 JSON一份是 Claude Code 场景下的 settings.json。三份都对齐同一个 Base URL、Key、Model ID 三件套。先看运行时的 settings 配置我用 TOML 写方便你放进项目根目录# agent-settings.toml [provider] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [models] # 主 Agent 用推理强的模型 main claude-sonnet-4-20250514 # Explore 类型 SubAgent 用快而省的模型 explore claude-haiku-4-20250514 # Plan 类型 SubAgent 用推理强的模型 plan claude-sonnet-4-20250514 [subagent] default_type general-purpose default_isolation shared max_parallel 4 timeout_seconds 300注意api_key_env指向的是环境变量名不是 Key 本身。这样配置可以进版本库Key 留在本地环境。max_parallel 4是并发上限后面调度章节会解释为什么这个值不能拍脑袋定。再看 SubAgent 的创建调用这是主 Agent 实际发出的结构字段含义我在注释里标清楚{ tool: Agent, parameters: { description: 审查认证模块安全漏洞, prompt: 分析 src/auth/ 目录下的认证逻辑重点检查1) token 刷新时机是否存在竞态2) 权限校验是否可绕过3) 密钥是否硬编码。输出 Markdown包含文件路径、函数签名、风险等级。只搜索 src/auth/忽略 test/。, subagent_type: Explore, run_in_background: true, isolation: worktree, model: claude-haiku-4-20250514 } }这里model字段就是统一通道的落点——同一个 Base URL、同一个 Key靠这个字段切换实际模型。prompt是上下文传递的唯一载体这一点下一节展开。isolation: worktree让 SubAgent 在 git worktree 副本上跑改文件不影响主工作区。最后是 Claude Code 场景下的 settings.json路径放在~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [Read, Grep, Glob] } }三件套在这里的对应关系是Base URL 填ANTHROPIC_BASE_URLKey 填ANTHROPIC_API_KEYModel ID 填ANTHROPIC_MODEL。如果你用的是 Cline 或带 MCP 的客户端配置逻辑一样只是字段名不同——Base URL、Key、Model ID 这三个位置必须都填对缺一个就会在请求阶段报错。配置写完先别急着跑多 Agent用单次请求验证通道。这一步很关键因为多 Agent 出问题时你很难判断是通道问题还是编排问题。验证命令curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-haiku-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }返回里能看到content字段带正常文本说明 Base URL、Key、Model ID 三件套全部对齐。这一步过了再往上叠 Agent 编排出问题就能快速定位到是编排层而不是通道层。4. 上下文传递与调度验证从创建到结果回传上下文传递是 SubAgent 机制里最容易被误解的地方。很多人以为 SubAgent 会自动继承主 Agent 的完整对话历史实际上不会。SubAgent 收到的只有prompt参数里的内容主 Agent 的对话历史、之前的 tool_call 结果、用户的原始输入、主 Agent 的思考过程SubAgent 一概看不到。这个设计是有意的控制上下文窗口、减少干扰、做安全隔离、省 token。所以主 Agent 构造 prompt 的策略直接决定 SubAgent 能不能干对活。我实测下来有效的 prompt 遵循四条原则说目标不说步骤让 SubAgent 自己规划、给关键上下文不给全部历史、指定输出格式、设置边界。对比一下差先搜索文件 A再读文件 B然后分析第 42 行…… 好分析认证系统的架构找出所有安全漏洞 差粘贴整个之前的对话记录 好我们在重构 auth 模块已知问题有 token 竞态和权限绕过 差随便输出点东西 好输出 Markdown包含文件列表、函数签名、调用关系 差搜索整个项目 好只搜索 src/auth/忽略 test/验证上下文传递是否按预期工作最直接的办法是在 SubAgent 的 prompt 里埋一个只有主 Agent 知道的标记然后看 SubAgent 的输出里有没有用到它。比如主 Agent 在 prompt 里写“本次审查基于 commit a1b2c3d”如果 SubAgent 输出里引用了这个 commit说明上下文透传成功如果 SubAgent 说“我不知道基于哪个版本”说明 prompt 构造漏了信息。调度层面同步和异步的选择决定了整个链路的形态。同步模式run_in_background: false下主 Agent 阻塞等待适合结果直接影响下一步决策的场景比如先搜索代码再决定怎么改。异步模式run_in_background: true下主 Agent 立即拿到 task_id 继续干活适合多个独立任务并行比如同时搜前端、后端、配置。并行调度的实际时间轴是这样的SubAgent A ████████████████████░░░░░░░░ 已完成 SubAgent B ██████████████████████████████ 已完成 SubAgent C ██████████░░░░░░░░░░░░░░░░░░ 已完成 主 Agent t0: 同时创建 A、B、C全部 run_in_background: true t0: 收到三个 task_id记录到任务列表 t0: 主 Agent 继续执行自己的任务不阻塞 t1: 收到通知 → C 完成取回结果并入上下文 t2: 收到通知 → A 完成发现新问题 → 创建 SubAgent D t3: 收到通知 → B 完成所有结果收集完毕 → 整合输出关键点是主 Agent 不等待所有 SubAgent 完成才行动它边等边做收到一个处理一个甚至根据某个子结果动态再开新 SubAgent。这就是 Agent Loop 五步循环Plan → Execute → Observe → Decide → 循环在调度层的体现。依赖管理有三种典型模式。完全并行无依赖三个 SubAgent 同时启动各自完成串行依赖链A 的结果作为 B 的输入B 的结果作为 C 的输入必须逐个等待混合依赖最复杂也最常见A 和 C 并行B 等 AD 等 CE 等 B 和 D 都完成。混合依赖下主 Agent 的调度逻辑要显式写清楚“等谁完成再启动谁”不能靠默认行为。验证调度是否按预期并行可以在每个 SubAgent 的 prompt 里让它输出开始和结束时间戳然后对比时间轴。如果三个本该并行的 SubAgent 时间戳是串行的说明run_in_background没设成 true或者并发上限被卡住了。5. 常见报错排查401、local proxy failed、reading choices、OAuth多 Agent 链路出问题时报错信息往往指向底层通道而不是编排逻辑。这一节把四类高频报错和对应处理列清楚你按顺序排查基本能定位。401 Unauthorized。最常见的原因是 Key 没传对或环境变量没生效。先确认环境变量在当前 shell 里可见echo $TAOTOKEN_API_KEY | head -c 8如果为空说明 export 没执行或在新终端里丢了。如果 Key 有值但仍 401检查请求头字段名是否正确——Anthropic 风格用x-api-keyOpenAI 风格用Authorization: Bearer两者不能混。还要确认 Base URL 没有多余斜杠https://taotoken.net/api后面不要再拼/v1之外的路径。local proxy failed。这个报错通常出现在客户端配置了本地代理但代理没起来或者 Base URL 指向了本地地址。检查你的 settings.json 里ANTHROPIC_BASE_URL是不是被改成了http://localhost:xxxx之类的本地地址。统一通道场景下Base URL 应该直接是https://taotoken.net/api不需要经过任何本地转发。如果确实需要本地代理做日志确保代理进程在跑且端口对得上。reading choices 相关报错。这类报错一般出现在 OpenAI 兼容格式的响应解析阶段说明返回结构里没有choices字段。原因通常是 Model ID 填错了请求打到了不支持该格式的模型上或者 Base URL 路径不对导致返回了错误页而不是 JSON。排查方法用第 3 节的 curl 命令直接打一次看返回体是 JSON 还是 HTML。如果是 HTML说明路径错了如果是 JSON 但没有 choices说明 Model ID 和接口格式不匹配。OAuth 相关报错。如果你用的是 Claude Code 或 Codex 这类带 OAuth 登录的客户端报错可能来自它尝试走 OAuth 流程而不是 API Key。这时候要确认配置里用的是 API Key 模式而不是登录态模式。Claude Code 场景下ANTHROPIC_API_KEY和 OAuth 登录态是互斥的配了 Key 就走 Key不要再触发登录流程。Codex 的auth.json里如果同时有 OAuth token 和 API Key优先走哪个取决于客户端版本建议清掉 OAuth 部分只留 Key。排查顺序建议固定成先 curl 验证通道 → 再验证单 Agent 请求 → 最后验证多 Agent 编排。这样每层都能独立确认不会出现“改了五处配置不知道哪处生效”的情况。另外SubAgent 在 worktree 隔离环境里跑时环境变量可能不继承如果隔离环境下报 401检查是不是 Key 没通过环境变量传进去。6. 把链路跑稳从单 Agent 到多 Agent 的落地建议多 Agent 协作链路能不能稳定跑取决于几个容易被忽略的细节。第一是 prompt 粒度太粗 SubAgent 理解困难太细又失去自主决策优势。“分析 src/auth/ 下的认证逻辑”是好粒度“审查整个项目”太粗“读 login.ts 第 42 行”太细。第二是并行上限max_parallel不要拍脑袋设成 10要看你用的模型通道的并发承载能力设成 4 左右先跑观察有没有限流再调。第三是结果验证SubAgent 也会出错主 Agent 收到结果后要检查完整性、交叉验证重叠范围、关键发现自己复查。如果你打算长期跑多 Agent 编码或 Agent 类任务Coding Plan 比按次调用更划算入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各客户端的完整配置示例。Claude Code 专项接入参考 https://taotoken.net/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。最后给一个实用技巧在项目根目录放一个.agent/config.toml把 Base URL、Model ID 映射、并发上限写进去主 Agent 和 SubAgent 都从这里读。这样切换模型或调整并发时只改一处不用满项目找配置。跑通之后你会发现SubAgent 机制真正的价值不是“多开几个进程”而是让主 Agent 能根据任务形态动态决定拆不拆、拆几个、用哪个模型——这套决策能力才是 Agent 和普通脚本的本质区别。