背景任務

Note

尋找排程功能？請參閱

Automation

以選擇合適的機制。此頁面是背景工作的活動記錄，而非排程器。

背景任務會追蹤在您的主要對話工作階段之外執行的工作：ACP 執行、子代理生成、隔離的 cron 工作執行，以及 CLI 初始化的操作。

工作不會取代對話階段、cron 排程工作或心跳——它們是記錄已分離工作發生時間、內容及成功與否的 活動記錄帳。

Note

並非每個代理執行都會建立任務。心跳週期和正常的互動式聊天不會。所有的 cron 執行、ACP 衍生、子代理衍生和 CLI 代理指令都會。

TL;DR

• 工作是 記錄，而非排程器——cron 和心跳決定工作何時執行，而工作追蹤發生了什麼。
• ACP、子代理、所有 cron 工作和 CLI 操作都會建立任務。心跳週期則不會。
• 每個工作都會經過 queued → running → terminal（succeeded、failed、timed_out、cancelled 或 lost）。
• 只要 cron 執行時期仍擁有該工作，Cron 任務就會保持活躍；如果記憶體中的執行時期狀態消失，任務維護程式會在將任務標記為 lost 之前，先檢查持久化的 cron 執行記錄。
• 完成作業是由推送驅動的：分離的工作可以在完成時直接通知或喚醒請求者工作階段/心跳，因此狀態輪詢迴圈通常是不正確的模式。
• 獨立的 cron 執行和子代理完成作業會在進行最終清理簿記之前，盡力清理其子工作階段的追蹤瀏覽器分頁/程序。
• 隔離的 cron 傳送會在後代子代理工作仍在排空時抑制過時的中繼父層回覆，並且如果最終的後代輸出在傳送之前抵達，則會優先採用該輸出。
• 完成通知會直接傳送到頻道，或排入佇列等待下一次心跳。
• openclaw tasks list 顯示所有工作；openclaw tasks audit 則會顯示問題。
• 終端記錄會保留 7 天，然後自動修剪。

快速入門

列出與篩選InspectCancel and notifyAudit and maintenanceTask flow

# List all tasks (newest first)
openclaw tasks list

# Filter by runtime or status
openclaw tasks list --runtime acp
openclaw tasks list --status running

# Show details for a specific task (by ID, run ID, or session key)
openclaw tasks show

# Cancel a running task (kills the child session)
openclaw tasks cancel

Change notification policy for a task

openclaw tasks notify

state_changes

# Run a health audit
openclaw tasks audit

# Preview or apply maintenance
openclaw tasks maintenance
openclaw tasks maintenance --apply

# Inspect TaskFlow state
openclaw tasks flow list
openclaw tasks flow show

openclaw tasks flow cancel

什麼會建立任務

來源	執行時期類型	建立任務記錄的時機	預設通知原則
ACP 背景執行	acp	產生子 ACP 工作階段	done_only
子代理協調流程	subagent	透過 sessions_spawn 產生子代理	done_only
Cron 工作（所有類型）	cron	每次 cron 執行（主要工作階段與隔離）	silent
CLI 操作	cli	透過閘道執行的 openclaw agent 指令	silent
代理媒體工作	cli	Session-backed image_generate/music_generate/video_generate runs	silent

Notify defaults for cron and media

主會話 cron 任務預設使用 silent 通知政策——它們會建立追蹤記錄但不產生通知。獨立 cron 任務同樣預設為 silent，但因為它們在自己的會話中執行，所以更為顯眼。

由會話支援的 image_generate、music_generate 和 video_generate 執行也使用 silent 通知政策。它們仍會建立任務記錄，但完成狀態會透過內部喚醒交還給原始代理程式會話，以便代理程式撰寫後續訊息並自行附加完成的媒體。請求代理程式遵循其一般可見回覆合約：設定時自動發出最終回覆，或在會話需要訊息工具回覆時發出 message(action="send") 加上 NO_REPLY。如果請求會話已不再有效，或其作用中的喚醒失敗，且完成代理程式遺漏了部分或全部產生的媒體，OpenClaw 會向原始頻道目標發送一個僅包含遺失媒體的等幕直接後援。

