Claude Code：背景指令的 30 分鐘限制

Claude Code 在無人值守執行時，會於 30 分鐘後停止背景指令：例如使用 -p 旗標啟動、Agent SDK 應用程式、CI 工作，或雲端工作階段。如果 Claude 為指令本身指定執行時間，最多可執行 2 小時；而一般終端機、桌面應用程式和 VS Code 從 2.1.288 版起便不再有時間限制。

我以前一整天都坐在螢幕前：交代代理程式一個步驟、查看結果、做些修正，再叫它繼續。每個階段都這樣反覆進行。程式碼或許是機器在寫，但真正駕駛流程的人是我。現在我會先寫好計畫、拆分階段，晚上把實作交給子代理程式處理，然後離開。沒有我在旁的 8 小時裡，Claude 會按計畫逐步執行：研究、建置並完善成果。到了早上，我花在驗收成果上的時間比重做還多。

但是，如果一整晚的執行使用 -p，或是在伺服器上排程、於 CI 或雲端執行，那麼在背景執行的開發伺服器和建置工作會在 30 分鐘後停止。接著 Claude Code 會將它們停止，夜間工作也會在半途受阻。我會說明哪些情況會受限、如何提高限制，以及指令已經停止時該怎麼處理。開始吧。

如需服務使用說明，請參閱 Ailoot 文件。

哪些情況會受限#

背景指令是指 Claude 啟動後，自己去忙其他工作時仍持續執行的指令。例如使用 npm run dev 啟動的開發伺服器，或持續監看檔案變更的建置工作。

Claude Code 文件指出：

換句話說，你不在場時執行的工作會受限：使用 -p 旗標執行、Agent SDK 應用程式、CI 工作或雲端工作階段。當你親自在終端機、桌面應用程式或 VS Code 中操作工作階段時，不受限制。此限制於 2.1.285 版推出，在 2.1.288 版之前適用於所有工作階段。

如何判斷自己是否受影響：

• 你在終端機或 VS Code 中開啟 Claude Code，交代一項任務後就去睡覺。 如果版本是 2.1.288 或更新版本，就不受限制。在 2.1.285 到 2.1.287 版中，這種情況也會受限。我在另一篇文章說明了如何更新到最新版。
• Claude Code 透過排程、你自己的 Agent SDK 應用程式或 CI，以 claude -p "task" 啟動。 會受限。
• 任務在雲端工作階段中執行。 會受限。

我讓代理程式獨立工作時，會在提示中要求：「將這些條件和停止原因寫入工作計畫。確認流程不會依賴我將關閉的視窗或電腦本身。」30 分鐘限制就是這些停止原因之一。

背景指令會執行多久#

倒數會從指令進入背景時開始。有 2 種情況。

Claude 一開始就將指令放在背景執行。 它會執行 30 分鐘。如果 Claude 在啟動時指定時間（timeout 參數），就會依該時間執行，但最多不超過 2 小時。

Claude 等待期間，指令尚未完成。 一般指令 Claude 會等待 2 分鐘。如果仍未完成，Claude Code 不會停止它，而是將它移至背景。從那一刻起，它會執行 30 分鐘。

時間到時，Claude Code 會停止指令，並告知 Claude：

Background command "<description>" was stopped after reaching its background time limit

如果工作尚未完成，Claude 可以用較長的時間重新執行指令。

另外還有一點關於 -p。使用這種執行方式時，背景指令會在 Claude 最後一次回覆約 5 秒後終止。在一整晚的 -p 執行中啟動的伺服器，只會持續執行到整個工作階段結束。只有當工作階段執行更久時，30 分鐘限制才會有影響：例如 Claude 一開始啟動伺服器，接著花 1 小時對它執行檢查。

如何安排 Claude Code 的夜間工作#

我厭倦了整天駕駛代理程式，因此改用一個協調器提示詞。晚上啟動後，Claude 就會依序處理各階段，整晚自行編寫、檢查、修正並提交成果。

