当你的 AI Agent 任务从演示时的 5 分钟脚本升级为持续 5 天的生产级作业时，断点续跑能力就成了生死线。本文将基于 OpenClaw WorkBuddy 的实际案例，拆解多步工具管线中常被忽视的状态可恢复性设计。

为什么你的 Agent 一断就废？

多数开发者首次构建工具调用管线时，会自然地写出线性执行脚本：

def run_pipeline():
    step1()  # 数据抓取
    step2()  # 清洗转换
    step3()  # 模型推理

这种结构在演示环境运行良好，但面临真实场景的四大挑战： 1. 网络抖动导致步骤 2 失败后，必须从步骤 1 重新执行 2. 人工审批介入步骤 3 时，前两步的中间状态已丢失 3. 无法区分「从未执行」和「执行失败」两种状态 4. 资源密集型步骤重复执行造成成本飙升

状态机设计的三个工程锚点

1. 幂等性与 Artifact 路径契约

每个步骤需要明确： - 输入槽：依赖上一步哪些输出文件/变量（如 step2_input = "/artifacts/step1_output.json"） - 输出槽：固定写入路径（如 step2_output = "/artifacts/step2_processed.parquet"） - 完成标记：原子性写入完成状态（推荐 SQLite 或 _SUCCESS 空文件）

OpenClaw 的 Canvas 工作台通过路径模板变量实现跨步骤引用：

steps:
  - name: data_fetch
    outputs:
      - "{{.ArtifactsDir}}/raw_{{.TaskID}}.json"
  - name: data_clean
    inputs:
      - "{{steps.data_fetch.outputs[0]}}"

2. 人类审批的超时熔断

对于需要人工确认的步骤（如数据标注复核），必须设置： - 审批超时（默认 24h）后自动转人工工单 - 上下文快照保存触发时的输入/输出快照 - 续跑上下文注入接口（ClawBridge 的 /v1/resume 端点）

实际案例：某电商风控 Agent 在标注环节超时后，通过 Slack 发送如下结构化消息：

[Action Required] 任务 T-3827 等待审核
超时剩余: 2h 
快照链接: s3://audit-logs/T-3827/ctx.json
可选操作:
- /approve T-3827
- /reject T-3827 "理由"
- /extend T-3827 4h

3. 可观测性埋点矩阵

在 ClawSDK 中内置的四类埋点：

指标类型	采集频率	可视化示例	告警阈值
步骤耗时	每步骤完成	火焰图	>同类步骤平均耗时 3σ
资源消耗(CPU/Mem)	10s/次	堆叠面积图	>预设配额 80%
状态机转换	实时	状态转换图	停滞任一状态>1h
工具调用次数	聚合上报	日历热力图	RateLimit 触发预警

通过 clawctl observability 生成的 Prometheus 配置片段：

- name: agent_steps
  rules:
  - record: step_duration_seconds:rate5m
    expr: avg(rate(agent_step_duration_seconds[5m])) by(step_name)
  - alert: StepStalled
    expr: agent_step_state_duration_seconds > 3600
    annotations:
      severity: critical

混沌测试：你的恢复方案真的有效吗？

模拟以下故障场景验证状态机健壮性： 1. 暴力杀进程：在步骤执行中途 kill -9，检查是否能从最近完步骤恢复 2. 磁盘写满：在输出 artifact 时触发 ENOSPC 错误 3. 网络隔离：使用 iptables 随机丢弃 50% 出站流量 4. 时钟回拨：修改系统时间测试时序敏感逻辑

实测案例：某物流路径规划 Agent 在模拟 72h 网络抖动后： - 原始线性脚本：平均需要 18.7 次全流程重试 - 状态机版本：仅重试中断步骤，成功率 92.3%

延伸设计：成本与可靠性权衡

长任务执行往往需要在重试策略和资源成本之间取得平衡： 1. 指数退避重试：对于暂时性故障（如 API 限流），采用 min(2^retry_count * 200ms, 10s) 的延迟策略 2. 资源回收机制：当任务暂停超过阈值（如 6h），自动释放占用的 GPU 实例 3. 检查点快照：每小时将内存状态持久化到磁盘，避免重复计算

典型案例对比： - 无快照方案：处理 50GB 数据时崩溃，需从头开始消耗 32 vCPU·h - 快照方案：每小时保存中间状态，崩溃后仅损失最近 1h 计算量

从设计到部署的检查清单

1. [ ] 所有步骤声明了输入/输出路径契约
2. [ ] 完成状态写入与检查是原子操作
3. [ ] 审批环节有超时回退流程
4. [ ] 关键指标接入监控系统
5. [ ] 混沌测试覆盖主流故障模式
6. [ ] 重试策略与资源回收阈值已文档化
7. [ ] 检查点间隔与业务 SLA 匹配

下次当你听到「我的 Agent 跑了一周然后崩了」时，不妨问这三个问题： - 状态机图是画给 IDE 看的还是给 on-call 工程师看的？ - 断点续跑是否考虑了审批流程的异步性？ - 监控面板能否区分「正在运行」和「已经卡死」？

实战建议： 1. 使用 clawctl task inspect <TASK_ID> 命令实时查看状态机拓扑 2. 通过 claw-logger --structured 输出符合 OpenTelemetry 规范的日志 3. 在 CI 流水线中加入 claw-chaos --scenario=network_partition 自动化测试

附：本文所述方案已在 ClawHub 的 v0.7.3+ 版本实现，相关讨论见 GitHub 的 #471 号提案。