# Claude Code 子代理

> Claude Code 子代理的内置类型、自定义 agents、作用域、frontmatter、权限、模型、MCP、Hooks、上下文隔离和 fork。

URL: https://docs.passion8.cc/docs/claude-code/subagents
Language: zh-CN
Publisher: Passion8

Subagent 是 Claude Code 里的专用子代理。它适合处理会产生大量搜索结果、日志、文件内容或中间推理的支线任务:子代理在自己的上下文窗口里工作,最后只把摘要或结果交回主会话。




把子代理理解成“可配置的临时同事”:它有自己的系统提示、工具范围、权限模式、模型选择和上下文,但仍属于当前 Claude Code 会话。




## 适合做什么

| 场景 | 为什么适合子代理 |
| --- | --- |
| 大范围代码探索 | 大量 Grep/Read 输出不会塞进主会话 |
| 专项审查 | 用固定 prompt 和只读工具保证审查口径 |
| 并行研究 | 多个方向独立查,主会话汇总结果 |
| 高风险工具收敛 | 用 `tools`、`disallowedTools`、`permissionMode` 限制能力 |
| 成本控制 | 给探索型子代理指定更便宜的模型别名 |

如果任务需要你持续来回确认、每一步都依赖主会话历史,通常放在主会话更自然。如果只是复用提示词或工作流,但想继续使用主会话上下文,优先考虑 [Skills](https://docs.passion8.cc/docs/claude-code/plugins)。

## 内置子代理

Claude Code 会在合适时自动使用内置子代理。它们继承主会话权限,但有各自的工具限制。

| 子代理 | 工具和模型 | 典型用途 |
| --- | --- | --- |
| `Explore` | 只读工具;继承主会话模型,Claude API 上会封顶到 Opus | 搜索、理解代码库、快速定位文件 |
| `Plan` | 只读工具;继承主会话模型 | plan mode 下先研究再给计划 |
| `general-purpose` | 通常可用全部工具;继承主会话模型 | 复杂多步骤任务、需要探索也需要修改 |
| `statusline-setup` | Sonnet | 配置 `/statusline` 时使用 |
| `claude-code-guide` | Haiku | 回答 Claude Code 功能问题 |

`Explore` 和 `Plan` 为了速度和成本,不会加载 `CLAUDE.md` 和父会话 git status。其他内置子代理和自定义子代理会加载这些上下文。




如果你有必须让 `Explore` 或 `Plan` 知道的规则,例如“不要读 vendor 目录”,需要在本次委托提示里明确写出来,不要只依赖 `CLAUDE.md`。




限制内置子代理的常见方式:

| 需求 | 做法 |
| --- | --- |
| 禁用某个内置子代理 | 在 permissions deny 里加 `Agent(Explore)` |
| 禁止所有子代理委托 | deny `Agent` 工具 |
| 只禁用 `Explore` / `Plan` | 设置 `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1` |
| 非交互或 SDK 里移除全部内置类型 | 设置 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1` |

## 创建一个自定义子代理

自定义子代理是一个 Markdown 文件:上方 YAML frontmatter 写配置,正文写系统提示。





### 选择作用域


项目专用放 `.claude/agents/`,个人全局放 `~/.claude/agents/`。




### 写 agent 文件


```markdown title=".claude/agents/code-reviewer.md"
---
name: code-reviewer
description: 代码审查专家。写完或修改代码后主动使用,检查质量、安全性和可维护性。
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是资深代码审查员。被调用时先查看相关改动,只做审查和建议,不要编辑文件。
按严重程度输出:必须修复、建议修复、可选优化。每条都给出文件位置、原因和修复方向。
```




### 显式调用


```text
Use the code-reviewer subagent to review my recent changes
```

也可以在输入框里用 `@` 选择 agent,例如 `@"code-reviewer (agent)" 看一下认证模块改动`。







Claude Code 会监听 `~/.claude/agents/` 和 `.claude/agents/` 的变更。新建或编辑文件后,通常几秒内生效。两个情况需要重启:会话启动时目标 `agents` 目录还不存在,或启动时用了 `--disable-slash-commands`。




官方 v2.1.198 起,`/agents` 不再打开旧的交互式创建向导。现在更推荐让 Claude 生成 agent 文件,或直接编辑 `.claude/agents/` / `~/.claude/agents/`。




## 作用域和优先级

同名子代理同时存在时,Claude Code 按优先级选择一个定义。

| 位置 | 作用域 | 优先级 |
| --- | --- | --- |
| Managed settings | 组织级 | 最高 |
| `--agents` CLI JSON | 当前会话 | 2 |
| `.claude/agents/` | 当前项目 | 3 |
| `~/.claude/agents/` | 个人所有项目 | 4 |
| 插件 `agents/` | 启用插件的项目 | 最低 |

补充规则:

- `.claude/agents/` 会从当前工作目录向上扫描;嵌套目录里同名时,离当前目录最近的定义优先。
- `.claude/agents/` 和 `~/.claude/agents/` 会递归扫描,但 agent 身份只由 frontmatter 的 `name` 决定,不是文件名或子目录。
- 同一作用域内不要重复 `name`;`/doctor` 可报告部分重复定义问题。
- 插件 agent 的子目录会进入作用域名,例如 `my-plugin:review:security`。
- 插件 agent 出于安全原因会忽略 `hooks`、`mcpServers`、`permissionMode`。

临时会话也可以用 `--agents` 传 JSON:

```bash
claude --agents '{
  "safe-reviewer": {
    "description": "只读代码审查。修改代码后使用。",
    "prompt": "你是只读代码审查员,输出问题和建议,不要改文件。",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'
```

## Frontmatter 字段

只有 `name` 和 `description` 必填。正文是子代理的系统提示。

| 字段 | 作用 |
| --- | --- |
| `name` | 唯一标识,建议小写字母和连字符;Hook 里会作为 `agent_type` |
| `description` | 告诉 Claude 什么时候应该委托给它;写得越具体越容易自动触发 |
| `tools` | 工具 allowlist;省略时继承主会话可用工具 |
| `disallowedTools` | 从继承或指定工具里移除某些工具 |
| `model` | `inherit`、`sonnet`、`opus`、`haiku`、`fable` 或完整模型 ID;默认 `inherit` |
| `permissionMode` | `default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan` |
| `maxTurns` | 限制 agentic turn 数量 |
| `skills` | 启动时预加载 Skill 全文 |
| `mcpServers` | 只给该子代理连接或引用 MCP server |
| `hooks` | 只在该子代理生命周期内运行的 hooks |
| `memory` | 持久记忆作用域:`user`、`project`、`local` |
| `background` | 设为 `true` 时总是后台运行 |
| `effort` | 覆盖当前会话 effort,可用值取决于模型 |
| `isolation` | 设为 `worktree` 时在临时 git worktree 里运行 |
| `color` | 面板和 transcript 中的显示颜色 |
| `initialPrompt` | 当该 agent 作为主会话 agent 启动时自动提交的第一条 prompt |




`bypassPermissions` 会跳过大部分权限提示,风险很高。子代理仍会受明确 ask 规则、根目录/家目录删除保护等限制,但不要把它当成常规默认值。




## 模型选择

子代理模型按这个顺序解析:

1. `CLAUDE_CODE_SUBAGENT_MODEL`
2. 本次调用传入的模型参数
3. agent frontmatter 的 `model`
4. 主会话模型

`model` 省略时等同于 `inherit`。如果组织或 provider 的模型 allowlist 不允许某个值,Claude Code 会跳过该值并回退到继承模型。




接入 Passion8 时,模型别名和完整模型 ID 最终要以 Passion8 控制台可用模型及网关映射为准。子代理不会单独配置 Base URL,仍使用当前 Claude Code 会话的接入配置。




## 工具和 MCP 限制

`tools` 是 allowlist,`disallowedTools` 是 denylist。两者同时出现时,先移除 denylist,再从剩余工具里解析 allowlist。

```yaml
---
name: safe-researcher
description: 只读研究代理,用于探索代码和日志。
tools: Read, Grep, Glob, Bash
---
```

```yaml
---
name: local-only
description: 继承所有工具,但禁止 GitHub MCP。
disallowedTools: mcp__github
---
```

MCP 工具可以用精确工具名,也可以用 server 级模式:

| 写法 | 含义 |
| --- | --- |
| `mcp__github` | 匹配 GitHub server 的全部工具 |
| `mcp__github__*` | 同上,显式通配 |
| `mcp__*` | 匹配所有 MCP 工具,常用于 deny |

某些依赖主 UI 或会话状态的工具不会给子代理使用,即使写进 `tools` 也无效,例如 `AskUserQuestion`、`EnterPlanMode`、`ScheduleWakeup`、`WaitForMcpServers`。

### 子代理专属 MCP

把 MCP server 写进 `mcpServers` 可以只让这个子代理看到它,避免主会话上下文塞满工具描述。

```yaml
---
name: browser-tester
description: 用真实浏览器验证页面。
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github
---
```

内联 MCP 在子代理启动时连接、结束时断开。字符串引用则复用主会话已经配置的同名 server。企业 MCP 策略、`--strict-mcp-config`、`--bare` 等限制仍会生效。

## 权限和 Hooks

子代理继承主会话权限上下文,也可以用 `permissionMode` 覆盖。例外是主会话已处于 `bypassPermissions`、`acceptEdits` 或 `auto` 时,父级模式优先。

| 模式 | 行为 |
| --- | --- |
| `default` | 标准权限检查和提示 |
| `acceptEdits` | 自动接受工作目录内编辑和常见文件命令 |
| `auto` | 用后台分类器判断命令和受保护目录写入 |
| `dontAsk` | 自动拒绝需要询问的权限请求 |
| `bypassPermissions` | 跳过大部分权限提示 |
| `plan` | 只读计划模式 |

子代理 frontmatter 里可以写只对它生效的 hooks:

```yaml
---
name: db-reader
description: 只执行只读数据库查询。
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---
```

项目级 `settings.json` 也能监听子代理生命周期:

```json title=".claude/settings.json"
{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-reader",
        "hooks": [{ "type": "command", "command": "./scripts/setup-db.sh" }]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [{ "type": "command", "command": "./scripts/cleanup-db.sh" }]
      }
    ]
  }
}
```

## 调用方式

| 方式 | 用法 | 适合 |
| --- | --- | --- |
| 自动委托 | 在 `description` 写清楚触发条件 | 日常无需指定 |
| 自然语言 | `Use the code-reviewer subagent...` | 偶尔指定 |
| `@` mention | `@"code-reviewer (agent)" ...` | 必须用某个 agent |
| `--agent` | `claude --agent code-reviewer` | 整个会话都以该 agent 身份运行 |
| settings | `{ "agent": "code-reviewer" }` | 项目默认 agent |
| `--agents` | 启动时传 JSON | 临时实验或自动化 |

`--agent` 会让主会话本身使用该 agent 的系统提示、工具限制和模型。它不是“启动一个子任务”,而是替换当前会话的默认行为。

## 前台、后台和恢复

官方 v2.1.198 起,子代理默认偏向后台运行;当 Claude 需要结果才能继续时会放到前台。

| 模式 | 行为 |
| --- | --- |
| 前台子代理 | 主会话等待它完成;权限提示即时转给你 |
| 后台子代理 | 你可以继续工作;需要权限时会在主会话弹出并标明是谁在请求 |

你可以明确要求“后台运行”或“前台运行”,也可以用 `Ctrl+B` 把运行中的任务转到后台。设置 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` 可禁用后台任务能力。

