在长周期任务、易中断网络环境或需要严格可追溯的自动化流程里，“跑到一半断了”几乎是必然会遇到的情况。对 OpenClaw 这类面向实战的执行框架而言，断点续跑与恢复不只是“存个进度条”，而是一套涵盖：检查点（Checkpoint）、状态持久化（State Persistence）、回滚（Rollback）与幂等（Idempotency）的工程化方案。

本文作为《OpenClaw教程：从入门到实战的分层学习路线》系列中的实战篇，聚焦如何把“可恢复”能力落地到你的 OpenClaw 任务里：中断后能继续、错误后能回退、重复执行不会造成脏数据，并且能定位到是哪一步、用的什么输入、产生了什么输出。

为什么要做断点续跑：先把失败当常态

常见中断/失败来源：

• 进程退出：部署重启、容器 OOM、机器断电。
• 外部依赖不稳定：第三方接口 5xx、超时、限流。
• 数据规模大：任务需要运行数小时/数天，中途不可避免会被打断。
• 逻辑错误或数据脏：某条数据异常导致流程整体失败。

如果没有断点续跑，你通常只能：

1. 从头再跑（成本极高）；
2. 手动改数据、跳步骤（不可审计、不可复现）；
3. 在“可能成功/可能重复”之间赌运气（重复扣费/重复写入）。

断点续跑的目标应明确：

• 恢复后继续推进：已经成功的步骤不再重复执行。
• 保证一致性：失败不会留下半完成状态。
• 可观测可审计：知道每一步是否执行、何时执行、输入输出是什么。

核心概念：检查点、状态与回滚分别解决什么

检查点（Checkpoint）：记录“跑到哪一步了”

检查点是流程级别的“位置记录”，典型记录内容包括：

• 当前阶段/步骤 ID（例如 step=fetch_page）
• 已完成的项（例如已处理到第 320 条）
• 关键参数（输入数据版本、运行配置摘要）

检查点最常见的误区是只记录“第 N 步”，但不记录输入版本/配置，导致恢复后使用了不同输入，出现不可追溯。

状态持久化（State Persistence）：记录“我已经做了什么”和“结果是什么”

状态不仅是位置，还包括：

• 每个 item 的处理状态：pending/running/success/failed/skipped
• 成功产物引用：输出文件路径、对象存储 key、数据库主键
• 重试次数、最后一次错误栈、最后一次请求响应摘要

它解决的问题是：同一步骤内批量处理时，断在中间也能知道哪些 item 已完成。

回滚（Rollback）：记录“如果失败如何撤销”

回滚解决“半完成”问题。例如：

• 写数据库成功了一半
• 已经创建了远端资源，但后续失败

回滚并不总是必须“反向删除”，更现实的是：

• 补偿事务（Compensation）：写入一条反向记录、标记失效
• 版本化写入：新版本不覆盖旧版本，失败只需不切换“指针”

设计原则：让恢复简单、让回滚可靠

1）把步骤做成幂等：重复执行也不产生副作用

幂等策略清单：

• 对外部写入使用唯一幂等键（例如 request_id = job_id + item_id + step_name）
• 写数据库用 UPSERT 或“先查再写 + 唯一索引”
• 文件输出使用“临时文件 + 原子 rename”
• 远端创建资源使用“查重/幂等创建接口”或自己维护映射表

经验：如果你只能做一件事，请先做幂等。因为幂等能把“恢复”从复杂事务，降级为“放心重跑”。

2）检查点粒度：不要太粗，也不要太碎

• 太粗：一批 1 万条数据，成功 9000 条后中断，恢复仍要重跑 9000 条
• 太碎：每条数据都写一次 checkpoint，存储/IO 开销大，性能下降

推荐做法：

• 批处理时每处理 N 条 或每隔 T 秒 刷新一次 checkpoint（例如 N=100，T=10s）
• 每个 item 的结果写入状态表（或状态文件），checkpoint 只记录“进度游标”

3）状态数据结构：能对齐“步骤 + item + 产物”

至少要能回答：

• 某个 item 在某一步是否成功？
• 成功的输出是什么？（可复用）
• 失败原因是什么？还能否重试？

4）恢复策略：先校验，再继续

恢复时不要立刻继续跑，应先做：

