为什么需要专门的监控姿势

sessions_spawn 把任务交给隐藏子代理后，最容易犯两个错：

  1. 疯狂轮询：每隔几秒调一次 subagents(action=list)，既烧 token 又没意义——子代理跑完会主动推送结果回来，你不用问。
  1. 误以为要自己收尾：子代理的结果回来时，OpenClaw 会通知你，而不是等你来取。

subagents 工具就是给"已派出去的活"做轻量治理的：列状态、取消卡死的。

subagents 的两个动作

| 动作 | 用途 |

|------|------|

| list | 看当前所有后台子代理/媒体生成/自动化任务的状态 |

| cancel | 取消某个卡死或不再需要的任务（按 taskId） |

list：按需看，不定时刷

subagents({ action: "list" })

返回每个任务的状态（running / completed / failed）、类型、启动时间。你只在需要时查——比如用户来问"那个活怎么样了"，或者你怀疑它卡住了。

不要写成 cron 每 30 秒查一次：子代理完成时会主动通知，轮询是冗余的。

cancel：卡死了再动手

subagents({ action: "cancel", taskId: "abc123" })

适用于：子代理长时间无输出、明显卡死、或者你改了主意不需要结果了。取消后资源释放，不影响主会话。

和 sessions 工具的区别

| 工具 | 看什么 |

|------|------|

| subagents | 后台子代理、媒体生成、自动化运行（轻量状态） |

| sessions_list | 可见会话/分组（侧边栏级别的会话） |

| sessions_history | 某个历史会话的完整对话内容 |

简单说：subagents 管"后台在跑的活"，sessions_* 管"对话会话"。派活之后盯进度用 subagents，翻历史聊天用 sessions_history。

关键行为（必须知道）

  1. 完成后主动通知：子代理跑完会把结果推回主会话，不需要你 yield 或轮询等待。
  1. list 是只读轻量操作：随时能查，但别设成高频定时任务。
  1. cancel 不可逆：取消后任务终止，想重跑得重新 sessions_spawn。
  1. 隐藏子代理自动归档：你 spawn 时没标 visible:true 的，结束后自动进归档，不占侧边栏。

标准工作流

  1. 派活：sessions_spawn({task, visible:true/false}) 把大活丢出去。
  1. 继续干别的：主会话不被阻塞，你可以回用户、做别的事。
  1. 需要时查状态：用户问起或怀疑卡死 → subagents({action:"list"})。
  1. 结果回来：自动通知，读结果、交付。
  1. 卡死才 cancel：确认无进展 → subagents({action:"cancel", taskId})。

踩坑与反模式

  • ❌ 轮询 list 等结果：子代理会主动通知，定时刷是浪费。
  • ❌ 把 subagents 当 sessions_history 用：前者看后台任务，后者看对话内容，别混。
  • ❌ 该 cancel 时不 cancel：明显卡死的任务占着资源，果断 cancel 重派。
  • ✅ 大活丢后台 + 等通知：主会话保持响应，结果到了再处理。

一句话总结

sessions_spawn 派活，subagents 只在"用户问起/怀疑卡死"时 list 一眼，跑完主动通知你——别轮询，该 cancel 时别手软。

扫码关注公众号，获取更多 OpenClaw 实操技巧：

公众号二维码