用法

Claude Code 子代理（Subagents）教程：建立、配置和呼叫

Q: 怎麼阻止 Claude 使用某個子代理？

把它加進 settings 的 deny 陣列，格式是 Agent(subagent-name)，其中 subagent-name 要和子代理的 name 欄位一致，內建和自定義子代理都適用：{"permissions": {"deny": ["Agent(Explore)", "Agent(my-custom-agent)"]}}。也可以用 claude --disallowedTools "Agent(Explore)"。想完全阻止 Claude 委派給任何子代理，文件說是拒絕 Agent 工具本身。

Q: 子代理能再生成子代理嗎？

預設可以，最多在主對話之下三層。想改這個上限，把 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 設為你想要的層數；設為 1 就關閉巢狀。想讓某個子代理不能生成子代理，把 Agent 從它的 tools 列表裡去掉，或加進 disallowedTools。

釋出於 2026 年 10 月 30 日 · 最後核對 2026 年 10 月 30 日

子代理是處理特定型別任務的專用 AI 助手，在自己的上下文視窗裡幹活，只把摘要還給主對話。這一頁按 Anthropic 的 Create custom subagents 文件，中文整理子代理是什麼、內建了哪幾個、怎麼建立、檔案放在哪裡、frontmatter 怎麼寫、怎麼選模型、怎麼呼叫，以及找不到子代理時怎麼排查。文件於 2026 年 10 月 30 日核對。

要點

子代理是帶 YAML frontmatter 的 Markdown 檔案；每個子代理有自己的上下文視窗、自定義系統提示詞、特定的工具權限和獨立的權限。
個人子代理放 ~/.claude/agents/，專案子代理放 .claude/agents/；重名時專案優先於個人。
只有 name 和 description 是必填的；Claude 靠 description 決定什麼時候委派。
tools 限制它能用的工具，省略則繼承全部；model 可以設為 sonnet、opus、haiku、fable、完整模型 ID 或 inherit。
想確保某個子代理執行，用 @ 提及；想讓整個工作階段以它執行，用 claude --agent <name>。

子代理是什麼，什麼時候用

文件的說法：當一個旁支任務會用你不會再引用的搜尋結果、日誌或檔案內容淹沒主對話時，就用子代理，它在自己的上下文裡完成這些工作，只返回摘要。如果你總是在生成同一類工作者、用同一套指令，就定義一個自定義子代理。

每個子代理在自己的上下文視窗裡執行，有自定義系統提示詞、特定的工具權限和獨立的權限。它也會發出自己的請求，這些請求和你的主對話計入同一份用量限額。Claude 遇到和某個子代理的描述匹配的任務時，會委派給它，它獨立工作並返回結果。文件列出的好處：

保留上下文：把探索和實現擋在主對話之外
強制約束：限制子代理能用的工具
複用配置：使用者級子代理可以跨專案使用
專門化行為：用聚焦的系統提示詞針對特定領域
控制成本：把任務路由到更快、更便宜的模型，比如 Haiku

文件還有一條提醒：子代理在單個工作階段內工作。想並行跑很多獨立工作階段並在一處監控，文件指向 background agents；想要由 Claude 生成並監督的工作階段團隊，文件指向 agent teams。

內建子代理

Claude Code 內建了一些子代理，Claude 會在合適的時候自動使用。每個都繼承父對話的權限規則，大多數以受限的工具集執行。

子代理	用途	工具	模型
`Explore`	快速、只讀，用於搜尋和分析程式碼庫：檔案發現、程式碼搜尋、程式碼庫探索	只讀工具；Write 和 Edit 被拒絕	主對話的模型（主對話執行 Fable 時的情況見文件）
`Plan`	在計劃模式下收集上下文，供 Claude 提出計劃	只讀工具；Write 和 Edit 被拒絕	繼承主對話，除非設定了 `CLAUDE_CODE_SUBAGENT_MODEL` 並強制應用到每個子代理
`General-purpose`	複雜研究、多步操作、程式碼修改	子代理可用的所有工具	如果設定了 `CLAUDE_CODE_SUBAGENT_MODEL` 且沒有其他方式指定模型，用它；否則用主對話的模型