每次调用通常会创建新的子代理实例。要继续旧实例,直接让 Claude resume 它。可恢复的子代理保留完整历史、工具结果和推理上下文。`Explore` 和 `Plan` 是一次性内置代理,不会返回可恢复 agent ID;需要继续上下文时用 `general-purpose` 或自定义 agent。

子代理 transcript 独立保存于主会话之外。主会话 compact 不会清掉它们;清理周期由 `cleanupPeriodDays` 控制,默认 30 天。

## 上下文边界

非 fork 子代理启动时是新的独立上下文,不会看到主会话的完整聊天历史、已经读过的文件或已经调用过的 Skills。它通常会收到:

- 自己的系统提示和 Claude Code 附加的基础环境信息
- Claude 写给它的任务说明
- `CLAUDE.md` 和 memory 层级,但 `Explore` / `Plan` 例外
- 会话开始时的 git status,但 `Explore` / `Plan` 例外
- `skills` 字段预加载的 Skill 全文

需要完整继承主会话上下文时,用 fork。

## Fork 当前会话

`/fork` 会创建一种特殊子代理:它继承当前会话完整上下文、系统提示、工具、模型和历史,但它的工具调用仍留在子代理 transcript 里,最终只把结果回传。

```text
/fork draft tests for the parser changes so far
```

