一、Openflow的基础定位

1. Openflow不是全新的技术/产品，而是AI agent这类应用的一种新形态，是大模型与传统技术的结合体，其底层核心逻辑与常规的网页应用、APP、Web coding开发的产品一致，仅在三个核心能力上做出了差异化设计；

1. Openflow的创作者将三个核心差异化能力嵌入到了agent（智能体） 应用场景中，使其成为一款可本地部署的个人AI助手网关；

1. 核心价值：实现本地常驻服务+多IM平台通信+自动化定时任务的AI agent能力，打破了常规agent应用“被动响应、需手动激活”的限制。

二、先掌握：常规应用的底层运行逻辑

学习Openflow前，必须先理解所有常规应用/AI agent的通用运行逻辑，这是零基础学员的核心基础，Openflow的所有差异均基于此逻辑展开。

2.1 常规应用的三大核心组成

任何给人使用的应用（APP、网页、常规AI agent）都由三部分组成，零基础学员可简单理解为“前端操作界面+后端处理大脑+底层存储/运行载体”，具体说明如下：

组成部分	通俗解释	举例
前端UI（用户界面）	用户能看到、能点击操作的部分，仅负责样式/行为交互，不能直接处理数据/逻辑	浏览器网页的按钮、网易云音乐的播放界面、Cursor的对话框
后端服务	应用的“大脑”，负责接收前端的操作指令、做数据计算/逻辑处理，再将结果返回给前端	点击网页“创作”按钮后，背后处理生成内容的程序
数据存储/服务器运维	应用的“运行载体+数据仓库”，后端服务跑在服务器（本地电脑/云端）上，数据存在服务器的文件夹/数据库中	阿里云/腾讯云的云服务器、本地电脑的硬盘文件夹

2.2 常规应用的核心交互流程

前端触发操作 → 后端接收指令并计算处理 → 后端将结果返回前端 → 前端呈现给用户

• 关键特点：前端不能直接获取数据，必须依赖后端服务；后端被动响应，只有收到前端指令才会工作。

2.3 服务的运行方式：本地/云端一致

1. 无论是在本地电脑运行的服务（比如用NPM run Dev启动的程序），还是在云端服务器（阿里云/腾讯云）运行的服务，底层逻辑完全一样；

1. 云端服务器本质上就是一台“永远开机的电脑”，和本地电脑一样需要安装运行环境（如nodejs）、创建文件夹，只是拥有公网IP，能被外网访问；

1. 本地运行服务的常见指令：NPM run Dev（前端/后端服务启动），启动后终端会被占用，关闭终端则服务停止。

2.4 常规AI agent的两种常见形态

目前常规的大模型agent应用只有两种形态，均遵循上述“前端+后端”逻辑，且均需手动激活、被动响应，也是Openflow的主要对比对象：

1. 有客户端的agent：如Cursor，有可视化前端界面（对话框），前端跑在本地电脑，后端服务需向云端大模型发送API请求，互通后返回结果；

1. 无客户端的agent：如Claude code，无可视化网页/APP前端，将终端作为前端，在终端输入指令即相当于“点击前端按钮”，激活后端服务并交互。

核心共性：两种agent的后端服务都需要手动激活（打开客户端/终端输入指令），且服务挂在终端上，关闭终端则服务停止。

三、核心重点：Openflow与常规应用的三大差异化能力

这是Openflow的核心内容，也是其区别于Cursor、Claude code等常规agent的关键，三个差异点层层递进，共同实现了Openflow的“本地常驻、多端通信、自动运行”能力。

3.1 差异点1：系统层常驻服务，无需手动激活，开机即运行

3.1.1 常规应用的服务痛点

常规应用/agent的服务挂在终端/客户端上，需手动激活（打开客户端/输入NPM run Dev），且终端/客户端关闭后，服务立即停止；即使通过Daemon（影子进程）、PM2（进程管理器）让服务不占用当前终端，本质还是依赖终端/应用，无法做到“脱离载体持续运行”。

3.1.2 Openflow的实现方式：注册为系统级服务

Openflow将自身服务直接写入系统的PID1层（系统内核之上的最底层基建，和电脑的文件系统、网络服务同级），实现开机自启、常驻运行，具体特点：

1. 无需手动双击应用/输入终端指令激活，电脑开机后服务自动运行；

