子代理（Subagents）是运行在独立上下文窗口中的专用 AI 助手，每个子代理可以拥有自定义的系统提示、独立的工具权限集和隔离的会话状态。截至 2026 年 5 月，Claude Code 已经内置了 Explore、Plan、general-purpose 三种子代理，并允许开发者按需创建自定义子代理。v2.1.139 版本引入的 Agent View 则能在一个面板中集中管理所有并行会话。

子代理要解决的核心痛点

在主会话中直接运行测试套件、爬取文档或分析日志，很容易把大量只需临时使用的输出堆积在上下文中，挤压宝贵的 token 空间。子代理的设计思路就是把这些“产出多、复用少”的任务移进独立的上下文窗口：

• 为主会话保留 token：搜索结果、日志分析、测试报告等只有精简摘要返回主会话。

• 强制工具权限约束：可以给只读类研究代理关闭 Write/Edit 等修改性工具，避免意外更改。

• 并行执行能力：多个子代理可以同时工作，延迟远低于串行执行。

• 按需选择模型以优化成本：轻量检索路由到 Haiku，复杂分析交给 Opus，避免“杀鸡用牛刀”。

按照 Anthropic 官方文档（2026 年）的建议，只要任务会生成大量不需要永久保留在主对话中的输出——比如运行测试、搜索代码库、处理日志——派发给子代理就是最优解。

内置子代理概览

Claude Code 开箱提供了以下内置子代理，无需额外配置即可直接使用：

子代理名称	模型	工具权限	典型触发场景
Explore	Haiku	只读（Read/Grep/Glob）	在代码库中搜索、定位文件
Plan	继承主会话	只读	Plan 模式下收集上下文
general-purpose	继承主会话	全部工具	复杂的多步骤任务
statusline-setup	Sonnet	读写	执行 /statusline 配置时
claude-code-guide	Haiku	只读	询问 Claude Code 自身功能

需要留意的是，Explore 和 Plan 会跳过 CLAUDE.md 和 git status 的加载，因此启动更快、成本更低。其余内置子代理以及所有自定义子代理则会正常加载 CLAUDE.md 中的项目指引。

快速上手：定义第一个自定义子代理

方式一：通过 /agents 命令（推荐）

在会话中输入：

text

/agents

在打开的管理界面中，切换到 Library 标签 → Create new agent → 选择 Personal（保存到 ~/.claude/agents/）→ Generate with Claude。只需用自然语言描述代理的职责，配置就会自动生成。

方式二：手写 Markdown 配置文件

子代理的定义文件采用 YAML frontmatter 加 Markdown 的组合格式：

markdown

---
name: code-reviewer
description: 专家级代码审查，写完代码后主动调用。检查质量、安全性和可维护性。
tools: Read, Grep, Glob, Bash
model: sonnet
color: blue
---

你是一位资深代码审查员。被调用时：
1. 运行 git diff 查看近期改动
2. 重点关注被修改的文件
3. 按优先级分类反馈（严重/警告/建议）
4. 每条问题提供具体修复示例

文件放置位置

text

# 当前项目专用（可纳入版本控制）
.claude/agents/code-reviewer.md

# 所有项目通用（个人配置）
~/.claude/agents/code-reviewer.md

子代理文件在会话启动时自动加载；通过 /agents 界面创建的代理则会立即生效，无需重启。

核心配置字段详解

yaml

---
name: my-agent          # 必填，小写字母和连字符
description: 用途描述    # 必填，Claude 据此判断何时委派
tools: Read, Bash, Grep # 可选，省略则继承主会话的全部工具
disallowedTools: Write  # 可选，工具黑名单（与 tools 互为补充）
model: sonnet           # 可选：sonnet/opus/haiku/inherit
permissionMode: auto    # 可选：default/acceptEdits/auto/dontAsk
maxTurns: 20            # 可选，最大交互轮次
memory: project         # 可选：user/project/local（跨会话记忆）
background: false       # 可选，是否始终后台运行
effort: high            # 可选：low/medium/high/xhigh/max
isolation: worktree     # 可选，在独立 git worktree 中运行
color: cyan             # 可选：red/blue/green/yellow/purple 等
---