Fork 适合“同一上下文下试一个并行方向”,例如让它草拟测试、比较实现方案或继续调查一个分支。它和命名子代理的区别:

| 对比 | Fork | 命名子代理 |
| --- | --- | --- |
| 上下文 | 继承完整主会话 | 新上下文,只拿到任务说明 |
| 系统提示和工具 | 与主会话一致 | 来自 agent 定义 |
| 模型 | 与主会话一致 | 来自 `model` 字段或继承 |
| Prompt cache | 可复用主会话前缀 | 单独缓存 |

`CLAUDE_CODE_FORK_SUBAGENT=1` 可显式启用 fork 模式,设为 `0` 可禁用。Fork 不能再 spawn 另一个 fork。

## 最佳实践

| 做法 | 原因 |
| --- | --- |
| 让每个 agent 专注一类任务 | `description` 更容易匹配,输出也更稳定 |
| 审查型 agent 默认只读 | 避免“审查”过程中顺手修改 |
| 项目 agent 提交到版本库 | 团队共享同一套审查和实现规则 |
| 长日志、测试、搜索交给子代理 | 主会话上下文更干净 |
| 高风险能力用 hooks 再兜底 | `tools` 只能限制工具,hook 能检查具体命令 |
| 要并行修改时配合 worktree | 避免多个 agent 改同一工作区互相覆盖 |

## 官方参考

- [Create custom subagents](https://code.claude.com/docs/en/sub-agents.md)
- [Run parallel sessions with worktrees](https://code.claude.com/docs/en/worktrees.md)
- [Tools reference](https://code.claude.com/docs/en/tools-reference.md)
- [Hooks reference](https://code.claude.com/docs/en/hooks.md)