背景任務

背景工作會追蹤在主要對話工作階段之外執行的工作：ACP 執行、子代理程式衍生、隔離的 Cron 作業執行，以及 CLI 啟動的操作。

工作不會取代工作階段、Cron 作業或 Heartbeat，它們是記錄已分離工作發生內容、時間，以及是否成功的活動帳本。

# TL;DR

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

# 快速開始

# 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 <lookup>

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

# Change notification policy for a task
openclaw tasks notify <lookup> 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 <lookup>
openclaw tasks flow cancel <lookup>

# 什麼會建立工作

# 工作生命週期

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

轉換會自動發生；當相關代理程式執行結束時，工作狀態會更新為相符狀態。

對於作用中的工作記錄，代理程式執行完成是權威依據。成功的分離執行會最終化為 succeeded，一般執行錯誤會最終化為 failed，逾時或中止結果會最終化為 timed_out。如果操作者已經取消該工作，或執行階段已經記錄了更強的終端狀態，例如 failed、timed_out 或 lost，稍後的成功訊號不會降級該終端狀態。

lost 具備執行階段感知：

• ACP 工作：支援用的 ACP 子工作階段中繼資料消失。
• 子代理程式工作：支援用的子工作階段已從目標代理程式存放區消失。
• Cron 工作：Cron 執行階段不再將該作業追蹤為作用中，且持久化 Cron 執行歷史並未顯示該執行有終端結果。離線 CLI 稽核不會將自身空的程序內 Cron 執行階段狀態視為權威。
• CLI 工作：具有執行 ID/來源 ID 的工作會使用即時執行內容，因此 在 Gateway 擁有的執行消失後，殘留的子工作階段或聊天工作階段資料列不會讓它們保持作用中。沒有執行身分的舊版 CLI 工作仍會退回使用子工作階段。由 Gateway 支援的 openclaw agent 執行也會依據其執行結果最終化，因此已完成的執行不會一直保持作用中，直到清掃器將它們標記為 lost。

# 傳遞與通知

當工作達到終端狀態時，OpenClaw 會通知你。共有兩種傳遞路徑：

直接傳遞；如果工作有頻道目標（requesterOrigin），完成訊息會直接傳到該頻道（Telegram、Discord、Slack 等）。對於子代理程式完成，OpenClaw 也會在可用時保留已繫結的執行緒/主題路由，並且可以在放棄直接傳遞前，從請求者工作階段儲存的路由（lastChannel / lastTo / lastAccountId）補齊缺少的 to / 帳戶。

工作階段佇列傳遞；如果直接傳遞失敗或未設定來源，更新會在請求者工作階段中排入佇列作為系統事件，並在下一次 Heartbeat 時呈現。

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

# 通知原則

控制你會聽到每個工作的多少資訊：

在工作執行中變更原則：

openclaw tasks notify <lookup> state_changes

# CLI 參考

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

openclaw tasks show <lookup>

openclaw tasks cancel <lookup>

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

openclaw tasks audit [--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 會退回到代理程式本機任務計數，因此你仍可取得概覽，而不會洩漏其他工作階段的詳細資訊。

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

# 狀態整合（任務壓力）

openclaw status 包含一眼可讀的任務摘要：

Tasks: 3 queued · 2 running · 1 issues

摘要會回報：

• 作用中 - queued + running 的數量
• 失敗 - failed + timed_out + lost 的數量
• byRuntime - 依 acp、subagent、cron、cli 分解

/status 和 session_status 工具都使用會感知清理的任務快照：優先顯示作用中任務、隱藏過時的已完成資料列，而且只有在沒有剩餘作用中工作時才顯示近期失敗。這會讓狀態卡專注於目前重要的事項。

# 儲存與維護

# 任務存放位置

任務記錄持久化於 SQLite：

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

登錄檔會在 gateway 啟動時載入記憶體，並將寫入同步至 SQLite，以便在重新啟動後保持耐久性。 Gateway 會使用 SQLite 的預設自動檢查點閾值，加上定期和關機時的 TRUNCATE 檢查點，讓 SQLite 預寫式記錄保持有界。

# 自動維護

清掃器每 60 秒執行一次，並處理四件事：

# 任務如何與其他系統相關

# 相關

• 自動化與任務 - 所有自動化機制一覽
• CLI：任務 - CLI 命令參考
• Heartbeat - 定期的主要工作階段回合
• 排程任務 - 排程背景工作
• Task Flow - 任務之上的流程編排