oclaw/skills/_workspace/public/background-jobs/SKILL.md

name	description
background-jobs	长时间任务（数分钟到数小时）用 start_job/get_job；同轮不要干等；断线后任务可继续，靠 job_id 恢复或 notify 通知。

后台长任务 — Background Jobs

核心事实

1. 同轮等不了两小时（也不该等）。sleep 最多 120 秒。
2. start_job 立刻返回 job_id；agent 断线 / 本轮结束，进程仍可继续跑（gateway 进程在的前提下）。
3. 正确姿势是 交作业 → 告知用户 job_id → 结束本轮；以后再查，或靠完成通知。

推荐流程（1–2 小时任务）

1. write_file 写自包含脚本（输入/输出路径写死）
2. start_job(command=..., timeout_s=7200, name=..., notify={...可选})
3. 回复用户：已提交后台任务，job_id=...，跑完会通知 / 请稍后问「查任务 job_xxx」
4. 结束本轮（不要 sleep 循环两小时）
5. 之后任意一轮：get_job(job_id) 或 list_jobs → 读产出 → 需要时 save_deliverable_attachment

断线后会怎样

情况	行为
本轮对话结束 / 用户离开	任务继续；磁盘有 data/jobs/<job_id>/
用户过一会再问	get_job / list_jobs 恢复状态
Gateway 重启但子进程还在	后台 reaper（约 15s）按超时/pid 对账回收；Chat 徽章也会刷新
Gateway 整机挂掉	子进程可能被系统清掉；下次 reaper/get_job 标失败/超时

notify（可选，推荐渠道场景）

start_job 可带：

"notify": {
  "channel": "whatsapp",
  "chat_id": "<群或会话 id>",
  "account_id": "wa-default",
  "message": "可选自定义文案"
}

任务结束（成功/失败/超时/取消）后会往该渠道塞一条出站提醒（含 job_id）。
微信需额外 context_token（与现有 weixin 出站一致）。

WebChat：没有渠道 notify 时，靠用户稍后再问 + list_jobs。

工具

工具	作用
start_job	后台启动，返回 job_id（默认 2h，最大 3h）
get_job	查状态与日志尾；done=true 表示结束
list_jobs	近期任务
cancel_job	取消
sleep	仅短轮询间隙（≤120s），不是长等

与 run_command 同一开关：AIA_ENABLE_RUN_COMMAND。

Chat 可视化

Chat 左侧导航底部 「后台任务」（用户区上方）右侧数字徽章持续显示运行中数量（约每 4 秒刷新，无需点开面板）；用户菜单也有入口：

• 有任务时按钮高亮，右侧数字徽章变红
• 点开后可：列表 / 终止 / 全部终止 / 清除记录 / 日志
• 面板打开时约每 4 秒自动刷新列表

不要做

• 同轮 sleep/get_job 死循环拖两小时
• 用 run_command 跑多小时脚本
• 不告诉用户 job_id 就结束（断线后难找回，除非用户记得或去 Chat「后台任务」/ list_jobs）