1. 从黄金分析 Agent 案例里我拆出了什么可复用的骨架如果你正在用 Claude Code 做多智能体协作大概率会遇到一个很实际的问题单个 Agent 能跑但一旦要拆成「主 Agent 调度 若干 Sub-Agent 并行干活」配置就开始乱。.claude/目录里到底该放什么settings.json和config.toml各管哪一块Sub-Agent 和 Skill 为什么不能塞进同一个文件夹这些问题不搞清楚后面每加一个 Agent 都要重新踩一遍坑。我拿一个黄金市场分析的 Agent 案例做拆解。这个案例的完整配置体系围绕一个核心目标用真实公开数据驱动分析主 Agent 负责规划调度Sub-Agent 并行收集数据Skill 作为知识注入给主 Agent 自己用。它把.claude/目录分成了settings.json主配置、prompts/系统提示词、agents/Sub-Agent 定义、skills/可调用技能、mcp.jsonMCP 服务器、plugins.json插件注册表、config/paths.conf路径变量七块。这套结构之所以值得学是因为它把「执行单元」和「知识单元」彻底分开了。Sub-Agent 是独立进程需要声明自己用什么工具、用什么模型Skill 只是一段注入到主 Agent 上下文里的指导文本不声明工具也不声明模型。理解这一点你就能把任何单 Agent 案例拆成可复用的多智能体骨架。下面我会给出settings.json与config.toml的可复制骨架、TaoToken 统一 Key 的接入步骤以及 Sub-Agent 调用与报错排查的验证动作。2. TaoToken 前置统一 Key 怎么接进 Claude Code在搭 Sub-Agent 骨架之前先把模型接入这一层理顺。多智能体场景下最烦的是每个 Sub-Agent 都要单独配一套 Key 和 endpoint改一次要动好几个文件。TaoToken 的思路是给你一个统一入口主 Agent 和 Sub-Agent 共用同一套 Key配置只写一次。TaoToken 的 API 地址是https://taotoken.net/api官网在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。你需要先去控制台生成 API Key控制台入口在https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleKey 管理页面在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keys。拿到 Key 之后Claude Code 侧有两种接法一种是通过环境变量注入另一种是写进settings.json的env字段。我建议用环境变量因为 Sub-Agent 启动时会继承主进程的环境不用每个 Agent 单独配。# 写入 shell 配置主 Agent 和 Sub-Agent 共用 export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你更想把配置固化在项目里可以在.claude/settings.json的env字段里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }这里有个细节要注意Sub-Agent 如果是通过 Claude Code 的 Task 工具派发的它会复用主进程的环境变量所以你在主配置里写一次就够了。但如果你用config.toml单独定义 Sub-Agent 的模型参数就要确保config.toml里没有覆盖掉 base_url否则会出现主 Agent 能通、Sub-Agent 报 401 的情况。提示接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc里面有各语言 SDK 的完整示例配之前扫一眼能省不少排查时间。3. 可复制配置settings.json 与 config.toml 骨架这一节是全文的核心我直接把案例里的结构抽象成可复制的骨架。你新建一个项目把下面两个文件放进.claude/目录就能跑起来。3.1 settings.json 主配置骨架settings.json管的是主 Agent 的身份、默认模型、允许的工具集以及 Sub-Agent 的注册入口。{ model: claude-sonnet-4-20250514, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 }, permissions: { allow: [Bash, Read, Write, WebSearch, WebFetch], deny: [] }, agents: { search-specialist: { description: 负责公开信息检索与事件收集, promptFile: .claude/agents/search-specialist.md, tools: [WebSearch, WebFetch, Read], model: claude-haiku-4-20250514 }, data-analyst: { description: 负责结构化数据计算与指标生成, promptFile: .claude/agents/data-analyst.md, tools: [Bash, Read, Write], model: claude-sonnet-4-20250514 } } }这里的关键点是agents字段每个 Sub-Agent 声明自己的promptFile、tools和model。tools决定了这个 Sub-Agent 能调哪些工具model决定了它用哪个模型跑。案例里搜索类 Sub-Agent 用 haiku 这种轻量模型分析类用 sonnet成本和质量能兼顾。3.2 config.toml 补充配置骨架有些项目习惯用config.toml管路径变量和运行时参数案例里的config/paths.conf就是这个角色。如果你用 TOML 格式可以这样写[project] name multi-agent-skeleton root .claude [paths] prompts .claude/prompts agents .claude/agents skills .claude/skills output ./output [subagent.defaults] max_parallel 3 timeout_seconds 120 inherit_env true [subagent.search-specialist] model claude-haiku-4-20250514 tools [WebSearch, WebFetch] [subagent.data-analyst] model claude-sonnet-4-20250514 tools [Bash, Read, Write]inherit_env true这一行很重要它保证 Sub-Agent 继承主进程的ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这样你只需要在settings.json里配一次 TaoToken 的 Key。3.3 Sub-Agent 提示词文件骨架agents/目录下每个.md文件就是一个 Sub-Agent 的提示词。骨架长这样# search-specialist ## 角色 你是信息检索专家负责从公开来源收集事实性信息。 ## 工具使用 - 优先使用 WebSearch 获取最新信息 - 用 WebFetch 抓取具体页面内容 - 禁止编造任何未检索到的数据 ## 输出格式 返回 JSON 数组每项包含 title、source、date、summary 四个字段。 ## 边界 只做检索和整理不做分析判断分析交给主 Agent。注意最后一条「边界」Sub-Agent 的职责要收窄越窄越稳定。案例里三个 Sub-Agent 分别只管搜索、只管指标计算、只管 ETF 数据互不重叠这样并行跑才不会互相污染上下文。4. 验证请求Sub-Agent 调用与成功结果配置写完怎么确认 Sub-Agent 真的被派发、真的返回了结果我分三步验证。4.1 验证主 Agent 能通模型先跑一个最小请求确认 TaoToken 的 Key 和 base_url 生效curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK}] }返回里能看到content字段有内容说明接入层通了。如果这里就报 401先查 Key 有没有多余空格再查 base_url 是不是写成了带/v1的完整路径。4.2 验证 Sub-Agent 被派发在 Claude Code 里发一条会触发 Sub-Agent 的指令比如「用 search-specialist 检索最近的黄金价格新闻」。观察输出里有没有出现 Sub-Agent 的启动标记。正常情况下你会看到类似Task(search-specialist)的调用记录以及它独立返回的结果块。4.3 验证并行与结果整合案例里的并行模式是主 Agent 同时派三个 Sub-Agent。你可以这样测请并行执行 1. search-specialist 检索黄金相关新闻 2. data-analyst 计算一组模拟价格的均值 3. 你自己汇总两者的结果成功的结果是两个 Sub-Agent 各自返回独立结果主 Agent 在两者都返回后做汇总。如果只看到一个 Sub-Agent 的结果说明并行派发没生效检查max_parallel配置。注意Sub-Agent 的上下文是独立的它看不到主 Agent 的对话历史。所以派发时要把必要信息写进 prompt不能指望它「记得」之前聊过什么。5. 本篇常见错排查搭这套骨架时我遇到过几类高频报错按出现频率排一下。第一类Sub-Agent 报 401 或 model not found。九成是环境变量没继承。检查config.toml里inherit_env是不是true或者 Sub-Agent 的model字段写了一个 TaoToken 不支持的模型名。模型名要和接入文档里列出的保持一致。第二类Sub-Agent 启动了但一直不返回。通常是timeout_seconds设太短或者 Sub-Agent 的 prompt 里让它做了超出tools范围的事。比如你只给了Read却让它写文件它会卡住。检查tools声明和 prompt 里的动作是否匹配。第三类主 Agent 能通、Sub-Agent 不通。这种最迷惑。原因是 Sub-Agent 可能用了独立的config.toml段而那段里覆盖了base_url。把 Sub-Agent 段里的 base_url 删掉让它继承主配置。第四类并行派发变成串行。检查max_parallel是不是被设成了 1或者 Sub-Agent 之间有隐式的依赖。案例里三个 Sub-Agent 完全独立所以能并行如果你让 B 依赖 A 的结果框架会自动串行。第五类Skill 和 Sub-Agent 混淆导致行为异常。记住区别Sub-Agent 是独立进程有tools和modelSkill 是注入主 Agent 的知识文本没有这两个字段。如果你把该做 Skill 的内容写成了 Sub-Agent会多启动一个进程浪费上下文还容易出错。排查时有个通用动作把settings.json里的permissions.allow临时放宽到全允许看问题是否消失。如果消失说明是工具权限卡住了某个 Sub-Agent。6. 把骨架跑起来之后下一步做什么骨架搭好、验证通过之后你可以按这个顺序扩展先加一个 Skill 文件到skills/目录测试主 Agent 能不能加载它再把 Skill 的调用写进主 Agent 的 prompt观察知识注入是否生效最后把 Sub-Agent 的数量从两个加到三个测并行调度的稳定性。如果你要长期跑编码类或 Agent 类任务建议了解一下 Coding Plan入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-plan它针对高频调用场景做了额度优化。想先验证模型对话效果的话模型对话入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chat。Claude Code 相关的接入细节可以看https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode。这套骨架的价值不在于它多复杂而在于它把「执行」和「知识」分清楚了。你以后每加一个 Sub-Agent只需要在agents/放一个 md 文件、在settings.json注册一条每加一个 Skill只需要在skills/放一个 md 文件。配置不会随着 Agent 数量增长而失控这才是可复用的关键。
1. 从黄金分析 Agent 案例里我拆出了什么可复用的骨架如果你正在用 Claude Code 做多智能体协作大概率会遇到一个很实际的问题单个 Agent 能跑但一旦要拆成「主 Agent 调度 若干 Sub-Agent 并行干活」配置就开始乱。.claude/目录里到底该放什么settings.json和config.toml各管哪一块Sub-Agent 和 Skill 为什么不能塞进同一个文件夹这些问题不搞清楚后面每加一个 Agent 都要重新踩一遍坑。我拿一个黄金市场分析的 Agent 案例做拆解。这个案例的完整配置体系围绕一个核心目标用真实公开数据驱动分析主 Agent 负责规划调度Sub-Agent 并行收集数据Skill 作为知识注入给主 Agent 自己用。它把.claude/目录分成了settings.json主配置、prompts/系统提示词、agents/Sub-Agent 定义、skills/可调用技能、mcp.jsonMCP 服务器、plugins.json插件注册表、config/paths.conf路径变量七块。这套结构之所以值得学是因为它把「执行单元」和「知识单元」彻底分开了。Sub-Agent 是独立进程需要声明自己用什么工具、用什么模型Skill 只是一段注入到主 Agent 上下文里的指导文本不声明工具也不声明模型。理解这一点你就能把任何单 Agent 案例拆成可复用的多智能体骨架。下面我会给出settings.json与config.toml的可复制骨架、TaoToken 统一 Key 的接入步骤以及 Sub-Agent 调用与报错排查的验证动作。2. TaoToken 前置统一 Key 怎么接进 Claude Code在搭 Sub-Agent 骨架之前先把模型接入这一层理顺。多智能体场景下最烦的是每个 Sub-Agent 都要单独配一套 Key 和 endpoint改一次要动好几个文件。TaoToken 的思路是给你一个统一入口主 Agent 和 Sub-Agent 共用同一套 Key配置只写一次。TaoToken 的 API 地址是https://taotoken.net/api官网在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。你需要先去控制台生成 API Key控制台入口在https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleKey 管理页面在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keys。拿到 Key 之后Claude Code 侧有两种接法一种是通过环境变量注入另一种是写进settings.json的env字段。我建议用环境变量因为 Sub-Agent 启动时会继承主进程的环境不用每个 Agent 单独配。# 写入 shell 配置主 Agent 和 Sub-Agent 共用 export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你更想把配置固化在项目里可以在.claude/settings.json的env字段里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }这里有个细节要注意Sub-Agent 如果是通过 Claude Code 的 Task 工具派发的它会复用主进程的环境变量所以你在主配置里写一次就够了。但如果你用config.toml单独定义 Sub-Agent 的模型参数就要确保config.toml里没有覆盖掉 base_url否则会出现主 Agent 能通、Sub-Agent 报 401 的情况。提示接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc里面有各语言 SDK 的完整示例配之前扫一眼能省不少排查时间。3. 可复制配置settings.json 与 config.toml 骨架这一节是全文的核心我直接把案例里的结构抽象成可复制的骨架。你新建一个项目把下面两个文件放进.claude/目录就能跑起来。3.1 settings.json 主配置骨架settings.json管的是主 Agent 的身份、默认模型、允许的工具集以及 Sub-Agent 的注册入口。{ model: claude-sonnet-4-20250514, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 }, permissions: { allow: [Bash, Read, Write, WebSearch, WebFetch], deny: [] }, agents: { search-specialist: { description: 负责公开信息检索与事件收集, promptFile: .claude/agents/search-specialist.md, tools: [WebSearch, WebFetch, Read], model: claude-haiku-4-20250514 }, data-analyst: { description: 负责结构化数据计算与指标生成, promptFile: .claude/agents/data-analyst.md, tools: [Bash, Read, Write], model: claude-sonnet-4-20250514 } } }这里的关键点是agents字段每个 Sub-Agent 声明自己的promptFile、tools和model。tools决定了这个 Sub-Agent 能调哪些工具model决定了它用哪个模型跑。案例里搜索类 Sub-Agent 用 haiku 这种轻量模型分析类用 sonnet成本和质量能兼顾。3.2 config.toml 补充配置骨架有些项目习惯用config.toml管路径变量和运行时参数案例里的config/paths.conf就是这个角色。如果你用 TOML 格式可以这样写[project] name multi-agent-skeleton root .claude [paths] prompts .claude/prompts agents .claude/agents skills .claude/skills output ./output [subagent.defaults] max_parallel 3 timeout_seconds 120 inherit_env true [subagent.search-specialist] model claude-haiku-4-20250514 tools [WebSearch, WebFetch] [subagent.data-analyst] model claude-sonnet-4-20250514 tools [Bash, Read, Write]inherit_env true这一行很重要它保证 Sub-Agent 继承主进程的ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这样你只需要在settings.json里配一次 TaoToken 的 Key。3.3 Sub-Agent 提示词文件骨架agents/目录下每个.md文件就是一个 Sub-Agent 的提示词。骨架长这样# search-specialist ## 角色 你是信息检索专家负责从公开来源收集事实性信息。 ## 工具使用 - 优先使用 WebSearch 获取最新信息 - 用 WebFetch 抓取具体页面内容 - 禁止编造任何未检索到的数据 ## 输出格式 返回 JSON 数组每项包含 title、source、date、summary 四个字段。 ## 边界 只做检索和整理不做分析判断分析交给主 Agent。注意最后一条「边界」Sub-Agent 的职责要收窄越窄越稳定。案例里三个 Sub-Agent 分别只管搜索、只管指标计算、只管 ETF 数据互不重叠这样并行跑才不会互相污染上下文。4. 验证请求Sub-Agent 调用与成功结果配置写完怎么确认 Sub-Agent 真的被派发、真的返回了结果我分三步验证。4.1 验证主 Agent 能通模型先跑一个最小请求确认 TaoToken 的 Key 和 base_url 生效curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK}] }返回里能看到content字段有内容说明接入层通了。如果这里就报 401先查 Key 有没有多余空格再查 base_url 是不是写成了带/v1的完整路径。4.2 验证 Sub-Agent 被派发在 Claude Code 里发一条会触发 Sub-Agent 的指令比如「用 search-specialist 检索最近的黄金价格新闻」。观察输出里有没有出现 Sub-Agent 的启动标记。正常情况下你会看到类似Task(search-specialist)的调用记录以及它独立返回的结果块。4.3 验证并行与结果整合案例里的并行模式是主 Agent 同时派三个 Sub-Agent。你可以这样测请并行执行 1. search-specialist 检索黄金相关新闻 2. data-analyst 计算一组模拟价格的均值 3. 你自己汇总两者的结果成功的结果是两个 Sub-Agent 各自返回独立结果主 Agent 在两者都返回后做汇总。如果只看到一个 Sub-Agent 的结果说明并行派发没生效检查max_parallel配置。注意Sub-Agent 的上下文是独立的它看不到主 Agent 的对话历史。所以派发时要把必要信息写进 prompt不能指望它「记得」之前聊过什么。5. 本篇常见错排查搭这套骨架时我遇到过几类高频报错按出现频率排一下。第一类Sub-Agent 报 401 或 model not found。九成是环境变量没继承。检查config.toml里inherit_env是不是true或者 Sub-Agent 的model字段写了一个 TaoToken 不支持的模型名。模型名要和接入文档里列出的保持一致。第二类Sub-Agent 启动了但一直不返回。通常是timeout_seconds设太短或者 Sub-Agent 的 prompt 里让它做了超出tools范围的事。比如你只给了Read却让它写文件它会卡住。检查tools声明和 prompt 里的动作是否匹配。第三类主 Agent 能通、Sub-Agent 不通。这种最迷惑。原因是 Sub-Agent 可能用了独立的config.toml段而那段里覆盖了base_url。把 Sub-Agent 段里的 base_url 删掉让它继承主配置。第四类并行派发变成串行。检查max_parallel是不是被设成了 1或者 Sub-Agent 之间有隐式的依赖。案例里三个 Sub-Agent 完全独立所以能并行如果你让 B 依赖 A 的结果框架会自动串行。第五类Skill 和 Sub-Agent 混淆导致行为异常。记住区别Sub-Agent 是独立进程有tools和modelSkill 是注入主 Agent 的知识文本没有这两个字段。如果你把该做 Skill 的内容写成了 Sub-Agent会多启动一个进程浪费上下文还容易出错。排查时有个通用动作把settings.json里的permissions.allow临时放宽到全允许看问题是否消失。如果消失说明是工具权限卡住了某个 Sub-Agent。6. 把骨架跑起来之后下一步做什么骨架搭好、验证通过之后你可以按这个顺序扩展先加一个 Skill 文件到skills/目录测试主 Agent 能不能加载它再把 Skill 的调用写进主 Agent 的 prompt观察知识注入是否生效最后把 Sub-Agent 的数量从两个加到三个测并行调度的稳定性。如果你要长期跑编码类或 Agent 类任务建议了解一下 Coding Plan入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-plan它针对高频调用场景做了额度优化。想先验证模型对话效果的话模型对话入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chat。Claude Code 相关的接入细节可以看https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode。这套骨架的价值不在于它多复杂而在于它把「执行」和「知识」分清楚了。你以后每加一个 Sub-Agent只需要在agents/放一个 md 文件、在settings.json注册一条每加一个 Skill只需要在skills/放一个 md 文件。配置不会随着 Agent 数量增长而失控这才是可复用的关键。