Explore 和 Plan 啟動時不帶你的 CLAUDE.md 檔案和 git status 快照，讓調研又快又省；其他內建子代理和自定義子代理兩者都會載入。呼叫 Explore 時，Claude 會指定徹底程度：quick 用於有針對性的查詢，medium 用於均衡的探索，very thorough 用於全面分析。

文件還列出了幾個通常自動呼叫的輔助子代理：

子代理	模型	Claude 什麼時候用
`claude`	自己沒有模型；Claude 把它當子代理生成時，按模型順序決定	任務不屬於更專門的子代理時。一個擁有子代理可用的所有工具的兜底選項
`statusline-setup`	Sonnet	執行 `/statusline` 配置狀態列時
`claude-code-guide`	Haiku	你詢問 Claude Code 功能的問題時

想阻止 Claude 使用某個內建子代理，把它加進 permissions.deny，寫法見下面的常見問題。想移除內建的 Explore 和 Plan，設定 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1，Claude 會直接讀取和探索檔案，需要 Claude Code v2.1.198 或更高版本。

建立第一個子代理

子代理是帶 YAML frontmatter 的 Markdown 檔案。建立的方式有兩種：讓 Claude 幫你寫，或者自己寫檔案。下面的流程來自文件，建立一個使用者級子代理，審查程式碼並提出改進建議。

第一步，在 Claude Code 裡描述你想要的子代理和儲存位置：

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude 會寫出帶 name、description、tools 列表、model 和系統提示詞的檔案。第二步，開啟 ~/.claude/agents/code-improver.md，確認 frontmatter 和你要求的一致。結果類似這樣：

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

檔案在 ~/.claude/agents/ 裡，所以這個子代理在你機器上的每個專案裡都可用。想只用在一個專案，就把它移到那個專案的 .claude/agents/ 目錄。第三步，讓 Claude 委派給它：

Use the code-improver agent to suggest improvements in this project

Claude 會委派給新的子代理，它掃描程式碼庫並返回改進建議。在對話記錄裡，委派顯示為一行工具呼叫，寫著子代理的名字和一句簡短的任務描述，例如 code-improver(Suggest code improvements)。

關於 /agents：文件說，執行 /agents 會列印一條提醒，讓你去問 Claude，或直接編輯 .claude/agents/ 和 ~/.claude/agents/。在 Claude Code v2.1.197 及更早版本里，/agents 會開啟一個互動式嚮導，其中 Running 標籤頁列出正在執行的子代理，Library 標籤頁用來建立、編輯和刪除子代理。

改動不需要重啟：文件說，Claude Code 會監視 ~/.claude/agents/ 和 .claude/agents/，你在磁碟上新增或編輯子代理檔案，或讓 Claude 寫一個，它會在幾秒內檢測到變化，下一次委派就用更新後的定義。有三種情況仍然需要重啟，見後面的排查。

子代理檔案放在哪裡

檔案的位置決定誰能用它，frontmatter 決定它能做什麼。多個子代理同名時，Claude Code 使用優先順序更高的位置裡的那個。

位置	範圍	優先順序	怎麼建立
託管設定	整個組織	1（最高）	透過託管設定部署
`--agents` CLI 引數	當前工作階段	2	啟動 Claude Code 時傳入 JSON
`.claude/agents/`	當前專案	3	讓 Claude 建立，或手動建立檔案
`~/.claude/agents/`	你的所有專案	4	讓 Claude 建立，或手動建立檔案
外掛的 `agents/` 目錄	外掛啟用的地方	5（最低）	隨外掛安裝

專案子代理（.claude/agents/）適合針對某個程式碼庫的子代理。文件建議把它們提交進版本控制，讓團隊一起使用和改進。
使用者子代理（~/.claude/agents/）是個人子代理，在你所有專案裡可用。
Claude Code 會遞迴掃描 .claude/agents/ 和 ~/.claude/agents/，所以可以用 agents/review/ 或 agents/research/ 這樣的子資料夾整理。子目錄路徑不影響子代理怎麼識別和呼叫，識別只看 name 欄位。
名字要在整棵目錄樹裡保持唯一：同一個 .claude/agents/ 目錄（含子資料夾）裡兩個檔案宣告同一個名字，Claude Code 只會載入其中一個，由檔案系統讀取順序決定，沒有文件化的優先規則。

