配置子智能体

版本要求与措辞以官方为准。

选择作用范围

子智能体文件放在哪里决定谁能用它，前置信息决定它能做什么。同名时用高优先级位置的那个：

项目子智能体适合特定代码库，检入版本控制让团队一起改进；它们从当前工作目录向上查找，所以到仓库根之间每个 .claude/agents/ 都会被扫描，多个嵌套目录定义同名 name 时用离工作目录最近的。用 --add-dir 或 /add-dir 添加目录时，也会加载其 .claude/agents/。用户子智能体是个人的、所有项目可用。插件的 agents/ 目录也递归扫描，子文件夹成为带作用域的标识的一部分：插件 my-plugin 里的 agents/review/security.md 注册为 my-plugin:review:security。CLI 定义的子智能体以 JSON 在启动时传入，只存在于该会话、不存盘，适合快速测试或自动化脚本；一次 --agents 可定义多个：

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

非交互模式下 --agents 还接受指向含同样对象的 JSON 文件的路径（定义太大时用，如 claude -p --agents ./agents.json "Review my changes"；交互会话里会拒绝文件路径）。每个顶层键是智能体名（不要以 - 开头），值是定义，含：prompt（系统提示，等价于文件式子智能体的 Markdown 正文，可以为空；用 --agent 选择一个 prompt 为空且无 memory 字段的智能体作会话智能体时，会话的系统提示保持不变，空 prompt 需要 v2.1.281+）、前置信息字段（description、tools、disallowedTools、model、permissionMode、mcpServers、hooks、maxTurns、skills、initialPrompt、memory、effort、background、omitClaudeMd、isolation），color 和 experimental 在这里被忽略而不是拒绝。托管子智能体由组织管理员部署：把 Markdown 文件放在托管设置目录里的 .claude/agents/，格式同项目和用户子智能体，优先于它们。插件子智能体来自你安装的插件，随你的自定义子智能体自动加载，在 @ 提及补全里以带作用域的名称出现；出于安全，插件子智能体不支持 hooks、mcpServers、permissionMode 字段（加载时被忽略），需要它们就把智能体文件复制到 .claude/agents/ 或 ~/.claude/agents/。任何范围的子智能体定义也可用于智能体团队：生成队友时可引用某个子智能体类型，Claude Code 把定义的一部分应用到队友上。

文件格式

子智能体文件是 YAML 前置信息加 Markdown 系统提示：

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Claude Code 监视 ~/.claude/agents/ 和 .claude/agents/：你在磁盘上添加或编辑子智能体文件、或让 Claude 写一个，几秒内就会被检测到，下次委派用更新后的定义，不需要重启。仍需重启的三种情况：监视器只覆盖会话启动时已存在的目录，所以在新 agents 目录里创建某范围的第一个智能体文件后要重启；不监视 --add-dir//add-dir 添加目录里的 .claude/agents/；用 --disable-slash-commands 启动的会话完全不监视这些目录。正文成为子智能体的系统提示：子智能体只收到这个系统提示加工作目录等基本环境信息，不是 Claude Code 的系统提示。非交互模式下用 --append-subagent-system-prompt 把文本附加到每个子智能体系统提示的末尾（含嵌套的，fork 除外）。子智能体在主对话的当前工作目录里启动，其内部的 cd 命令在 Bash/PowerShell 工具调用之间不持久，也不影响主对话的工作目录；想给子智能体一份隔离的仓库副本就设 isolation: worktree——此时它的命令在 worktree 里运行，工作目录解析到主检出的命令会失败（v2.1.203 之前可能在主检出里运行）；检查覆盖启动 Claude Code 的目录所在的整个仓库，会话本身在关联 worktree 里时还覆盖该 worktree 所链接的主检出；对 Bash 命令还会阻止把 git 重定向到主检出的命令，以及无法从命令文本验证其 git 留在 worktree 内的命令（如命令名在运行时计算）；PowerShell 命令只做工作目录检查，Monitor 命令与 Bash 命令走同样的检查。

前置信息字段

只有 name 和 description 必填。多词字段名用 camelCase（如 maxTurns、disallowedTools），必须与下表完全一致：Claude Code 会忽略不认识的字段且不报错。

