Gushen888 Docs

主题

子代理 ​

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

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

适合做什么 ​

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

如果任务需要你持续来回确认、每一步都依赖主会话历史,通常放在主会话更自然。如果只是复用提示词或工作流,但想继续使用主会话上下文,优先考虑 Skills。

内置子代理 ​

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

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

.claude/agents/code-reviewer.md

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

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

显式调用 ​

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:

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

Frontmatter 字段 ​

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

字段作用
name唯一标识,建议小写字母和连字符;Hook 里会作为 agent_type
description告诉 Claude 什么时候应该委托给它;写得越具体越容易自动触发
tools工具 allowlist;省略时继承主会话可用工具
disallowedTools从继承或指定工具里移除某些工具
modelinherit、sonnet、opus、haiku、fable 或完整模型 ID;默认 inherit
permissionModedefault、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 规则、根目录/家目录删除保护等限制,但不要把它当成常规默认值。

模型选择 ​

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

  • CLAUDE_CODE_SUBAGENT_MODEL
  • 本次调用传入的模型参数
  • agent frontmatter 的 model
  • 主会话模型

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

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

工具和 MCP 限制 ​

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

---
name: safe-researcher
description: 只读研究代理,用于探索代码和日志。
tools: Read, Grep, Glob, Bash
---
---
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 可以只让这个子代理看到它,避免主会话上下文塞满工具描述。

---
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:

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

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

.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
--agentclaude --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 里,最终只把结果回传。

/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 改同一工作区互相覆盖

官方参考 ​

面向编码工具与 Agent 工作流的稳定模型网关。

Gushen888 · 客服微信 zbzy_888 · 邮箱 gulin1989@163.com