07 SubAgent 子代理系统——Agent 的后台线程

原文：Create custom subagents

什么是 SubAgent

SubAgent 是在独立上下文中运行的专门化 AI 助手。每个 SubAgent 有自己的上下文窗口、系统提示、工具限制和权限模式。

类比：SubAgent 就像 Node.js 的 Worker Thread 或 Python 的 subprocess。你把一个任务丢给独立的工作线程，它独立执行，完成后把结果回传给主线程。关键是：后台执行的详细过程不会污染主线程的内存。

这也是 SubAgent 最大的价值：上下文隔离。SubAgent 可能读了 50 个文件，但你的主会话只收到一段摘要。

内置 SubAgent

Agent	模型	工具	用途
Explore	Haiku（快速）	只读	搜索和分析代码库
Plan	继承	只读	Plan Mode 下的研究
general-purpose	继承	全部	复杂多步任务

创建自定义 SubAgent

文件结构

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. Analyze code and provide
specific, actionable feedback on quality and security.

存放位置与优先级

位置	优先级	用途
`--agents` CLI 参数	最高	临时/测试
`.claude/agents/`	高	项目级（提交到 git）
`~/.claude/agents/`	中	个人级（所有项目）
Plugin `agents/`	低	插件提供

关键 Frontmatter 字段

字段	作用
`name` / `description`	标识和触发（必须）
`tools`	工具白名单
`disallowedTools`	工具黑名单
`model`	使用的模型（sonnet/opus/haiku/inherit）
`permissionMode`	权限模式
`skills`	预加载的 Skill
`mcpServers`	可用的 MCP Server
`hooks`	生命周期钩子
`memory`	持久记忆（user/project/local）
`background`	是否在后台运行
`isolation: worktree`	在独立 git worktree 中运行

SubAgent 的持久记忆

SubAgent 可以有自己的跨会话记忆：

---
name: code-reviewer
memory: project  # user | project | local
---

记忆存储在 <scope>/agent-memory/<name>/，包含 MEMORY.md 索引和主题文件。SubAgent 在工作中自动读写这些笔记，越用越”聪明”。

前台 vs 后台

	前台 SubAgent	后台 SubAgent
主会话	阻塞等待	继续工作
权限	实时询问你	预先申请
适用	需要交互的任务	独立任务

Ctrl+B 可以把正在运行的前台任务切到后台。

常见模式

隔离大量输出

Use a subagent to run the test suite and report only the failing tests

测试输出可能有数千行，但你只需要失败摘要。

并行研究

Research the authentication, database, and API modules in parallel using separate subagents

三个 SubAgent 同时工作，各自报告发现。

写者-审阅者模式

Session A: Implement the rate limiter
Session B: Review Session A's implementation for edge cases

新鲜的上下文让审阅不受实现思路影响。

SubAgent vs 其他选项

我需要…	用什么
频繁来回交互	主会话
产出大量输出但只需摘要	SubAgent
限制工具权限	SubAgent
可复用的知识/工作流	Skill
快速小问题	`/btw`（不进入历史）

知识检测

概念理解题

SubAgent 的核心价值是”上下文隔离”。为什么这在 AI Agent 中如此重要？（提示：联系 Context Window 的限制）
SubAgent 不能嵌套（不能 spawn 其他 SubAgent）。这个设计限制的原因是什么？
SubAgent 的持久记忆（memory）和主会话的 Auto Memory 有什么区别？为什么要分开？

应用题

你的 iOS 项目有一个 2000 行的 AppDelegate.swift。你想让 Claude 重构它，但担心上下文不够。怎么用 SubAgent 来组织这个任务？
设计一个 security-reviewer SubAgent，它需要：只能读文件不能写、使用 Opus 模型、检查完后把发现保存到持久记忆。写出完整的 frontmatter。

迁移思考题

OpenClaw 的 “isolated session” 和 Claude Code 的 SubAgent 本质上解决同一个问题。对比两者的实现方式——OpenClaw 用独立的 session 实例，Claude Code 用同一个会话内的子上下文。各有什么优缺点？

参见

03-扩展体系总览 — SubAgent 在扩展架构中的位置
04-Skill-技能系统 — Skill 和 SubAgent 的组合使用
SlipBox 相关：Agent、Session、Context Window

参考答案

1. 上下文隔离的重要性

AI Agent 的上下文窗口有限且珍贵。如果所有工作都在主会话中进行，调查任务（读 50 个文件、搜索大量代码）会迅速填满上下文，挤压实际编码的空间，且模型在拥挤上下文中的准确率下降（Context Rot）。SubAgent 让”脏活”在独立空间完成，只把精华结果回传——就像移动开发中在后台线程处理大量数据，主线程只接收处理结果。

2. 不能嵌套的原因

防止资源失控。如果 SubAgent A 可以 spawn SubAgent B，B 又 spawn C——每个都有独立上下文窗口和模型调用——成本和复杂度会指数级增长。而且深层嵌套的 SubAgent 链条很难调试。单层限制保证行为可预测、成本可控。

3. SubAgent Memory vs 主会话 Auto Memory

分开是因为专业化：一个 security-reviewer SubAgent 应该记住”上次发现的安全模式”和”项目的安全策略”，而主会话应该记住”构建命令”和”用户偏好”。如果混在一起，安全 SubAgent 的笔记会污染主会话的上下文（每次都加载 200 行安全笔记但你在做 UI 开发）。

4. 用 SubAgent 重构 2000 行 server.ts

(1) 先用 Explore SubAgent 分析 server.ts 的功能块（路由定义、中间件配置、数据库连接、错误处理等）(2) 用 Plan SubAgent 制定拆分方案——每个功能块提取到独立的模块文件 (3) 逐个功能块开 SubAgent 执行提取，每个 SubAgent 只关注一个功能块 (4) 最后在主会话中整合，更新 server.ts 为”入口协调者”角色，只导入和挂载各模块。这样每个 SubAgent 只需要看几百行代码，而非全部 2000 行。

5. security-reviewer SubAgent frontmatter

---
name: security-reviewer
description: Reviews code for security vulnerabilities, injection risks, and permission issues
tools: Read, Glob, Grep
model: opus
permissionMode: plan
memory: project
---
You are a security code reviewer. Focus on: injection vulnerabilities, authentication bypasses, insecure data storage, improper permission handling. Report findings with severity (critical/high/medium/low), affected file and line, and remediation suggestion.

6. OpenClaw isolated session vs SubAgent

OpenClaw isolated session 是完全独立的 session 实例（有自己的 sessionId、消息历史、生命周期），通过 Gateway RPC 通信。优点：真正的隔离，crash 不影响主 session；可以长时间存在。缺点：启动开销大，通信延迟高。Claude Code SubAgent 是主会话内的子上下文，共享同一进程。优点：启动快，结果直接回传。缺点：进程级别不隔离，主进程崩溃 SubAgent 也挂。