★ FEATURED ARTICLE 1. 为什么你的 Claude Code 越用越卡subagent 能解决什么如果你用 Claude Code 处理过稍微大一点的项目大概率遇到过这种情况让它跑一遍测试、翻一遍日志、扫一遍依赖主对话的上下文瞬间被几万行输出塞满后面再问什么都开始答非所问。这不是模型变笨了是上下文窗口被无关信息挤爆了。subagent子代理就是为这个场景设计的。简单说它是一个跑在独立上下文窗口里的专门 AI 助手有自己的系统提示词、自己的工具权限、自己的模型选择。当主 Claude 判断当前任务匹配某个子代理的描述时就把活派给它子代理独立干完只把结果摘要回传给主对话。那些冗长的中间过程——测试输出、日志、搜索结果——全部留在子代理自己的窗口里不污染你的主对话。它适合谁三类人最该用一是经常让 Claude 跑测试、查日志、做代码库探索的开发者二是需要把「只读审查」和「可写修改」严格分开的团队三是想在多任务场景下拆分代理职责、控制 token 成本的人。Claude Code 内置了 Explore、Plan、general-purpose 等子代理你也可以在~/.claude/agents/或项目的.claude/agents/下写自己的 Markdown 文件来定义。这篇就把配置骨架、创建流程、验证动作和踩坑排查一次讲清楚。2. 前置准备TaoToken 接入与 Claude Code 环境确认在折腾 subagent 之前得先保证 Claude Code 本身能正常跑起来。如果你还没配好模型接入subagent 的验证环节会卡在第一步。我这边用的是 TaoToken 的接入方式它提供兼容 Anthropic 的 API 端点配置起来比较直接。先确认你的 Claude Code 版本支持 subagent。运行下面这条命令看版本claude --versionsubagent 和/agents命令在较新的版本里才有如果版本太旧先升级。接着配置 API 接入核心是设置环境变量指向 TaoToken 的 API 地址export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的API KeyAPI Key 在控制台创建地址是https://taotoken.net/api-keys。创建后复制出来注意别提交到 Git 仓库里。如果你想让配置持久化把这两行写进~/.bashrc或~/.zshrc然后source一下。注意ANTHROPIC_BASE_URL不要带末尾斜杠也不要手动拼/v1Claude Code 会自己处理路径。写错了会报 404这是最常见的接入错误。配好之后跑一个最小验证确认主对话能通claude -p 回复 ok 两个字母即可能正常返回就说明接入没问题可以进入 subagent 环节了。如果你更习惯用图形界面调试模型也可以先在模型对话里确认 key 有效再回来配 Claude Code。3. 可复制配置subagent 文件骨架与字段说明subagent 的本质是一个带 YAML frontmatter 的 Markdown 文件。frontmatter 定义元数据和配置正文部分就是它的系统提示词。先看目录结构这是所有配置的基础# 用户级所有项目都能用 ~/.claude/agents/ # 项目级只对当前项目生效建议提交到版本控制 你的项目/.claude/agents/优先级从高到低是--agentsCLI 标志仅当前会话 项目级.claude/agents/ 用户级~/.claude/agents/ 插件目录。同名子代理高优先级覆盖低优先级。下面是一个可直接复制的只读代码审查子代理骨架保存为~/.claude/agents/code-reviewer.md--- name: code-reviewer description: 代码审查专家。在编写或修改代码后主动使用审查质量、安全性和可维护性。 tools: Read, Grep, Glob, Bash model: sonnet --- 你是一名资深代码审查员确保代码质量和安全达到高标准。 被调用时 1. 运行 git diff 查看最近的改动 2. 聚焦被修改的文件 3. 立即开始审查 审查清单 - 代码清晰可读命名规范 - 无重复代码错误处理完整 - 没有暴露的密钥或 API Key - 输入校验到位测试覆盖合理 按优先级输出反馈严重问题必须修、警告应该修、建议可优化。 每个问题给出具体修复示例。frontmatter 里只有name和description是必填的其余字段说明如下字段作用取值name唯一标识小写字母加连字符如 code-reviewerdescriptionClaude 据此判断何时委派自然语言建议含「主动使用」tools允许使用的工具白名单Read, Grep, Glob, Bash, Edit, Write 等disallowedTools明确禁止的工具黑名单同上model使用的模型sonnet / opus / haiku / inheritpermissionMode权限模式default / acceptEdits / dontAsk / bypassPermissions / planskills启动时注入的技能技能名列表hooks生命周期钩子PreToolUse / PostToolUse / Stopdescription这个字段值得单独强调。Claude 就是靠它来决定要不要把任务派给这个子代理的写得越具体委派越准。比如「审查代码」就太泛「在代码修改后主动审查质量、安全性和可维护性」就明确得多。如果你不想写文件也可以用 CLI 标志临时定义一个只对当前会话生效claude --agents { code-reviewer: { description: 代码审查专家。在代码更改后主动使用。, prompt: 你是资深代码审查员关注质量、安全和最佳实践。, tools: [Read, Grep, Glob, Bash], model: sonnet } }注意 CLI 方式里系统提示词用的是prompt字段对应文件方式里的 Markdown 正文。4. 创建自定义子代理并验证调用结果配置写好了接下来走一遍完整的创建和验证流程。推荐用/agents交互命令它会引导你选作用范围、生成配置、挑工具和模型。在 Claude Code 里运行/agents选择 Create new agent然后选 User-level这样会存到~/.claude/agents/所有项目都能用。接着选 Generate with Claude用自然语言描述你要的子代理比如一个代码改进代理扫描文件并对可读性、性能和最佳实践提出改进建议。 它应该解释每个问题展示当前代码并给出改进版本。Claude 会生成系统提示词和配置按e可以在编辑器里改。然后选工具——只读审查就只勾 Read、Grep、Glob、Bash别勾 Edit 和 Write。再选模型审查类任务选 Sonnet 比较均衡。最后选个颜色方便在 UI 里区分保存即可无需重启。保存后立刻验证。在 Claude Code 里输入Use the code-reviewer agent to review this project如果委派成功你会看到主对话里出现子代理被调用的提示子代理独立跑完后返回审查结果。验证时重点看三件事一是子代理确实被触发了不是主对话自己干的二是返回的是摘要而非大段原始输出三是结果里包含你提示词里要求的格式比如按优先级分类。想确认子代理的转录文件可以去这个路径找~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl每个子代理的完整对话历史都存在这里独立于主对话。主对话压缩时子代理转录不受影响。默认 30 天清理由cleanupPeriodDays设置控制。如果你想让子代理继续之前的工作而不是重开直接跟 Claude 说「继续刚才那个代码审查现在分析授权逻辑」它会用完整上下文恢复子代理。5. 本篇常见错误排查subagent 用起来坑不算多但有几个特别容易踩。子代理没被触发。最常见的原因是description写得太模糊。Claude 靠描述匹配任务描述里没有明确的使用场景它就不会委派。解决办法是在描述里加上「主动使用」「在 X 之后使用」这类触发语并把适用场景写具体。手动创建文件后不生效。子代理在会话启动时加载。如果你是手动往~/.claude/agents/里丢文件当前会话不会自动识别。要么重启会话要么运行/agents让它立即加载。后台子代理工具调用失败。后台运行的子代理会继承父代理权限并自动拒绝未经预先批准的操作。如果它需要额外权限或要问澄清问题那个工具调用会失败但子代理会继续跑。另外后台子代理里 MCP 工具不可用。所以涉及 MCP 或需要交互确认的任务尽量放前台跑。真遇到权限失败可以在前台恢复它重试。权限模式用错。bypassPermissions会跳过所有权限检查子代理能执行任何操作而无需批准务必谨慎。而且如果父代理用了bypassPermissions这个设置会优先且无法被覆盖。只读审查类子代理建议用default或plan。想禁用某个子代理。在 settings.json 的permissions.deny里加Task(子代理名)比如Task(Explore)。CLI 方式则是claude --disallowedTools Task(Explore)。子代理嵌套失败。子代理不能再生成子代理这是硬限制。如果你的工作流需要嵌套委派改用 Skills或者从主对话里链式调用多个子代理。模型选错导致成本失控。探索、搜索这类任务用 Haiku 就够了快且便宜复杂推理和代码修改再用 Sonnet 或 inherit。把重活全丢给 Opus 会让成本飙升。6. 下一步把 subagent 用进你的日常编码流subagent 真正的价值在于把「高噪音、可自包含」的任务隔离出去。跑测试套件只回传失败用例、并行研究认证和数据库模块、链式调用审查加优化——这些都是典型场景。判断标准很简单任务输出量大、你不需要中间过程、能返回摘要就交给子代理需要频繁来回沟通、多阶段共享上下文、追求低延迟就留在主对话。如果你还没配好接入先去控制台创建 API Key再对照接入文档把环境变量配好。想先验证模型是否正常可以在模型对话里试一句。长期做编码和 Agent 工作流的建议了解一下 Coding Plan把日常调用成本压下来。配好之后从写一个只读的 code-reviewer 子代理开始跑通一次委派你就摸到门道了。
阅读完成 · 觉得有帮助？