1. 脱离终端/客户端，即使关闭所有终端、杀掉进程，服务也会自动重启；

1. 运行级别与系统终端同级，是本地最底层的服务，不依赖任何其他应用/载体。

3.1.3 通俗理解：和“病毒的生存模式”类似（非真病毒）

很多流氓软件会将自己注册为系统级服务，因此关闭后会自动重启，Openflow的运行模式和其一致，这也是其“权限高、不安全”的原因，但并非真的病毒，只是服务运行的层级特殊。

3.1.4 零基础小知识

• PID：进程的唯一标识，电脑上每个运行的程序都对应一个/多个PID，关闭PID则程序停止；

• 系统级服务：电脑开机后系统自动启动的服务，如网络、蓝牙，优先级远高于普通应用服务。

3.2 差异点2：基于本地网关+长链接，支持多IM平台跨端通信

3.2.1 常规应用的通信痛点

常规应用的前后端通信基于HTTP/API请求，是一问一答的被动模式：前端主动发请求，后端才会回应；且如果是本地部署的应用，因无公网IP，云端服务（如飞书/企微）无法主动向本地发消息，只能本地持续向云端“轮询”（反复请求）获取信息。

3.2.2 Openflow的实现方式：本地网关+Websocket长链接

Openflow在本地搭建了一个网关服务（Gateway），作为本地服务和云端IM平台（飞书/钉钉/企微）的通信桥梁，核心采用Websocket长链接实现通信，具体逻辑：

1. 本地网关：Openflow安装后会启动本地网关，是本地服务的“通信入口”，网关未启动则无法和云端通信；

1. Websocket长链接：本地网关主动和云端IM平台建立持续的双向通信通道，替代常规的“一问一答”API请求，通道建立后：

• 本地有消息可直接发给云端IM平台；

• 云端IM平台有消息可直接推送给本地网关；

• 无需本地反复轮询，也无需云端访问本地公网IP。

3.2.3 两种通信方式的对比（零基础易懂）

Openflow支持和IM平台的两种通信方式，本地部署仅能用Websocket长链接，云端部署可使用Webhook，具体区别：

通信方式	核心逻辑	适用场景	痛点
Websocket（长链接）	本地网关主动和云端建立持续双向通道，本地找云端通信	本地部署Openflow（无公网IP）	需本地网关先启动，否则无法建立通道
Webhook（钩子/触发器）	云端IM平台主动向本地服务发HTTP请求，云端找本地通信	云端部署Openflow（有公网IP）	本地无公网IP时，云端无法访问本地，无法使用

3.2.4 零基础小知识

• 网关：简单理解为“通信中转站”，负责连接两个不同的网络/服务，转发消息；

• 长链接：一次连接后持续保持通信，直到主动断开；

• 公网IP：能被外网访问的IP地址，家用电脑/本地服务器一般只有内网IP（如[127.0.0.1](127.0.0.1)），无法被云端访问。

3.2.5 重要细节

企微早期无Websocket长链接能力，本地部署的Openflow无法和企微通信，需云端部署；企微最新版本已新增长链接能力，现在本地部署也可对接。

3.3 差异点3：支持自动化定时任务，无需人工手动发送指令

3.3.1 常规agent的操作痛点

常规agent（Cursor/Claude code）必须人工手动操作：打开应用/终端，输入指令并发送，agent才会工作，无法实现“自动执行任务”。

3.3.2 Openflow的实现基础

因Openflow是系统层常驻服务（一直运行），且有本地网关通信能力，因此可以通过“自动化脚本/程序”向其发送指令，替代人工操作，实现定时任务。

3.3.3 Openflow的两种定时任务实现方式

Openflow内置了两套定时任务逻辑，均基于“到点自动向自身服务发送指令”实现，核心是“自动化触发，替代人工”，具体如下：

方式1：心跳轮询任务（基础版，固定间隔）

1. 核心逻辑：Openflow内置心跳（heartbeat） 功能，会在工作空间生成一个heartbeat文档，系统每隔半小时自动读取该文档，相当于“给Openflow发一次指令”；

1. 执行规则：读取文档时，若文档中有待执行任务，则自动执行；若无任务，则仅返回“心跳OK”，无任何操作；

