Claude Code 背景子代理完整教學 — 開一個 subagent 不再卡死整個對話

你叫 Claude 開一個 subagent 去跑整套測試，心想趁這空檔先去改另一個檔案——結果游標卡住了。你打字沒反應，整個對話凍在那裡，畫面上就一行「subagent running…」。測試跑三分鐘，你就盯著螢幕乾等三分鐘。

這個情境每個重度用 subagent 的人都遇過。而它有解，解法叫「背景執行」。這篇就從這個卡死的現場講起，把它怎麼解、解到什麼程度、又得付出什麼代價，一次說完。

先搞懂：為什麼開一個 subagent 會把你整個卡住

要解這個問題，得先知道它為什麼會發生。

預設情況下，Claude Code 開出來的 subagent 是「前景」執行的。前景的意思是——它佔住了你跟主對話之間那條唯一的通道。subagent 在忙的時候，主對話被擋住，你送不了新訊息，因為那條線正被它佔線。

打個比方。你是辦公室主管，手下有個實習生。你叫他去檔案室找一份三年前的合約，然後你做了一件有點蠢的事：你跟著走到檔案室門口，站在那裡，什麼都不做，等他翻箱倒櫃找出來。他找十分鐘，你就在門口站十分鐘。這就是前景 subagent——你明明可以回座位繼續做自己的事，卻選擇站在門口等。

問題是，你為什麼要站在那裡？

兩個你可能已經試過、但都不太對的辦法

遇到這個卡死，多數人會本能地用兩種方法繞，但兩種都有副作用。

第一種，認命等。 反正三分鐘而已，等就等。但你一天開十次 subagent，每次三五分鐘，加起來就是半小時純粹的發呆。而且這種等最磨人的地方在於，它把你從心流裡踢出來——你本來腦袋正轉著別的事，被迫停下來盯進度條，回過神時思路已經斷了。

第二種，乾脆不開 subagent，自己在主對話裡跑。 這樣是不會卡，但你會付出另一個代價：那一大坨測試輸出——幾百行的 log、stack trace、一堆綠的紅的勾勾叉叉——全部灌進你的主對話。主對話的 context 被這些你根本不會再看第二眼的雜訊塞滿，Claude 開始變笨、開始忘記你前面交代的事。你省掉了等待，卻弄髒了腦袋。

開 subagent 的本意，就是要把這種雜活的雜訊隔離在外、只把結論帶回來。所以第二種辦法等於自廢武功。真正對的方向，是保留 subagent 的隔離好處，同時把「等待」這件事拿掉。那就是背景執行。

背景執行：叫他去找，你回座位繼續做事

回到那個實習生的比方。背景執行就是你叫他去檔案室找合約，然後你轉身回座位，繼續處理手上的報表。他找到了，再過來敲你的門、把合約放你桌上。期間你一秒都沒浪費。

在 Claude Code 裡，把 subagent 丟到背景有幾種方式：

直接讓它在背景啟動。 你可以明確要求 Claude 用背景模式開任務——例如「開一個背景任務去跑完整測試套件，我繼續改前端」。底層對應的是 Task 工具的 run_in_background 參數設成 true。subagent 在背景跑，完整的過程會寫進一個 output 檔，你想看細節隨時去翻；不想看，就等它把結論丟回來。需要的話還能用 max_turns 限制它最多跑幾輪，避免它在背景失控暴衝。

跑到一半才丟背景。 如果一個任務已經在前景跑起來了，你才發現「欸這要跑很久」，不用砍掉重開——按 Ctrl+B，就能把正在跑的這個任務直接踢到背景去，然後你繼續做別的。

值得一提的是，這件事正在變成預設。Claude Code 團隊已經對外說明，接下來的版本會讓 subagent 預設就在背景跑，主對話自然保持暢通；你反而要在「想盯著它跑」的時候，才特別交代讓它在前景執行。換句話說，「站在檔案室門口等」這個蠢動作，官方準備幫你預設拿掉。

