task-ledger
Use Task Ledger to turn long-running agent work into durable task objects instead of relying on fragile chat context.
Task Ledger is a workflow layer on top of OpenClaw execution primitives.
It does not replace ACP, sub-agents, exec, cron, or skills.
It gives them a durable task structure:
- - checkpoint files in INLINECODE0
- execution logs in INLINECODE1
- artifacts and reports in INLINECODE2
- execution bindings for process/session/cron references
- parent/child task trees
- dependency and readiness checks
- recovery protocol
- short-first reporting
Trigger
Use this skill when any of these are true:
- - task runtime will likely exceed 5 minutes
- task has more than 3 stages
- task uses background INLINECODE3
- task uses INLINECODE4
- task uses INLINECODE5
- task has external side effects
- task involves restart / deploy / maintenance workflows with risky side effects
- task should be split into parent/child tasks or tracked with dependencies
- multiple agents or sub-agents will work in parallel
- task readiness should be checked before starting downstream work
- task reporting should prefer short updates backed by long file-based reports
- the user wants the work to be recoverable / resumable / auditable
Do not use this skill for every tiny action.
It is meant for work where losing state or execution structure would be costly.
What this skill provides
This package includes:
- - task checkpoint JSON files in INLINECODE6
- execution logs in INLINECODE7
- outputs/artifacts in INLINECODE8
- lifecycle helpers for create/update/advance/close
- recovery helpers for verify/resume-summary
- binding helpers for process/subtask/cron references
- rollback metadata in the task schema
- parent/child task relations and dependency-aware tooling
- readiness-aware scheduling helpers
- specialized templates for restart and deployment workflows
- human-friendly export for reports, handoff, archival, and graph views
- short-first reporting with optional file-backed long reports
Bundled files live next to this skill under toolkit/.
First-use bootstrap
If the current workspace does not already contain the toolkit, copy these bundled assets into the workspace root:
- -
toolkit/scripts/* → INLINECODE11 - INLINECODE12 → INLINECODE13
- INLINECODE14 → INLINECODE15
Always create the runtime directories if missing:
- - INLINECODE16
- INLINECODE17
- INLINECODE18
Do not overwrite user-modified files silently unless explicitly asked.
Prefer copying only missing files and then report what was installed.
Operating protocol
- 1. Confirm the plan with the user before execution.
- Create the task skeleton first.
- Choose explicit stages that match reality.
- Record execution references (
process.sessionId, subtask.sessionKey, cron.jobId) when they exist. - Link parent/child tasks and dependencies when the work is larger than a single task object.
- If work is parallelized, prefer one parent task plus one child task per worker.
- Check readiness before starting dependent tasks; use start-if-ready when appropriate.
- Update the task file after every completed stage.
- On recovery, read the resume summary and verify real state first.
- If reality and the checkpoint disagree, correct the checkpoint before continuing.
- Continue only the unfinished work.
- Prefer short user-facing summaries and keep long reports on file when appropriate.
- Export or summarize task state in a human-friendly form when needed.
- Proactively notify on completion.
- If execution was interrupted and later resumed/reconnected, proactively notify that too.
Parallel task pattern
For multi-agent or multi-sub-agent work:
- - create one parent task for the overall goal
- create one child task per worker / subtask branch
- bind each child task to its own execution reference
- keep detailed stage tracking on child tasks
- let the parent task orchestrate readiness, finalization, and reporting
Avoid treating one task JSON file as a shared concurrent write target.
Task trees are safer than shared state.
Core commands
Create a task skeleton:
CODEBLOCK0
Useful helpers:
CODEBLOCK1
Specialized templates
Use bundled examples for common risky workflows:
- - INLINECODE22
- INLINECODE23
- INLINECODE24
Practical rule
Task files are not truth.
They are cached descriptions of truth.
Reality wins.
task-ledger
使用 Task Ledger 将长时间运行的代理工作转化为持久化的任务对象,而非依赖脆弱的对话上下文。
Task Ledger 是构建在 OpenClaw 执行原语之上的工作流层。
它不替代 ACP、子代理、exec、cron 或技能。
它为这些功能提供了持久化的任务结构:
- - tasks/ 目录下的检查点文件
- logs/ 目录下的执行日志
- outputs/ 目录下的产物和报告
- 用于进程/会话/cron 引用的执行绑定
- 父/子任务树
- 依赖与就绪检查
- 恢复协议
- 短优先报告
触发条件
当以下任一条件成立时,使用此技能:
- - 任务运行时间可能超过 5 分钟
- 任务包含 3 个以上阶段
- 任务使用后台 exec
- 任务使用 sessions_spawn
- 任务使用 cron
- 任务具有外部副作用
- 任务涉及重启/部署/维护等具有风险副作用的工作流
- 任务应拆分为父/子任务或通过依赖关系进行跟踪
- 多个代理或子代理将并行工作
- 在启动下游工作前应检查任务就绪状态
- 任务报告应优先提供简短更新,辅以基于文件的详细报告
- 用户希望工作可恢复/可续接/可审计
不要对每个微小操作都使用此技能。
它适用于状态丢失或执行结构丢失代价高昂的工作。
此技能提供的内容
本包包含:
- - tasks/ 目录下的任务检查点 JSON 文件
- logs/ 目录下的执行日志
- outputs/ 目录下的输出/产物
- 用于创建/更新/推进/关闭的生命周期辅助工具
- 用于验证/恢复摘要的恢复辅助工具
- 用于进程/子任务/cron 引用的绑定辅助工具
- 任务模式中的回滚元数据
- 父/子任务关系及依赖感知工具
- 就绪感知调度辅助工具
- 重启和部署工作流的专用模板
- 面向报告、交接、归档和图视图的友好导出
- 短优先报告,可选基于文件的详细报告
捆绑文件位于此技能旁边的 toolkit/ 目录下。
首次使用引导
如果当前工作空间尚未包含工具包,请将这些捆绑资源复制到工作空间根目录:
- - toolkit/scripts/ → /scripts/
- toolkit/task-templates/ → /task-templates/
- toolkit/tasks/README.md → /tasks/README.md
如果运行时目录不存在,请始终创建:
除非明确要求,否则不要静默覆盖用户修改过的文件。
优先仅复制缺失的文件,然后报告已安装的内容。
操作协议
- 1. 在执行前与用户确认计划。
- 首先创建任务骨架。
- 选择与实际情况匹配的明确阶段。
- 记录执行引用(process.sessionId、subtask.sessionKey、cron.jobId)。
- 当工作规模超过单个任务对象时,链接父/子任务和依赖关系。
- 如果工作并行化,优先采用一个父任务加每个工作者一个子任务的模式。
- 在启动依赖任务前检查就绪状态;适当时使用 start-if-ready。
- 每个阶段完成后更新任务文件。
- 恢复时,先读取恢复摘要并验证实际状态。
- 如果实际情况与检查点不一致,先修正检查点再继续。
- 仅继续未完成的工作。
- 优先提供面向用户的简短摘要,适当时将详细报告保留在文件中。
- 需要时以友好形式导出或总结任务状态。
- 主动通知完成情况。
- 如果执行被中断后恢复/重新连接,也主动通知。
并行任务模式
对于多代理或多子代理工作:
- - 为总体目标创建一个父任务
- 为每个工作者/子任务分支创建一个子任务
- 将每个子任务绑定到其自己的执行引用
- 在子任务上保留详细的阶段跟踪
- 让父任务协调就绪、完成和报告
避免将单个任务 JSON 文件作为共享并发写入目标。
任务树比共享状态更安全。
核心命令
创建任务骨架:
bash
./scripts/new-task.sh [goal] [executionMode] [stagesCsv] [priority] [owner]
有用的辅助工具:
bash
./scripts/list-open-tasks.py
python3 ./scripts/task-ls-tree.py
python3 ./scripts/task-ready.py [--json]
python3 ./scripts/task-start-if-ready.py [nextAction]
python3 ./scripts/task-graph-export.py [--format markdown|dot|json] [--open-only]
./scripts/show-task.py
./scripts/task-events.py [limit] [--type ] [--json]
./scripts/update-task.py ...
./scripts/task-advance.py [nextAction]
./scripts/task-bind-process.py [pid] [--state ]
./scripts/task-bind-subtask.py [--agent-id ]
./scripts/task-bind-cron.py [--schedule ] [--next-run-at ]
./scripts/task-verify.py ...
./scripts/task-resume-summary.py [--json|--markdown]
./scripts/task-export.py [--format markdown|json|short] [--write-report]
./scripts/close-task.py [summary]
./scripts/task-doctor.py [taskId] [--strict] [--json]
专用模板
使用捆绑的示例处理常见的高风险工作流:
- - restart-openclaw-gateway.example.json
- deploy-service.example.json
- sync-feishu-doc.example.json
实用规则
任务文件并非真相。
它们是对真相的缓存描述。
现实优先。