1. 痛点：任务执行间隔固定为半小时，无法精准到具体时间（如想在16:45执行任务，可能因轮询间隔错过）。

方式2：专用定时器（进阶版，精准定时）

1. 核心逻辑：Openflow内置时间轴式定时器，可将任务按具体时间挂在时间轴上，定时器分秒走时，到达设定时间后自动触发任务；

1. 执行规则：

• 到达时间点，自动向Openflow服务发送指令，执行预设任务（如运行脚本、发大模型提示词、文件操作）；

• 任务执行完成后，自动更新下次执行时间（如每天5:30执行，完成后自动改到次日5:30）；

1. 优势：支持精准定时，可设置任意时间/间隔的任务，无固定间隔限制。

3.3.4 通俗理解

定时任务的本质就是Openflow模拟了“人工操作”：就像用“按键精灵”每隔10分钟自动在Cursor对话框输入指令并回车，只是Openflow将这个过程内置到系统中，无需额外的脚本工具。

四、Openflow核心功能模块（复刻版：flow mini）

零基础学员无需掌握复杂的工程逻辑，只需了解Openflow的核心功能模块（文档中以复刻版flow mini为例），所有模块均围绕上述三大差异化能力设计，也是开发复刻Openflow的核心参考。

4.1 网关服务（核心控制入口）

1. 核心功能：提供HTTP和Websocket双服务，是本地服务与外部（飞书/大模型）通信的唯一入口；

1. 关键配置：默认端口18791（避免和原Openflow的18790端口冲突），提供健康检查端点（检测服务是否正常运行）；

1. 便捷能力：支持热重载，服务出问题后无需重启电脑，仅重启网关服务即可恢复。

4.2 飞书集成（IM平台通信核心）

基于飞书官方SDK开发，实现和飞书的跨端通信，核心功能：

1. 建立Websocket长链接，实现本地与飞书的双向消息互通；

1. 自动认证+心跳重连，避免链接断开后无法通信；

1. 处理消息推送/表情/事件回应，实现飞书聊天界面与Openflow的直接交互。

4.3 AI对话处理（基础agent能力）

保留常规AI agent的核心能力，在其基础上增加网关服务对接，核心功能：

1. 集成大模型API，支持常规的AI对话、内容生成；

1. 提供文件处理+终端Shell工具，支持本地文件的读取、写入、执行命令三大操作；

1. 关键限制：增加安全限制，防止本地文件被误删/篡改（本地部署的核心安全要求）。

4.4 定时任务模块

实现上述两种定时任务能力，核心功能：

1. 支持心跳轮询任务：读取heartbeat文档，执行预设任务；

1. 支持专用精准定时器：添加/删除/列出定时任务，按时间轴自动执行；

1. 任务类型：支持运行脚本、发送大模型提示词、执行本地文件操作等。

4.5 系统服务模块

实现Openflow的系统级常驻能力，核心功能：

1. 将应用注册为系统常驻服务，实现开机自启、脱离终端运行；

1. 支持服务的启动/停止/重启，无需操作系统底层文件；

1. 自动配置备份：定时备份服务配置文件，支持恢复到最近一次健康状态。

4.6 CLI终端命令工具

为零基础/开发人员提供终端操作入口，注册系统服务后，可在终端直接输入指令操作Openflow，核心指令：

1. flow mini config：打开配置界面，修改大模型API Key、基础URL、模型名字、机器人配置等；

1. flow mini fix：自动修复服务，恢复到最近一次健康的配置状态；

1. 关键特点：无需记住复杂的系统底层命令，简化操作难度。

五、零基础入门：Openflow复刻开发实操思路

文档中作者通过Cursor（sonnet4.6版本） 一键复刻了简化版Openflow（flow mini），零基础学员无需掌握代码编写，只需了解开发核心思路和步骤，快速上手实操。

5.1 开发工具

• 核心工具：Cursor（AI代码编辑器，sonnet4.6版本），内置大模型，可通过提示词直接生成代码；

• 核心优势：零基础友好，无需手动写代码，仅需提供清晰的功能需求提示词，大模型即可一键生成完整应用。

5.2 核心开发思路：按“三大差异+六大功能模块”写提示词

Cursor开发的核心是提示词，只需将Openflow的核心逻辑、功能模块、配置要求写进提示词，大模型即可自动生成代码，提示词的核心要素：