並行媒體生成防護機制

當由會話支援的媒體生成任務仍處於活躍狀態時，媒體工具也充當防止意外重試的防護機制。針對相同提示詞重複呼叫 image_generate 會傳回相符的活躍任務狀態，而不同的圖片提示詞則可以啟動其自身的任務。music_generate 和 video_generate 的呼叫仍然會傳回該會話的活躍任務狀態，而不是啟動第二次並行生成。當您想要從代理程式端進行明確的進度/狀態查詢時，請使用 action: "status"。

What does not create tasks

• Heartbeat 週期 - 主會話；請參閱 Heartbeat
• 一般互動式聊天週期
• 直接 /command 回應

任務生命週期

stateDiagram-v2
    [*] --> queued
    queued --> running : agent starts
    running --> succeeded : completes ok
    running --> failed : error
    running --> timed_out : timeout exceeded
    running --> cancelled : operator cancels
    queued --> lost : session gone > 5 min
    running --> lost : session gone > 5 min

狀態	含義
queued	已建立，正在等待代理程式開始
running	代理程式週期正在主動執行
succeeded	成功完成
failed	完成但發生錯誤
timed_out	超過設定的逾時時間
cancelled	由操作員透過 openclaw tasks cancel 停止
lost	運行時在 5 分鐘寬限期後失去了權威的備份狀態

轉換會自動發生——當關聯的代理執行結束時，任務狀態會隨之更新以相符。

Agent 執行的完成狀態是作用中任務記錄的依據。成功的分離執行會定案為 succeeded，一般執行錯誤會定案為 failed，而逾時或中止結果會定案為 timed_out。如果操作員已經取消任務，或者執行時環境已經記錄了更強的終端狀態，例如 failed、timed_out 或 lost，則後續的成功訊號不會降級該終端狀態。

lost 具備執行時感知能力：

• ACP 任務：備份 ACP 子會話元數據已消失。
• 子代理任務：備份子會話從目標代理存儲中消失。
• Cron 任務：cron 運行時不再追蹤該任務為活動和持久狀態， 且 cron 運行歷史未顯示該運行的最終結果。離線 CLI 審計不會將其自己空的進程中 cron 運行時狀態視為權威。
• CLI 任務：具有執行 ID/來源 ID 的任務會使用即時執行內文，因此當閘道擁有的執行消失後，殘留的子會話 (child-session) 或聊天會話 (chat-session) 記錄不會讓它們保持活躍。沒有執行身分的舊版 CLI 任務仍然會退回到子會話。由閘道支援的 openclaw agent 執行也會根據其執行結果定案，因此已完成的執行不會一直保持作用中，直到清理程式 (sweeper) 將其標記為 lost。

交付與通知

當任務達到最終狀態時，OpenClaw 會通知您。有兩種交付途徑：

直接傳送 - 如果任務具有頻道目標 (即 requesterOrigin)，完成訊息會直接傳送到該頻道（Telegram、Discord、Slack 等）。群組和頻道任務的完成則會改透過請求者的會話進行路由，讓父 Agent 能夠撰寫可見的回覆。對於子 Agent 的完成項目，OpenClaw 也會在可用時保留綁定的執行緒/主題路由，並且可以在放棄直接傳送之前，從請求者會話的儲存路由 (lastChannel / lastTo / lastAccountId) 填補缺失的 to / 帳戶。

會話排隊傳遞 - 如果直接傳遞失敗或未設定來源，更新會作為系統事件在請求者的會話中排隊，並在下次心跳時顯示。

Tip

任務完成會觸發立即的心跳喚醒，因此您可以快速看到結果 - 您不必等待下一次排程的心跳跳動。

這意味著常見的工作流程是基於推送的：啟動一次分離工作，然後讓執行時在完成時喚醒或通知您。僅在需要偵錯、干預或明確稽核時才輪詢任務狀態。

