OpenClaw 重磅重构：Flow 更名为 Task-flow 的完整迁移指南

OpenClaw 正在进行一项重大重构：将原有的 “Flow” 系统全面更名为 “Task-flow”。这项变更涉及命名空间、API、工具调用等多个层面，本文将提供完整的迁移指南。

为什么更名为 Task-flow

命名更清晰

Flow 这个词在编程领域含义模糊，可能指：

工作流（Workflow）
数据流（Data Flow）
控制流（Control Flow）
异步流（Async Stream）

Task-flow 明确表达了 “任务流” 的概念：

以任务为核心单元
强调执行流程
与 OpenClaw 的任务系统概念一致

架构一致性

OpenClaw 的核心概念体系：

Task（任务）→ Task-flow（任务流）→ Pipeline（管道）

更名为 Task-flow 后，概念层次更加清晰。

变更范围总览

1. 模块重命名

• 旧路径：flow/tooling；新路径：task-flow/tooling
• 旧路径：flow/registry；新路径：task-flow/registry
• 旧路径：flow/runtime；新路径：task-flow/runtime

2. API 变更

旧 API（已废弃）:

import { FlowTool } from '@openclaw/flow-tooling';
import { FlowRegistry } from '@openclaw/flow-registry';

新 API:

import { TaskFlowTool } from '@openclaw/task-flow/tooling';
import { TaskFlowRegistry } from '@openclaw/task-flow/registry';

3. 工具调用变更

• 旧工具名：flow_tool；新工具名：task_flow_tool
• 旧工具名：flow_execute；新工具名：task_flow_execute
• 旧工具名：flow_create；新工具名：task_flow_create

4. 配置变更

旧配置:

flow:
  enabled: true
  registry: flow-registry

新配置:

task_flow:
  enabled: true
  registry: task-flow-registry

迁移步骤详解

步骤 1: 更新导入路径

批量替换命令:

在项目根目录执行
find . -type f -name ".ts" -o -name ".js" | xargs sed -i \
  -e 's/@openclaw\/flow-tooling/@openclaw\/task-flow\/tooling/g' \
  -e 's/@openclaw\/flow-registry/@openclaw\/task-flow\/registry/g' \
  -e 's/FlowTool/TaskFlowTool/g' \
  -e 's/FlowRegistry/TaskFlowRegistry/g'

步骤 2: 更新配置文件

config.yaml

旧配置（删除）
flow:
  enabled: true

新配置
task_flow:
  enabled: true
  tooling:
    default_executor: "builtin"
  registry:
    auto_register: true
    modules:
      - "task-flow-core"
      - "task-flow-plugin"

步骤 3: 更新插件代码

ACP 插件更新示例:

// 更新前
import { useFlowRuntime } from '@openclaw/flow-runtime';

export class MyPlugin {
  async execute() {
    const flow = await useFlowRuntime();
    await flow.execute('my-flow');
  }
}

// 更新后
import { useTaskFlowRuntime } from '@openclaw/task-flow/runtime';

export class MyPlugin {
  async execute() {
    const taskFlow = await useTaskFlowRuntime();
    await taskFlow.execute('my-task-flow');
  }
}

Plugin SDK 更新:

// 更新前
import { FlowConsumer } from '@openclaw/plugin-sdk/flow';

// 更新后
import { TaskFlowConsumer } from '@openclaw/plugin-sdk/task-flow';

步骤 4: 更新运行时调用

// 更新前
await runtime.call('flow', {
  action: 'create',
  params: { name: 'my-flow' }
});

// 更新后
await runtime.call('task-flow', {
  action: 'create',
  params: { name: 'my-task-flow' }
});

代码示例对比

示例 1: 创建任务流

旧代码:

import { FlowFactory } from '@openclaw/flow-tooling';

const flow = FlowFactory.create({
  name: 'data-processing',
  steps: [
    { id: 'step1', action: 'fetch' },
    { id: 'step2', action: 'transform' },
    { id: 'step3', action: 'save' }
  ]
});

await flow.execute();

新代码:

import { TaskFlowFactory } from '@openclaw/task-flow/tooling';

const taskFlow = TaskFlowFactory.create({
  name: 'data-processing',
  steps: [
    { id: 'step1', action: 'fetch' },
    { id: 'step2', action: 'transform' },
    { id: 'step3', action: 'save' }
  ]
});

await taskFlow.execute();

示例 2: 注册自定义任务流

旧代码:

import { FlowRegistry } from '@openclaw/flow-registry';

const registry = new FlowRegistry();
registry.register('custom-flow', CustomFlowHandler);

新代码:

import { TaskFlowRegistry } from '@openclaw/task-flow/registry';

const registry = new TaskFlowRegistry();
registry.register('custom-task-flow', CustomTaskFlowHandler);

示例 3: ACP 任务流消费

旧代码:

import { ACPFlowConsumer } from '@openclaw/acp/flow';

@FlowConsumer()
class MyACPPlugin {
  async onFlowEvent(event: FlowEvent) {
    // 处理 flow 事件
  }
}

新代码:

import { ACPTaskFlowConsumer } from '@openclaw/acp/task-flow';

@TaskFlowConsumer()
class MyACPPlugin {
  async onTaskFlowEvent(event: TaskFlowEvent) {
    // 处理 task-flow 事件
  }
}

迁移检查清单

[ ] 更新所有导入路径
[ ] 替换 Flow → TaskFlow 类名
[ ] 更新配置文件
[ ] 测试任务流执行
[ ] 验证插件兼容性
[ ] 更新文档注释

向后兼容性

OpenClaw 提供了临时兼容层：

config.yaml
compatibility:
  flow_aliases:
    enabled: true  # 启用 Flow → Task-flow 别名
    deprecation_warnings: true  # 显示废弃警告

注意：兼容层将在 v2026.6.0 版本中移除，请尽快完成迁移。

迁移工具

OpenClaw 提供了自动迁移工具：

安装迁移工具
npm install -g @openclaw/migrate

执行迁移
openclaw-migrate flow-to-task-flow --src ./my-project

预览变更（不实际修改）
openclaw-migrate flow-to-task-flow --src ./my-project --dry-run

总结

Flow → Task-flow 重构 是 OpenClaw 概念体系完善的重要一步：

1. 命名更清晰 — Task-flow 明确表达”任务流”概念
2. 架构更一致 — 与 Task、Pipeline 等概念形成完整体系
3. 迁移有工具 — 提供自动迁移工具和兼容层

关键行动：
1. 运行 openclaw-migrate 自动迁移
2. 测试任务流功能
3. 在 v2026.6.0 前完成迁移

常见问题

Q: 为什么需要这次重命名？

“Flow” 含义模糊，容易与其他概念混淆
“Task-flow” 更准确表达功能
统一 OpenClaw 的概念体系

Q: 旧代码还能运行吗？

A: 可以，通过兼容层暂时支持，但会在 v2026.6.0 移除。

Q: 迁移工具会修改哪些文件？

TypeScript/JavaScript 源码文件
配置文件（config.yaml）
类型定义文件
测试文件

Q: 如何验证迁移成功？

1. 检查是否还有 flow 引用
grep -r "from.flow" --include=".ts" src/

2. 运行测试
npm test

3. 验证任务流执行
openclaw task-flow test

Q: 第三方插件受影响吗？

A: 是的，需要插件作者更新。OpenClaw 已通知主要插件作者。

Q: 配置文件需要手动更新吗？

A: 迁移工具会自动处理，但建议人工检查确认。

参考来源

—

相关阅读：