后台任务

后台任务跟踪在主会话之外运行的工作：ACP 运行、子代理生成、隔离的 cron 作业执行以及 CLI 发起的操作。

任务不替代会话、定时任务（cron jobs）或心跳 —— 它们是记录发生了什么分离工作、何时发生以及是否成功的活动账本。

TL;DR

任务是记录，而非调度器 —— 定时任务和心跳决定工作何时运行，任务追踪发生了什么。
ACP、子代理、所有 cron 作业和 CLI 操作都会创建任务。Heartbeat 轮次则不会。
每个任务都会经历 queued → running → terminal（成功、失败、超时、取消或丢失）。
只要 cron 运行时仍然拥有该作业，Cron 任务就会保持活跃；如果内存中的运行时状态消失，任务维护会在将任务标记为丢失之前先检查持久的 cron 运行历史。
完成是由推送驱动的：分离的工作可以在完成时直接通知或唤醒请求者的会话/心跳，因此状态轮询循环通常是错误的模式。
隔离的 cron 运行和子代理完成操作会尽最大努力在最终清理簿记之前，为其子会话清理受跟踪的浏览器选项卡/进程。
隔离的 cron 传递会在子代理工作仍在排空时抑制过时的临时父级回复，并且如果最终子级输出在传递之前到达，则优先使用该输出。
完成通知会直接投递到渠道或排队等待下一次心跳。
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

# 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`	支持会话的 `image_generate`/`music_generate`/`video_generate` 运行	`silent`

Cron 和媒体的默认通知设置

主会话 Cron 任务默认使用 silent 通知策略——它们会创建记录用于跟踪，但不生成通知。独立的 Cron 任务也默认使用 silent，但由于它们在自己的会话中运行，因此更为显眼。

由会话支持的 image_generate、music_generate 和 video_generate 运行也使用 silent 通知策略。它们仍会创建任务记录，但完成状态会作为内部唤醒交还给原始代理会话，以便代理可以撰写后续消息并自行附加完成的媒体。请求代理遵循其正常的可见回复约定：配置时自动最终回复，或者在会话需要消息工具回复时使用 message(action="send") 加上 NO_REPLY。如果请求会话不再处于活动状态或其活动唤醒失败，并且完成代理错过了部分或全部生成的媒体，OpenClaw 会向原始渠道目标发送一个仅包含缺失媒体的幂等直接回退。

Concurrent media-generation guardrail

当一个由会话支持的媒体生成任务仍处于活动状态时，媒体工具也会充当防止意外重试的护栏。针对同一提示的重复 image_generate 调用将返回匹配的活动任务状态，而不同的图像提示可以启动其自己的任务。music_generate 和 video_generate 调用仍然返回该会话的活动任务状态，而不是启动第二次并发生成。当你需要从代理侧显式查找进度/状态时，请使用 action: "status"。

什么不会创建任务

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 的任务使用实时运行上下文，因此当 Gateway 拥有的运行消失后，残留的子会话或聊天会话记录不会使它们保持活动状态。没有运行标识的旧版 CLI 任务仍回退到子会话。Gateway 支持的 CLICLIGateway(网关)openclaw agent 运行也会根据其运行结果完成，因此已完成的运行不会保持活动状态，直到清理程序将它们标记为 lost。

传递和通知

当任务达到终止状态时，OpenClaw 会通知您。有两条传递路径：

直接投递 - 如果任务具有渠道目标（即 requesterOriginTelegramDiscordSlackOpenClaw），完成消息将直接发送到该渠道（Telegram、Discord、Slack 等）。组和渠道任务完成改为通过请求者会话路由，以便父代理可以编写可见的回复。对于子代理完成，OpenClaw 还会在可用时保留绑定的主题/话题路由，并且可以在放弃直接投递之前，从请求者会话存储的路由（lastChannel / lastTo / lastAccountId）中填充缺失的 to / 账户。

会话排队投递 - 如果直接投递失败或未设置来源，更新将作为系统事件排队在请求者的会话中，并在下一次心跳时显示。

这意味着通常的工作流是基于推送的：启动一次分离的工作，然后让运行时在工作完成时唤醒或通知您。仅在需要调试、干预或显式审计时才轮询任务状态。

通知策略

控制您接收关于每个任务的通知频率：

策略	传递内容
`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、运行 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/subagent 任务会检查其后备子会话。
如果子会话具有重启恢复标记，则 Subagent 任务将被标记为丢失，而不是被视为可恢复的后备会话。
Cron 任务会检查 cron 运行时是否仍拥有该作业，然后从持久化的 cron 运行日志/作业状态中恢复最终状态，最后才回退到 lost。只有 Gateway(网关) 进程才是内存中 cron 活跃作业集的权威来源；离线 CLI 审计使用持久历史记录，但不会仅仅因为该本地 Set 为空就将 cron 任务标记为丢失。
具有运行标识的 CLI 任务会检查所属的实时运行上下文，而不仅仅是子会话或聊天会话行。

完成清理也具有运行时感知能力：

Subagent 完成后会尽力关闭子会话的受跟踪浏览器选项卡/进程，然后再继续公告清理。
隔离的 cron 完成后会尽力关闭 cron 会话的受跟踪浏览器选项卡/进程，然后再完全拆除运行。
隔离的 cron 投递会在需要时等待子代 subagent 的后续跟进，并抑制过时的父级确认文本，而不是公告它。
Subagent 完成投递仅使用子级的最新可见助手文本。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：CLIopenclaw tasks list。

状态集成（任务压力）

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

Tasks: 3 queued · 2 running · 1 issues

摘要报告：

active（活动） - queued + running 的计数
failures（失败） - failed + timed_out + lost 的计数
byRuntime（按运行时） - 按 acp、subagent、cron``cli、%%PH:INLINE_CODE:152:42cb9279** 细分

/status 和 session_status 工具都使用支持清理的任务快照：优先显示活动任务，隐藏过时的已完成行，且仅当没有剩余活动工作时才显示最近的失败。这使状态卡片能专注于当前重要的事项。

存储与维护

任务的存储位置

任务记录持久保存在 SQLite 的以下位置：

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

注册表在网关启动时加载到内存中，并将写入同步到 SQLite 以在重启间保持持久性。 Gateway 通过使用 SQLite 默认的自动检查点阈值加上定期和关机时的 Gateway(网关)TRUNCATE 检查点，来控制 SQLite 预写日志的大小。

自动维护

清理器每 60 秒 运行一次并处理四件事：

Reconciliation
检查活动任务是否仍具有权威的运行时支持。ACP/子代理任务使用子会话状态，cron 任务使用活动作业所有权，具有运行标识的 CLI 任务使用所属运行上下文。如果该支持状态丢失超过 5 分钟，任务将被标记为 lost。
ACP 会话 repair
关闭终端或孤立的父级拥有的一次性 ACP 会话，并仅在不存在活跃对话绑定时关闭过时的终端或孤立的持久化 ACP 会话。
清理标记
在已结束的任务上设置 cleanupAfter 时间戳（endedAt + 7 天）。在保留期间，丢失的任务在审核中仍显示为警告；在 cleanupAfter 过期或清理元数据丢失后，它们将显示为错误。
修剪
删除超过其 cleanupAfter 日期的记录。

任务与其他系统的关系

任务与任务流

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 生命周期事件（开始、结束、错误）会自动更新任务状态——您无需手动管理生命周期。