模型选择的优先级从高到低依次是：

1. 环境变量 CLAUDE_CODE_SUBAGENT_MODEL

2. 调用时传入的 model 参数

3. frontmatter 中的 model 字段

4. 主会话当前使用的模型

bash

# 强制所有子代理统一使用 Haiku 以降低费用
export CLAUDE_CODE_SUBAGENT_MODEL=claude-haiku-4-5

并行子代理实践

同时调研多个模块

分别启动独立的子代理并行研究 authentication、database 和 API 三个模块，最后汇总结论：

text

同时研究 authentication、database、API 三个模块的代码

Claude 会同时派发三个 Explore 子代理，每个聚焦于一个目录，完成后将发现汇报给主会话。对大型代码库而言，相比逐个串行调研，这种方式能显著缩短等待时间。

后台执行耗时任务

按 Ctrl+B 将当前任务转入后台，或者直接在请求中说明：

text

在后台运行完整测试套件，只需返回失败用例和报错信息

后台子代理的行为特点如下：

• 与主会话并发执行，你可以继续交互而不被阻塞。

• 使用会话中已授予的权限，不会弹出新的授权请求。

• 如果遇到未经授权的操作，对应工具调用将失败，但子代理会继续剩余工作。

• 完成后在状态栏展示总耗时，形如 Agent completed · 3h 2m 5s。

• 若后台子代理因权限不足而失败，可以启动前台子代理重试，此时权限弹窗会正常出现。

bash

# 需要完全同步执行时，禁用所有后台任务
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

Agent View：并行会话的统一管理

v2.1.139（2026 年 5 月 11 日）正式引入了 Agent View，能够在一个视图内概览所有 Claude Code 会话：

bash

# 启动 Agent View（当前为 Research Preview）
claude agents

# 输出 JSON 格式的会话列表，便于脚本或 tmux 集成
claude agents --json

Agent View 会展示所有正在运行、等待输入和已结束的会话，包含状态、耗时、token 消耗等信息，并支持从列表直接切换到任意会话。

/goal 命令：设定完成条件自动推进

v2.1.139 同步新增的 /goal 命令允许设置一个完成条件，Claude 将持续跨轮次工作直到目标达成：

text

/goal 所有单元测试通过，且没有 TypeScript 类型错误

运行过程中会实时显示耗时、轮次和 token 用量面板，支持交互式、-p 和 Remote Control 三种模式。

固定后台会话（Pinned Background Sessions）

从 v2.1.147（2026 年 5 月 21 日）起，可以通过 Ctrl+T 创建固定后台会话，其特点包括：

• 空闲时保持存活，避免频繁初始化的开销。

• 在内存紧张时最后被回收，优先级高于普通临时会话。

• 特别适合需要频繁调用的常驻代理，比如持续监控脚本或实时 lint 服务。

Fork 模式：继承完整对话上下文的子代理

Fork 子代理会继承主会话当前的完整对话历史，免去向新代理重新解释背景的麻烦：

bash

# 启用 Fork 模式（需要 v2.1.117+）
export CLAUDE_CODE_FORK_SUBAGENT=1

启用后使用 /fork 命令派发：

text

/fork 为刚才的 parser 改动起草单元测试

Fork 与普通子代理的关键差异：

对比维度	Fork	普通子代理
上下文	继承全部对话历史	空白新上下文
系统提示	与主会话相同	来源于自定文件
Prompt Cache	与主会话共享，成本更低	独立缓存
权限提示	终端内正常弹出	后台时自动拒绝

因为系统提示和工具定义完全一致，Fork 的首次请求可以复用父会话的 prompt cache，派发成本比常规子代理更低。

子代理 Hooks 配置

可以在 frontmatter 中为子代理定义生命周期 Hook：

yaml

---
name: safe-bash-agent
description: 执行受限 bash 命令的代理
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

示例：创建仅允许 SELECT 查询的数据库只读代理

yaml