1. 应用定位：本地部署的个人AI助手网关，基于Websocket长链接对接飞书；

1. 核心差异：系统级常驻服务、多IM平台通信、自动化定时任务；

1. 功能模块：网关服务、飞书集成、AI对话处理、定时任务、系统服务、CLI命令；

1. 配置要求：端口、安全限制、热重载、自动备份等；

1. 技术要求：基于nodejs开发，支持NPM启动，提供CLI命令。

5.3 开发核心步骤（零基础可直接操作）

1. 打开Cursor，新建项目，在对话框中输入上述完整提示词；

1. 等待大模型生成代码（作者仅消耗90K Token，一轮生成，无额外对话）；

1. 生成完成后，用NPM run Dev启动服务，测试网关是否正常运行；

1. 配置飞书长链接：启动本地网关后，在飞书开发者后台配置长链接，完成通信对接；

1. 测试功能：飞书聊天界面发送指令，测试AI对话、文件操作；添加定时任务，测试自动执行能力；

1. 注册系统服务：将生成的应用注册为本地系统服务，实现开机自启；

1. 调试与修复：使用flow mini fix修复配置问题，使用flow mini config修改大模型/机器人配置。

5.4 实操关键细节

1. 首次启动需填写基础配置（API Key、飞书配置等），后续可通过config指令二次修改；

1. 本地部署时，飞书集成必须先启动网关，否则无法建立长链接；

1. 生成的应用会在本地根目录创建工作空间，包含log日志文件、heartbeat心跳文件、配置文件，请勿随意删除。

六、常见问题与零基础答疑

6.1 agent和“智能体”的区别是什么？

agent不能直接等同于“智能体”，需明确具体定义：常规的agent（如Cursor/Claude code）只是**“能调用大模型的程序”，仅具备基础的对话/任务执行能力，无真正的“智能”；而完整的智能体是具备感知、决策、执行、学习能力的闭环系统**，Openflow只是增强版的agent，并非完整的智能体。

6.2 为什么本地部署的Openflow不能用Webhook？

因为本地电脑/服务器只有内网IP（如[127.0.0.1](127.0.0.1)），无公网IP，云端IM平台（飞书/企微）无法通过IP地址访问本地服务，而Webhook需要云端主动向本地发HTTP请求，因此无法使用；Websocket长链接是本地主动找云端通信，无需公网IP，因此是本地部署的唯一选择。

6.3 为什么在活动监视器/任务管理器中杀掉Openflow进程，它会自动重启？

因为Openflow是系统级常驻服务，其进程注册在系统PID1层，普通的任务管理器/活动监视器只能杀掉表层进程，无法删除系统层的服务注册信息，因此杀掉后系统会自动重启该服务，这是其“常驻运行”的核心设计，并非程序故障。

6.4 如何让Openflow的定时任务精准执行？

放弃心跳轮询任务（固定半小时间隔，无法精准），使用Openflow的专用定时器，将任务按具体时间点挂在时间轴上，定时器会分秒走时，到达时间后自动触发，支持任意时间/间隔的精准定时。

6.5 零基础学员学习Openflow的核心难点是什么？

核心难点不是代码开发，而是理解“系统级服务”和“网络通信”的基础逻辑，建议先掌握“常规应用的前端+后端”运行逻辑，再通过对比学习理解Openflow的三大差异，最后通过复刻flow mini动手实操，快速突破难点。

七、零基础学习小贴士

1. 先基础后差异：不要直接学Openflow的差异，先吃透常规应用的运行逻辑，否则会难以理解；

1. 重逻辑轻代码：零基础学员无需掌握复杂的编程代码，重点理解Openflow的底层逻辑和功能设计，代码可由AI工具（Cursor）生成；

1. 动手实操是关键：按文档中的思路，用Cursor复刻简化版Openflow（flow mini），通过测试功能（如飞书通信、定时任务）加深理解；

1. 不懂就查基础：遇到陌生术语（如PID、Websocket、PM2），先查基础定义，再结合文档中的通俗解释理解，不要死记硬背；

1. 关注核心价值：始终记住Openflow的核心价值是“本地常驻+多端通信+自动运行”，所有功能/差异都是为这三个价值服务。