# Claude Code：背景指令的 30 分鐘限制
> Claude Code 在無人值守執行時會於 30 分鐘後停止背景指令：-p、Agent SDK、CI、雲端。如何提高限制，以及指令停止後該怎麼做。
Source: https://ailoot.ai/blog/zh-hant-tw/claude-code-background-30-min-timeout/
Canonical: https://ailoot.ai/blog/zh-hant-tw/claude-code-background-30-min-timeout/
Language: zh-Hant-TW
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-043
Revision: sha256-ca128084e21c16fa9219c2ba64d3006587f9d6f3da40c85949e95b42e791ba80
Claude Code 在無人值守執行時，會於 30 分鐘後停止背景指令：例如使用 `-p` 旗標啟動、Agent SDK 應用程式、CI 工作，或雲端工作階段。如果 Claude 為指令本身指定執行時間，最多可執行 2 小時；而一般終端機、桌面應用程式和 VS Code 從 2.1.288 版起便不再有時間限制。
我以前一整天都坐在螢幕前：交代代理程式一個步驟、查看結果、做些修正，再叫它繼續。每個階段都這樣反覆進行。程式碼或許是機器在寫，但真正駕駛流程的人是我。現在我會先寫好計畫、拆分階段，晚上把實作交給子代理程式處理，然後離開。沒有我在旁的 8 小時裡，Claude 會按計畫逐步執行：研究、建置並完善成果。到了早上，我花在驗收成果上的時間比重做還多。
但是，如果一整晚的執行使用 `-p`，或是在伺服器上排程、於 CI 或雲端執行，那麼在背景執行的開發伺服器和建置工作會在 30 分鐘後停止。接著 Claude Code 會將它們停止，夜間工作也會在半途受阻。我會說明哪些情況會受限、如何提高限制，以及指令已經停止時該怎麼處理。開始吧。
如需服務使用說明，請參閱 [Ailoot 文件](https://ailoot.ai/docs/)。
本節重點
從 2.1.285 版起，Claude Code 會在背景指令達到時間限制時自行停止，並告知 Claude 停止原因。從 2.1.288 版起，限制僅適用於無人值守執行：`-p`、Agent SDK、CI 和雲端工作階段。直接在背景啟動的指令會執行 30 分鐘，或依指定時間執行，但最多不超過 2 小時。逾時後移至背景的指令，會從移入背景時起執行 30 分鐘。你可以在 `~/.claude/settings.json` 設定檔中使用 2 個變數提高限制。
## 哪些情況會受限
背景指令是指 Claude 啟動後，自己去忙其他工作時仍持續執行的指令。例如使用 `npm run dev` 啟動的開發伺服器，或持續監看檔案變更的建置工作。
Claude Code 文件指出：
在無人值守執行的工作階段中，例如使用 `-p` 旗標執行、Agent SDK 應用程式、CI 工作或雲端工作階段，背景 Bash 和 PowerShell 指令會有時間限制。你在終端機、桌面應用程式或 VS Code 擴充功能中操作的本機工作階段，背景指令沒有時間限制。
時間限制需要 Claude Code v2.1.285 或更新版本。v2.1.288 之前，所有工作階段都適用此限制。
— Anthropic，工具參考文件，https://code.claude.com/docs/en/tools-reference.md
換句話說，你不在場時執行的工作會受限：使用 `-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 版中，這種情況也會受限。我在[另一篇文章](https://ailoot.ai/blog/zh-hant-tw/update-claude-code/)說明了如何更新到最新版。
- **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 "" was stopped after reaching its background time limit
```
如果工作尚未完成，Claude 可以用較長的時間重新執行指令。
另外還有一點關於 `-p`。使用這種執行方式時，背景指令會在 Claude 最後一次回覆約 5 秒後終止。在一整晚的 `-p` 執行中啟動的伺服器，只會持續執行到整個工作階段結束。只有當工作階段執行更久時，30 分鐘限制才會有影響：例如 Claude 一開始啟動伺服器，接著花 1 小時對它執行檢查。
## 如何安排 Claude Code 的夜間工作
我厭倦了整天駕駛代理程式，因此改用一個協調器提示詞。晚上啟動後，Claude 就會依序處理各階段，整晚自行編寫、檢查、修正並提交成果。
子代理程式會分組撰寫程式碼，各自負責不同檔案，避免互相妨礙。接著由另一組全新的代理程式驗收成果：進行程式碼審查、安全檢查和實際環境檢查。如果發現問題，就立即修正並重新執行檢查。提示詞中包含這句話：「如果上下文用完，請記錄目前狀態；下一次執行會接著處理。」
在這個例子中，3 天內以此方式完成了 14 個階段中的 8 個。
只要記住 2 點。協調器不會替你思考：首先要撰寫包含各階段的詳細計畫，然後再開始夜間工作。此外，這會大量消耗你的訂閱額度，因此小型任務不太值得這樣安排。務必限制嘗試次數，否則代理程式可能一夜之間耗盡你的全部訂閱額度。我在[另一篇文章](https://ailoot.ai/blog/zh-hant-tw/ai-agent-burned-budget-claude-code/)說明了如何設定這些使用上限。
## 如何提高限制
**方法 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 小時限制的設定如下：
```json
{
"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 的報告再次出現「達到背景時間限制後停止」這句話，表示該設定沒有套用到那個指令。
子代理和例行流程能讓代理程式在你離開時繼續工作。
我在[另一篇文章](https://ailoot.ai/blog/zh-hant-tw/claude-code-loop-engineering/)說明了如何讓代理程式整夜循環執行。至於如何設定 Claude Code，避免它在夜間弄壞專案，請參閱[這裡](https://ailoot.ai/blog/zh-hant-tw/claude-code-safe-overnight-setup/)。
確認夜間執行在哪個步驟停止，並將停止原因與上述限制對照。
### 來源
- [Claude Code：工具參考文件](https://code.claude.com/docs/en/tools-reference.md) - 限制適用的情況、2.1.285 和 2.1.288 版、30 分鐘和 2 小時限制、逾時後將指令移至背景、通知文字，以及 `BASH_DEFAULT_TIMEOUT_MS` 和 `BASH_MAX_TIMEOUT_MS` 變數。
- [Claude Code：環境變數](https://code.claude.com/docs/en/env-vars.md) - 一般指令預設等待 2 分鐘、`~/.claude/settings.json` 中的 env 區塊，以及工作階段套用新值的時機。
- [Claude Code：無頭模式](https://code.claude.com/docs/en/headless.md) - 使用 -p 旗標執行；背景指令會在最後一次回覆後約 5 秒終止。
- [Claude Code：設定](https://code.claude.com/docs/en/settings.md) - Windows 上 `~/.claude/settings.json` 的位置。
認識一下 [Ailoot](https://ailoot.ai/)。
## 常見問題：Claude Code：背景指令的 30 分鐘限制
### 互動工作階段放整晚，會觸發 30 分鐘上限嗎？
本文 2.1.288 以上限制適用 -p、Agent SDK、CI、雲端等無人值守執行。單純保持普通本機互動工作階段開啟，不歸此類。
### timeout 加大會讓 -p 結束後伺服器繼續嗎？
不會。-p 背景指令在最終回覆後不久終止。timeout 改的是執行中持續時間，不會變成長期託管。
## Ailoot · 公司及其專案組合
Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。
公司及其專案組合：數百萬客戶，每月銷售額達數十億。
Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。