Claude Code 子代理实战2026：并行任务+后台会话+Agent View完整配置指南

agents---description: 执行受限 bash 命令的代理hooks:hooks:hooks:---

七牛云行业应用

322人浏览 · 2026-05-26 10:23:12

七牛云行业应用 · 2026-05-26 10:23:12 发布

Claude Code 子代理完整实战指南：并行任务、后台会话、Agent View 全解

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

子代理解决什么问题

在 Claude Code 主会话中直接运行测试、抓取文档、处理日志，会把大量无关输出堆积进上下文，压缩可用 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` 命令（推荐）

/agents

在打开的界面中，切换到 Library 标签 → Create new agent → 选择 Personal（保存到 ~/.claude/agents/）→ Generate with Claude，输入描述后自动生成配置。

方式二：手写 Markdown 文件

子代理文件使用 YAML frontmatter + Markdown 格式：

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

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

文件存放位置

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

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

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

子代理核心配置字段

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

模型选择优先级（从高到低）：

CLAUDE_CODE_SUBAGENT_MODEL 环境变量
调用时传入的 model 参数
frontmatter 中的 model 字段
主会话模型

# 将所有子代理强制使用 Haiku 降低成本
export CLAUDE_CODE_SUBAGENT_MODEL=claude-haiku-4-5

并行子代理实战

同时研究多个模块

用独立子代理并行研究 authentication、database、API 三个模块，然后综合结论

Claude 会同时派发三个 Explore 子代理，每个专注一个目录，完成后汇报给主会话。相比串行研究，对大型代码库速度提升显著。

后台运行长时任务

按 Ctrl+B 将当前任务移至后台，或在请求中说明：

在后台跑完整测试套件，只返回失败用例和错误信息

后台子代理（Background Subagents）的行为特征：

与你继续工作的主会话并发执行
使用会话中已授权的权限，不弹出新权限请求
如遇到未授权操作，该工具调用失败但子代理继续运行
完成时在状态栏显示耗时，如 Agent completed · 3h 2m 5s

若后台子代理因权限缺失失败，可启动前台子代理重试（会正常弹出权限确认）。

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

Agent View：统一管理并行会话

v2.1.139（2026 年 5 月 11 日）正式引入 Agent View，提供所有 Claude Code 会话的统一视图：

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

# 以 JSON 格式输出会话列表（供脚本/tmux 使用）
claude agents --json

Agent View 展示内容：

所有运行中、等待输入、已完成的会话
每个会话的状态、耗时、token 消耗
支持从列表直接切换进入任意会话

`/goal` 命令：设置完成条件持续工作

v2.1.139 同步引入 /goal 命令，设置完成条件后 Claude 持续跨轮次工作直到满足：

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

运行时显示实时耗时、轮次数、token 覆盖面板。支持交互式、-p 和 Remote Control 三种模式。

固定后台会话（Pinned Background Sessions）

v2.1.147（2026 年 5 月 21 日）推出固定后台会话功能：

# 创建固定后台会话
Ctrl+T

特性：

空闲时保持存活，避免重复初始化开销
在内存压力下最后被释放（优先级高于普通临时会话）
适合需要频繁调用的长驻代理（如监控脚本、实时 lint）

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

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

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

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

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

Fork 与普通子代理的关键区别：

对比项	Fork	普通子代理
上下文	继承完整对话历史	全新上下文
系统提示	同主会话	来自定义文件
Prompt Cache	与主会话共享（更便宜）	独立缓存
权限提示	在终端正常弹出	后台时自动拒绝

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

子代理 Hooks 配置

在 frontmatter 中定义子代理生命周期 Hook

---
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 查询的数据库代理

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

对应验证脚本：

#!/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

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

在 settings.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 字段后，子代理在独立目录积累知识，跨会话保持：

---
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 规则：

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

或用 CLI 参数：claude --disallowedTools "Agent(Explore)"

Q：子代理的上下文窗口满了怎么办？
子代理支持与主会话相同的自动压缩逻辑，默认在约 95% 容量时触发。可通过 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 提前触发（设为 50 表示 50% 时压缩）。

Q：如何查看子代理的完整执行记录？
子代理 transcript 存储在：

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

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

实战推荐配置：团队代码审查流水线

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

# .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 可选优化）

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

@pr-reviewer 审查本次 PR 改动

Claude Code 会将任务委派给 pr-reviewer 子代理，审查结果作为摘要返回主会话。结合 memory: project 设置，审查代理会随时间积累对项目规范的理解，审查质量持续提升。

部署子代理并启用 Agent View 后，可通过 claude agents --json 输出实时会话状态集成到 CI/CD 流水线或 tmux 看板。例如七牛云推理服务兼容 OpenAI/Anthropic 标准接口，开发者可将子代理的 API 调用无缝对接国内推理节点，无需修改现有子代理配置文件。

把 PR 审查代理配置加入团队 Runbook，每次 merge 前自动运行，可将代码审查 P0 问题漏检率降至接近零。下一步建议先在个人项目验证 memory: project 的知识积累效果，再推广到团队共享仓库。

延伸资源

多模型 API 调用与 Agent 接入：七牛云 AI 推理服务
OpenClaw/Claude Code 配置指南：通过 Router 配置 Claude Code
官方子代理完整文档：Claude Code Sub-agents
Claude Code Changelog（v2.1.139+）：code.claude.com/docs/en/changelog

AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

聚合AI工具KULAAI：GPT、Claude、Gemini、DeepSeek热门模型一键使用

AI Agent技术社区

本地部署更安全！OpenClaw 数字员工搭建教程

AI Agent技术社区

NuminaMath-7B-CoT-openmind未来路线图：数学AI的发展方向

NuminaMath-7B-CoT-openmind作为一款专注于数学推理的AI模型，正引领着数学问题解决的智能化浪潮。本文将深入探讨这款数学AI的未来发展方向，为您揭示其在提升推理能力、扩展应用场景等方面的清晰路径。## 强化数学推理能力：迈向更高难度问题NuminaMath-7B-CoT-openmind目前已在AMC 12级别的数学竞赛问题上展现出一定的解题能力，但在AIME和数学奥