Agents

Agents（代理） 在 Claude Code 里主要指 subagent（子代理）：拥有独立上下文窗口、可并行运行的 Claude 实例。主会话把子任务派给 subagent，只收回摘要结果，从而节省主上下文、提高探索与并行开发的效率。v2.1.198 起，subagent 默认在后台运行，主会话可继续其它工作；v2.1.232 起又默认开启 fork 型 subagent（subagent_type: "fork"）：它继承完整对话与 prompt 缓存，适合「接着当前上下文分头干」。

三种使用方式

日常开发多数时候不用手动管——Claude 会在需要时自己开 subagent；你要做的是在复杂任务时知道如何监控和显式编排。

⚠️ v2.1.277 起，subagent 的结果交回主 agent 时放在一个标明「subagent 输出」的标头下并缩进，结果里的文字无法冒充会话自身的指令；v2.1.271 起 auto mode 下 subagent 改用专门的交还调用（hand-back call）向调用方回报，由安全分类器审查，而不是事后再审查它的最后一条消息。

自定义 Subagent：.claude/agents/

与技能类似，subagent 用 Markdown + frontmatter 定义，放在：

示例 .claude/agents/security-reviewer.md：

---
name: security-reviewer
description: 专注 OWASP Top 10、密钥泄露、依赖 CVE 的安全评审
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是一名安全评审专家。收到代码路径或 diff 描述后：

1. 列出潜在漏洞与误报可能
2. 标注严重级别（critical / high / medium / low）
3. 给出可操作的修复建议，不要直接改代码除非用户要求

创建或修改后，让 Claude「创建一个 security-reviewer agent」或直接编辑文件即可；旧版交互式 /agents 管理界面已在 v2.1.198 移除，改为直接编辑 .claude/agents/ 或在对话中描述需求由 Claude 生成。

🆕 v2.1.248 起 agent frontmatter 还支持 experimental.cacheTtl（"5m" 或 "1h"），在没有全局 subagent 缓存 TTL 设置时为这个 agent 单独指定 prompt 缓存时长。

🆕 v2.1.271 起 frontmatter（以及 --agents 传入的 JSON）支持 omitClaudeMd：让自定义与插件 subagent 运行时不加载用户、项目与本机的 CLAUDE.md，托管策略文件仍会加载。

🆕 v2.1.281 起 --agents 配合 -p 也可以传一个 JSON 文件的路径（例如 claude -p --agents ./agents.json "Review my changes"），适合命令行放不下的大段定义；定义里的 prompt 也允许为空。

内置 Subagent

在对话中说「用 Explore subagent 查一下认证模块」即可触发；Explore 自 v2.0.17 起内置。

手动编排命令

详见 并行与后台协作。

动态工作流（Dynamic Workflow）

v2.1.154 引入：Claude 把超大任务自动编排成数十到数百个 subagent 的后台执行图，适合：

• 全仓库迁移（框架升级、语言改写）
• 大规模文档生成
• 跨模块一致性重构

用 /workflows 查看进度；/config 里可调整「动态工作流规模」建议值（非硬限制）。关闭：disableWorkflows in settings 或 CLAUDE_CODE_DISABLE_BUNDLED_SKILLS 相关开关。

⚠️ v2.1.219 起默认采用「中等规模」建议：目标少于 15 个 agent。 想要更大或不限制，在 /config 的「Dynamic workflow size」里改；也可以把 workflowSizeGuideline 写进任意 settings 文件固定下来（写了之后 /config 里那一行会隐藏）。运行中的工作流状态栏会显示当前默认规模。

⚠️ v2.1.271 起又下调了一档：「中等」规模的指导值从 15 个 agent 降到 10 个，Pro 套餐默认改为「小」规模。同版本起工作流撞到用量上限时会暂停，额度重置后自动继续，不再丢掉受影响的 agent。

v2.1.281 起提示框下方的后台工作流行会显示名称、进度条、agent 数（宽终端）、已运行时间、总 token 数与大规模工作流告警，/workflows 里按 x 停止指针所在的那次运行；v2.1.283 修复了模型回退期间启动的工作流让每个 agent 都跑在回退模型上（现在会重试配置的模型）。

扇出闸门：三个默认上限

从 v2.1.212 到 v2.1.219，Claude Code 陆续给「无限并行」加上了默认闸门。这是这一批版本里最容易让人困惑的一组变化——同一个任务在旧版本能开出几十个 agent，新版本可能自己收着跑：

后台 Agent 与 claude agents

v2.1.198 起 subagent 默认后台化后的典型工作流：

# 终端 1：主会话继续交互
claude

# 终端 2：统一监控
claude agents

claude agents 可查看多个并行会话状态、attach 到后台任务。禁用后台能力：CLAUDE_CODE_DISABLE_AGENT_VIEW=1（见环境变量）。

⚠️ v2.1.281 起，Claude 工作时按「立即发送」（ctrl+enter，或任何终端都能用的 ctrl+x ctrl+s）不再取消这一轮：正在运行的 shell 命令、subagent 等能转入后台的工作会转入后台继续跑，Claude 在同一轮里读到你的消息。同版本起 --setting-sources 限制会传给派生的会话，队友、/bg、claude agents 会话与 --worktree --tmux 都沿用父会话的设置来源。