• 配置一致性校验：本次运行配置 hash 是否与上次一致（或明确允许差异）
• 输入数据版本校验：数据源版本/快照 ID 是否一致
• 产物存在性校验：已记录的输出文件/对象存储 key 是否仍存在

校验不过：

• 要么拒绝继续（强一致）
• 要么进入“修复模式”（重新生成缺失产物，或回滚到上一个稳定点）

实操方案一：用本地文件实现轻量级断点续跑（适合单机/小任务）

下面给一个可直接落地的“文件型检查点 + 状态清单”设计。你可以把它嵌入 OpenClaw 的任务执行结构中（例如每个 step 执行前后写入）。

目录结构建议

• runs/<job_id>/meta.json：运行元信息（配置 hash、创建时间、输入版本）
• runs/<job_id>/checkpoint.json：检查点（当前 step、游标等）
• runs/<job_id>/state.ndjson：逐行追加的 item 状态日志（NDJSON）
• runs/<job_id>/artifacts/：产物目录（中间文件、缓存）

这种结构的优点是：

• 容易人肉排查
• 追加写日志成本低
• 崩溃时也能最大概率保留已写入的行

checkpoint.json 示例

建议字段：

• job_id：本次运行唯一 ID
• step：当前步骤名
• cursor：游标（如处理到第几条、分页 token）
• updated_at：最后更新时间
• config_hash：运行配置摘要
• input_version：输入版本（如日期分区、快照号、git commit）

state.ndjson 行级示例

每处理一个 item，就追加一行：

• item_id
• step
• status：success/failed/skipped
• attempt
• output_ref：输出引用（文件路径、对象 key、主键）
• error：失败原因摘要
• ts

写入策略：追加日志 + 定期刷 checkpoint

建议：

1. item 级别结果写 state.ndjson（追加写）
2. 每处理 100 条或每 10 秒更新一次 checkpoint.json
3. 每个 step 完成时强制 flush 一次 checkpoint

恢复流程（本地文件版）

1. 读取 meta.json 校验 config_hash 与 input_version
2. 读取 checkpoint.json 获取 step 与 cursor
3. 扫描/索引 state.ndjson，建立 item_id -> 已完成步骤 的集合（可在首次启动时生成 state_index.json 缓存）

4. 从 checkpoint 指定位置继续：

   • 对已经成功的 item：直接跳过（或复用 output_ref）
   • 对 failed 的 item：按策略重试（比如最多 3 次）

建议：恢复时先进入 dry-run 模式打印“将要跳过多少、重试多少、从哪里继续”，确认后再正式跑。

实操方案二：用数据库/Redis实现可并发的断点续跑（适合生产/多进程）

当你需要并发处理、分布式 worker 或更强的查询能力时，状态存储最好进入数据库。

表设计建议：job / step / item_state

1）job 表（作业级）

• job_id（主键）
• status：running/success/failed/canceled
• config_hash
• input_version
• created_at/updated_at

2）step 表（步骤级）

• job_id
• step_name
• status
• checkpoint_cursor（JSON 或文本）
• updated_at

3）item_state 表（条目级）

• job_id
• step_name
• item_id
• status
• attempt
• output_ref（JSON）
• error_code/error_message
• updated_at

并发时的关键点：

• 用唯一约束：(job_id, step_name, item_id)，保证幂等写入
• worker 领任务用“原子更新”方式锁定（例如将 pending 改成 running 并返回行）

领任务与重试的建议策略

• 指数退避重试：第 1 次等 1s，第 2 次 2s，第 3 次 4s
• 对可重试错误（超时/限流）与不可重试错误（参数非法）区分处理
• 达到最大重试次数后标记为 failed_final，避免无限循环

恢复时怎么做

恢复不再依赖扫描日志：

1. 查 job 是否存在且 config/input 校验通过
2. 查 step 的 checkpoint_cursor

3. 直接查询 item_state：

   • success：跳过
   • failed 且 attempt < max：加入重试队列
   • running：判断是否“僵死”（超时未更新），必要时回收为 pending

回滚策略：三种常用做法与适用场景

1）基于“补偿动作”的回滚（最通用）

做法：每个会产生副作用的 step，都定义一个对应的 compensate 操作。

示例：

• step：创建订单 -> compensate：取消订单
• step：写入积分 -> compensate：写入负积分抵消

落地建议：

