古法编程

Appearance

OpenClaw 后台任务是记录分离工作的活动账本，不是调度器。ACP 运行、子 Agent 派生、Cron 执行和 CLI 操作会自动创建任务记录，使用 openclaw tasks list 查看、openclaw tasks audit 发现异常，任务完成后会直接通知或通过 heartbeat 唤醒。记录保留 7 天后自动清理，无需手动配置。

OpenClaw 后台任务指南：ACP/子Agent/Cron 任务追踪与排查 ​

如果找的是定时调度，请移步自动化与任务。本页说明追踪后台进行的工作，而不是如何调度。

后台任务追踪在主会话之外运行的工作：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 天后自动清理

快速上手 ​

列出和筛选

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

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

查看详情

```bash
# 显示某个任务的完整记录（支持 ID、run ID 或 session key）
openclaw tasks show <lookup>
```

取消和通知

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

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

审计和维护

```bash
# 运行健康检查
openclaw tasks audit

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

Task Flow 状态

```bash
openclaw tasks flow list
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>
```

哪些操作会创建任务 ​

来源运行时类型创建时机默认通知策略
ACP 后台运行acp派生子 ACP 会话done_only
子 Agent 编排subagent通过 sessions_spawn 派生子 Agentdone_only
Cron 任务（所有类型）cron每次 cron 执行（主会话和隔离）silent
CLI 操作cli通过 Gateway 运行的 openclaw agent 命令silent
Agent 媒体任务（图片/音乐/视频生成）cli会话支持的 image_generate / music_generate / video_generate 运行silent

cron 和媒体任务的默认通知

主会话 cron 任务默认 `silent` 策略——记录用于追踪但不生成通知。隔离 cron 任务同样默认 `silent`，但由于运行在自己的会话中，你更容易看到它们的进度。

会话支持的 `image_generate`、`music_generate`、`video_generate` 也默认 `silent`。完成后会唤醒原 Agent 会话，由 Agent 自己发送包含生成媒体的后续消息。如果需要生成媒体从 Agent 端直接投递到渠道，需启用 `tools.media.asyncCompletion.directSend`；若不启用则走会话内唤醒路径。

并发媒体生成的防护

当会话中已有一个媒体生成任务处于活跃状态，再次调用同类媒体工具（例如同一 `music_generate` 命令）不会启动第二个任务，而是返回当前任务的活跃状态。使用 `action: "status"` 可以从 Agent 侧显式查询进度。不同 prompt 的 `image_generate` 可以启动独立任务。

不创建任务的情况

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

任务生命周期 ​

任务状态流转：

queued → running → succeeded
                → failed
                → timed_out
                → cancelled
queued → lost（会话消失超过 5 分钟）
running → lost（会话消失超过 5 分钟）
状态含义
queued已创建，等待 Agent 开始
runningAgent 轮次正在执行
succeeded成功完成
failed出错完成
timed_out超过配置的超时时间
cancelled通过 openclaw tasks cancel 手动取消
lost运行时在 5 分钟宽限期后失去了任务的支持状态（子会话消失、cron 不再拥有作业、CLI run 上下文丢失等）

状态更新是自动的：当关联的 Agent 运行结束，任务状态同步更新。如果任务已经被取消或已进入更严格的终态（如 failed、timed_out、lost），后续的成功信号不会降级该状态。

lost 的判定因运行时类型而异：

  • ACP 任务：对应的 ACP 子会话元数据消失。
  • 子 Agent 任务：子会话从目标 Agent 存储中消失；如果有重启恢复墓碑（restart-recovery tombstone），也会被标记为 lost。
  • Cron 任务：cron 运行时不再追踪该作业为活跃状态，且持久化 cron 运行历史中没有该运行的终态记录。仅离线 CLI 审计不使用自己内存中的空作业集合作为权威依据；只有 Gateway 进程的内存 cron 活跃作业集才是权威的。离线 CLI 审计会先检查持久化历史，找到终态则回填，找不到才标记 lost。
  • CLI 任务：如果任务有 run id / source id，则检查实际 run 上下文；不再仅依赖子会话或聊天会话行。Gateway 支持的 openclaw agent 运行也从 run 结果终态化，不会一直处于活跃直到清理器标记 lost。

投递与通知 ​

任务到达终态时，OpenClaw 会通知你：有两条路径。

直接投递：如果任务有渠道目标（requesterOrigin），完成消息直接发送到该渠道（Telegram、Discord、Slack 等）。对于群组和频道中的任务完成，则通过请求方会话路由，由父 Agent 写出可见回复。子 Agent 完成时，如果绑定过线程/话题路由，会尽量保留；如果缺少 to / account，会从请求方会话的存储路由（lastChannel / lastTo / lastAccountId）填补后尝试直接投递。

会话队列投递：直接投递失败或未设置 origin 时，更新排队到请求方会话的系统事件，在下一次 heartbeat 时展示。

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

这意味着通常的交互是推送式的：发起一次分离工作，运行时在完成后唤醒或通知。轮询任务状态只在需要调试、干预或显式审计时进行。

通知策略 ​

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

运行时修改策略：

bash
openclaw tasks notify <lookup> state_changes

CLI 参考 ​

tasks list

```bash
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
```
输出列：Task ID、Kind、Status、Delivery、Run ID、Child Session、Summary。

tasks show

```bash
openclaw tasks show <lookup>
```
lookup 支持任务 ID、run ID 或 session key。显示完整记录，包含时间、投递状态、错误和终态摘要。

tasks cancel

```bash
openclaw tasks cancel <lookup>
```
对 ACP 和子 Agent 任务会终止子会话；对 CLI 追踪的任务，取消记录在任务注册表中（无独立子运行时句柄）。任务状态变为 `cancelled` 并发送投递通知。

tasks notify

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

tasks audit

```bash
openclaw tasks audit [--json]
```
暴露的操作问题也会出现在 `openclaw status` 中。

| 发现项 | 严重程度 | 触发条件 |
| --- | --- | --- |
| `stale_queued` | warn | 排队超过 10 分钟 |
| `stale_running` | error | 运行超过 30 分钟 |
| `lost` | warn/error | 运行时支持的任务所有权消失；保留的 lost 任务先警告，超出 `cleanupAfter` 后变为 error |
| `delivery_failed` | warn | 投递失败且通知策略非 `silent` |
| `missing_cleanup` | warn | 终态任务无清理时间戳 |
| `inconsistent_timestamps` | warn | 时间线违规（例如结束时间早于开始时间）|

tasks maintenance

```bash
openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
```
预览或应用协调、清理标记和修剪。协调是运行时感知的（如 ACP/子 Agent 检查子会话、cron 检查持久记录和运行时活跃集、CLI 任务检查 run 上下文）。应用维护还会清除超过 7 天的 `cron:<jobId>:run:&lt;uuid&gt;` 会话注册表行，保留仍在运行的 cron 作业行。

tasks flow list | show | cancel

```bash
openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
```
当你更关心编排层 Task Flow 而非单个后台任务时使用。

聊天任务板（/tasks） ​

在任何聊天会话中输入 /tasks 查看关联的后台任务。表格显示活跃和最近完成的任务，包含运行时、状态、时间和进度/错误详情。如果当前会话没有可见的关联任务，/tasks 会回退显示 Agent 本地任务计数，让你仍能获得概览而不泄露其他会话信息。

完整操作账本请用 CLI：openclaw tasks list。

状态集成（任务压力） ​

openclaw status 输出包含任务摘要：

Tasks: 3 queued · 2 running · 1 issues

摘要报告：

  • active：queued + running 的计数
  • failures：failed + timed_out + lost 的计数
  • byRuntime：按 acp、subagent、cron、cli 分类统计

/status 和 session_status 工具都使用感知清理的任务快照：优先显示活跃任务，隐藏陈旧的已完成行，近期失败仅在无活跃工作时才浮现。

存储与维护 ​

任务记录持久化在 SQLite 数据库中：

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

Gateway 启动时加载注册表到内存，同步写入 SQLite 确保重启后的持久性。Gateway 通过 SQLite 默认自动检查点阈值加上定期和关闭时的 TRUNCATE 检查点，限制预写日志大小。

自动清理器每 60 秒运行一次，处理四项任务：

  1. 协调：确认活跃任务是否仍有权威运行时支持。ACP/子 Agent 任务使用子会话状态，cron 任务检查活跃作业所有权，CLI 任务检查 run 上下文。如果支持状态消失超过 5 分钟，任务标记为 lost。
  2. ACP 会话修复：关闭终态或孤立的父拥有的一次性 ACP 会话；仅在无活跃会话绑定时才关闭陈旧的终态或孤立的持久 ACP 会话。
  3. 清理标记：为终态任务设置 cleanupAfter 时间戳（结束时间 + 7 天）。在保留期内，lost 任务在审计中显示为警告；cleanupAfter 过期后变为错误。
  4. 修剪：删除超过 cleanupAfter 日期的记录。

保留期：终态任务记录保留 7 天，然后自动修剪。无需额外配置。

如何与其他系统关联 ​

任务与 Task Flow

[Task Flow](/ai/ai-tools/openclaw/automation/taskflow) 是后台任务之上的流程编排层，一个流可以协调多个任务（managed/mirrored 同步模式）。用 `openclaw tasks` 检查单个任务记录，用 `openclaw tasks flow` 检查编排流。

任务与 Cron

cron 作业**定义**存储在 `~/.openclaw/cron/jobs.json`；运行时执行状态存储在 `~/.openclaw/cron/jobs-state.json`。**每次** cron 执行都会创建任务记录——包括主会话和隔离执行。主会话 cron 任务默认 `silent` 策略，只记录不生成通知。

参见[Cron Jobs](/ai/ai-tools/openclaw/automation/cron-jobs)。

任务与 Heartbeat

Heartbeat 运行是主会话轮次——不创建任务记录。任务完成时可触发 heartbeat 唤醒，让你快速看到结果。

参见[Heartbeat](/ai/ai-tools/openclaw/gateway/heartbeat)。

任务与 Session

每个任务可能引用 `childSessionKey`（工作运行的会话）和 `requesterSessionKey`（发起者的会话）。会话是对话上下文，任务是构建在会话之上的活动跟踪。

任务与 Agent Runs

任务的 `runId` 链接到实际执行工作的 Agent 运行。Agent 生命周期事件（开始、结束、错误）自动更新任务状态——无需手动管理。

相关文档 ​

常见问题 ​

为什么 openclaw tasks audit 报了很多 inconsistent_timestamps 警告？ ​

这通常是旧版 bug（#69229），startedAt 早于 createdAt 属于误报。执行 openclaw tasks maintenance --apply 可以修复损坏的时间戳记录，不影响实际任务结果。

任务完成后我在 Telegram 收不到通知，怎么排查？ ​

先用 openclaw tasks show &lt;id&gt; 检查通知策略是否为 done_only（不是 silent），再检查 requesterOrigin 是否记录了正确的 Telegram 渠道。如果为空白，说明任务创建时未绑定渠道，完成消息会走 heartbeat 队列而不是直接推送。

任务状态 lost 还能恢复吗？ ​

不能。lost 表示 5 分钟宽限期后运行时支持状态已消失，任务被永久标记为失去追踪。你需要重新发起任务。如果 ACP 或子 Agent 任务频繁出现 lost，请检查子会话是否被意外关闭或会话超时设置是否过短。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策