v2.1.280 修复了一批后台 subagent 问题：LSP 插件启用时后台 subagent 可以用 LSP 工具；无头与 SDK 会话里发给正在收尾的后台 subagent 的消息不再丢失；启动它的对话在读取报告前被压缩，也不再丢掉已完成 subagent 的报告；后台 subagent 运行时按两次 Ctrl+C 即可退出。

并行开发还可为每个任务开独立 worktree（claude --worktree feature-a），在上手使用 · 并行开发有逐步说明。

跨会话消息：SendMessage 与 ListAgents

🆕 v2.1.224 起，不同的 Claude Code 会话之间可以互相发消息——本机的也好，你其它机器上的 Remote Control 会话也好。Claude 用 ListAgents 发现可达的会话，用 SendMessage 把任务或问题递过去：

• 点名：v2.1.232 起在输入框里 @会话名 即可，Claude 会直接联系那个会话。同一台机器上的交互式会话名字保持唯一，重名时自动加 name-word-word 后缀并告诉你。
• 等对方空闲：v2.1.236 起可以带 notify_when_idle，请对方下次空闲时通知你一次（macOS 与 Linux，一次性，不轮询）。
• 平台：首发支持 macOS 与 Linux，v2.1.239 起 Windows 也可用；v2.1.248 起 Bedrock、Vertex、Foundry 与关闭遥测时同样可用。
• 入站控制：crossSessionInbound 设置（或 /config 里的「Messages from your other sessions」）决定别的会话发来的消息是接受、暂存还是拒绝；以绕过权限模式运行的会话收到的消息会先暂存等你批准。v2.1.271 起消息被对方的权限模式策略暂存时，无头发送方会收到投递通知，SendMessage 的结果也不再暗示对方已读。

技能 + Agent：context: fork

在 Skills 里设置：

context: fork
agent: Explore

技能正文会在指定 subagent 内执行，结果摘要回到主会话——适合深度调研而不撑爆主上下文。

⚠️ v2.1.218 起，带 context: fork 的技能默认在后台运行（此前是同步等待）。也就是说触发后主会话立刻能继续干别的，结果稍后以通知形式回来。需要同步等结果的技能，在其 frontmatter 里单独写 background: false 退出这个默认。

Task 工具与任务追踪

v2.1.142 起默认用结构化 Task API 替代旧版 TodoWrite：

• TaskCreate / TaskUpdate / TaskGet / TaskList

Claude 在复杂多步任务中用来维护任务板；与 subagent 并行互补——Task 管「计划」，subagent 管「谁去干活」。

⚠️ 这组工具在新模型上已不再提供：v2.1.233 起 Opus 4.8、Sonnet 5、Fable 5 及更新的模型拿不到 Task 系列与 TodoWrite；v2.1.268 起进一步收窄到只有 Claude 3.x、Opus 4.0–4.7、Sonnet 4.0–4.6、Haiku 4.5 提供。确实需要的话设 CLAUDE_CODE_ENABLE_TODO_TOOLS=1 找回。

环境变量精选

与插件、MCP 的关系

插件可打包 agents + skills + hooks + MCP，一次安装全团队对齐编排能力：

/plugin install my-team-pack@company-marketplace

MCP 服务器暴露的工具对 subagent 同样可用（受 manifest 权限约束）。

常见误区

1. 「每个 subagent 有无限上下文」——仍有模型窗口上限；Explore 用 Haiku 是为了又快又省，不是魔法。
2. 「后台 = 电脑关机也能跑」——本地后台会话依赖本机进程；长期无人值守用 Claude Code on the web、Routines 或 CI。
3. 「/agents 打不开管理界面」——v2.1.198 后改为编辑 .claude/agents/ 或口述让 Claude 创建。
4. 「subagent 输出总是完整文件内容」——应要求 subagent 只返回摘要。旧版本靠 TASK_MAX_OUTPUT_LENGTH 截断，⚠️ v2.1.277 起这个变量已不再有任何作用。
5. 「subagent 返回了就是做完了」——v2.1.246 起撞到 maxTurns 上限的 subagent 会返回标记为「部分完成」的输出，并提示可以用 SendMessage 让它继续；看到这个标记别当成已完成。

建议实践

1. 探索型问题交给 Explore，主会话只收结论。
2. 大重构用 /batch 或动态工作流，不要在一个会话里硬扛。
3. 团队专用评审/安全/agent 放进 .claude/agents/ 并提交 git。
4. 用 claude agents 或 /tasks 养成「先看后台在跑什么」的习惯。

延伸阅读

• 并行与后台协作——命令速查表
• Skills——context: fork 与 bundled skills
• Plugins——把 agents 打包分发给团队
• 配置文件——agents 路径与作用域
• 版本 Changelog——subagent 与动态工作流演进时间线

← 上一篇：Skills · 下一篇：Plugins