• 将补偿动作也写入状态，确保补偿本身可重试
• 补偿失败要可观测（告警/人工介入队列）

2）版本化写入 + 指针切换（数据类任务非常好用）

适用：生成报表、导出文件、生成索引等。

做法：

• 新产物写到 artifact_v2
• 完全成功后更新“当前版本指针”到 v2
• 失败则不切换指针，相当于自动回滚

优点：

• 回滚几乎零成本
• 线上读取始终指向稳定版本

3）两阶段提交（复杂但强一致）

适用：跨多个资源写入且一致性要求极高。

做法：

• prepare：写入临时状态/锁定资源
• commit：全部成功后统一提交
• abort：任一失败则释放锁/删除临时数据

实践建议：除非你确实需要强一致，否则优先用“补偿”或“版本化”。

把断点续跑落到 OpenClaw 任务：推荐的“步骤模板”

你可以把每个 step 统一成如下执行模板（无论你用文件还是数据库存储）：

Step 执行前

1. 读取并校验 job/meta（config_hash、input_version）
2. 加载 checkpoint（step、cursor）
3. 构建本 step 需要的 item 列表（或分页游标）

处理循环（批量/分页）

对每个 item：

1. 查询 item_state 是否 success：是则跳过
2. 标记 running（可选，用于并发与观测）
3. 执行业务逻辑，产出 output_ref
4. 标记 success 并记录 output_ref
5. 定期刷新 checkpoint（cursor 前移）

异常处理：

• 捕获异常 -> 写 failed + error 摘要
• 若可重试：按策略重试
• 若不可重试：标记 failed_final，继续下一个 item（不要让单条数据拖死全局）

Step 完成后

1. 强制刷新 checkpoint 到“step 完成态”
2. 写 step 状态 success
3. 可选：产出本 step 的汇总指标（成功数、失败数、耗时）

常见坑与排障清单（非常实用）

坑 1：恢复后重复写入导致脏数据

排查与修复：

• 是否缺少幂等键？
• 数据库是否缺唯一索引？
• 文件写入是否用了临时文件 + 原子替换？

坑 2：checkpoint 更新太频繁导致性能雪崩

建议：

• item 状态用追加写（NDJSON）或批量 upsert
• checkpoint 降频（按 N 条/按 T 秒）
• 使用异步写入队列（但要保证崩溃时不丢关键状态）

坑 3：running 状态“僵死”，恢复后卡住

建议：

• running 记录心跳时间 updated_at
• 恢复时将超过阈值（例如 10 分钟未更新）的 running 回收为 pending

坑 4：配置变了但仍然续跑，结果不可复现

建议：

• 强制记录 config_hash
• 恢复时默认拒绝不同 hash 的续跑，除非显式指定 --force

坑 5：回滚没做，失败后留下半成品

建议：

• 对“外部可见”的副作用（对用户可见数据、扣费、发货）必须有补偿或版本化
• 把补偿也当成 step，写入状态并可重试

一套可直接照抄的最小落地清单

如果你希望在 1 天内把“OpenClaw 断点续跑与恢复”做出来，可以按以下顺序实施：

1. 定义 job_id：每次运行生成唯一 job_id（时间 + 随机 + 输入摘要）
2. 记录 meta：写入 config_hash、input_version、启动时间
3. 实现 item_state：至少记录 success/failed、attempt、output_ref
4. 实现 checkpoint：记录 step + cursor，支持定期刷新
5. 实现恢复入口：启动时检测是否存在 job_id 的状态，允许 --resume
6. 补齐幂等：为对外写入加唯一约束/幂等键
7. 加回滚或版本化：选择一种适合你业务的策略
8. 加可观测：输出汇总指标与错误样本（前 10 条失败原因）

做到第 1~5 条，你就能实现“断了能接着跑”；做到第 6~8 条，才算“生产可用、可审计、可回退”。

小结

OpenClaw 的断点续跑不是单点功能，而是一个组合拳：

• 用 Checkpoint 解决“跑到哪”
• 用 State Persistence 解决“做过什么、结果是什么”
• 用 幂等 解决“重复跑也不怕”
• 用 回滚/版本化 解决“失败不留半成品”

下一步你可以把本文的模板应用到你当前的 OpenClaw 实战任务里：先从文件型方案起步，稳定后再迁移到数据库型方案，以支持更高并发与更强审计能力。