背景工作

背景任務會追蹤主要對話工作階段之外執行的工作：ACP 執行、子代理程式產生、排程工作執行，以及透過命令列介面啟動的操作。

任務不會取代工作階段、排程工作或心跳偵測，而是記錄已發生哪些分離式工作、發生時間及是否成功的活動紀錄。

重點摘要

• 任務是紀錄，而非排程器；排程和心跳偵測決定工作_何時_執行，任務則追蹤_發生了什麼_。
• ACP、子代理程式、所有排程工作及命令列介面操作都會建立任務。心跳偵測回合不會。
• 每項任務都會經歷 queued → running → terminal（成功、失敗、逾時、取消或遺失）。
• 只要排程執行階段仍擁有該工作，排程任務就會保持作用中；若記憶體內的執行階段狀態已消失，任務維護會先檢查持久化的排程執行歷史記錄，再將任務標記為遺失。
• 完成通知由推送驅動：分離式工作完成時可直接通知，或喚醒請求者工作階段／心跳偵測，因此狀態輪詢迴圈通常不是正確的做法。
• 隔離的排程執行和子代理程式完成時，會在最終清理記帳前，盡力清理其子工作階段所追蹤的瀏覽器分頁／程序。
• 當後代子代理程式工作仍在收尾時，隔離的排程傳遞會抑制過時的父層中間回覆；若最終後代輸出在傳遞前抵達，則會優先採用該輸出。
• 完成通知會直接傳遞至頻道，或排入佇列以待下一次心跳偵測。
• openclaw tasks list 顯示所有任務；openclaw tasks audit 則會呈現問題。
• 終止狀態紀錄會保留 7 天（lost 紀錄保留 24 小時），之後自動刪除。

快速開始

# 列出所有任務（最新的優先）openclaw tasks list # 依執行階段或狀態篩選openclaw tasks list --runtime acpopenclaw tasks list --status running

# 顯示特定任務的詳細資料（依任務 ID、執行 ID 或工作階段金鑰）openclaw tasks show <lookup>

# 取消執行中的任務（終止子工作階段）openclaw tasks cancel <lookup> # 變更任務的通知原則openclaw tasks notify <lookup> state_changes

# 執行健康狀態稽核openclaw tasks audit # 預覽或套用維護openclaw tasks maintenanceopenclaw tasks maintenance --apply

# 檢查 TaskFlow 狀態openclaw tasks flow listopenclaw tasks flow show <lookup>openclaw tasks flow cancel <lookup>

哪些動作會建立任務

任務生命週期

stateDiagram-v2
    [*] --> queued
    queued --> running : 代理程式啟動
    running --> succeeded : 成功完成
    running --> failed : 錯誤
    running --> timed_out : 超過逾時限制
    queued --> cancelled : 操作者取消
    running --> cancelled : 操作者取消
    queued --> lost : 支援狀態消失超過 5 分鐘
    running --> lost : 支援狀態消失超過 5 分鐘

狀態轉換會自動發生；代理程式執行生命週期事件（開始、結束、錯誤）會更新任務狀態，你不需要手動管理。

對於作用中的任務紀錄，代理程式執行完成事件具有權威性。成功的分離式執行會結束為 succeeded，一般執行錯誤會結束為 failed，逾時會結束為 timed_out，取消／中止結果則會結束為 cancelled。任務進入終止狀態後，後續生命週期訊號不會將其降級；由操作者取消或已為 failed/timed_out/lost 的任務，即使之後收到成功訊號，仍會維持原狀。

lost 會依執行階段而定：

• ACP 任務：只有閘道中作用中的處理程序內 ACP 回合才能證明執行仍在進行；僅有持久化的工作階段中繼資料並不足以證明。離線命令列介面稽核會採保守策略，且絕不回收 ACP 任務。
• 子代理程式任務：支援該任務的子工作階段已從目標代理程式儲存區消失（或帶有重新啟動復原墓碑）。
• 排程任務：排程執行階段已不再將該工作追蹤為作用中，且持久化的排程執行歷史記錄中沒有該次執行的終止結果。離線命令列介面稽核不會將自身空白的處理程序內排程執行階段狀態視為權威依據。
• 命令列介面任務：具有執行 ID／來源 ID 的任務會使用即時執行內容，因此閘道所擁有的執行消失後，殘留的子工作階段或聊天工作階段資料列不會讓它們繼續保持作用中。沒有執行識別資訊的舊版命令列介面任務仍會回退使用子工作階段。以閘道為基礎的 openclaw agent 執行也會根據其執行結果結束，因此已完成的執行不會持續保持作用中，直到清理程式將它們標記為 lost。

傳遞與通知

當任務到達終止狀態時，OpenClaw 會通知你。有兩種傳遞路徑：

直接傳遞－如果任務有頻道目標（requesterOrigin），完成訊息會直接傳送至該頻道（Discord、Slack、Telegram 等）。群組和頻道任務的完成事件則會改由請求者工作階段路由，讓父代理程式撰寫可見回覆。對於子代理程式完成事件，OpenClaw 也會在可用時保留已繫結的討論串／主題路由，並可在放棄直接傳遞前，從請求者工作階段儲存的路由（lastChannel / lastTo / lastAccountId）補上缺少的 to／帳號。

