后台任务

后台任务跟踪在主对话会话之外运行的工作：ACP 运行、子智能体生成、定时任务执行以及由 CLI 发起的操作。

任务不会取代会话、定时任务或 Heartbeat——它们是记录已发生哪些分离式工作、发生时间及其是否成功的活动账本。

简而言之

• 任务是记录，而不是调度器——定时任务和 Heartbeat 决定工作在_何时_运行，任务跟踪_发生了什么_。
• ACP、子智能体、所有定时任务和 CLI 操作都会创建任务。Heartbeat 轮次不会。
• 每个任务都会经历 queued → running → terminal（成功、失败、超时、已取消或丢失）。
• 只要定时任务运行时仍拥有该作业，定时任务就会保持活动状态；如果内存中的运行时状态已消失，任务维护会先检查持久化的定时任务运行历史，然后再将任务标记为丢失。
• 完成通知由推送驱动：分离式工作完成时可以直接通知，也可以唤醒请求方会话或 Heartbeat，因此状态轮询循环通常不是正确的实现方式。
• 隔离的定时任务运行和子智能体完成后，会尽力为其子会话清理受跟踪的浏览器标签页和进程，然后再执行最终清理记录工作。
• 当后代子智能体工作仍在收尾时，隔离的定时任务交付会抑制过时的父级中间回复；如果最终后代输出在交付前到达，则优先使用该输出。
• 完成通知会直接发送到渠道，或排队等待下一次 Heartbeat。
• 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 任务：只有 Gateway 网关中处于活动状态的进程内 ACP 轮次才能证明运行仍然存活；仅有持久化的会话元数据无法证明。离线 CLI 审计采取保守策略，绝不会回收 ACP 任务。
• 子智能体任务：支撑它的子会话已从目标智能体存储中消失（或带有重启恢复墓碑）。
• 定时任务：定时任务运行时不再将该作业作为活动作业跟踪，并且持久化的定时任务运行历史中没有该次运行的终止结果。离线 CLI 审计不会将其自身为空的进程内定时任务运行时状态视为权威依据。
• CLI 任务：具有运行 ID 或来源 ID 的任务使用实时运行上下文，因此在 Gateway 网关拥有的运行消失后，残留的子会话或聊天会话行不会使其继续保持活动状态。没有运行标识的旧版 CLI 任务仍会回退到子会话。由 Gateway 网关支持的 openclaw agent 运行也会根据其运行结果最终确定状态，因此已完成的运行不会一直保持活动状态，直到清理器将其标记为 lost。

交付和通知

当任务进入终止状态时，OpenClaw 会通知你。有两种交付路径：

直接交付——如果任务具有渠道目标（即 requesterOrigin），完成消息会直接发送到该渠道（Discord、Slack、Telegram 等）。群组和频道任务的完成消息则会通过请求方会话路由，以便父智能体编写可见回复。对于子智能体完成消息，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> [--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 会回退到 Agent 本地任务计数，让你仍能获得概览，同时不会泄露其他会话的详情。

如需完整的操作员账本，请使用 CLI：openclaw tasks list。

Control UI

Web Control UI 的侧边栏中有一个任务页面，其中显示实时的活动任务和近期后台任务。你可以用它检查进度、打开关联会话、刷新账本，或取消排队中和运行中的任务。

聊天窗格还有一个可折叠的后台任务栏，其范围限定为该窗格的 Agent：其中包含带停止控件的运行中任务和子智能体、已完成部分，以及用于进入各任务子会话的“查看转录”链接。可通过窗格标题栏中的活动切换按钮打开它（在单窗格聊天中，也可通过浮动活动按钮打开）。

在该栏中选择任务，即可检查其限定范围的输入提示词以及最新输出或错误摘要。运行中的工作与已完成的工作分开显示，已完成行会指明任务是成功完成还是失败。在 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，因此记录在 Gateway 网关重启后仍会保留。通过 SQLite 的默认自动检查点阈值以及定期的 PASSIVE 检查点，将 WAL 增长控制在有限范围内；关闭和显式维护检查点使用 TRUNCATE，因此正常关闭可以回收 WAL 空间，而无需让后台清理程序等待活动读取者。

旧版安装中的遗留边车存储（tasks/runs.sqlite、flows/registry.sqlite）由 openclaw doctor 导入共享数据库。

自动维护

清理程序每 60 秒运行一次（Gateway 网关启动约 5 秒后进行首次处理），并处理以下四项工作：

任务与其他系统的关系

相关内容

• 自动化 - 一览所有自动化机制
• CLI：任务 - CLI 命令参考
• Heartbeat - 周期性的主会话轮次
• 定时任务 - 调度后台工作
• Task Flow - 任务之上的流程编排