Claude Code 会静默跳过的文件（在项目、用户、托管 agents 目录或 --add-dir 下的目录里，前置信息有这些问题时不在会话里报告）：没有 name（当作与智能体放在一起的文档）；开头的 --- 不是文件第一行（读作没有前置信息）；name 以 - 开头或含 :（写入调试日志错误）；有 name 没有 description（原因写入调试日志）；YAML 无法解析（不读任何字段、跳过、解析错误写入调试日志）。用 --debug 看日志。没有 name 或无法解析的插件子智能体仍以文件名加载。会话前检查 agents 目录：对该目录运行 claude plugin validate（如 .claude/agents、~/.claude/agents），能找出前置信息无法解析的文件。

选择模型

model 字段控制子智能体用哪个模型。Claude 调用子智能体时还可以为这次调用传 model 参数。Claude Code 按此顺序确定模型：1 本次调用的 model 参数；2 子智能体定义的 model 前置信息（inherit 选主对话的模型）；3 环境变量 CLAUDE_CODE_SUBAGENT_MODEL（设为模型别名或 ID 时）；4 主对话的模型。有两种情况下，调用参数或前置信息里的族别名（如 opus）解析为主对话的模型，而不是别名指向的版本：主对话的模型属于该族（子智能体用主对话的精确模型，含 [1m] 后缀，从而得到同样的扩展上下文窗口）；在非 Anthropic API 的服务商上 Claude Code 无法判断主对话的模型族（如 Bedrock 上尚未解析到底层模型的应用推理 profile ARN）。CLAUDE_CODE_SUBAGENT_MODEL 里的别名总是解析到别名指向的版本。单独设置它不改变内置 Explore 和 Plan 子智能体用的模型；设为 inherit 等于不设置（v2.1.251 之前它排在最前，覆盖调用参数和前置信息）。Claude Code 会对照你组织的 availableModels 允许列表检查这些值，被阻止时替换模型：族别名（如 opus）运行在允许列表所许可的该族最新版本上；其他被阻止的值、替换机制不适用的服务商、或允许列表不允许该族任何版本时，改用继承的模型；交互会话里会显示点名请求模型与实际运行模型的警告。用 /tasks 查看子智能体实际在用的模型（有 effort 时也显示）；调用参数里的 model 也适用于恢复或后续消息（v2.1.211 之前恢复会丢掉它）。自 v2.1.198 起，子智能体继承主对话的扩展思考配置（没有按子智能体的思考设置）。让所有子智能体用同一个模型：CLAUDE_CODE_SUBAGENT_MODEL 只是默认值，子智能体定义或 Claude 传入的模型仍优先；要对每个子智能体、队友和工作流智能体应用一个模型，同时把 CLAUDE_CODE_SUBAGENT_MODEL_FORCE 设为 1（需要 v2.1.257+）——两者都设则用 CLAUDE_CODE_SUBAGENT_MODEL 的模型，只设 _FORCE 则用主对话的模型；例如在设置文件的 env 里同时设 "CLAUDE_CODE_SUBAGENT_MODEL": "haiku" 和 "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"，运行时用 /tasks 验证。_FORCE 开启时 Claude Code 忽略每个子智能体定义的 model（含内置 Explore 和 Plan），Claude 启动子智能体时也不能传模型；fork 和以 model: inherit 在子智能体里运行的 Skill 仍用主对话的模型。

控制子智能体的能力

可用工具：子智能体继承主对话里的内置工具和 MCP 工具，再经两个过滤器收窄：第一个从每个子智能体里去掉一小撮工具——Agent（子智能体处于深度上限时；fork 里该工具仍列出但调用时报错）、AskUserQuestion、EndConversation、EnterPlanMode、ExitPlanMode（除非 permissionMode 为 plan）、ScheduleWakeup、WaitForMcpServers、Workflow；第二个作用于后台运行的子智能体：除 Agent 与 ExitPlanMode 照第一个过滤器的条件外，后台子智能体保留每个 MCP 工具，但内置工具只保留 Read、Grep、Glob、LSP（v2.1.280 之前不行）、Bash、PowerShell、Edit、Write、NotebookEdit 等一小部分；智能体团队的队友另外保留任务工具和 cron 工具（TaskCreate、TaskGet、TaskList、TaskUpdate、CronCreate、CronDelete、CronList）。限制工具用 tools 作允许列表，或用 disallowedTools 作拒绝列表：tools: Read, Grep, Glob, Bash 让子智能体不能编辑或写文件、不能用任何 MCP 工具；disallowedTools: Write, Edit 则继承其余工具池。两者都设时先应用 disallowedTools，再对剩余工具池解析 tools，两边都列出的工具被移除。两个字段还接受 MCP 服务器级模式：mcp__<服务器> 或 mcp__<服务器>__* 授予或移除该服务器的所有工具（disallowedTools 里的 mcp__* 移除任何服务器的所有 MCP 工具）。带限定符的 disallowedTools 条目（如 Bash(git push *)）仍然移除整个工具，想保留 Bash 又拦截特定命令，要在设置的 permissions.deny 里加 Bash deny 规则。