---
name: db-reader
description: 执行只读数据库查询，用于数据分析和报告生成。
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

对应的验证脚本：

bash

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# 阻断所有 SQL 写操作（不区分大小写）
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "已阻断：仅允许 SELECT 查询" >&2
  exit 2
fi

exit 0
bash

chmod +x ./scripts/validate-readonly-query.sh

在 settings.json 中也可以监听子代理的生命周期事件：

json

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup.sh" }
        ]
      }
    ]
  }
}

子代理的跨会话记忆（Persistent Memory）

开启 memory 字段后，子代理会在独立目录中逐步积累知识，在跨会话时保持记忆：

yaml

---
name: code-reviewer
description: 持续学习代码库规范的审查代理
memory: project
---

审查代码时，将发现的架构模式、命名规范和反复出现的问题记录到 agent memory。
这会帮助你在后续会话中提供更准确的建议。

memory 取值与存储位置对应关系：

值	存储路径	适用场景
user	~/.claude/agent-memory/<name>/	跨项目通用知识
project	.claude/agent-memory/<name>/	项目专属，可纳入版本控制
local	.claude/agent-memory-local/<name>/	项目专属，不提交到 git

常见问题

Q：子代理能否继续调用其他子代理？
不能。子代理不支持嵌套派生子代理。若需要多层委派，可考虑使用 Skills，或由主会话链式调用多个子代理。

Q：后台子代理因权限不足报错怎么办？
后台子代理会自动拒绝所有会触发权限弹窗的操作。解决方法是用相同任务启动一个前台子代理，在弹窗中手动授权；或者提前在 settings.json 的 permissions.allow 中添加对应规则。

Q：如何禁用某个内置子代理？
在 settings.json 中添加 deny 规则：

json

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(Plan)"]
  }
}

或者通过 CLI 参数：claude --disallowedTools "Agent(Explore)"

Q：子代理上下文窗口快满了怎么办？
子代理使用与主会话相同的自动压缩逻辑，默认在约 95% 容量时触发。可以通过环境变量提前触发，例如 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 表示在 50% 时压缩。

Q：如何查看子代理的完整执行记录？
子代理的 transcript 文件位于：

text

~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl

默认保留 30 天（由 cleanupPeriodDays 控制）。

实践推荐：团队代码审查流水线

将以下文件检入 .claude/agents/ 目录，团队成员即可共用：

yaml

# .claude/agents/pr-reviewer.md
---
name: pr-reviewer
description: PR 审查专家，提交 PR 前主动调用。检查代码质量、测试覆盖率和安全隐患。
tools: Read, Grep, Glob, Bash
model: sonnet
memory: project
color: purple
---

你是团队的 PR 审查员。被调用时：
1. 运行 `git diff main` 获取完整改动
2. 检查每个改动文件的测试覆盖
3. 扫描安全隐患（SQL 注入、XSS、密钥泄漏）
4. 检查是否符合 CLAUDE.md 中的团队规范
5. 输出分级反馈（P0 必须修复 / P1 建议修复 / P2 可选优化）

将文件提交后，开发者只需输入：

text

@pr-reviewer 审查本次 PR 改动

Claude Code 就会把任务委派给 pr-reviewer 子代理，审查结果以摘要的形式返回主会话。配合 memory: project 设置，审查代理会随着时间推移逐步深化对项目规范的理解，审查质量也会持续提高。

部署子代理并启用 Agent View 后，可以通过 claude agents --json 输出实时会话状态，方便集成到 CI/CD 流程或 tmux 看板中。对于需要对接国内推理资源的使用场景，星链4SAPI等AI大模型API中转平台支持 OpenAI/Anthropic 标准接口的第三方服务，能够让子代理的 API 调用直接接入，无需修改现有的子代理配置文件，减少额外适配工作。

将 PR 审查代理配置纳入团队 Runbook，每次合并前自动运行，可以将代码审查中 P0 问题的漏检率控制在极低水平。建议先在个人项目中验证 memory: project 的知识积累效果，后续再推广到团队共享仓库。