OpenClaw ACP Harness 系列 06:TaskFlow——让长任务跨会话持续运行

AI 会话有上下文限制，复杂任务做到一半可能被打断。TaskFlow 是 OpenClaw 的任务持久化系统，让任务状态跨越会话边界继续存活。

一、为什么需要 TaskFlow？

普通会话的问题：

场景：让 AI 处理100份文档，每份需要3分钟
问题：
  - 上下文窗口会满（20万 token 左右）
  - 中途可能被打断
  - 打断后无法知道处理到第几份
  - 无法向用户报告进度

TaskFlow 的解法：
  - 为整个批处理任务创建一个 flow_id
  - 记录当前步骤（step 12/100）
  - 支持暂停/恢复
  - 完成后统一通知用户

二、TaskFlow 核心 API

// 通过 Skill 引导 AI 使用 TaskFlow
// 实际调用由 OpenClaw 运行时处理

// 1. 创建托管流程
api.runtime.tasks.flow.createManaged({
title: "处理100份合同文档",
sessionKey: currentSessionKey,
stateJson: JSON.stringify({ total: 100, processed: 0 })
})

// 2. 运行子任务
api.runtime.tasks.flow.runTask(flowId, {
title: "处理第1-10份文档",
fn: async () => { /* 处理逻辑 */ }
})

// 3. 需要等待时挂起（如等待用户确认）
api.runtime.tasks.flow.setWaiting(flowId, {
reason: "等待用户确认批次2的处理方式",
waitJson: JSON.stringify({ batch: 2 })
})

// 4. 用户回复后恢复
api.runtime.tasks.flow.resume(flowId)

// 5. 完成
api.runtime.tasks.flow.finish(flowId, {
summary: "成功处理100份文档，耗时45分钟"
})

三、典型使用场景

场景一：批量文件处理

任务：把100篇英文技术文章翻译成中文
流程：
  1. createManaged（创建翻译任务）
  2. 循环 runTask（每次处理10篇）
  3. 每批次结束更新 stateJson（记录进度）
  4. 全部完成后 finish（通知用户）

优势：
  - 即使会话中断，重启后可以从第30篇继续
  - 用户可以随时查询进度

场景二：需要人工确认的流程

任务：自动整理代码库，但关键删除需要确认
流程：
  1. 分析代码库
  2. 找到可以删除的文件
  3. setWaiting（向用户展示删除列表，等待确认）
  4. 用户回复"确认"
  5. resume → 执行删除
  6. finish

场景三：等待外部系统响应

任务：提交部署请求，等待 CI/CD 完成
流程：
  1. 提交 PR
  2. setWaiting（等待 CI 完成）
  3. Cron 定时检查 CI 状态
  4. CI 完成 → resume
  5. 通知用户部署结果

四、TaskFlow vs Subagent 选择

经验法则： 任务可以30分钟内完成 → 用 Subagent；需要跨天或需要人工干预 → 用 TaskFlow。

五、状态持久化

TaskFlow 的状态通过 stateJson 持久化：

// 一个文档处理任务的 stateJson 示例
{
"total": 100,
"processed": 45,
"failed": [12, 38],
"currentBatch": 5,
"outputDir": "/tmp/translated/",
"startTime": 1713661234
}

即使进程重启，OpenClaw 也能从数据库中恢复这个状态，从第46份文档继续处理。

下一篇：多平台集成——飞书/Discord/Telegram 接入实战