限制可以生成哪些子智能体：作为主线程用 claude --agent 运行的智能体可以用 Agent 工具生成子智能体；用 tools 字段里的 Agent(agent_type) 语法限制类型（v2.1.63 起 Task 工具改名为 Agent，旧的 Task(...) 引用仍作为别名有效）。例如 tools: Agent(worker, researcher), Read, Bash 是允许列表，只有 worker 和 researcher 能被生成，试图生成别的类型会失败；想按名阻止特定智能体而允许其余的，改用 permissions.deny；不带括号的 Agent 允许生成任何子智能体；完全省略 Agent 则不能用 Agent 工具生成任何子智能体。该允许列表语法只适用于用 --agent 作主线程的智能体；在子智能体定义里列出 Agent 让它在深度上限允许时生成自己的子智能体，括号里的类型列表被忽略。

把 MCP 服务器限定给某个子智能体：用 mcpServers 字段让子智能体访问主对话里没有的 MCP 服务器。内联定义的服务器在子智能体启动时连接、结束时断开；字符串引用共享父会话的连接。该字段在智能体文件可运行的两种情境都适用：作为子智能体（经 Agent 工具或 @ 提及），或作为主会话（--agent 或 agent 设置，此时内联服务器在启动时与 .mcp.json 和设置文件里的服务器一起连接）。每项是内联定义（以服务器名为键，schema 同 .mcp.json，支持 stdio、http、sse、ws）或已配置服务器的名字：

mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github

想让某个 MCP 服务器完全不进入主对话、避免它的工具描述占用那里的上下文，就在这里内联定义而不是放进 .mcp.json——子智能体拿到工具，父对话没有。来自你项目 .claude/agents/ 或 --add-dir 目录 .claude/agents/ 的智能体文件里的内联服务器，只有信任了该智能体文件所在文件夹之后才加载（父文件夹的信任、-p/SDK 会话对设置文件里 Hook 的自动信任都不算；信任之前 Claude Code 跳过该文件里的每个内联服务器，并在调试日志里写出应设的确切 projects["<文件夹>"].hasTrustDialogAccepted 键）；两类服务器不检查信任：引用已配置服务器的名字，以及来自 ~/.claude/agents/、--agents 或 SDK agents 选项、托管设置的智能体文件里的内联服务器。适用于主会话的 MCP 限制同样覆盖子智能体前置信息里声明的服务器：--strict-mcp-config、--bare、企业托管 MCP 配置、allowedMcpServers/deniedMcpServers 策略；被阻止时 Claude Code 跳过并警告。托管设置的限制适用于每个子智能体，不论如何定义；--strict-mcp-config 不过滤你经 --agents 或 SDK agents 选项内联传入的服务器（那是调用方的显式输入）。

权限模式：用 permissionMode 选择子智能体运行的权限模式（用配置值，Manual 模式即 default）；不设则继承主对话的权限模式。主对话的模式决定 Claude Code 是否采用你设的值：主对话处于 bypassPermissions、acceptEdits 或 auto 模式时，子智能体以同样的模式运行，忽略你设的 permissionMode（auto 模式下分类器用主对话的设置评估子智能体的工具调用）；主对话处于 default、dontAsk 或 plan 时，子智能体以你设的模式运行，bypassPermissions 除外——声明了 bypassPermissions 的子智能体保留主对话的模式（需要 v2.1.267+）。取值：default（提示权限）、acceptEdits（自动接受工作目录或 additionalDirectories 里路径的文件编辑和常见文件系统命令）、auto（后台分类器评审命令和受保护目录的写入）、dontAsk（自动拒绝权限提示，明确允许的工具仍可用）、bypassPermissions（跳过权限提示，子智能体只在主对话如此时才这样运行）、plan（计划模式，只读探索）。