通知原則

控制您收到每個任務的資訊量：

原則	傳遞內容
done_only (預設)	僅終止狀態 (成功、失敗等) - 這是預設值
state_changes	每次狀態轉換和進度更新
silent	完全不傳遞

在任務執行時變更原則：

openclaw tasks notify <lookup> state_changes

CLI 參考

tasks list

openclaw tasks list [--runtime

] [—status

] [—json] ```

輸出欄位：Task ID, Kind, Status, Delivery, Run ID, Child Session, Summary。

tasks show

openclaw tasks show

查詢權杖接受任務 ID、Run ID 或會話金鑰。顯示完整紀錄，包括計時、傳遞狀態、錯誤和終止摘要。

tasks cancel

openclaw tasks cancel

對於 ACP 和子代理程式任務，這會終止子工作階段。對於 CLI 追蹤的任務，取消操作會記錄在任務登錄檔中（沒有個別的子執行時期控制代碼）。狀態轉變為 `cancelled`，並在適用時發送傳送通知。

tasks notify

openclaw tasks notify

tasks audit

openclaw tasks audit [--json]

顯示操作問題。當偵測到問題時，發現結果也會出現在 openclaw status 中。

Finding	Severity	Trigger
stale_queued	warn	排隊超過 10 分鐘
stale_running	error	執行超過 30 分鐘
lost	warn/error	執行時期支援的任務擁有權已消失；保留的遺失任務會發出警告直到 cleanupAfter，然後變成錯誤
delivery_failed	warn	傳送失敗且通知原則不是 silent
missing_cleanup	warn	沒有清理時間戳記的終端任務
inconsistent_timestamps	warn	時間線違規（例如在開始前結束）

tasks maintenance

openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]

使用此項來預覽或套用任務、Task Flow 狀態以及過時 cron 執行階段會話登錄檔行的對帳、清理標記和修剪。

對帳具備執行時感知能力：

• ACP/子代理任務會檢查其支援的子會話。
• 若子會話具備重新啟動復原標記，則子代理任務會被標記為遺失，而不會被視為可復原的支援會話。
• Cron 任務會檢查 cron 執行時是否仍擁有該工作，然後在回退到 lost 之前，從持久的 cron 執行紀錄/工作狀態中復原終端狀態。僅 Gateway 程序對記憶體中的 cron 使用中工作集具有權威性；離線 CLI 稽核會使用持久的歷史紀錄，但不會僅因該本地 Set 為空就將 cron 任務標記為遺失。
• 具備執行身分的 CLI 任務會檢查擁有的即時執行內容，而不僅是子會話或聊天會話列。

完成清理也具備執行時感知能力：

• 子代理完成會在繼續公告清理之前，盡力為子會話關閉追蹤的瀏覽器分頁/程序。
• 隔離的 cron 完成會在執行完全拆除之前，盡力為 cron 會話關閉追蹤的瀏覽器分頁/程序。
• 隔離的 cron 傳遞會在需要時等待後代子代理的後續追蹤，並抑制過時的父層確認文字，而不是將其公告。
• 子代理完成傳遞僅使用子項最新的可見助理文字。Tool/toolResult 輸出不會被提升至子項結果文字。終端失敗的執行會公告失敗狀態，而不會重新播放擷取的回覆文字。
• 清理失敗不會遮蔽真正的任務結果。

套用維護時，OpenClaw 也會移除超過 7 天的過時 `cron:

:run:

