Slickflow 与 OpenClaw 结合实践：技术原理、集成方式与 Skill 说明

本文基于 sfbpmn-project（Slickflow 引擎、设计器、sfdapi 等）与 sfai-project（如 aichatbackend 等 AI 业务后端）的典型架构，说明如何通过 Web API 将 OpenClaw 智能体与 Slickflow 工作流打通。文中 API 路径以通用 REST 风格描述，实际路由请以你仓库中 sfdapi / 业务 WebAPI 的 Controller 为准。

一、各自在技术栈中的位置

1.1 Slickflow（sfbpmn-project）

• 引擎层：Slickflow.Engine 作为依赖嵌入 ASP.NET Core 或其它 .NET 宿主进程，负责解析 BPMN、驱动流程实例、执行 ServiceTask / UserTask、持久化等。
• 自动化运行：通过 WorkflowExecutor、WfAppRunner 等，在代码中 UseProcess / Run()，适合「一次请求 → 一整条自动化流水线」（见仓库内《Slickflow 流程自动化运行技术指南》）。
• 人工审批：传统模式依赖数据库中的流程实例、待办任务，前端或 API 多次调用 WorkflowService.Run 推进。
• 服务任务类型（引擎内部）：包括 WebAPI（ServiceMethodEnum.WebApi）、LocalService、CSharpLibrary 等（见 docs/BPMN2_SERVICE_TASK_OPTIMIZATION.md）。
  注意：这是 流程节点 去调外部 HTTP 或本地实现；与「外部智能体经 REST 调 Slickflow」是相反方向。

1.2 sfai-project（典型如智能客服后端）

• 常见模式：ASP.NET Core Web API 接收对话请求（例如 POST /api/AiChatApp/GetChatMessage），在 Service 层根据流程编码/版本构造变量，调用 WorkflowExecutor 启动并 Run()（见《Slickflow AI 智能客服多轮问答系统实现指南》）。
• 也就是说：业务编排的入口已经是 HTTP，引擎在服务端进程内随宿主应用一起运行。

1.3 OpenClaw

• OpenClaw 是 智能体网关 + 工具（Tools）+ 技能（Skills）+ 插件（Plugins） 的分层架构：模型通过 函数式工具调用 完成读文件、执行命令、HTTP 请求等。
• 网关提供 HTTP 工具调用 能力，例如对网关地址执行 POST /tools/invoke，在请求体中指定 tool、args 等（见 OpenClaw Tools Invoke API）。
• Skills 通常是 Markdown 说明文档，在运行时注入系统提示，教会模型 何时、如何用哪个工具、传什么参数——适合把「调用 Slickflow 的规范」固化下来。

二、OpenClaw 与 Slickflow 的集成方式：Web API

OpenClaw 运行在独立网关/代理进程中，通过 工具 与外部系统交互，适合且应当通过 HTTP/REST 访问你方暴露的业务接口。集成路径可概括为：智能体 → HTTPS → ASP.NET 应用（sfdapi / sfai）→ 应用内调用 Slickflow 引擎 API（如 WorkflowService、WorkflowExecutor 等）。

智能体侧可使用 web_fetch、自定义 HTTP 工具、exec 调 curl，或封装专用工具访问上述业务 API。

2.1 与「流程里的 WebAPI 节点」不要混淆

• BPMN 里配置 WebAPI 类型的 ServiceTask：表示 流程执行到该节点时，引擎代表流程去 HTTP 调用别的系统。
• OpenClaw 调 Slickflow：表示 智能体要下达「启动流程」「终止实例」等指令，应调用 你暴露的 REST 接口，由 Controller / Application Service 再调 WorkflowService / WorkflowExecutor。

三、指令型操作：启动流程与结束流程（概念与接口形态）

以下命名是常见工作流产品能力映射到 Slickflow 时的语义；具体 URL 需在 sfdapi 或 sfai 后端 中查找对应 Controller。

3.1 启动流程（Start）

• 语义：创建流程实例、写入初始变量、可能首次 Run（自动化）或生成首个 UserTask（人工审批）。
• HTTP 侧：通常为 POST，Body 含 processCode / processId、version、JSON 形式的 variables（如业务单号、发起人）。
• 服务端实现：在业务后端中调用与 WfAppRunner、WorkflowExecutor 或 WorkflowService.Start 等一致的引擎 API（与《流程自动化运行技术指南》中 AddVariable + Run() 的模式一致）。

3.2 结束 / 终止流程（End / Terminate）