專案子代理透過從當前工作目錄向上查詢來發現，所以從那裡到倉庫根目錄之間的每個 .claude/agents/ 都會被掃描；多個巢狀目錄定義了同一個 name 時，用離工作目錄最近的那個。

最常用的 frontmatter 欄位

用兩個 --- 標記之間的 YAML frontmatter 配置子代理，閉合 --- 之後用 Markdown 寫它的系統提示詞。只有 name 和 description 是必填的。多個單詞的欄位名用 camelCase，例如 maxTurns 和 disallowedTools，必須和表裡完全一致：Claude Code 會忽略不認識的欄位，而且不報錯。

欄位	必填	作用
`name`	是	唯一標識，最多 256 個字元，例如 `code-reviewer` 或 `reviewer-v2`。檔名不必和它一致。名字裡不能有 `:`，它留給外掛作用域的識別符號。
`description`	是	Claude 什麼時候應該委派給這個子代理。
`tools`	否	子代理能用的工具，寫成逗號分隔的字串，如 `Read, Grep, Bash`，或 YAML 列表。省略時繼承子代理可用的所有工具。
`disallowedTools`	否	要拒絕的工具，從繼承的或指定的列表裡移除。格式和 `tools` 相同。
`model`	否	使用的模型：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（如 `claude-opus-5-5`）或 `inherit`。省略時，Claude Code 按子代理模型順序選擇。
`permissionMode`	否	權限模式：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan`，`manual` 是 `default` 的別名。對外掛子代理無效。
`maxTurns`	否	子代理停止前的最大代理輪數。
`skills`	否	啟動時預載入進子代理上下文的 skills，注入的是完整內容，不只是描述。
`mcpServers`	否	這個子代理可用的 MCP 伺服器。對外掛子代理無效。
`hooks`	否	作用域限定在這個子代理的生命週期 hooks。對外掛子代理無效。
`memory`	否	持久記憶的範圍：`user`、`project` 或 `local`，支援跨工作階段學習。
`background`	否	設為 `true`，即使 Claude 要求等待，也讓這個子代理留在後臺。
`effort`	否	這個子代理活躍時的 effort 級別，覆蓋工作階段的 effort 級別，但不覆蓋 `CLAUDE_CODE_EFFORT_LEVEL` 環境變數。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用級別取決於模型。
`isolation`	否	設為 `worktree`，在臨時的 git worktree 裡執行子代理，給它一份隔離的倉庫副本。沒有改動時，worktree 會自動清理。

文件裡還有 autoCompactWindow、omitClaudeMd、color、initialPrompt 和 experimental 等欄位，這裡不展開。有一點要注意：子代理檔案的正文成為系統提示詞，子代理只收到這段系統提示詞加工作目錄等基本環境資訊，不收到 Claude Code 的系統提示詞。

限制工具

限制工具用 tools 作為允許列表，或 disallowedTools 作為拒絕列表。兩個都設定時，先應用 disallowedTools，再在剩下的工具池裡解析 tools；兩邊都列出的工具會被移除。下面的例子來自文件，只允許 Read、Grep、Glob 和 Bash，子代理不能編輯檔案、寫檔案，也不能使用任何 MCP 工具：

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

下面這個用 disallowedTools，繼承子代理的工具池，只去掉 Write 和 Edit，子代理保留 Bash、MCP 工具和池裡的其餘部分：

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

選模型

model 欄位控制子代理用哪個模型，可以是別名（sonnet、opus、haiku 或 fable）、完整模型 ID（如 claude-opus-5-5 或 claude-sonnet-5，接受和 --model 引數相同的值），或者 inherit（用和主對話相同的模型）。Claude 呼叫子代理時，還可以為這一次呼叫傳一個 model 引數。Claude Code 按這個順序決定子代理的模型：

每次呼叫的 model 引數
子代理定義裡的 model frontmatter，其中 inherit 選主對話的模型
環境變數 CLAUDE_CODE_SUBAGENT_MODEL，當你把它設為模型別名或模型 ID 時
主對話的模型

想檢查某個子代理在用哪個模型，執行 /tasks，Claude Code 會在子代理那一行寫出模型名（需要 Claude Code v2.1.242 或更高版本）。文件給出的例子是，在 settings 檔案的 env 塊裡同時設定兩個變數，讓每個子代理都用 Haiku：

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

CLAUDE_CODE_SUBAGENT_MODEL_FORCE 需要 Claude Code v2.1.257 或更高版本。開啟它之後，Claude Code 會忽略子代理定義裡的 model 欄位。

子代理可以和主對話用不同的模型，而且它發出的是自己的請求。所以如果你按 token 計費，這些請求會以子代理自己的模型出現，不是主工作階段的模型；我們在這份說明裡解釋了這一點。怎麼選模型見模型和思考強度怎麼選。

自動委派和手動呼叫

自動委派。Claude 根據你請求裡的任務描述、子代理配置裡的 description 欄位和當前上下文自動委派。想鼓勵主動委派，在子代理的 description 裡寫上“use proactively”這樣的短語。描述要簡短：當你的子代理的描述合計超過 15,000 個 token（不含內建子代理），Claude Code 會在啟動時顯示警告，但仍會載入每個子代理。

手動呼叫。自動委派不夠時，可以自己請求子代理。三種方式從一次性建議升級到整個工作階段的預設：

自然語言：在提示裡點名子代理，由 Claude 決定是否委派
@ 提及：保證子代理為這一個任務執行
整個工作階段：透過 --agent 引數或 agent 設定，讓整個工作階段以那個子代理執行

自然語言沒有特殊語法，點名子代理，Claude 通常就會委派：

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@ 提及：輸入 @，從補全列表裡選子代理，和 @ 提及檔案的方式一樣。這能確保執行的是那個子代理，不留給 Claude 選：

@"code-reviewer (agent)" look at the auth changes

你的完整訊息仍然發給 Claude，由它根據你的請求寫出子代理的任務提示。@ 提及控制的是 Claude 呼叫哪個子代理，不是它收到什麼提示。也可以不用選擇器，手動輸入 @agent-<name>。

整個工作階段以子代理執行：傳入 --agent <name>，主執行緒本身就帶上那個子代理的工具限制和模型：

claude --agent code-reviewer

啟動標題裡會以 @<name> 顯示代理名，方便確認它已生效。想讓它成為專案裡每個工作階段的預設，在 .claude/settings.json 裡設定 agent；兩者同時存在時，CLI 引數優先：

{
  "agent": "code-reviewer"
}

前臺和後臺：前臺子代理會阻塞主對話直到完成，權限提示會傳給你；後臺子代理在你繼續工作時併發執行。文件說，什麼都不配置時，Claude 從主對話生成的子代理預設在後臺啟動。

完整示例：程式碼審查子代理

下面這個例子來自文件的 Example subagents：一個只讀子代理，審查程式碼但不修改。它展示了怎麼設計一個工具權限有限（不含 Edit 和 Write）的聚焦子代理，以及一個詳細說明要看什麼、輸出什麼格式的提示詞。把它存成 .claude/agents/code-reviewer.md 即可。

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

這個檔案裡 model: inherit，所以它用和主對話相同的模型；description 裡的 “Proactively” 和 “Use immediately after writing or modifying code” 是在告訴 Claude 什麼時候該委派。

文件給的提示

文件的最佳實踐：

設計聚焦的子代理：每個子代理只擅長一個具體任務。
寫能單獨指向某一個子代理的描述：Claude 用描述決定何時委派，所以每個描述要具體到能路由到正確的子代理，並讓整體保持在 15,000 token 的描述預算之內。
限制工具權限：只授予必要的權限，出於安全和專注。
提交進版本控制：和團隊共享專案子代理。

文件裡的常見用法：

隔離大輸出的操作：執行測試、獲取文件或處理日誌檔案會消耗大量上下文，委派給子代理後，冗長的輸出留在子代理的上下文裡，只有相關摘要回到主對話。例如：Use a subagent to run the test suite and report only the failing tests with their error messages
並行研究：對互相獨立的調查，生成多個子代理同時工作。例如：Research the authentication, database, and API modules in parallel using separate subagents。研究路徑互不依賴時效果最好。
串聯子代理：多步工作流裡，讓 Claude 按順序使用子代理。例如：Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

文件的警告：子代理完成後，結果會回到你的主對話。執行很多個各自返回詳細結果的子代理，會消耗大量上下文，而且每個子代理執行時都會花費自己的 token。

什麼時候不用子代理：任務需要頻繁來回或反覆修改、多個階段共享大量上下文、只是快速而有針對性的改動，或者在意延遲（不是 fork 的子代理從頭開始，可能需要時間收集上下文），就用主對話。想要在主對話上下文裡執行的可複用提示詞或工作流，文件建議考慮 Skills。

常見問題排查

Claude 找不到新子代理

重啟 Claude Code 再試。文件說，這隻發生在工作階段啟動前 ~/.claude/agents/ 不存在的情況下，因為執行中的工作階段檢測不到新建的 agents 目錄。三種情況仍需重啟：在新的 agents 目錄裡建立某個範圍的第一個代理檔案之後；在用 --add-dir 或 /add-dir 新增的目錄裡新增或編輯子代理之後；用 --disable-slash-commands 啟動的工作階段（根本不監視這些目錄）。

檔案被悄悄跳過

文件說，frontmatter 有下面任何一個問題時，Claude Code 會跳過檔案，且不在工作階段裡報告：

沒有 name：Claude Code 把這個檔案當作放在代理旁邊的文件。
開頭的 --- 不是檔案的第一行：Claude Code 認為檔案沒有 frontmatter，同樣當作文件。
name 以 - 開頭、包含 :，或超過 256 個字元：跳過檔案，並把錯誤寫進 debug 日誌。
有 name 但沒有 description：跳過檔案，並把原因寫進 debug 日誌。
YAML 解析不了：不讀取檔案的任何欄位，跳過它，並把解析錯誤寫進 debug 日誌。

要看 debug 日誌，用 --debug 執行 Claude Code。要找出 frontmatter 解析失敗的檔案，對目錄執行 claude plugin validate，例如 .claude/agents 或 ~/.claude/agents（需要 Claude Code v2.1.233 或更高版本）；它不會標出 frontmatter 能解析但缺少 name 的檔案。

欄位拼錯了，沒有任何報錯

Claude Code 忽略不認識的欄位且不報錯。對已載入的子代理，在 shell 裡執行 claude --debug，在 ~/.claude/debug/<session-id>.txt 的 debug 日誌裡搜尋 does not recognize or apply，日誌會列出最多五個它不認識的頂層欄位，接近某個受支援欄位時還會給出可能想寫的名字（需要 Claude Code v2.1.296 或更高版本）。

子代理啟動失敗

當 tools 列表裡沒有任何條目能解析成工具，例如每個條目都拼錯了，或者寫的是子代理用不了的工具，Claude Code 通常會拒絕啟動這個子代理，Agent 工具返回一個點名未解析條目的錯誤。

子代理不知道你的規則或對話

每個子代理從全新的、隔離的上下文視窗開始，看不到你的對話歷史、你已呼叫的 skills，或 Claude 已讀過的檔案。Claude 會寫一條委派訊息，概括任務，子代理從那裡開始工作。如果某條規則必須傳到子代理那裡，例如“忽略 vendor/ 目錄”，就在你委派時給 Claude 的提示裡重述它。

常見問題

怎麼阻止 Claude 使用某個子代理？

把它加進 settings 的 deny 陣列，格式是 Agent(subagent-name)，其中 subagent-name 要和子代理的 name 欄位一致，內建和自定義子代理都適用：{"permissions": {"deny": ["Agent(Explore)", "Agent(my-custom-agent)"]}}。也可以用 claude --disallowedTools "Agent(Explore)"。想完全阻止 Claude 委派給任何子代理，文件說是拒絕 Agent 工具本身。

子代理能再生成子代理嗎？

預設可以，最多在主對話之下三層。想改這個上限，把 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 設為你想要的層數；設為 1 就關閉巢狀。想讓某個子代理不能生成子代理，把 Agent 從它的 tools 列表裡去掉，或加進 disallowedTools。

該用子代理還是 skill？

文件的區分：任務會產生你不需要留在主上下文裡的冗長輸出、你想強制特定的工具限制或權限，或者工作自成一體並能返回摘要，用子代理。想要在主對話上下文裡執行、而不是隔離的子代理上下文裡執行的可複用提示詞或工作流，考慮 skill，寫法見 Claude Code Skills 使用教程。內建命令見 Claude Code 命令，省錢的做法見Claude Code 省錢指南。

來源

Claude Code：Create custom subagents（內建子代理、建立流程、檔案位置與優先順序、frontmatter 欄位、模型順序、呼叫方式、常見用法、示例、排查）