` 會話登錄檔列，同時保留目前執行中 cron 工作的列，並保持非 cron 會話列不變。

tasks flow list | show | cancel

openclaw tasks flow list [--status

] [—json] openclaw tasks flow show

[—json] openclaw tasks flow cancel

當您關心的是協調任務流程而非單一背景工作記錄時，請使用這些指令。

聊天任務看板 (/tasks)

在任何聊天階段中使用 /tasks 以查看連結至該階段的背景任務。看板會顯示作用中及最近完成的任務，並包含執行時、狀態、時間，以及進度或錯誤細節。

當目前的工作階段沒有可見的連結任務時，/tasks 會改為顯示代理程式本機的任務計數，讓您仍能獲得概覺，而不會洩漏其他工作階段的細節。

若要查看完整的操作員帳本，請使用 CLI：openclaw tasks list。

狀態整合 (任務壓力)

openclaw status 包含一目了然的任務摘要：

Tasks: 3 queued · 2 running · 1 issues

摘要回報：

• active - queued + running 的計數
• failures - failed + timed_out + lost 的計數
• byRuntime - 依 acp、subagent、cron、cli 細分

/status 和 session_status 工具都使用具有清理感知能力的任務快照：優先顯示作用中任務，隱藏過期的已完成列，且僅當無作用中工作時才顯示最近的失敗。這可讓狀態卡專注於當下重要的事項。

儲存與維護

任務儲存位置

任務記錄會持久保存在 SQLite 的以下位置：

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

登錄檔會在閘道啟動時載入至記憶體，並將寫入同步至 SQLite 以確保重新啟動後的持久性。 閘道透過使用 SQLite 預設的自動檢查點閾值，加上定期與關閉 TRUNCATE 檢查點，將 SQLite 的預寫式日誌保持在一定範圍內。

自動維護

掃掠程式 (sweeper) 每 60 秒 執行一次，並處理四件事：

1. Reconciliation

   檢查作用中任務是否仍具備權威的執行期支援。ACP/子代理程式任務使用子工作階段狀態，Cron 任務使用作用中工作擁有權，而具備執行身分的 CLI 任務則使用擁有的執行內容。如果該支援狀態消失超過 5 分鐘，任務會被標記為 lost。

2. ACP session repair

   關閉終結或孤立的父擁有一次性 ACP 工作階段，並僅當沒有剩餘的作用中對話連結時，才關閉陳舊的終結或孤立持久式 ACP 工作階段。

3. Cleanup stamping

   在終端任務上設定 cleanupAfter 時間戳記 (endedAt + 7 天)。在保留期間，遺失的任務仍會在稽核中以警告顯示；在 cleanupAfter 過期或缺少清理中繼資料後，它們會變成錯誤。

4. Pruning

   刪除超過其 cleanupAfter 日期的記錄。

Note

保留期限：

終止任務記錄會保留

7 天

，然後自動修剪。無需配置。

任務與其他系統的關聯

Tasks and Task Flow

Task Flow 是位於背景任務上層的流程編排層。單一流程在其生命週期中可以使用受管或鏡像同步模式來協調多個任務。使用 openclaw tasks 檢查個別任務記錄，並使用 openclaw tasks flow 檢查編排流程。

詳情請參閱 Task Flow。

Tasks and cron

Cron 工作定義、執行時執行狀態和執行歷史記錄存在於 OpenClaw 的共享 SQLite 狀態資料庫中。每個 Cron 執行都會建立一個任務記錄——包括主會話和獨立的。主會話 Cron 任務預設採用 silent 通知策略，以便它們進行追蹤而不產生通知。

參閱 Cron Jobs。

Tasks and heartbeat

Heartbeat 執行是主會話輪次——它們不會建立任務記錄。當任務完成時，它可以觸發 Heartbeat 喚醒，以便您及時看到結果。

參閱 Heartbeat。

Tasks and sessions

任務可能會參照 childSessionKey（工作執行的地方）和 requesterSessionKey（誰啟動了它）。會話是對話上下文；任務是建構在其上的活動追蹤。

Tasks and agent runs

任務的 runId 連結到執行工作的 Agent 執行。Agent 生命週期事件（開始、結束、錯誤）會自動更新任務狀態——您無需手動管理生命週期。

相關

• Automation - 一目瞭然的所有自動化機制
• CLI: Tasks - CLI 指令參考
• Heartbeat - 週期性主會話輪次
• Scheduled Tasks - 排程背景工作
• Task Flow - 任務之上的流程編排