Task Watchdog

核心概念

Lock 文件是任务的外部状态载体，放于 ~/.openclaw/agents/{agent_id}/locks/：

• active/ — 正在执行的任务
• archive/YYYY-MM-DD/ — 归档（done / abandoned / timeout）

两个时间字段，职责不同：

last_heartbeat  — lock-self-check 更新（纯心跳维持，不说明任务有进展）
last_progress   — lock-update --progress 时更新（标记真实进展）

状态判断（用 last_progress，不看 last_heartbeat）：

✅ 正常      session 存在，last_progress 正常
⚠️ SESSION_DEAD  session 已消失
⚠️ STALLED      session 存在，但 last_progress 超 GRACE×3
⚠️ HEARTBEAT_DELAY  心跳延迟
🚫 abandoned  session 消失 + last_progress 超 GRACE×3
📦 done       任务完成，立即归档

脚本

推荐用法

关键节点调用：

任务开始 → lock-create
每个关键步骤完成 → lock-update --progress "X完成，开始Y"
任务全部完成 → lock-done

HEARTBEAT 触发时调用自检：

收到心跳轮询时
  → 调用 lock-self-check.sh
  → 自动完成：
      无活跃任务 → 无输出，agent 回复 HEARTBEAT_OK
      owner session 存活 → 只更新 last_heartbeat
      owner session 已死 → 接管任务（更新 session_id + last_heartbeat）
  → 无需判断逻辑，脚本自动处理

设计目标

任务续做保障系统，不是即时告警系统：

• 中断后 lock 留在 active/，Supervisor 扫描归档
• 自检机制让 agent 自动继续被中断的任务
• 定期报告让负责人知道哪些任务需要接管或放弃

常用命令

./lock-self-check.sh --agent-id xxx --session-id xxx   # HEARTBEAT 触发时调用
./lock-report.sh                                        # 查看所有活跃任务状态
./lock-archive.sh --list                              # 同上
./lock-archive.sh --archive-days 7                   # 归档7天前完成的任务
./lock-archive.sh --cleanup-days 30                   # 清理30天前的归档