后台任务

找调度功能？ 调度相关见自动化与任务。本页介绍追踪后台工作，而不是如何调度。

后台任务追踪在主会话之外运行的工作：ACP 运行、子 Agent 派生、隔离 cron 任务执行和 CLI 发起的操作。

任务不替代会话、cron 任务或 heartbeat——它们是记录分离工作发生时间、内容及是否成功的活动账本。

并非所有 Agent 运行都会创建任务。Heartbeat 轮次和普通交互聊天不会。所有 cron 执行、ACP 派生、子 Agent 派生和 CLI Agent 命令会创建任务。

要点速览

• 任务是记录，不是调度器——cron 和 heartbeat 决定何时运行，任务追踪发生了什么
• ACP、子 Agent、所有 cron 任务和 CLI 操作创建任务；Heartbeat 轮次不会
• 每个任务经历 queued → running → 终态（succeeded、failed、timed_out、cancelled 或 lost）
• 完成是推送驱动的：分离工作完成时可直接通知或唤醒请求方会话/heartbeat
• openclaw tasks list 显示所有任务；openclaw tasks audit 发现问题
• 终态记录保留 7 天后自动清理

快速上手

# 列出所有任务（最新优先）
openclaw tasks list

# 按运行时或状态筛选
openclaw tasks list --runtime acp
openclaw tasks list --status running

# 显示特定任务详情（支持 ID、run ID 或 session key 查找）
openclaw tasks show <lookup>

# 取消运行中的任务（终止子会话）
openclaw tasks cancel <lookup>

# 修改任务通知策略
openclaw tasks notify <lookup> state_changes

# 运行健康检查
openclaw tasks audit

# 预览或应用维护操作
openclaw tasks maintenance
openclaw tasks maintenance --apply

# 查看 TaskFlow 状态
openclaw tasks flow list
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>

哪些操作会创建任务

来源	运行时类型	创建时机	默认通知策略
ACP 后台运行	acp	派生子 ACP 会话	done_only
子 Agent 编排	subagent	通过 sessions_spawn 派生子 Agent	done_only
Cron 任务（所有类型）	cron	每次 cron 执行（主会话和隔离）	silent
CLI 操作	cli	通过 Gateway 运行的 openclaw agent 命令	silent

主会话 cron 任务默认使用 silent 策略——创建记录用于追踪，但不生成通知。

不创建任务的操作：

• Heartbeat 轮次（主会话）
• 普通交互聊天轮次
• 直接 /command 响应

任务生命周期

queued → running → succeeded
                → failed
                → timed_out
                → cancelled
queued → lost（会话消失超过 5 分钟）
running → lost（会话消失超过 5 分钟）

状态	含义
queued	已创建，等待 Agent 开始
running	Agent 轮次正在执行
succeeded	成功完成
failed	出错完成
timed_out	超过配置的超时时间
cancelled	操作者通过 openclaw tasks cancel 停止
lost	运行时在 5 分钟宽限期后丢失了权威支持状态

投递与通知

任务到达终态时，OpenClaw 会通知你：

• 直接投递：如果任务有渠道目标（requesterOrigin），完成消息直接发到该渠道（Telegram、Discord、Slack 等）
• 会话队列投递：直接投递失败或未设置 origin 时，更新入队到请求方会话，在下次 heartbeat 时显示

任务完成会立即触发 heartbeat 唤醒，让你快速看到结果——无需等待下次定时 heartbeat。

通知策略

策略	投递内容
done_only（默认）	只投递终态（succeeded、failed 等）
state_changes	每次状态变化和进度更新
silent	不投递任何内容

运行时修改策略：

openclaw tasks notify <lookup> state_changes

CLI 参考

tasks list

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

输出列：任务 ID、类型、状态、投递、Run ID、子会话、摘要。

tasks show

openclaw tasks show <lookup>

查找 token 支持任务 ID、run ID 或 session key。显示完整记录，包括时间、投递状态、错误和终态摘要。

tasks cancel

openclaw tasks cancel <lookup>

对 ACP 和子 Agent 任务，终止子会话。状态变为 cancelled 并发送投递通知。

tasks audit

openclaw tasks audit [--json]

发现操作问题。问题也会出现在 openclaw status 中。

发现项	严重程度	触发条件
stale_queued	warn	排队超过 10 分钟
stale_running	error	运行超过 30 分钟
lost	error	运行时支持的任务所有权消失
delivery_failed	warn	投递失败且通知策略非 silent

tasks maintenance

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

预览或应用协调、清理和修剪操作。

/tasks 聊天任务板

在任何聊天会话中使用 /tasks 查看与该会话关联的后台任务，显示活跃和最近完成的任务，包含运行时、状态、时间和进度或错误详情。

存储与维护

任务记录持久化在 SQLite 中：

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

清理器每 60 秒运行一次，处理三件事：

1. 协调：检查活跃任务是否仍有运行时支持
2. 清理标记：为终态任务设置 cleanupAfter 时间戳（结束时间 + 7 天）
3. 修剪：删除过期记录

保留期：终态记录保留 7 天，然后自动清理。

与其他系统的关系

任务与 Task Flow

Task Flow 是后台任务之上的流程编排层。用 openclaw tasks 检查单个任务记录，用 openclaw tasks flow 检查编排流程。

任务与 Cron

每次 cron 执行都会创建任务记录——包括主会话和隔离执行。主会话 cron 任务默认 silent 策略，不产生通知。

参见定时任务。

任务与 Heartbeat

Heartbeat 运行是主会话轮次——不创建任务记录。任务完成时可触发 heartbeat 唤醒。

参见Heartbeat。

相关文档

• 自动化与任务 — 所有自动化机制一览
• Task Flow — 任务之上的流程编排
• 定时任务 — 调度后台工作