子代理程式會分組撰寫程式碼，各自負責不同檔案，避免互相妨礙。接著由另一組全新的代理程式驗收成果：進行程式碼審查、安全檢查和實際環境檢查。如果發現問題，就立即修正並重新執行檢查。提示詞中包含這句話：「如果上下文用完，請記錄目前狀態；下一次執行會接著處理。」

在這個例子中，3 天內以此方式完成了 14 個階段中的 8 個。

只要記住 2 點。協調器不會替你思考：首先要撰寫包含各階段的詳細計畫，然後再開始夜間工作。此外，這會大量消耗你的訂閱額度，因此小型任務不太值得這樣安排。務必限制嘗試次數，否則代理程式可能一夜之間耗盡你的全部訂閱額度。我在另一篇文章說明了如何設定這些使用上限。

如何提高限制#

方法 1：請 Claude 設定。 特定指令的執行時間由 Claude 決定，你無法自行設定。不過，你可以在任務中寫：「讓開發伺服器在背景執行 2 小時。」透過這種方式，最多只能設為 2 小時。

方法 2：在設定檔中設定變數。 值的單位是毫秒。你無法將限制調低到 30 分鐘和 2 小時以下，只能調高。

• BASH_DEFAULT_TIMEOUT_MS 設定為大於 1800000（30 分鐘）時，會變更 30 分鐘的預設值。它同時適用於 Claude 未指定時間便在背景啟動的指令，以及逾時後移至背景的指令。如果設定值大於 7200000（2 小時），上限也會提高。
• BASH_MAX_TIMEOUT_MS 設定為大於 7200000（2 小時）時，會提高 2 小時上限，但不會改變 30 分鐘的預設值：未指定執行時間的指令仍會在 30 分鐘後停止。

BASH_DEFAULT_TIMEOUT_MS 有一項副作用。同一個變數也會設定 Claude 在將一般指令移至背景前的等待時間。設為 1 小時後，Claude 就會等待 1 小時，而非 2 分鐘。這不會妨礙夜間工作；但白天執行耗時指令時，你會等待更久才收到回應。

如果不想處理細節：若一般指令和上限都需要 3 小時，將 BASH_DEFAULT_TIMEOUT_MS 設為 10800000 即可。這樣就夠了，不需要第二個變數。

設定檔位於主目錄的 .claude 資料夾中：macOS 和 Linux 使用 ~/.claude/settings.json，Windows 使用 %USERPROFILE%\.claude\settings.json。如果檔案不存在，請建立它。1 小時限制的設定如下：

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "3600000"
  }
}

如果檔案已有 env 區塊，請將該行加入其中。儲存檔案後，執行中的工作階段就會套用新值。移除變數後，變更只有在下一次啟動 claude 時才會生效。

設定檔必須位於代理程式執行的那台機器上。若要讓代理程式整晚工作，電腦就不能進入睡眠。或者，也可以在遠端伺服器上執行 Claude Code，並將設定放在該伺服器上。

指令已經停止時#

你不需要手動做任何事。Claude Code 會告訴 Claude 指令停止的原因，所以先直接問它發生了什麼事。

接著逐步處理：

1. 一次性長時間執行，最長 2 小時。 請 Claude 延長執行時間後重新執行指令。
2. 指令經常需要超過 30 分鐘。 如上例所示，在設定檔中將 BASH_DEFAULT_TIMEOUT_MS 設為大於 1800000。如果需要超過 2 小時，也請在該處將 BASH_MAX_TIMEOUT_MS 設為大於 7200000。
3. 再次執行指令。 文件並未保證設定變更適用於變更前就已在背景執行的指令。
4. 檢查下一次執行的結果。 如果 Claude 的報告再次出現「達到背景時間限制後停止」這句話，表示該設定沒有套用到那個指令。

子代理和例行流程能讓代理程式在你離開時繼續工作。

我在另一篇文章說明了如何讓代理程式整夜循環執行。至於如何設定 Claude Code，避免它在夜間弄壞專案，請參閱這裡。

確認夜間執行在哪個步驟停止，並將停止原因與上述限制對照。

認識一下 Ailoot。