预载 Skill：用 skills 字段在启动时把 Skill 内容注入子智能体上下文，让它无需在执行中发现和加载 Skill 就有领域知识；每个列出的 Skill 的完整内容都被注入。该字段控制预载哪些，而不是子智能体能访问哪些：不设它，子智能体在执行中仍可通过 Skill 工具发现并调用项目、用户、插件 Skill。设了 disable-model-invocation: true 的 Skill 不能预载（包括内置的 /verify，只有你能运行它）；列出的 Skill 缺失或被禁用（如被组织策略）时 Claude Code 跳过并在调试日志里警告。这与「在子智能体里运行 Skill」相反：子智能体里的 skills 是由子智能体掌控系统提示并加载 Skill 内容；Skill 里的 context: fork 是把 Skill 内容注入你指定的智能体。

持久记忆：memory 字段给子智能体一个跨对话持久的目录，子智能体用它逐步积累知识（代码库模式、调试心得、架构决策）。范围：user（~/.claude/agent-memory/<名称>/，子智能体应跨所有项目记住所学）、project（.claude/agent-memory/<名称>/，知识针对项目、可经版本控制共享，推荐的默认值）、local（.claude/agent-memory-local/<名称>/，针对项目但不该检入版本控制）。子智能体记忆是自动记忆的一部分：用 autoMemoryEnabled 设置或 CLAUDE_CODE_DISABLE_AUTO_MEMORY 关闭自动记忆后，memory 字段没有效果。启用时：系统提示包含读写记忆目录的说明；系统提示还包含记忆目录里 MEMORY.md 的前 200 行或 25KB（先到者），并说明超出时要整理它；自动启用 Read、Write、Edit 工具以便管理记忆文件。提示：让子智能体开工前查阅记忆（「Review this PR, and check your memory for patterns you've seen before」），完成后更新记忆（「save what you learned to your memory」），也可以直接在智能体 Markdown 里写入记忆指令（如「Update your agent memory as you discover codepaths, patterns, library locations, and key architectural decisions…」）。

用 Hook 做条件规则：想允许工具的某些操作而阻止其他操作时，用 PreToolUse Hook 在执行前校验。例如让子智能体只允许只读数据库查询：tools: Bash，加 hooks.PreToolUse（matcher Bash，命令 ./scripts/validate-readonly-query.sh）；脚本从 stdin 读 JSON，提取 tool_input.command，发现 INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE 就向 stderr 输出 Blocked: Only SELECT queries are allowed 并以退出码 2 阻止，否则退出 0；macOS 和 Linux 上要让脚本可执行（chmod +x），否则 Hook 会失败而不是阻止；Windows 上用 PowerShell 写并在 Hook 条目里加 shell: powershell。禁用特定子智能体：在设置的 permissions.deny 里加 Agent(子智能体名)（内置和自定义都适用，如 ["Agent(Explore)", "Agent(my-custom-agent)"]），或用 claude --disallowedTools "Agent(Explore)"。

子智能体的 Hook

两种配置方式：写在子智能体前置信息里（只在该子智能体活跃期间运行，结束时清理）；或写在 settings.json 里（会话范围的 Hook 也在子智能体内触发：PreToolUse、PostToolUse 等工具事件对子智能体的工具调用与主对话里一样触发，SubagentStart/SubagentStop 在子智能体开始或结束时触发）。来自设置文件、托管策略和插件的 Hook 都在子智能体内生效。前置信息里的 Hook 在智能体作为子智能体（经 Agent 工具或 @ 提及）生成、以及作为主会话（--agent 或 agent 设置）运行时触发（后一种情形与 settings.json 里的 Hook 并行运行）。要让项目级子智能体前置信息里的 Hook 运行，需要接受包含该智能体文件的文件夹的工作区信任对话框；~/.claude/agents/ 里的用户级子智能体和你经 --agents 传入的定义无需这一步；信任之前子智能体照常运行，但 Claude Code 跳过它的前置信息 Hook 并在调试日志里写错误说明如何信任（比设置文件里 Hook 的规则更严：父文件夹的信任不够，-p 会话也不算已信任）。支持所有 Hook 事件，最常见：PreToolUse（子智能体用工具前）、PostToolUse（之后）、Stop（子智能体结束时，运行时被转换为 SubagentStop）。例如用 PreToolUse 校验 Bash 命令、用 PostToolUse（matcher Edit|Write）在文件编辑后运行 linter。项目级 Hook 响应子智能体事件：settings.json 里的 SubagentStart、SubagentStop，matcher 是智能体类型名（项目和用户级子智能体用前置信息的 name，插件子智能体用 my-plugin:db-agent 这样的作用域标识；作用域名含冒号，所以按正则而不是精确字符串求值），例如只在 db-agent 启动时运行 setup 脚本、任何子智能体停止时运行 cleanup 脚本。