工作階段佇列傳遞－如果直接傳遞失敗或未設定來源，更新會以系統事件的形式排入請求者工作階段的佇列，並在下一次心跳偵測時呈現。

這表示一般工作流程以推送為基礎：啟動分離式工作一次，然後讓執行階段在完成時喚醒或通知你。只有在需要偵錯、介入或明確稽核時，才輪詢任務狀態。

通知原則

控制每項任務通知你的詳細程度：

任務執行期間可變更原則：

openclaw tasks notify <lookup> state_changes

命令列介面參考

openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]

openclaw tasks show <lookup> [--json]

openclaw tasks cancel <lookup>

openclaw tasks notify <lookup> <done_only|state_changes|silent>

openclaw tasks audit [--severity <warn|error>] [--code <name>] [--limit <n>] [--json]

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

openclaw tasks flow list [--status <status>] [--json]openclaw tasks flow show <lookup> [--json]openclaw tasks flow cancel <lookup>

聊天工作面板（/tasks）

在任何聊天工作階段中使用 /tasks，即可查看連結至該工作階段的背景工作。面板最多會顯示五個作用中和最近完成的工作，並包含執行階段、狀態、時間，以及進度或錯誤詳細資訊。

當目前工作階段沒有可見的連結工作時，/tasks 會退回顯示代理程式本機工作計數，讓你仍可取得概覽，而不會洩漏其他工作階段的詳細資訊。

如需完整的操作員總帳，請使用命令列介面：openclaw tasks list。

控制介面

網頁控制介面的側邊欄中有一個工作頁面，會即時顯示作用中和最近的背景工作。你可以使用它來檢查進度、開啟連結的工作階段、重新整理總帳，或取消已排入佇列和執行中的工作。

聊天窗格也有一個可收合的背景工作側欄，其範圍限定於該窗格的代理程式：其中包含具有停止控制項的執行中工作和子代理程式、已完成區段，以及可進入每個工作子工作階段的「檢視轉錄內容」連結。請從窗格標題列中的活動切換按鈕開啟它（在單窗格聊天中則使用浮動活動按鈕）。

在側欄中選取工作，即可檢查其限定範圍的輸入提示，以及最新輸出或錯誤摘要。執行中的工作會與已完成的工作分開，而已完成的資料列會顯示工作是成功完成還是失敗。在 iOS 上，開啟 Chat actions → Background Tasks；在 Android 上，開啟 Chat 的溢位選單並選取 Background tasks。兩個行動版檢視都使用相同的 Running 和 Finished 分組，並會在選取時開啟工作詳細資料。

狀態整合（工作壓力）

openclaw status 包含一行可快速瀏覽的工作資訊：

工作    2 個作用中 · 1 個已排入佇列 · 1 個執行中 · 1 個問題 · 稽核正常 · 6 筆已追蹤

摘要會計算作用中的工作（queued + running）、失敗（failed + timed_out + lost）、稽核發現和追蹤記錄總數；JSON 承載資料也會依執行階段細分計數（acp、subagent、cron、cli）。

/status 和 session_status 工具都使用會感知清理狀態的工作快照：優先顯示作用中工作、隱藏已過期資料列，而且終止工作只會在短暫的近期時間範圍（5 分鐘）內顯示；當沒有剩餘的作用中工作時，則會聚焦顯示失敗。這能讓狀態卡片專注於目前最重要的資訊。

儲存與維護

工作的儲存位置

工作記錄和交付狀態會持久化在共用的 OpenClaw SQLite 狀態資料庫中：

~/.openclaw/state/openclaw.sqlite   （資料表：task_runs、task_delivery_state、flow_runs）

設定 OPENCLAW_STATE_DIR 可將整個狀態根目錄（預設為 ~/.openclaw）移至其他位置；共用資料庫路徑也會隨之移動。

登錄會在首次使用時載入記憶體，並將每次寫入持久化回 SQLite，因此記錄可在閘道重新啟動後保留。WAL 增長會透過 SQLite 的預設自動檢查點閾值，加上定期的 PASSIVE 檢查點維持在有限範圍內；關閉和明確維護的檢查點會使用 TRUNCATE，讓正常關閉能回收 WAL 空間，而不會使背景清理程式等待作用中的讀取者。

舊版安裝中的傳統附屬儲存區（tasks/runs.sqlite、flows/registry.sqlite）會由 openclaw doctor 匯入共用資料庫。

自動維護

清理程式每 60 秒執行一次（首次執行約在閘道啟動後 5 秒），並處理四件事：

工作與其他系統的關係

相關內容

• 自動化 - 一覽所有自動化機制
• 命令列介面：任務 - 命令列介面指令參考
• 心跳偵測 - 定期執行的主要工作階段輪次
• 排程任務 - 排程背景工作
• TaskFlow - 位於任務之上的流程協調機制