• 语义区分：
  • 正常结束：走完 BPMN 到 End Event。
  • 作废 / 终止实例：业务上撤销流程，引擎侧可能对应删除实例、状态置为终止等（以你方封装为准）。
• HTTP 侧：可能为 POST /.../Terminate、POST /.../Cancel 或带 processInstanceId 的专用接口。
• 人工任务场景：「完成当前节点」常是 POST .../Run 或 CompleteTask，传入 activityInstanceId、办理意见等——这也常被业务称为「让流程继续直到结束」。

智能体侧只需 稳定、可鉴权 的 REST 契约；不要让 OpenClaw 直接操作数据库。

四、OpenClaw 侧：如何用「工具」调用你的 WebAPI

4.1 直接 HTTP（通用）

• 使用具备 HTTP 能力的工具（如文档中的 web_fetch 或网关提供的 HTTP 类工具），对你的 https://your-sfdapi/api/... 发起 POST/GET。
• 若 OpenClaw 网关启用了 POST /tools/invoke，则是调用 OpenClaw 内置工具 的通道；要让智能体操作 Slickflow，通常仍需：
  • 要么写一个 自定义 Tool/Plugin，在其实现里用 HttpClient 调你的 sfdapi；
  • 要么在 Skill 里写清楚：使用 web_fetch（或等价工具）访问固定 Base URL 与路径。

4.2 鉴权

• 业务 API：建议使用 Bearer Token、API Key 或 mTLS，并在网关或反向代理上限制来源 IP。
• OpenClaw 网关自身：若调用 /tools/invoke，需按文档使用 Authorization: Bearer <OPENCLAW_GATEWAY_TOKEN> 等（参见 OpenClaw 文档中的 gateway.auth）。

五、Skill 编写说明（具体模板）

Skills 用于 约束模型行为：何时触发、参数、错误处理。下面是一则可直接改编的 Skill 正文示例（存放为 OpenClaw 技能 Markdown，并按项目调整 URL）。

---
name: slickflow-workflow-ops
description: 通过公司 sfdapi 对 Slickflow 流程做指令级操作（启动、查询状态、终止）。仅在用户明确要求操作工作流或审批流程时使用。
---

# Slickflow 流程操作

## 前置条件
- 已知环境 Base URL，例如 `https://api.internal.example.com/sfdapi`.
- 请求头携带 `Authorization: Bearer <业务令牌>`（以实际为准）。

## 何时使用
- 用户说「发起某某流程」「提交审批」「取消流程实例」「流程跑到哪了」时使用 HTTP 工具调用下列接口；不要猜测流程编码，缺省时向用户确认 `processCode` 或业务单号。

## 接口约定（示例，需与 sfdapi 实际路由一致）

### 1. 启动流程
- **方法**: POST  
- **路径**: `/api/Workflow/Start`（示例）  
- **Body (JSON)**:
  - `processCode` (string, 必填)
  - `version` (string, 可选)
  - `variables` (object, 可选): 流程变量键值

成功响应中应包含 `processInstanceId`，后续操作用该 ID。

### 2. 终止 / 作废流程实例
- **方法**: POST  
- **路径**: `/api/Workflow/Terminate`（示例）  
- **Body**: `processInstanceId`, `reason`

### 3. 查询实例状态（可选）
- **方法**: GET  
- **路径**: `/api/Workflow/Instance/{processInstanceId}`

## 工具调用注意
- 使用 HTTP 客户端类工具；Content-Type 使用 `application/json`。
- 4xx/5xx 时将响应 body 简要反馈给用户，不要伪造成功。
- 不要在对话中输出完整 Bearer Token。

将上述文件注册到 OpenClaw 的 Skills 配置后，代理在「工具 + Skill」双重约束下，会更稳定地发起 启动 / 结束 类指令，而不是泛泛聊天。

六、架构小结（一张图说清楚）

七、参考（本仓库与外部）

• 本仓库：blogs/Slickflow_流程自动化运行_技术指南.md、blogs/Slickflow_AI智能客服多轮问答系统实现指南.md、docs/BPMN2_SERVICE_TASK_OPTIMIZATION.md
• OpenClaw：Tools Invoke (HTTP)、Tools 总览
• 实际 sfbpmn-project 中路由以 sfdapi/Controllers 与 sfai 后端代码为准，上线前请用 Swagger 或接口文档对齐路径与 DTO。

文档版本说明：OpenClaw 的网关端口、工具名以官方当前文档为准；Slickflow 侧 API 以 D:/sfbpmn2 或当前分支实现为准。