1. 为什么子代理的“最后一步”总是各走各的通道子代理Subagent的配置本身并不难在.cursor/agents/或.claude/agents/下写一个 Markdownfrontmatter 里声明model、tools、effort主 Agent 就能按描述把它调度起来。难的是“声明完了之后”——子代理的模型调用仍然走 Cursor 或 Claude Code 各自的官方通道Key 和 Base URL 分散在多个配置里换模型或者跨工具很容易配错。TaoToken 的思路是给这些 AI 编程工具一个统一的兼容通道先去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册并创建 API Key拿到一把 Key 和统一的 Base URLCursor 和 Claude Code 的子代理都从这一条路走模型调用。本文就按原文的目录节奏把创建、调用、参数、避坑和实战完整走一遍。1.1 子代理的上下文是独立的模型通道却不是原文对子代理的定义是“主 Agent 派生的专业智能体”它拥有独立上下文窗口、工具集和执行环境执行完任务只把结果摘要交回主 Agent。这个设计解决的是全局上下文污染主 Agent 不需要知道安全审计的每个细节收到一份“哪里有问题、怎么修”的结论就行。但请注意这个“独立”只到上下文和工具为止模型调用并没有独立。你写在 frontmatter 里的model字段最终还是交给 Cursor 或 Claude Code 的模型通道去发请求。也就是说子代理的职责拆得再精细只要通道没统一就会在“最后一步”断掉——你明明在 frontmatter 里指定了一个模型实际请求却走了另一个模型或者因为 Key 不对直接 401。1.2 子代理数量上来之后多 Key 分散才是真痛点当你只有一两个子代理时官方通道还能忍。等你按原文的实战案例建出 api-designer、db-expert、gis-processor、security-reviewer、test-writer 五六个角色每个角色还可能要不同模型麻烦就来了Cursor 里存一个 KeyClaude Code 的 settings.json 里又存一个 KeyCLI 临时会话再填一个 Key换个模型还要核对这个模型在哪个通道里可用。这不是配置能力的问题而是 Key 和 Base URL 的对应关系太分散。TaoToken 的解法很直接官网负责注册、建 Key、看模型广场和用量工具里只填一个统一的 Base URL。一处配好所有子代理的模型调用都收口到同一把 Key 上。1.3 官网和接口分开记就不会混使用 TaoToken 时有两类地址需要分清。一类是给人点的落地页https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 用来注册账号、创建 API Key、查看模型广场和用量记录。另一类是填进工具里的接口地址https://taotoken.net/api末尾不要加/v1。前者是控制台后者是数据通道混了就容易出现“官网能打开但工具一直报错”的情况。2. Cursor 子代理从 .cursor/agents/ 到模型通道两层配置分开看2.1 手动创建 security-auditor.mdfrontmatter 里先写清职责原文推荐在项目根目录创建.cursor/agents/文件夹新建一个 Markdown 文件比如security-auditor.md。下面的 frontmatter 可以直接复制使用--- name: security-auditor description: 检测代码中 OWASP Top 10 漏洞包括 SQL 注入、XSS、硬编码密钥等使用最小权限原则 model: claude-3-sonnet-20240229 tools: - Read - Grep - Glob - Bash effort: medium maxTurns: 20 --- # 安全审计专家子代理 ## 核心职责 1. 审查代码中的安全漏洞 2. 提供修复建议和代码示例 3. 生成详细审计报告 ## 审计流程 1. 使用 Grep 搜索敏感关键词password、secret、token 等 2. 检查输入验证和输出编码 3. 验证权限控制逻辑 4. 扫描依赖包漏洞注意这里的model: claude-3-sonnet-20240229是原文里的示例值。真实使用前请先到 TaoToken 的模型广场确认这个 ID 当前是否可用因为模型列表会随上游调整。保存后 Cursor 会自动识别这个子代理不需要重启。2.2 让子代理真正走 TaoToken在 Cursor 模型设置里配 Base URLfrontmatter 只解决了“子代理是谁”的问题没有解决“模型请求发给谁”。Cursor 在发起模型调用时读的是全局模型通道配置。你需要在 Cursor 的模型设置里添加一个自定义供应商OpenAI 兼容类型然后填写三个信息Base URLhttps://taotoken.net/apiAPI KeyYOUR_API_KEY模型 ID从模型广场复制和 frontmatter 里的model保持一致这里的YOUR_API_KEY是你从 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建的真实 Key。配好之后/subagent触发 security-auditor 时模型请求才会发到 TaoToken而不是 Cursor 的官方通道。2.3 命令行创建之后记得回头检查 model 字段在 Cursor 聊天框输入/subagent或/agent按提示输入名称、描述、工具集系统会自动生成配置文件并保存到.cursor/agents/目录。这种方式很方便但它只负责写文件不负责改模型通道。生成文件后打开这个新 Markdown确认model字段值与模型广场一致再回到模型设置里确认 Base URL 是https://taotoken.net/api。两步都对了显式调用和自动调用才都会走 TaoToken。3. Claude Code 子代理/agents、手动文件、CLI 三种方式都读同一组 env3.1 先把 ~/.claude/settings.json 的 env 配好Claude Code 的模型通道不在 frontmatter 里而在环境变量中。原文讲了三种创建子代理的方式但无论哪一种只要~/.claude/settings.json里的 env 配置好了通道就统一了。下面是一个可直接使用的配置示例{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: claude-3-sonnet-20240229 } }ANTHROPIC_BASE_URL指向 TaoToken 的统一接口地址末尾没有/v1ANTHROPIC_AUTH_TOKEN填你的 KeyANTHROPIC_MODEL是示例模型 ID具体以 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 的模型广场为准。配好这一组 env下面三种创建方式都会自动继承不需要每个子代理重复填 Key。3.2 /agents 可视化创建先选作用域在 Claude Code 聊天框输入/agents选择 Create new agent然后选作用域User-level全局可用保存到~/.claude/agents/Project-level仅当前项目可用保存到.claude/agents/输入名称、描述和工具集后Claude Code 会自动生成 frontmatter。你可以按e编辑系统提示。这个可视化流程不涉及 Key 配置因为 Key 和 Base URL 已经由 settings.json 里的 env 接管了。你只需要关注这个子代理负责什么、需要哪些工具。3.3 手动创建 gis-data-processor.md以及 CLI 临时会话如果你需要更精细地控制工具集和轮次手动创建文件是更好的方式。在.claude/agents/目录下新建gis-data-processor.mdfrontmatter 可以写成这样--- name: gis-data-processor description: 处理地理空间数据包括格式转换、投影变换、DEM 分析遵循 GIS 最佳实践 model: claude-3-opus-20240229 tools: - Read - Grep - GDAL - ArcGIS effort: high maxTurns: 30 use_proactively: true --- # GIS 数据处理专家 ## 核心能力 1. Shapefile 到 GeoJSON 格式转换 2. DEM 空洞修复与地形分析 3. 遥感影像语义分割 4. 生成 GIS 分析报告与可视化地图原文还提到一种 CLI 临时创建的方式适用于只想在当前会话里用一次的场景claude --agents { temp-gis-agent: { description: 临时 GIS 数据处理子代理, prompt: 你是 GIS 专家..., tools: [Read, GDAL] } }这个临时子代理虽然只存活于当前会话但它同样读取 settings.json 里配好的ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。也就是说三种创建方式最终都会把模型请求发到https://taotoken.net/api你用同一把 Key 就能跟踪所有调用。4. Frontmatter 字段对照model 负责“用哪个模型”通道负责“从哪条路走”4.1 主要字段作用表原文列了多个 frontmatter 字段。它们决定的是子代理的行为和边界而不是网络出口。下面这张表把几个关键字段的作用和配置建议整理在一起字段作用配置建议name子代理唯一标识小写加连字符一个子代理只做一件事名字要能体现职责description主 Agent 判断何时调用该子代理的依据写清楚触发场景避免“帮助开发”这类宽泛描述model指定该子代理使用的模型以 TaoToken 模型广场列出的 ID 为准tools授权工具列表只给完成任务必需的工具遵循最小权限effort执行成本low / medium / high复杂任务用 high简单任务用 lowmaxTurns最大交互轮次防止子代理跑偏或死循环use_proactively是否允许主 Agent 自动识别并调用需要自动调度时置为 true4.2 model 字段最容易配错很多人在配置子代理时凭印象写一个模型名比如看到教程里写了claude-3-sonnet-20240229就到处复制。问题是这个 ID 是否会一直有效需要看模型广场的实时列表。所以每次新建子代理之前先打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 的模型广场复制真实的模型 ID 再填进 frontmatter。这比事后查 400 错误要省事得多。4.3 tools 最小权限与渐进式披露原文多次强调渐进式披露和最小权限这两点在子代理配置里直接体现在description和tools上。description只放核心职责和触发条件详细规则放到子代理正文或独立文件里让子代理在需要时再读取。tools遵循最小权限原则能读文件就不给写能用Grep找到结果就不给Bash。工具给多了子代理容易做出计划外的操作上下文也会被无关信息污染。5. SPEC/PLAN 驱动的子代理协作调用记录在 TaoToken 控制台可查5.1 主 Agent 规划子代理分头执行原文的完整工作流是用户提出需求主 Agent 基于 SPEC 生成 PLAN把任务拆解给多个子代理并行执行每个子代理在独立上下文窗口里完成专项任务最后把结果摘要返回给主 Agent主 Agent 对照 SPEC 验收并输出最终代码和文档。在这个流程里每个子代理的模型调用都会产生一次独立的 API 请求。因为这些请求都发往https://taotoken.net/api所以你可以在一把 Key 下看到所有子代理的消耗而不需要分别登录 Cursor 和 Claude Code 的官方后台去核对。原文的主流程不需要改动只是把“模型通道”这一层换成了统一接入。5.2 在 PLAN 里指定子代理原文的 PLAN 集成用法很值得保留。你可以把子代理分工直接写进 PLAN让主 Agent 按计划调度## PLAN 1. api-designer 设计 RESTful API 2. gis-data-processor 负责 GIS 数据转换 3. security-reviewer 审查认证模块 4. test-writer 生成测试用例每一步子代理执行完毕后主 Agent 只接收摘要不接收完整上下文对话保持清爽。这种设计与“统一通道”并不冲突你可以在 PLAN 里直接写“子 Agentgis-data-processor 负责数据转换”同时让所有子代理走 TaoToken 这套 Base URL。通道是底层的事PLAN 是上层编排两者互不干扰。5.3 验证调用是否成功去控制台看用量子代理执行时主对话里只显示摘要你怎么知道它真的走了 TaoToken最直接的办法是打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 的用量页面查看刚才那次调用的请求记录。控制台会显示模型 ID、Token 数和响应状态码。看到一条状态码为 200 的记录才说明这个子代理从“创建”到“调用”整条链路都通了。6. 避坑清单frontmatter 正常但子代理不动多数出在通道这一层6.1 子代理不自动调用先查 description原文提到“子代理不自动调用”的常见原因是描述模糊、职责过多。如果你写了“帮助开发”这种描述主 Agent 很难判断该在什么时候用它。正确做法是让 description 包含明确的触发场景比如“当用户提到 JWT、OAuth、登录认证时执行安全审计”。一个子代理只负责一项核心任务触发率会明显提升。6.2 401 或者请求打到了官方通道先查 Base URL如果你发现子代理调用后返回 401或者用量在官方后台而不是 TaoToken 侧出现优先检查三处Cursor 模型设置里的 Base URL 是否写成了https://taotoken.net/api/末尾多了斜杠Claude Code 的 settings.json 里ANTHROPIC_BASE_URL是否多了/v1环境变量是否被项目级配置覆盖导致~/.claude/settings.json没有生效正确的接口地址始终是https://taotoken.net/api这个地址只填进工具不需要在浏览器里打开也不需要加任何 UTM 参数。6.3 模型 ID 对不上返回 400去模型广场复制有时候 frontmatter 写了一个印象中的模型名但实际请求返回 400 或 not found。原因通常是这个模型 ID 不在当前通道的可用列表中。解决办法是打开模型广场复制真实的 ID然后改掉 frontmatter 里的model字段。改完之后重启会话再试一次不要继续沿用旧的进程。7. 实战带 GIS 的电商后台五种子代理统一走 TaoToken7.1 先建五份 frontmatter原文的实战案例是开发一个带地理定位功能的电商后台需要多个专业角色协作。我们可以按同样的拆法建出五个子代理api-designer设计 RESTful API定义接口路径和响应结构db-expert数据库设计与优化负责表结构和索引gis-processor地理数据处理坐标转换、空间查询security-reviewer安全审计检查认证和权限逻辑test-writer生成单元测试和集成测试每个子代理都在.cursor/agents/或.claude/agents/下有自己的 Markdown 文件。model字段可以各不相同但 Base URL 和 Key 都来自 TaoToken不需要每个文件重复配置。7.2 SPEC → PLAN → 执行的节奏原文强调先出 SPEC再出 PLAN最后执行。具体到命令层可以这样触发/subagent --namesecurity-reviewer 审查用户认证模块的 JWT 实现执行时主 Agent 会把这个任务交给security-reviewer它的模型请求从 Cursor 的模型通道发出也就是https://taotoken.net/api。子代理完成后返回摘要主 Agent 继续下一步。整个流程和原文一致只是每个子代理的“燃料”都记在 TaoToken 这一把 Key 上。7.3 换模型时只动 frontmatter不改通道假设gis-processor一开始用的是claude-3-opus-20240229跑了几轮后发现成本偏高想换成更便宜的模型。你只需要修改gis-processor.md里的model字段Base URL 和 Key 完全不用动。因为所有子代理已经统一走 TaoToken只要新模型在模型广场可用切换就是改一行配置的事。这在多 Key 分散时是做不到的——那时你还要去确认新模型在哪个通道里存在。8. 收尾你的子代理建好了下一步去看第一笔调用记录8.1 最小验证清单从零到一把 Key 跑通子代理其实只需要四步。第一步在.cursor/agents/或.claude/agents/下建好 Markdown 文件frontmatter 里写明 model、tools、effort。第二步把 Cursor 的模型设置或 Claude Code 的 settings.json 里的 Base URL 指到https://taotoken.net/apiKey 填YOUR_API_KEY。第三步发起一次/subagent或/agent调用比如让 security-auditor 审查一个小文件。第四步打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 的用量页面确认刚才那次请求状态码是 200。8.2 原文问“需要模板吗”这里直接给你下一步原文结尾问“需要我提供一套可直接复制的子代理模板吗”答案是上面 2.1 和 3.3 的两份 frontmatter 已经可以直接复用。不过模板只是起点真正让子代理跑起来的是通道配置。你现在就可以打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册并创建 API Key把YOUR_API_KEY换成真实值然后回到 Cursor 或 Claude Code 里发起一次子代理调用。用量页面里出现那条 200 记录的时候你的子代理团队才算正式开工。