它在背景遇到要權限的事，怎麼辦？

這是背景執行最容易讓人卡住、也最值得搞懂的一段。

想想那個實習生：他在檔案室找資料，找到一半遇到一個上鎖的櫃子。他該怎麼辦？如果他不能問你，那他只有兩個選擇——硬闖（危險）或直接放棄那個櫃子（可能漏掉東西）。最好的情況是，他能跑回來問你一句「這個櫃子能開嗎」，你說能，他開；你說不行，他跳過這個櫃子、繼續找其他地方。

Claude Code 的權限處理就是照這個邏輯演進的，而且有個明確的版本分界。在 v2.1.186 之前，背景 subagent 遇到任何需要你授權的工具呼叫，會直接自動拒絕——等於那個實習生碰到鎖櫃就自己放棄，你事後才發現他漏了東西。從 v2.1.186 開始改好了：背景 subagent 撞到需要權限的呼叫時，提示會浮到你的主 session，而且會標明「是哪個 subagent 在問」。你可以批准讓它繼續，也可以按 Esc 只拒絕這一個呼叫、而不中斷整個 subagent。它會跳過這件事，繼續做剩下的。

實務上還有個細節：背景 subagent 一啟動，Claude Code 會先問你它「預計會用到的權限」。一旦跑起來，它就在這組預先批准的範圍內活動，超出範圍、又沒辦法即時問你的，會被自動擋下。所以開背景任務前，稍微想一下它需要碰什麼，先一次給足，省得它中途卡關。

順手要知道的三件事

背景執行不是孤立的功能，它跟旁邊幾個機制是連在一起的，知道了能少走彎路。

一是 fork 模式。 把環境變數 CLAUDE_CODE_FORK_SUBAGENT 設成 1（v2.1.117 之後），每個 subagent 不管你怎麼設定都會在背景跑，而且它複製的是父對話、共用父層的 prompt cache——對「需要帶大量背景脈絡」的任務特別省錢。如果你之前研究過 fork 跟 subagent 的差別，這裡剛好接得上。

二是巢狀子代理。 從 v2.1.172 起，一個 subagent 可以再開它自己的 subagent。當你丟給它的任務本身又能拆成好幾個平行小任務時，這很有用——中間那些零碎的過程不會冒到你的主對話，只有最上層那個 subagent 的總結會回來給你。隔離得更乾淨。

三是怎麼關掉它。 如果你在 CI 環境、或一台需要嚴格鎖定的機器上，不希望有任何背景任務在那邊自己跑，把 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 設成 1，整個背景化機制就關掉了。

天下沒有白跑的背景任務

講了一圈好處，得誠實補上代價，不然你會用過頭。

背景 agent 跟你互動式的 session 是用同樣的速率在燒 token 的。這話的意思很直接：你同時開三個背景 agent，就是三倍的 token 消耗在那邊並行燃燒。它們不會因為「在背景、你沒在看」就比較省——該花的算力一分不少。事實上，當「預設背景執行」這個改動被宣布時，社群就吵過這一點：有人覺得是體驗上的大躍進，也有人嫌它讓人不知不覺燒掉一堆錢。

所以背景執行真正的價值，不在「能同時跑很多東西」，而在它逼你做一個更清楚的分類。回到最前面那個卡死的現場——現在你會這樣處理：跑測試這種「我不需要全程盯著、跑完給我結論就好」的事，丟背景，你繼續改你的 code；至於那種「每一步都要我即時拍板、走錯一步就麻煩」的任務，留前景，老老實實盯著。

判準其實就一句話：這件事到底需不需要我盯著。需要我即時決策的，放前景；只要結論的，丟背景。把任務照這條線分一次，你會發現你乾等的時間少了一大半，而帳單也不會因為你一時手癢開了五個背景 agent 而爆掉。工具給了你並行的能力，但決定哪些值得並行的，還是你。