1. 项目缘起与整体设计思路1.1 为什么会有 paperclip 这个想法先说说 paperclip 到底是个什么东西。简单讲它是一个跑在 Node.js 环境里的轻量级 AI Agent 编排层前端用 React 做交互面板后端通过 Node.js 串联各种 AI Agent 的执行流程同时借助 OpenClaw 这类工具做本地化的 Agent 调度与文件系统监听。你可以把它理解成一个“AI 助手的调度中枢”——它不负责训练模型也不负责推理它负责的是把多个 Agent 的能力组织起来让它们按照你定义的流程去干活。我最初做这个东西是因为在实际工作中遇到一个很具体的问题手头有好几个 AI Agent有的负责代码审查有的负责文档生成有的负责数据抓取但它们之间是孤立的。每次要完成一个完整任务我得手动把上一个 Agent 的输出复制到下一个 Agent 的输入里中间还要做格式转换、状态记录、异常处理。这种“人肉编排”的方式在任务量小的时候还能忍一旦任务多起来整个人就被拖住了。paperclip 要解决的就是这个“编排”问题。它把 Agent 之间的调用关系、数据流转、状态管理、错误重试这些脏活累活全部接管你只需要定义好“谁在什么时候做什么”剩下的交给它。适合谁来参考呢如果你正在做 AI Agent 相关的项目或者你手头有一堆零散的自动化脚本想整合成一个系统又或者你单纯想学一下 Node.js React 怎么跟 AI Agent 配合那这篇内容应该能给你不少可以直接抄的东西。1.2 技术选型的取舍逻辑选 Node.js 作为后端运行时不是因为它性能最强而是因为它跟 AI Agent 生态的契合度最高。目前主流的 AI Agent 工具链无论是 OpenClaw 还是各种 SDK对 Node.js 的支持都是第一梯队的。而且 Node.js 的事件驱动模型天然适合处理 Agent 之间的异步调用——一个 Agent 在跑的时候主线程不用干等可以继续处理其他 Agent 的请求。这一点在编排场景里特别重要因为 Agent 的执行时间往往不可预测短则几百毫秒长则几分钟。前端选 React理由更直接paperclip 需要一个能实时反映 Agent 状态的交互面板React 的组件化模型和状态管理机制尤其是 Hooks让这种“状态驱动 UI”的场景变得很自然。你不需要手动去操作 DOM只需要关心状态怎么变UI 自动跟着变。而且 React 生态里有大量现成的图表库比如 uPlot 这种轻量级的用来展示 Agent 的执行耗时、成功率、任务队列长度这些指标非常方便。OpenClaw 在这个架构里扮演的是“执行器”的角色。paperclip 本身不直接跟文件系统或外部服务打交道它把具体的执行动作委托给 OpenClaw 去完成。这样做的好处是解耦——paperclip 只管编排逻辑OpenClaw 只管执行细节。如果哪天你想换一个执行器只要接口对得上paperclip 这边几乎不用改。1.3 整体架构长什么样paperclip 的架构可以分成四层。最底层是执行层由 OpenClaw 和各种 AI Agent 组成它们负责实际的任务执行。往上一层是编排层这是 paperclip 的核心用 Node.js 实现负责解析任务定义、调度 Agent、管理状态、处理异常。再往上是接口层提供 REST API 和 WebSocket 两种通信方式REST 用于常规的请求响应WebSocket 用于实时推送 Agent 的状态变化。最上面是展示层就是 React 做的那个交互面板。这四层之间的数据流是这样的用户在 React 面板上发起一个任务接口层收到请求后转给编排层编排层根据任务定义决定调用哪些 Agent、按什么顺序调用然后通过执行层去实际执行。执行过程中Agent 的状态变化通过 WebSocket 实时推回给 React 面板用户就能看到“当前哪个 Agent 在跑、跑到哪一步了、有没有报错”。注意编排层和执行层之间的通信协议一定要提前定义清楚不然后面改起来会很痛苦。我一开始用的是简单的 JSON 格式后来发现需要传递二进制数据比如图片又得回头改协议白白浪费了两天时间。2. 核心细节解析与实操要点2.1 Node.js 环境准备与版本选择paperclip 对 Node.js 的版本有要求建议用 18.20.4 LTS 或 22.12 这两个版本。为什么强调版本因为 paperclip 用到了 Node.js 的worker_threads来做 Agent 的隔离执行这个特性在 18.x 和 22.x 上的行为有细微差别。18.20.4 是 18.x 系列里比较稳定的一个 LTS 版本22.12 则是更新一些的 LTS两者都支持 paperclip 需要的所有 API。安装 Node.js 的步骤本身不复杂但有几个坑要注意。如果你是在 CentOS 7.9 上部署系统自带的 Node.js 版本可能太老需要先通过 NodeSource 的仓库来安装。具体操作是先用curl -fsSL https://rpm.nodesource.com/setup_18.x | bash -添加仓库然后yum install -y nodejs。装完之后用node -v和npm -v确认版本。如果node -v输出的不是 18.x那大概率是 PATH 里有旧版本的残留需要手动清理。在 Windows 或 macOS 上就简单多了直接去官网下载对应版本的安装包一路下一步就行。但要注意如果你之前装过其他版本的 Node.js最好先用nvmNode Version Manager来管理版本避免多个版本打架。nvm的安装和使用都很简单nvm install 18.20.4然后nvm use 18.20.4就切换过去了。实操心得装完 Node.js 之后建议把 npm 的源换成国内镜像不然装依赖的时候会慢到怀疑人生。命令是npm config set registry https://registry.npmmirror.com。这个操作在 CentOS 7.9 这种老系统上尤其重要因为默认源有时候连不上。2.2 React 面板的状态管理与 Hooks 设计React 面板的核心是状态管理。paperclip 的面板需要跟踪的状态包括当前有哪些 Agent 在运行、每个 Agent 的状态等待中/执行中/已完成/失败、任务的执行历史、实时的日志输出。这些状态如果用传统的class component来管理代码会变得非常臃肿。用 Hooks 就不一样了useState管局部状态useReducer管复杂的状态逻辑useEffect处理副作用比如 WebSocket 的连接和断开useContext做跨组件的状态共享。我重点说一下useReducer在 paperclip 里的用法。Agent 的状态变化其实是一个状态机从“等待中”到“执行中”再到“已完成”或“失败”每个状态之间的转换都有明确的触发条件。用useReducer来管理这种状态机非常合适因为你可以把所有可能的状态转换都写在一个 reducer 函数里逻辑集中不容易出错。const agentReducer (state, action) { switch (action.type) { case AGENT_START: return { ...state, status: running, startTime: Date.now() }; case AGENT_SUCCESS: return { ...state, status: completed, endTime: Date.now() }; case AGENT_FAIL: return { ...state, status: failed, error: action.payload }; default: return state; } };这个 reducer 看起来简单但它把 Agent 的状态转换规则固化下来了。任何地方想改 Agent 的状态都必须通过 dispatch 一个 action 来触发不能直接改 state。这种约束在多人协作的项目里特别有价值能避免很多“状态莫名其妙不对”的问题。2.3 OpenClaw 的接入与配置要点OpenClaw 在 paperclip 里的角色是执行器所以接入的重点是“怎么让 paperclip 把任务交给 OpenClaw以及怎么拿到执行结果”。OpenClaw 本身提供了命令行接口和 API 接口两种调用方式。paperclip 用的是 API 方式因为命令行方式在 Node.js 里调用需要起子进程性能和可控性都不如直接走 API。配置 OpenClaw 的时候有几个参数需要特别注意。第一个是maxConcurrentTasks这个参数控制 OpenClaw 同时能跑多少个任务。设得太小任务会排队设得太大机器资源会被吃满。我的经验值是 CPU 核心数乘以 1.5比如 4 核的机器就设成 6。第二个是taskTimeout这个参数控制单个任务的最长执行时间超过这个时间 OpenClaw 会强制终止任务并返回超时错误。这个值要根据你的实际任务来定我一般设成 300 秒因为大部分 Agent 任务在 5 分钟内都能跑完。还有一个容易忽略的点是 OpenClaw 的日志配置。默认情况下 OpenClaw 会把日志写到标准输出但在 paperclip 里我们需要把日志收集起来展示在 React 面板上。所以要把 OpenClaw 的日志输出重定向到一个文件然后 paperclip 通过监听文件变化来读取日志。这里就用到了 React SSE/WebSocket 轮询文件变化的机制——paperclip 的后端用fs.watch监听日志文件一旦有变化就通过 WebSocket 推给前端。注意fs.watch在不同操作系统上的行为不一致Linux 上比较可靠Windows 上偶尔会丢事件。如果发现日志推送不及时可以在fs.watch的基础上加一个定时轮询作为兜底比如每 2 秒读一次文件对比上次读取的位置有新增内容就推送。2.4 手写一个 React Agent 的最小实现为了让大家更直观地理解 paperclip 里 Agent 是怎么工作的我手写一个最小的 React Agent 实现。这个 Agent 的功能很简单接收一个 React 组件的代码字符串分析它用了哪些 Hooks然后返回一个分析报告。class ReactAgent { constructor(name) { this.name name; this.status idle; } async execute(input) { this.status running; try { const hooks this.analyzeHooks(input.code); this.status completed; return { success: true, hooks }; } catch (error) { this.status failed; return { success: false, error: error.message }; } } analyzeHooks(code) { const hookPattern /use[A-Z]\w/g; const matches code.match(hookPattern) || []; return [...new Set(matches)]; } }这个 Agent 虽然简单但它包含了 Agent 的基本要素有名字、有状态、有执行方法、有错误处理。paperclip 在编排的时候就是通过调用每个 Agent 的execute方法来驱动整个流程的。你可以基于这个模板扩展出更复杂的 Agent比如加上重试逻辑、加上超时控制、加上依赖注入等等。3. 实操过程与核心环节实现3.1 从零搭建 paperclip 的完整步骤搭建 paperclip 的过程可以分成五步环境准备、后端初始化、前端初始化、OpenClaw 接入、联调测试。每一步都有一些细节需要注意我按顺序说。第一步环境准备。确认 Node.js 版本符合要求然后创建一个项目目录比如mkdir paperclip cd paperclip。在项目目录下初始化 npmnpm init -y。这一步会生成一个package.json文件后面所有的依赖都会记录在这里。第二步后端初始化。安装后端需要的依赖npm install express ws axios chokidar。express 用来提供 REST APIws 用来实现 WebSocketaxios 用来调用 OpenClaw 的 APIchokidar 用来监听文件变化比原生的fs.watch更可靠。然后创建一个server.js文件写入基本的服务器代码。const express require(express); const WebSocket require(ws); const chokidar require(chokidar); const app express(); const server app.listen(3000, () { console.log(paperclip backend running on port 3000); }); const wss new WebSocket.Server({ server }); wss.on(connection, (ws) { console.log(client connected); ws.on(message, (message) { console.log(received:, message); }); }); const watcher chokidar.watch(./logs, { persistent: true }); watcher.on(change, (path) { wss.clients.forEach((client) { if (client.readyState WebSocket.OPEN) { client.send(JSON.stringify({ type: log_update, path })); } }); });这段代码做了三件事启动了一个 Express 服务器监听 3000 端口建立了一个 WebSocket 服务用于实时推送用 chokidar 监听了logs目录下的文件变化。当日志文件有更新时通过 WebSocket 把消息推给所有连接的客户端。第三步前端初始化。用 Create React App 或者 Vite 创建一个 React 项目。我推荐用 Vite因为它的启动速度比 CRA 快很多。命令是npm create vitelatest paperclip-ui -- --template react。创建完之后进入paperclip-ui目录安装依赖npm install。然后安装 uPlot 用来画图表npm install uplot。第四步OpenClaw 接入。在 paperclip 的后端里封装一个 OpenClaw 客户端负责跟 OpenClaw 的 API 通信。这个客户端需要提供三个方法submitTask提交任务、getTaskStatus查询任务状态、cancelTask取消任务。const axios require(axios); class OpenClawClient { constructor(baseURL) { this.baseURL baseURL; } async submitTask(task) { const response await axios.post(${this.baseURL}/tasks, task); return response.data; } async getTaskStatus(taskId) { const response await axios.get(${this.baseURL}/tasks/${taskId}); return response.data; } async cancelTask(taskId) { const response await axios.delete(${this.baseURL}/tasks/${taskId}); return response.data; } }第五步联调测试。把后端和前端都跑起来然后在 React 面板上发起一个测试任务看看任务能不能正常提交、状态能不能实时更新、日志能不能正常推送。这一步最容易出问题的地方是跨域——前端跑在 5173 端口后端跑在 3000 端口浏览器会拦截跨域请求。解决办法是在后端加一个 CORS 中间件app.use(require(cors)())。3.2 任务编排的核心逻辑实现paperclip 最核心的部分是任务编排逻辑。所谓编排就是定义“先做什么、再做什么、什么条件下做什么”。我用一个简单的例子来说明假设有一个任务需要先让 Agent A 生成代码然后让 Agent B 审查代码如果审查通过就让 Agent C 部署如果审查不通过就回到 Agent A 重新生成。这个逻辑用代码实现大概是这样async function orchestrate(task) { let maxRetries 3; let attempt 0; while (attempt maxRetries) { const code await agentA.execute(task); const review await agentB.execute(code); if (review.passed) { await agentC.execute(code); return { success: true, attempts: attempt 1 }; } attempt; console.log(review failed, retrying (${attempt}/${maxRetries})); } return { success: false, reason: max retries exceeded }; }这段代码看起来简单但它包含了编排的几个关键要素顺序执行A 完了才执行 B、条件分支审查通过才部署、循环重试审查不通过就重来。在实际项目里你可能还需要加上并行执行多个 Agent 同时跑、超时控制某个 Agent 跑太久就跳过、降级策略主 Agent 挂了就用备用 Agent等等。实操心得编排逻辑一定要写成可配置的不要硬编码在代码里。我一开始就是把流程写死在代码里后来业务方说要调整顺序我又得改代码、重新测试、重新部署非常麻烦。后来改成用 JSON 定义流程代码只负责解析和执行灵活多了。3.3 实时状态推送的实现细节React 面板要实时显示 Agent 的状态靠的就是 WebSocket 推送。后端的实现前面已经说了用ws库建立 WebSocket 服务用 chokidar 监听文件变化。前端的实现需要注意几点。第一WebSocket 的连接要在useEffect里建立并且在组件卸载时断开避免内存泄漏。useEffect(() { const ws new WebSocket(ws://localhost:3000); ws.onopen () console.log(connected); ws.onmessage (event) { const data JSON.parse(event.data); dispatch({ type: UPDATE_AGENT_STATUS, payload: data }); }; ws.onclose () console.log(disconnected); return () ws.close(); }, []);第二WebSocket 断线之后要自动重连。网络抖动或者后端重启都会导致 WebSocket 断开如果不重连前端就收不到状态更新了。重连的逻辑可以写在onclose回调里用setTimeout延迟几秒后重新建立连接。第三状态更新要节流。如果 Agent 的日志输出很频繁WebSocket 消息会非常多前端如果每收到一条消息就更新一次状态会导致频繁的 re-render页面会卡。解决办法是在前端做一个缓冲比如每 500 毫秒批量处理一次消息。3.4 用 uPlot 画 Agent 执行指标图表paperclip 的面板里有一个图表区域用来展示 Agent 的执行耗时、成功率、任务队列长度这些指标。我选的是 uPlot因为它足够轻量压缩后只有 40 多 KB渲染速度快适合实时更新的场景。用 uPlot 画图的基本步骤是先准备好数据数组然后创建 uPlot 实例最后在数据更新时调用setData方法。const data [ [1, 2, 3, 4, 5], // x 轴时间 [120, 150, 90, 200, 180], // y 轴耗时毫秒 ]; const opts { width: 600, height: 300, series: [ {}, { label: 执行耗时, stroke: blue }, ], }; const plot new uPlot(opts, data, document.getElementById(chart)); // 数据更新时 plot.setData([newX, newY]);uPlot 的 API 很简洁没有太多花哨的东西但该有的功能都有。如果你需要更复杂的图表比如 K 线图uPlot 也支持只是配置会复杂一些。对于 paperclip 这种监控面板来说uPlot 完全够用了。4. 常见问题与排查技巧实录4.1 Node.js 安装与版本问题速查问题现象可能原因解决方法node -v报 command not foundNode.js 没装或 PATH 没配重新安装或手动把 Node.js 的 bin 目录加到 PATH版本号不是 18.x 或 22.x系统自带旧版本或 nvm 没切换用nvm use 18.20.4切换或卸载旧版本npm install卡住不动默认源太慢或网络问题换国内镜像源npm config set registry https://registry.npmmirror.comCentOS 7.9 上安装失败系统 glibc 版本太老用 NodeSource 仓库安装或升级系统4.2 React 面板白屏问题排查React Native 启动白屏是热词里提到的问题虽然 paperclip 用的是 React 而不是 React Native但白屏问题的排查思路是相通的。白屏通常意味着 JavaScript 执行出错了但错误没有显示在界面上。排查步骤是这样的第一步打开浏览器的开发者工具看 Console 面板有没有报错。第二步如果 Console 没报错看 Network 面板确认 JavaScript 文件有没有加载成功。第三步如果文件加载了但页面还是白的可能是根组件渲染失败了在index.js里给ReactDOM.render加一个错误边界。class ErrorBoundary extends React.Component { state { hasError: false, error: null }; static getDerivedStateFromError(error) { return { hasError: true, error }; } render() { if (this.state.hasError) { return div出错了{this.state.error.message}/div; } return this.props.children; } }这个错误边界组件能捕获子组件渲染时的错误并显示一个友好的错误提示而不是白屏。在开发阶段特别有用能帮你快速定位问题。4.3 OpenClaw 部署与接入的坑OpenClaw 在 Ubuntu 上的安装相对简单官方有一键部署脚本。但在实际部署过程中我遇到过几个问题。第一个是权限问题。OpenClaw 需要访问文件系统来读写任务文件如果运行 OpenClaw 的用户没有对应目录的权限任务会失败。解决办法是确保 OpenClaw 的运行用户对工作目录有读写权限或者直接用 root 运行不推荐但省事。第二个是端口冲突。OpenClaw 默认监听 8080 端口如果这个端口被其他程序占用了OpenClaw 会启动失败。解决办法是改 OpenClaw 的配置文件换一个端口然后在 paperclip 的 OpenClawClient 里把 baseURL 改成对应的端口。第三个是日志文件不更新。前面说过paperclip 通过监听日志文件来获取 OpenClaw 的执行日志。如果 OpenClaw 的日志没有写到 paperclip 监听的目录那就什么都读不到。解决办法是检查 OpenClaw 的日志配置确保日志输出路径跟 paperclip 的监听路径一致。注意OpenClaw 接入 Microsoft Teams 的时候需要在 Teams 那边配置一个 Webhook然后把 Webhook 的 URL 填到 OpenClaw 的配置里。这个 Webhook 的 URL 有时候会变如果发现消息发不出去了先检查 Webhook 是不是失效了。4.4 文件变化监听的可靠性优化paperclip 用 chokidar 监听文件变化但 chokidar 在某些场景下也会漏事件。比如文件被快速修改多次chokidar 可能只触发一次 change 事件。解决办法是加一个防抖或者节流但更可靠的做法是记录上次读取的文件位置每次 change 事件触发时从上次的位置继续读而不是从头读。let lastPosition 0; watcher.on(change, (path) { const stats fs.statSync(path); if (stats.size lastPosition) { const stream fs.createReadStream(path, { start: lastPosition, end: stats.size, }); stream.on(data, (chunk) { // 处理新增的日志内容 }); lastPosition stats.size; } });这种方式能确保不丢日志即使 chokidar 漏了事件下次事件触发时也能把漏掉的内容补上。代价是需要维护lastPosition状态并且在文件被截断或轮转时重置这个值。4.5 性能优化的几个实用技巧paperclip 在任务量大的时候会遇到性能瓶颈我总结了几个优化技巧。第一个是 Agent 的复用。不要每次执行任务都新建一个 Agent 实例而是维护一个 Agent 池任务来了从池里取一个空闲的 Agent 来用。这样能避免频繁的对象创建和销毁也能控制并发数。第二个是日志的批量写入。如果每个 Agent 的每条日志都单独写文件IO 压力会很大。改成批量写入比如攒够 100 条或者每隔 1 秒写一次能显著降低 IO 次数。第三个是 WebSocket 消息的压缩。如果推送的消息比较大比如包含完整的日志内容可以开启 WebSocket 的 permessage-deflate 扩展来压缩消息。ws库默认就支持这个只需要在创建 WebSocket.Server 的时候传一个配置项。const wss new WebSocket.Server({ server, perMessageDeflate: true, });这个配置对文本消息的压缩效果很明显尤其是日志这种重复度高的内容压缩率能到 70% 以上。4.6 常见错误码与处理建议错误码含义处理建议ECONNREFUSED连接被拒绝检查 OpenClaw 是否启动端口是否正确ETIMEDOUT连接超时检查网络增加超时时间ENOENT文件不存在检查文件路径确保目录存在EACCES权限不足检查运行用户的权限或改文件权限MODULE_NOT_FOUND模块找不到检查依赖是否安装npm install重跑这些错误码在 Node.js 里很常见遇到的时候不用慌按表格里的建议一步步排查就行。大部分问题都是配置问题不是代码问题。5. 一些个人体会和后续扩展方向paperclip 这个项目我从零开始搭中间踩了不少坑也积累了一些经验。最大的体会是编排系统的核心不是“能跑”而是“跑得稳”。一个能跑的编排系统可能两天就能写出来但要让它稳定运行、出错能恢复、状态可追踪需要花十倍的时间去打磨。后续我打算在几个方向上继续扩展。一个是支持更多的 Agent 类型现在主要是代码相关的 Agent后面想加上数据处理、图像识别这些类型的 Agent。另一个是做一个可视化的流程编辑器让用户可以在界面上拖拽定义任务流程而不是手写 JSON。还有一个是加上任务优先级和资源配额让 paperclip 能更好地支持多用户场景。如果你也在做类似的东西我的建议是先把核心的编排逻辑跑通不要一开始就追求大而全。paperclip 的第一版只有 200 行代码但已经能完成基本的任务编排了。后面所有的功能都是在这个基础上慢慢加出来的。先跑起来再跑好这个顺序不能反。