如何在背景執行 Claude Code agent

在背景執行 Claude Code 的五種方式

差別在於什麼必須一直開著，以及由誰來啟動工作。

工作階段裡的背景任務

Claude 正在執行 Bash 指令或 subagent 時按 Ctrl+B（在 tmux 裡按兩次），就能把它丟到背景，你可以繼續和 Claude 對話。Claude 也可以自己在背景啟動指令。Claude 產生的 subagent 預設就在背景執行。

輸入 /tasks 可以列出執行中的 shell 和 subagent 並查看狀態。在本機終端機的工作階段裡，背景指令沒有時間限制，但 Claude Code 結束時它也會停止。想讓幾個 agent 並排工作，請看如何同時執行多個 Claude Code agent。

Agent view：比終端機活得更久的工作階段

claude --bg "<prompt>" 會在背景啟動一個工作階段並立即返回；/bg 會把你目前所在的工作階段移到背景。它們由一個監督程序執行，所以關掉終端機不會讓它們停下，但關機或重新開機就會；沒有連接的閒置工作階段大約一小時後會被停止。

claude agents 會開啟 agent view；claude attach <id>、claude logs <id> 和 claude stop <id> 用來管理單一工作階段。Agent view 仍是研究預覽版，指令可能會變動。

用 claude -p 以 headless 模式執行 Claude Code

1. 執行一個提示詞後結束

   -p（或 --print）不開啟互動介面、直接執行 Claude Code，完成後就結束，成功時結束代碼為 0。也可以用管線把內容傳進去。

   claude -p "List the failing tests and why they fail"
   cat error.log | claude -p "Explain this error"

2. 取得腳本讀得懂的輸出

   --output-format json 會回傳結果，以及工作階段 ID 和中繼資料，其中包括 total_cost_usd，這是在你的電腦上算出的估計值。stream-json（搭配 --verbose）會在事件發生時即時輸出。

   claude -p "Summarize this repo" --output-format json | jq -r '.result'

3. 只放行它需要的工具

   headless 模式下沒有人能核准權限提示。從 v2.1.302 起，沒有指定模式的執行會以 Manual 模式啟動，拒絕所有需要核准的操作。用 --allowedTools 列出它可以做的事，再用 --permission-mode dontAsk 直接拒絕其餘操作，而不是一直等待。

   claude -p "Run the test suite and summarize failures" \
     --permission-mode dontAsk --allowedTools "Read,Bash(npm test)"

4. 為執行設定上限

   --max-turns 會在達到一定的 agent 輪數後停止，--max-budget-usd 會在達到估算費用時停止（可能會稍微超出）。兩者都只能搭配 -p 使用。

   claude -p "Fix the lint errors" --max-turns 15 --max-budget-usd 3

5. 之後接續同一段對話

   從 JSON 輸出儲存工作階段 ID，傳給 --resume；或用 --continue 接續目前目錄下最近的一個工作階段。

   id=$(claude -p "Start a code review of src/" --output-format json | jq -r '.session_id')
   claude -p "Now check the tests too" --resume "$id"

6. 用 cron 定時執行

   Anthropic 的文件沒有 cron 範例，下面這個只用了文件裡有寫的參數。cron 的 PATH 非常精簡，所以要用 which claude 給出的完整路徑，並先建立記錄檔資料夾。這裡不要加 --bare：它會跳過你的訂閱登入，需要 API key。

   # crontab -e：平日 9:00
   0 9 * * 1-5  cd /path/to/repo && /path/to/claude -p "Summarize yesterday's commits and list new TODO comments. Do not edit files." --permission-mode dontAsk --allowedTools "Read,Bash(git log *),Bash(git diff *)" --max-turns 10 --output-format json >> "$HOME/logs/claude-daily.log" 2>&1

來源：Anthropic 的 headless 模式文件（英文）

無人看管執行的權限

• dontAsk 加上一份 --allowedTools 清單是最嚴格的選擇：不在清單上的一律拒絕。
• auto 讓一個分類器代替你審查每個操作。Anthropic 指出它無法保證安全。
• acceptEdits 放行檔案修改和簡單的檔案指令，但不放行其他 shell 指令。
• bypassPermissions 會跳過權限提示和安全檢查。Anthropic 表示只應在沒有網路連線的隔離容器或虛擬機器裡使用，因為它對提示詞注入完全沒有防護。
• 要為專案裡的每次執行訂規則，請把 permissions.allow 和 permissions.deny 寫進 .claude/settings.json。deny 規則永遠優先。

雲端選項：電腦關著的時候

• 雲端工作階段：claude --cloud "<task>" 會根據你的 GitHub 分支在 Anthropic 的基礎架構上執行，闔上筆電也會繼續。用 claude -p "..." --cloud <session-id> 傳送後續訊息。
• 雲端排程任務：用 /schedule 或在 claude.ai/code 上建立，可以依時間表（最多每小時一次）、透過 API 呼叫或由 GitHub 事件觸發執行。適用 Pro、Max、Ultra、Team 和 Enterprise；目前為研究預覽版。
• GitHub Actions：anthropics/claude-code-action@v1 搭配 schedule 觸發條件。用 claude setup-token 產生的 OAuth token 會使用你的訂閱；用 API key 則按 token 計費。

給背景 agent 一份長期的工作

背景任務、agent view 和 cron 啟動的，都是你已經決定好的工作。Crewmark 則給 Claude Code 工作階段一個長期的職位：工作時間內依心跳醒來，從看板上接手下一個 issue，卡關時傳訊息給你。

1. 把一個工作階段變成員工

   選一個職位和一個用數字寫的目標，在 Claude Code 裡執行 Crewmark 給你的設定指令。這段對話就成了這位員工。

2. 讓心跳來啟動工作

   Crewmark daemon 會在工作時間內每 15、30 或 60 分鐘喚醒這個工作階段，使用你已經付費的訂閱；下班時間不打擾它。

3. 指派 issue，回覆訊息

   把工作當成 issue 加到看板上；員工會接手，邊做邊留言，需要審核時來問你。請看什麼是 AI 員工。

Claude Code 背景 agent 常見問題