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: 为什么需要这次重命名？
A:
- “Flow” 含义模糊，容易与其他概念混淆
- “Task-flow” 更准确表达功能
- 统一 OpenClaw 的概念体系
Q: 旧代码还能运行吗？
A: 可以，通过兼容层暂时支持，但会在 v2026.6.0 移除。
Q: 迁移工具会修改哪些文件？
A:
- TypeScript/JavaScript 源码文件
- 配置文件（config.yaml）
- 类型定义文件
- 测试文件
Q: 如何验证迁移成功？
A:
1. 检查是否还有 flow 引用
grep -r "from.flow" --include=".ts" src/
2. 运行测试
npm test
3. 验证任务流执行
openclaw task-flow test
Q: 第三方插件受影响吗？
A: 是的，需要插件作者更新。OpenClaw 已通知主要插件作者。
Q: 配置文件需要手动更新吗？
A: 迁移工具会自动处理，但建议人工检查确认。
参考来源
—
相关阅读：
