1. 从 paperclip 这个名字说起一个被低估的 AI Agent 编排思路第一次看到 paperclip 这个词大部分人脑子里蹦出来的可能是那个经典的回形针助手——微软 Office 里那个总爱跳出来问需要帮忙吗的小动画。但在 2026 年的技术语境下paperclip 已经变成了一个很有意思的隐喻一个轻量、可插拔、随时待命的 AI Agent 编排层。它不抢戏不喧宾夺主但当你需要它的时候它就在那里帮你把散落各处的工具、模型、数据流串成一条能跑通的链路。我最近花了两周时间基于 Node.js React 的技术栈配合 OpenClaw 这类 Agent 运行时从零搭了一套 paperclip 风格的 Agent 编排系统。踩了不少坑也攒了一些在官方文档里绝对找不到的经验。这篇文章就是把这套东西完整拆开从设计思路到代码实现从环境配置到线上排查全部摊开讲。不管你是刚接触 AI Agent 的新手还是已经在用 OpenClaw 做自动化流程的老手应该都能从里面捞到点能直接用的东西。先明确一下 paperclip 在这个语境下到底指什么。它不是某个具体的 npm 包也不是某个框架的官方名字而是一种架构模式把 AI Agent 的能力拆成一个个独立的、可复用的夹子clip每个夹子负责一个明确的职责——比如读文件、调 API、跑命令、发消息——然后由一个轻量的调度层paperclip core根据任务上下文动态地把这些夹子组合起来执行。这个思路和 OpenClaw 的 Agent 编排理念高度契合但 paperclip 更强调最小化依赖和前端可观测。为什么是 Node.js React因为这套东西的核心诉求是实时反馈和跨端复用。Node.js 的事件驱动模型天然适合处理 Agent 的异步任务流而 React 的组件化思维可以直接映射到 Agent 的夹子可视化上。你可以在浏览器里实时看到每个夹子的状态、输入输出、耗时甚至能手动干预某个夹子的执行。这种人在回路的体验是纯后端 Agent 框架很难给到的。适合谁来读如果你正在用 OpenClaw 做自动化但觉得它的默认编排太黑盒想自己掌控每一步或者你是个前端工程师想把手写 React Agent 的能力扩展到真实的后端任务上又或者你只是好奇 AI Agent 到底是怎么跑起来的想从零搭一个能跑的最小系统——那这篇内容就是写给你的。我会尽量把每个技术决策背后的为什么讲清楚而不是只丢一堆代码让你抄。2. 整体架构设计为什么选择 Node.js React OpenClaw 这套组合2.1 核心设计原则夹子要小调度要薄观测要厚paperclip 架构的第一原则是夹子必须足够小。一个夹子只做一件事比如读取指定路径的文件内容、向指定 URL 发送 POST 请求、执行一条 shell 命令并返回 stdout。为什么因为 Agent 的可靠性瓶颈往往不在模型本身而在工具调用的边界处理上。夹子越小输入输出的契约就越清晰出错时定位问题的成本就越低。我试过把读取文件并解析 JSON 并提取某个字段做成一个夹子结果就是每次 JSON 格式有变化这个夹子就得改而且改完之后所有依赖它的流程都得重新测。后来拆成三个夹子readFile、parseJSON、pickField每个夹子只关心自己的输入输出组合逻辑交给调度层。这样任何一个环节出问题我只需要替换那一个夹子其他部分完全不受影响。第二原则是调度层要薄。paperclip core 本身不应该包含任何业务逻辑它只负责三件事解析任务描述、按顺序调用夹子、把夹子的输出传递给下一个夹子。所有的智能都来自夹子本身的实现和夹子之间的组合方式。这样做的好处是调度层可以做得非常稳定几乎不需要改动而业务逻辑的变化全部收敛在夹子层面。第三原则是观测要厚。每个夹子的执行都必须留下完整的痕迹输入是什么、输出是什么、耗时多少、有没有报错、报错信息是什么。这些数据不仅要写日志还要通过 SSE 或 WebSocket 实时推送到前端。为什么这么强调观测因为 Agent 的行为本质上是非确定性的同样的输入可能因为模型温度、上下文长度、外部 API 状态等因素产生不同的输出。没有厚实的观测层你根本不知道 Agent 到底在干什么。2.2 技术选型背后的权衡Node.js 22.12 与 React 19 的配合Node.js 这边我选的是 22.12 LTS 版本。为什么不用 18.20.4因为 22.x 对 WebSocket 的原生支持更完善而且node:sqlite模块已经稳定可以直接用来做夹子执行记录的本地存储不需要额外引入 better-sqlite3 这种需要编译的依赖。另外 22.x 的--watch模式在开发时非常方便改完夹子代码自动重启省去了 nodemon 的配置。安装 Node.js 这块如果你是在 Ubuntu 上部署 OpenClaw我建议直接用 NodeSource 的仓库装不要用系统自带的 apt 版本。系统自带的往往版本太老而且和 OpenClaw 的依赖容易冲突。具体命令后面实操部分会详细写。Windows 用户直接去官网下 22.12 的 msi 安装包就行安装时记得勾选Add to PATH不然命令行里找不到 node 命令。React 这边我用的是 19 的 canary 版本主要是看中了usehook 和 Server Components 的成熟度。但在 paperclip 这个场景里React 的核心作用不是渲染页面而是管理夹子执行状态的前端状态机。每个夹子在前端对应一个状态节点状态流转是pending → running → success / failed。用 React 的 reducer 来管理这些状态配合 SSE 推送的增量更新可以实现非常流畅的实时观测体验。这里有个坑要提前说React Native 启动白屏的问题在 paperclip 的移动端观测场景里也遇到过。原因是 SSE 连接在移动网络下容易断断了之后前端没有正确的重连逻辑导致状态一直卡在 loading。解决方案是在 SSE 的 onerror 回调里加指数退避重连并且在前端维护一个最后收到的事件 ID重连时带上这个 ID让服务端从断点继续推送。这个后面会详细讲。2.3 OpenClaw 在架构中的角色运行时还是编排器OpenClaw 在这套架构里扮演的是Agent 运行时的角色而不是编排器。编排逻辑由 paperclip core 自己控制OpenClaw 只负责提供 Agent 的基础能力模型调用、上下文管理、工具注册。这样设计的好处是我可以随时替换掉 OpenClaw换成其他的 Agent 运行时而 paperclip 的夹子和调度逻辑完全不用改。但 OpenClaw 有个特性需要特别注意它的 session 文件锁机制。如果你在 OpenClaw 里同时跑多个 Agent 实例而且它们共享同一个 session 文件就会出现 agent failed before reply: session file locked (timeout 60000ms) 这个错误。我一开始没注意起了三个 Agent 做并发测试结果全部卡死。后来改成每个 Agent 实例用独立的 session 文件路径问题就解决了。这个坑在后面常见问题部分会再展开。另外 OpenClaw 和 Obsidian 的集成也值得提一句。如果你用 Obsidian 做知识库OpenClaw 可以直接读取 vault 里的 markdown 文件作为 Agent 的上下文。paperclip 的 readFile 夹子可以和这个能力配合实现从知识库检索 → 交给 Agent 处理 → 结果写回知识库的闭环。这个场景在实际用起来非常顺手后面实操部分会给一个完整的例子。3. 核心细节解析夹子的设计、实现与注册机制3.1 夹子的接口契约输入、输出与错误处理每个夹子本质上是一个符合特定接口的 JavaScript 对象。我定义的接口是这样的// clip.interface.js /** * typedef {Object} ClipContext * property {string} taskId - 当前任务 ID * property {Object} prevOutput - 上一个夹子的输出 * property {Object} globalState - 全局状态所有夹子共享 * property {Function} log - 日志函数会推送到前端 */ /** * typedef {Object} ClipResult * property {boolean} success - 是否成功 * property {any} data - 成功时的输出数据 * property {string} [error] - 失败时的错误信息 * property {Object} [meta] - 元信息如耗时、重试次数等 */为什么要把prevOutput和globalState分开因为prevOutput是管道式的只关心上一个夹子的直接输出适合线性流程而globalState是共享的任何夹子都可以读写适合需要跨步骤传递状态的场景。比如一个发送邮件的夹子可能需要用到前面生成报告夹子的输出同时也需要用到更早的获取用户配置夹子写入 globalState 的邮箱地址。错误处理这块我强制要求每个夹子返回ClipResult对象而不是直接 throw。为什么因为 throw 会中断整个执行链而返回success: false可以让调度层决定是重试、跳过还是终止。比如调用外部 API的夹子如果遇到 429 限流可以返回失败并附带retryAfter元信息调度层看到这个就自动等待后重试而不是直接崩掉整个任务。3.2 夹子注册表动态发现与热加载夹子的注册我用了文件系统扫描 动态 import 的方式。所有夹子放在clips/目录下每个夹子一个文件文件名就是夹子 ID。调度层启动时扫描这个目录动态 import 每个文件把导出的对象注册到内存里的 Map 中。// clip-registry.js import { readdir } from node:fs/promises; import { join } from node:path; import { pathToFileURL } from node:url; const CLIPS_DIR join(process.cwd(), clips); const registry new Map(); export async function loadClips() { const files await readdir(CLIPS_DIR); for (const file of files) { if (!file.endsWith(.js)) continue; const clipId file.replace(.js, ); const module await import(pathToFileURL(join(CLIPS_DIR, file)).href); registry.set(clipId, module.default); console.log([registry] loaded clip: ${clipId}); } } export function getClip(clipId) { const clip registry.get(clipId); if (!clip) throw new Error(Clip not found: ${clipId}); return clip; }这个设计的好处是新增一个夹子只需要在clips/目录下加一个文件不需要改任何注册代码。配合 Node.js 的--watch模式改完夹子代码自动重启开发体验非常顺滑。但这里有个细节要注意动态 import 的模块会被缓存如果你在开发时改了夹子代码--watch重启后缓存会清空所以没问题。但如果你是在生产环境做热更新就需要手动清除 import 缓存或者用 worker 线程来隔离。我目前的做法是生产环境不做热更新夹子变更走完整的部署流程避免状态不一致。3.3 调度层的执行循环串行、并行与条件分支paperclip core 的执行循环支持三种模式串行、并行和条件分支。串行是最简单的按数组顺序依次执行夹子前一个的输出作为后一个的输入。并行是把多个夹子同时执行等全部完成后合并结果。条件分支是根据某个夹子的输出决定下一步走哪个分支。// executor.js export async function executeTask(task, context) { const results []; let prevOutput null; for (const step of task.steps) { if (step.type serial) { const clip getClip(step.clipId); const result await clip.execute({ ...context, prevOutput, globalState: context.globalState, }); results.push({ step: step.clipId, result }); if (!result.success) { if (step.onError continue) continue; break; } prevOutput result.data; } else if (step.type parallel) { const parallelResults await Promise.all( step.clips.map(async (clipId) { const clip getClip(clipId); return clip.execute({ ...context, prevOutput }); }) ); results.push({ step: parallel, results: parallelResults }); prevOutput parallelResults; } else if (step.type branch) { const condition await evaluateCondition(step.condition, prevOutput); const branchSteps condition ? step.then : step.else; const branchResult await executeTask({ steps: branchSteps }, context); results.push({ step: branch, result: branchResult }); prevOutput branchResult; } } return { results, finalOutput: prevOutput }; }这个执行循环看起来简单但实际用起来有几个坑。第一个坑是并行执行时的 globalState 竞争。如果两个并行夹子同时写 globalState 的同一个 key后写的会覆盖先写的。我的解决方案是给 globalState 加一个简单的版本号机制每次写入前检查版本号如果版本号变了就重新读取再写。这个在低并发场景下够用高并发场景建议用更严格的锁机制。第二个坑是条件分支的嵌套。如果分支里面还有分支递归调用 executeTask 会导致 context 的传递变得复杂。我的做法是限制嵌套深度最多三层超过三层就报错强制开发者把逻辑拆成多个任务。这样虽然牺牲了一些灵活性但大大降低了调试难度。4. 实操过程从零搭建一套可运行的 paperclip 系统4.1 环境准备Node.js 22.12 安装与 OpenClaw 部署先说 Node.js 的安装。Ubuntu 22.04 或 24.04 上直接用 NodeSource 的脚本curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs node -v # 应该输出 v22.12.x 或更高CentOS 7.9 上稍微麻烦一点因为 CentOS 7 的 glibc 版本比较老Node.js 22.x 需要 glibc 2.28。如果你非要在 CentOS 7.9 上跑要么升级 glibc风险很大不推荐要么用 Node.js 18.20.4 LTS 版本。但 18.x 不支持node:sqlite所以夹子执行记录得用文件存储或者外部数据库。我的建议是如果条件允许尽量用 Ubuntu 22.04 或者直接上 Docker。Windows 用户去 Node.js 官网下载 22.12 的 msi 安装包双击安装一路下一步记得勾选Add to PATH。装完之后打开 PowerShell输入node -v和npm -v确认安装成功。如果提示不是内部或外部命令说明 PATH 没配好手动把 Node.js 的安装目录加到系统环境变量里。怎么查看有没有安装 Node.js最简单的命令就是node -v。如果输出了版本号说明装好了。如果提示命令找不到那就是没装或者 PATH 有问题。另外可以用which nodeLinux/macOS或where nodeWindows查看 node 命令的实际路径确认是不是你期望的那个版本。OpenClaw 的部署官方推荐用 Docker但如果你想在本地一键部署可以直接用 npm 全局安装npm install -g openclaw openclaw init # 初始化配置 openclaw start # 启动服务OpenClaw 默认会监听 3000 端口配置文件在~/.openclaw/config.json。如果你要接入 Microsoft Teams需要在配置文件里填 Teams 的 webhook URL 和 bot token。这块官方文档写得比较清楚我就不重复了。重点说一下 session 文件锁的问题OpenClaw 默认把所有 Agent 的 session 存在同一个目录下如果你同时跑多个 Agent就会撞锁。解决方案是在配置里给每个 Agent 指定独立的sessionDir{ agents: [ { name: agent1, sessionDir: ./sessions/agent1 }, { name: agent2, sessionDir: ./sessions/agent2 } ] }这样每个 Agent 的 session 文件完全隔离就不会出现 session file locked 的错误了。4.2 第一个夹子readFile 的实现与测试环境准备好之后先写一个最简单的夹子来验证整条链路。在项目根目录建一个clips/文件夹然后创建readFile.js// clips/readFile.js import { readFile } from node:fs/promises; export default { id: readFile, description: 读取指定路径的文件内容, inputSchema: { type: object, properties: { path: { type: string, description: 文件路径 }, encoding: { type: string, default: utf-8 }, }, required: [path], }, async execute(ctx) { const startTime Date.now(); try { const { path, encoding utf-8 } ctx.prevOutput || {}; if (!path) { return { success: false, error: 缺少 path 参数 }; } const content await readFile(path, { encoding }); ctx.log(读取文件成功: ${path}, 长度: ${content.length}); return { success: true, data: { content, path, size: content.length }, meta: { duration: Date.now() - startTime }, }; } catch (err) { return { success: false, error: 读取文件失败: ${err.message}, meta: { duration: Date.now() - startTime }, }; } }, };这个夹子虽然简单但包含了 paperclip 夹子的所有核心要素id、description、inputSchema、execute 方法、日志、错误处理、耗时统计。inputSchema 我用了 JSON Schema 格式主要是为了后续能自动生成前端表单和文档。目前还没做自动校验但结构先定下来后面扩展方便。测试这个夹子可以写一个简单的脚本// test-readfile.js import { loadClips, getClip } from ./clip-registry.js; await loadClips(); const clip getClip(readFile); const result await clip.execute({ prevOutput: { path: ./package.json }, globalState: {}, log: console.log, }); console.log(result);跑一下node test-readfile.js如果看到文件内容和耗时统计说明第一个夹子跑通了。4.3 前端观测面板React SSE 实时展示夹子执行状态前端这块我用 Vite 起了一个 React 项目核心是一个useClipStreamhook负责连接 SSE 并维护夹子状态// useClipStream.js import { useEffect, useReducer, useRef } from react; const initialState { clips: {}, lastEventId: null }; function reducer(state, action) { switch (action.type) { case clip:start: return { ...state, clips: { ...state.clips, [action.clipId]: { status: running, startTime: Date.now() }, }, }; case clip:end: return { ...state, clips: { ...state.clips, [action.clipId]: { ...state.clips[action.clipId], status: action.success ? success : failed, output: action.data, error: action.error, duration: action.duration, }, }, }; case setLastEventId: return { ...state, lastEventId: action.id }; default: return state; } } export function useClipStream(taskId) { const [state, dispatch] useReducer(reducer, initialState); const retryDelay useRef(1000); useEffect(() { let es; let closed false; function connect() { const url /api/tasks/${taskId}/stream?lastEventId${state.lastEventId || }; es new EventSource(url); es.onmessage (event) { retryDelay.current 1000; // 重置退避 const data JSON.parse(event.data); dispatch({ type: data.type, ...data }); if (event.lastEventId) { dispatch({ type: setLastEventId, id: event.lastEventId }); } }; es.onerror () { es.close(); if (closed) return; // 指数退避重连 setTimeout(() { retryDelay.current Math.min(retryDelay.current * 2, 30000); connect(); }, retryDelay.current); }; } connect(); return () { closed true; es?.close(); }; }, [taskId]); return state; }这个 hook 的关键点是断线重连 断点续传。SSE 连接在移动网络下很容易断如果不做重连前端就会一直卡在 loading 状态。重连时带上lastEventId服务端可以从断点继续推送不会丢失中间的事件。这个机制和 React Native 启动白屏的修复思路是一样的核心是让前端知道我上次收到哪里了而不是盲目重连。服务端这边SSE 的实现在 Express 里大概是这样// sse-endpoint.js app.get(/api/tasks/:taskId/stream, (req, res) { res.setHeader(Content-Type, text/event-stream); res.setHeader(Cache-Control, no-cache); res.setHeader(Connection, keep-alive); const taskId req.params.taskId; const lastEventId req.query.lastEventId; // 从事件存储里读取 lastEventId 之后的事件 const events getEventsAfter(taskId, lastEventId); for (const event of events) { res.write(id: ${event.id}\n); res.write(data: ${JSON.stringify(event.data)}\n\n); } // 订阅后续事件 const unsubscribe subscribeToTask(taskId, (event) { res.write(id: ${event.id}\n); res.write(data: ${JSON.stringify(event.data)}\n\n); }); req.on(close, () { unsubscribe(); res.end(); }); });这里有个细节res.write之后不要立即res.end否则连接就断了。SSE 是长连接要保持打开状态直到客户端主动关闭。另外记得设置X-Accel-Buffering: no头防止 Nginx 之类的反向代理缓冲 SSE 数据导致前端收不到实时更新。4.4 一个完整的任务示例从 Obsidian 读取笔记并生成摘要把前面的东西串起来做一个完整的任务从 Obsidian vault 里读取一篇笔记交给 OpenClaw 的 Agent 生成摘要然后把摘要写回一个新的 markdown 文件。任务定义// tasks/summarize-note.js export default { id: summarize-note, steps: [ { type: serial, clipId: readFile, // 输入通过 globalState 传递 }, { type: serial, clipId: callOpenClaw, }, { type: serial, clipId: writeFile, }, ], };callOpenClaw夹子的实现// clips/callOpenClaw.js export default { id: callOpenClaw, description: 调用 OpenClaw Agent 处理文本, async execute(ctx) { const { content } ctx.prevOutput; const prompt 请为以下笔记生成一段 200 字以内的摘要\n\n${content}; const response await fetch(http://localhost:3000/api/agent/run, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ agent: summarizer, input: prompt, sessionDir: ./sessions/summarizer, }), }); if (!response.ok) { return { success: false, error: OpenClaw 调用失败: ${response.status} }; } const result await response.json(); return { success: true, data: { summary: result.output, originalLength: content.length }, }; }, };writeFile夹子// clips/writeFile.js import { writeFile, mkdir } from node:fs/promises; import { dirname } from node:path; export default { id: writeFile, async execute(ctx) { const { summary } ctx.prevOutput; const outputPath ./output/summary-${Date.now()}.md; try { await mkdir(dirname(outputPath), { recursive: true }); await writeFile(outputPath, # 摘要\n\n${summary}\n, utf-8); return { success: true, data: { path: outputPath } }; } catch (err) { return { success: false, error: err.message }; } }, };这个任务跑起来之后前端面板会依次显示 readFile → callOpenClaw → writeFile 三个夹子的状态流转每个夹子的输入输出都能实时看到。如果 callOpenClaw 失败了你能立刻看到是网络问题还是 Agent 返回了错误而不是等整个任务跑完才发现。5. 常见问题与排查技巧实录5.1 OpenClaw session 文件锁超时原因与三种解法agent failed before reply: session file locked (timeout 60000ms) 这个错误我遇到过至少五次每次原因都不太一样。最常见的原因是多个 Agent 实例共享了同一个 session 文件。OpenClaw 的 session 机制是文件级的排他锁一个 Agent 打开 session 文件后其他 Agent 尝试打开同一个文件就会等待等 60 秒还拿不到锁就报这个错。解法一给每个 Agent 配置独立的sessionDir。这是最彻底的方案前面已经讲过配置方法。缺点是 session 文件会变多磁盘占用增加但对于大多数场景来说这点开销可以忽略。解法二如果确实需要共享 session把 Agent 的并发数降到 1。在 OpenClaw 配置里设置maxConcurrent: 1这样同一时间只有一个 Agent 在跑不会撞锁。缺点是吞吐量下降适合低频任务。解法三检查是不是有僵尸进程占着 session 文件。有时候 Agent 异常退出锁没释放后续的 Agent 就会一直等。用lsof | grep session找到占用文件的进程手动 kill 掉。这个在开发环境很常见生产环境建议加一个定时清理任务定期检查并释放超过 5 分钟没活动的锁。5.2 SSE 连接不稳定从 Nginx 配置到心跳机制SSE 在生产环境最常见的问题是连接被中间层掐断。Nginx 默认的proxy_read_timeout是 60 秒如果 60 秒内没有数据传输Nginx 就会断开连接。对于长时间运行的 Agent 任务60 秒没有事件推送是很正常的所以必须调整这个配置location /api/tasks/ { proxy_pass http://localhost:3001; proxy_http_version 1.1; proxy_set_header Connection ; proxy_buffering off; proxy_cache off; proxy_read_timeout 3600s; proxy_send_timeout 3600s; chunked_transfer_encoding off; }另外服务端要加心跳每 15 秒发一个注释行: heartbeat\n\n保持连接活跃。这个注释行不会被 EventSource 解析成事件但能让中间层知道连接还活着。还有一个坑是浏览器的 SSE 连接数限制。HTTP/1.1 下同一个域名最多 6 个并发连接如果开了多个标签页都在连 SSE很容易把连接数占满。解决方案是升级到 HTTP/2或者用 WebSocket 替代 SSE。我目前的做法是观测面板只开一个 SSE 连接多个任务共用这个连接通过事件里的 taskId 来区分。5.3 夹子执行超时与重试参数怎么定才合理夹子的超时时间设置是个经验活。设太短正常的慢操作会被误杀设太长出问题时等半天才报错。我的经验值是文件读写类夹子 5 秒HTTP 请求类夹子 30 秒Agent 调用类夹子 120 秒。这些值不是拍脑袋定的而是根据实际运行的 P99 耗时来调整的。重试策略我用的是指数退避 最大重试次数。第一次失败等 1 秒重试第二次等 2 秒第三次等 4 秒最多重试 3 次。但要注意不是所有失败都值得重试。网络超时、429 限流、503 服务不可用这些可以重试参数错误、文件不存在、权限不足这些重试多少次都没用直接失败就行。所以在夹子的返回值里要区分retryable和non-retryable错误return { success: false, error: API rate limited, meta: { retryable: true, retryAfter: 5000 }, };调度层看到retryable: true就按退避策略重试看到retryable: false就直接终止。5.4 常见问题速查表问题现象可能原因排查方法解决方案session file locked 超时多 Agent 共享 session 文件检查 sessionDir 配置每个 Agent 独立 sessionDirSSE 连接频繁断开Nginx 超时或缓冲查看 Nginx error log调整 proxy_read_timeout关闭 buffering夹子执行卡住不返回异步操作没有超时控制加日志看卡在哪一步给每个夹子加 timeout 包装前端状态不更新SSE 事件 ID 不连续检查 lastEventId 传递服务端保证事件 ID 单调递增OpenClaw 调用返回空Agent 上下文超限查看 Agent 日志截断输入或增加上下文窗口并行夹子结果错乱globalState 竞争写入检查并行夹子的写入 key加版本号或改用串行Node.js 版本不兼容用了 18.x 但依赖需要 22.xnode -v确认版本升级到 22.12 LTSReact 面板白屏SSE 连接失败且无重连浏览器控制台看错误加指数退避重连逻辑这张表里的每一条都是我实际踩过的坑不是从文档里抄的。特别是 并行夹子结果错乱 这一条当时排查了整整一个下午最后发现是两个并行夹子同时写 globalState 的同一个 key后写的把先写的覆盖了。加版本号之后问题解决但性能有一点损耗后来改成并行夹子只读不写需要写的结果通过返回值合并性能就回来了。6. 一些关于手写 React Agent 和 paperclip 配合的思考手写 React Agent 和 paperclip 其实是两种不同层面的东西。手写 React Agent 关注的是Agent 怎么思考paperclip 关注的是Agent 怎么执行。两者可以配合但不应该混在一起。我的做法是Agent 的推理逻辑完全交给 OpenClaw 或者自己写的 Agent 循环paperclip 只负责把 Agent 的输出转化成具体的工具调用并管理这些调用的生命周期。举个例子Agent 决定我需要读取 config.json 文件这个决策是 Agent 做的。但具体怎么读、读完之后怎么解析、解析失败怎么重试这些是 paperclip 的夹子负责的。这样分工的好处是Agent 的 prompt 可以保持简洁不需要包含大量的工具使用细节而夹子的实现可以独立测试和优化不受 Agent 模型变化的影响。React 在这个架构里的角色也值得再强调一下。很多人把 React 只当成 UI 框架但在 paperclip 里React 的状态管理能力才是核心。每个夹子的执行状态、输入输出、错误信息本质上都是状态。用 React 的 reducer 来管理这些状态配合 SSE 的增量更新可以实现非常细粒度的观测。而且这种模式可以复用到 React Native 上做移动端的 Agent 监控面板。React Native 启动白屏的问题在加了 SSE 重连和本地状态缓存之后基本不会再出现了。最后说一个我个人的体会paperclip 这套东西的价值不在于技术有多复杂而在于它把 Agent 的执行过程变得可见、可控、可调试。在没有这套东西之前Agent 对我来说就是个黑盒输入进去等半天出来一个结果中间发生了什么完全不知道。有了 paperclip 之后我能看到每一步的输入输出能在某个夹子失败时手动重试能对比不同参数下的执行耗时。这种掌控感是让 Agent 从玩具变成工具的关键一步。如果你也在用 OpenClaw 或者类似的 Agent 运行时我强烈建议你花点时间搭一套自己的 paperclip。不需要很完整哪怕只是把最常用的几个操作封装成夹子加上一个简单的 SSE 观测面板你对 Agent 行为的理解就会完全不一样。踩过的坑都会变成经验而这些经验是任何文档都给不了的。 Paperclip AI Agent 编排实战：Node.js + React + OpenClaw 从零搭建
1. 从 paperclip 这个名字说起一个被低估的 AI Agent 编排思路第一次看到 paperclip 这个词大部分人脑子里蹦出来的可能是那个经典的回形针助手——微软 Office 里那个总爱跳出来问需要帮忙吗的小动画。但在 2026 年的技术语境下paperclip 已经变成了一个很有意思的隐喻一个轻量、可插拔、随时待命的 AI Agent 编排层。它不抢戏不喧宾夺主但当你需要它的时候它就在那里帮你把散落各处的工具、模型、数据流串成一条能跑通的链路。我最近花了两周时间基于 Node.js React 的技术栈配合 OpenClaw 这类 Agent 运行时从零搭了一套 paperclip 风格的 Agent 编排系统。踩了不少坑也攒了一些在官方文档里绝对找不到的经验。这篇文章就是把这套东西完整拆开从设计思路到代码实现从环境配置到线上排查全部摊开讲。不管你是刚接触 AI Agent 的新手还是已经在用 OpenClaw 做自动化流程的老手应该都能从里面捞到点能直接用的东西。先明确一下 paperclip 在这个语境下到底指什么。它不是某个具体的 npm 包也不是某个框架的官方名字而是一种架构模式把 AI Agent 的能力拆成一个个独立的、可复用的夹子clip每个夹子负责一个明确的职责——比如读文件、调 API、跑命令、发消息——然后由一个轻量的调度层paperclip core根据任务上下文动态地把这些夹子组合起来执行。这个思路和 OpenClaw 的 Agent 编排理念高度契合但 paperclip 更强调最小化依赖和前端可观测。为什么是 Node.js React因为这套东西的核心诉求是实时反馈和跨端复用。Node.js 的事件驱动模型天然适合处理 Agent 的异步任务流而 React 的组件化思维可以直接映射到 Agent 的夹子可视化上。你可以在浏览器里实时看到每个夹子的状态、输入输出、耗时甚至能手动干预某个夹子的执行。这种人在回路的体验是纯后端 Agent 框架很难给到的。适合谁来读如果你正在用 OpenClaw 做自动化但觉得它的默认编排太黑盒想自己掌控每一步或者你是个前端工程师想把手写 React Agent 的能力扩展到真实的后端任务上又或者你只是好奇 AI Agent 到底是怎么跑起来的想从零搭一个能跑的最小系统——那这篇内容就是写给你的。我会尽量把每个技术决策背后的为什么讲清楚而不是只丢一堆代码让你抄。2. 整体架构设计为什么选择 Node.js React OpenClaw 这套组合2.1 核心设计原则夹子要小调度要薄观测要厚paperclip 架构的第一原则是夹子必须足够小。一个夹子只做一件事比如读取指定路径的文件内容、向指定 URL 发送 POST 请求、执行一条 shell 命令并返回 stdout。为什么因为 Agent 的可靠性瓶颈往往不在模型本身而在工具调用的边界处理上。夹子越小输入输出的契约就越清晰出错时定位问题的成本就越低。我试过把读取文件并解析 JSON 并提取某个字段做成一个夹子结果就是每次 JSON 格式有变化这个夹子就得改而且改完之后所有依赖它的流程都得重新测。后来拆成三个夹子readFile、parseJSON、pickField每个夹子只关心自己的输入输出组合逻辑交给调度层。这样任何一个环节出问题我只需要替换那一个夹子其他部分完全不受影响。第二原则是调度层要薄。paperclip core 本身不应该包含任何业务逻辑它只负责三件事解析任务描述、按顺序调用夹子、把夹子的输出传递给下一个夹子。所有的智能都来自夹子本身的实现和夹子之间的组合方式。这样做的好处是调度层可以做得非常稳定几乎不需要改动而业务逻辑的变化全部收敛在夹子层面。第三原则是观测要厚。每个夹子的执行都必须留下完整的痕迹输入是什么、输出是什么、耗时多少、有没有报错、报错信息是什么。这些数据不仅要写日志还要通过 SSE 或 WebSocket 实时推送到前端。为什么这么强调观测因为 Agent 的行为本质上是非确定性的同样的输入可能因为模型温度、上下文长度、外部 API 状态等因素产生不同的输出。没有厚实的观测层你根本不知道 Agent 到底在干什么。2.2 技术选型背后的权衡Node.js 22.12 与 React 19 的配合Node.js 这边我选的是 22.12 LTS 版本。为什么不用 18.20.4因为 22.x 对 WebSocket 的原生支持更完善而且node:sqlite模块已经稳定可以直接用来做夹子执行记录的本地存储不需要额外引入 better-sqlite3 这种需要编译的依赖。另外 22.x 的--watch模式在开发时非常方便改完夹子代码自动重启省去了 nodemon 的配置。安装 Node.js 这块如果你是在 Ubuntu 上部署 OpenClaw我建议直接用 NodeSource 的仓库装不要用系统自带的 apt 版本。系统自带的往往版本太老而且和 OpenClaw 的依赖容易冲突。具体命令后面实操部分会详细写。Windows 用户直接去官网下 22.12 的 msi 安装包就行安装时记得勾选Add to PATH不然命令行里找不到 node 命令。React 这边我用的是 19 的 canary 版本主要是看中了usehook 和 Server Components 的成熟度。但在 paperclip 这个场景里React 的核心作用不是渲染页面而是管理夹子执行状态的前端状态机。每个夹子在前端对应一个状态节点状态流转是pending → running → success / failed。用 React 的 reducer 来管理这些状态配合 SSE 推送的增量更新可以实现非常流畅的实时观测体验。这里有个坑要提前说React Native 启动白屏的问题在 paperclip 的移动端观测场景里也遇到过。原因是 SSE 连接在移动网络下容易断断了之后前端没有正确的重连逻辑导致状态一直卡在 loading。解决方案是在 SSE 的 onerror 回调里加指数退避重连并且在前端维护一个最后收到的事件 ID重连时带上这个 ID让服务端从断点继续推送。这个后面会详细讲。2.3 OpenClaw 在架构中的角色运行时还是编排器OpenClaw 在这套架构里扮演的是Agent 运行时的角色而不是编排器。编排逻辑由 paperclip core 自己控制OpenClaw 只负责提供 Agent 的基础能力模型调用、上下文管理、工具注册。这样设计的好处是我可以随时替换掉 OpenClaw换成其他的 Agent 运行时而 paperclip 的夹子和调度逻辑完全不用改。但 OpenClaw 有个特性需要特别注意它的 session 文件锁机制。如果你在 OpenClaw 里同时跑多个 Agent 实例而且它们共享同一个 session 文件就会出现 agent failed before reply: session file locked (timeout 60000ms) 这个错误。我一开始没注意起了三个 Agent 做并发测试结果全部卡死。后来改成每个 Agent 实例用独立的 session 文件路径问题就解决了。这个坑在后面常见问题部分会再展开。另外 OpenClaw 和 Obsidian 的集成也值得提一句。如果你用 Obsidian 做知识库OpenClaw 可以直接读取 vault 里的 markdown 文件作为 Agent 的上下文。paperclip 的 readFile 夹子可以和这个能力配合实现从知识库检索 → 交给 Agent 处理 → 结果写回知识库的闭环。这个场景在实际用起来非常顺手后面实操部分会给一个完整的例子。3. 核心细节解析夹子的设计、实现与注册机制3.1 夹子的接口契约输入、输出与错误处理每个夹子本质上是一个符合特定接口的 JavaScript 对象。我定义的接口是这样的// clip.interface.js /** * typedef {Object} ClipContext * property {string} taskId - 当前任务 ID * property {Object} prevOutput - 上一个夹子的输出 * property {Object} globalState - 全局状态所有夹子共享 * property {Function} log - 日志函数会推送到前端 */ /** * typedef {Object} ClipResult * property {boolean} success - 是否成功 * property {any} data - 成功时的输出数据 * property {string} [error] - 失败时的错误信息 * property {Object} [meta] - 元信息如耗时、重试次数等 */为什么要把prevOutput和globalState分开因为prevOutput是管道式的只关心上一个夹子的直接输出适合线性流程而globalState是共享的任何夹子都可以读写适合需要跨步骤传递状态的场景。比如一个发送邮件的夹子可能需要用到前面生成报告夹子的输出同时也需要用到更早的获取用户配置夹子写入 globalState 的邮箱地址。错误处理这块我强制要求每个夹子返回ClipResult对象而不是直接 throw。为什么因为 throw 会中断整个执行链而返回success: false可以让调度层决定是重试、跳过还是终止。比如调用外部 API的夹子如果遇到 429 限流可以返回失败并附带retryAfter元信息调度层看到这个就自动等待后重试而不是直接崩掉整个任务。3.2 夹子注册表动态发现与热加载夹子的注册我用了文件系统扫描 动态 import 的方式。所有夹子放在clips/目录下每个夹子一个文件文件名就是夹子 ID。调度层启动时扫描这个目录动态 import 每个文件把导出的对象注册到内存里的 Map 中。// clip-registry.js import { readdir } from node:fs/promises; import { join } from node:path; import { pathToFileURL } from node:url; const CLIPS_DIR join(process.cwd(), clips); const registry new Map(); export async function loadClips() { const files await readdir(CLIPS_DIR); for (const file of files) { if (!file.endsWith(.js)) continue; const clipId file.replace(.js, ); const module await import(pathToFileURL(join(CLIPS_DIR, file)).href); registry.set(clipId, module.default); console.log([registry] loaded clip: ${clipId}); } } export function getClip(clipId) { const clip registry.get(clipId); if (!clip) throw new Error(Clip not found: ${clipId}); return clip; }这个设计的好处是新增一个夹子只需要在clips/目录下加一个文件不需要改任何注册代码。配合 Node.js 的--watch模式改完夹子代码自动重启开发体验非常顺滑。但这里有个细节要注意动态 import 的模块会被缓存如果你在开发时改了夹子代码--watch重启后缓存会清空所以没问题。但如果你是在生产环境做热更新就需要手动清除 import 缓存或者用 worker 线程来隔离。我目前的做法是生产环境不做热更新夹子变更走完整的部署流程避免状态不一致。3.3 调度层的执行循环串行、并行与条件分支paperclip core 的执行循环支持三种模式串行、并行和条件分支。串行是最简单的按数组顺序依次执行夹子前一个的输出作为后一个的输入。并行是把多个夹子同时执行等全部完成后合并结果。条件分支是根据某个夹子的输出决定下一步走哪个分支。// executor.js export async function executeTask(task, context) { const results []; let prevOutput null; for (const step of task.steps) { if (step.type serial) { const clip getClip(step.clipId); const result await clip.execute({ ...context, prevOutput, globalState: context.globalState, }); results.push({ step: step.clipId, result }); if (!result.success) { if (step.onError continue) continue; break; } prevOutput result.data; } else if (step.type parallel) { const parallelResults await Promise.all( step.clips.map(async (clipId) { const clip getClip(clipId); return clip.execute({ ...context, prevOutput }); }) ); results.push({ step: parallel, results: parallelResults }); prevOutput parallelResults; } else if (step.type branch) { const condition await evaluateCondition(step.condition, prevOutput); const branchSteps condition ? step.then : step.else; const branchResult await executeTask({ steps: branchSteps }, context); results.push({ step: branch, result: branchResult }); prevOutput branchResult; } } return { results, finalOutput: prevOutput }; }这个执行循环看起来简单但实际用起来有几个坑。第一个坑是并行执行时的 globalState 竞争。如果两个并行夹子同时写 globalState 的同一个 key后写的会覆盖先写的。我的解决方案是给 globalState 加一个简单的版本号机制每次写入前检查版本号如果版本号变了就重新读取再写。这个在低并发场景下够用高并发场景建议用更严格的锁机制。第二个坑是条件分支的嵌套。如果分支里面还有分支递归调用 executeTask 会导致 context 的传递变得复杂。我的做法是限制嵌套深度最多三层超过三层就报错强制开发者把逻辑拆成多个任务。这样虽然牺牲了一些灵活性但大大降低了调试难度。4. 实操过程从零搭建一套可运行的 paperclip 系统4.1 环境准备Node.js 22.12 安装与 OpenClaw 部署先说 Node.js 的安装。Ubuntu 22.04 或 24.04 上直接用 NodeSource 的脚本curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs node -v # 应该输出 v22.12.x 或更高CentOS 7.9 上稍微麻烦一点因为 CentOS 7 的 glibc 版本比较老Node.js 22.x 需要 glibc 2.28。如果你非要在 CentOS 7.9 上跑要么升级 glibc风险很大不推荐要么用 Node.js 18.20.4 LTS 版本。但 18.x 不支持node:sqlite所以夹子执行记录得用文件存储或者外部数据库。我的建议是如果条件允许尽量用 Ubuntu 22.04 或者直接上 Docker。Windows 用户去 Node.js 官网下载 22.12 的 msi 安装包双击安装一路下一步记得勾选Add to PATH。装完之后打开 PowerShell输入node -v和npm -v确认安装成功。如果提示不是内部或外部命令说明 PATH 没配好手动把 Node.js 的安装目录加到系统环境变量里。怎么查看有没有安装 Node.js最简单的命令就是node -v。如果输出了版本号说明装好了。如果提示命令找不到那就是没装或者 PATH 有问题。另外可以用which nodeLinux/macOS或where nodeWindows查看 node 命令的实际路径确认是不是你期望的那个版本。OpenClaw 的部署官方推荐用 Docker但如果你想在本地一键部署可以直接用 npm 全局安装npm install -g openclaw openclaw init # 初始化配置 openclaw start # 启动服务OpenClaw 默认会监听 3000 端口配置文件在~/.openclaw/config.json。如果你要接入 Microsoft Teams需要在配置文件里填 Teams 的 webhook URL 和 bot token。这块官方文档写得比较清楚我就不重复了。重点说一下 session 文件锁的问题OpenClaw 默认把所有 Agent 的 session 存在同一个目录下如果你同时跑多个 Agent就会撞锁。解决方案是在配置里给每个 Agent 指定独立的sessionDir{ agents: [ { name: agent1, sessionDir: ./sessions/agent1 }, { name: agent2, sessionDir: ./sessions/agent2 } ] }这样每个 Agent 的 session 文件完全隔离就不会出现 session file locked 的错误了。4.2 第一个夹子readFile 的实现与测试环境准备好之后先写一个最简单的夹子来验证整条链路。在项目根目录建一个clips/文件夹然后创建readFile.js// clips/readFile.js import { readFile } from node:fs/promises; export default { id: readFile, description: 读取指定路径的文件内容, inputSchema: { type: object, properties: { path: { type: string, description: 文件路径 }, encoding: { type: string, default: utf-8 }, }, required: [path], }, async execute(ctx) { const startTime Date.now(); try { const { path, encoding utf-8 } ctx.prevOutput || {}; if (!path) { return { success: false, error: 缺少 path 参数 }; } const content await readFile(path, { encoding }); ctx.log(读取文件成功: ${path}, 长度: ${content.length}); return { success: true, data: { content, path, size: content.length }, meta: { duration: Date.now() - startTime }, }; } catch (err) { return { success: false, error: 读取文件失败: ${err.message}, meta: { duration: Date.now() - startTime }, }; } }, };这个夹子虽然简单但包含了 paperclip 夹子的所有核心要素id、description、inputSchema、execute 方法、日志、错误处理、耗时统计。inputSchema 我用了 JSON Schema 格式主要是为了后续能自动生成前端表单和文档。目前还没做自动校验但结构先定下来后面扩展方便。测试这个夹子可以写一个简单的脚本// test-readfile.js import { loadClips, getClip } from ./clip-registry.js; await loadClips(); const clip getClip(readFile); const result await clip.execute({ prevOutput: { path: ./package.json }, globalState: {}, log: console.log, }); console.log(result);跑一下node test-readfile.js如果看到文件内容和耗时统计说明第一个夹子跑通了。4.3 前端观测面板React SSE 实时展示夹子执行状态前端这块我用 Vite 起了一个 React 项目核心是一个useClipStreamhook负责连接 SSE 并维护夹子状态// useClipStream.js import { useEffect, useReducer, useRef } from react; const initialState { clips: {}, lastEventId: null }; function reducer(state, action) { switch (action.type) { case clip:start: return { ...state, clips: { ...state.clips, [action.clipId]: { status: running, startTime: Date.now() }, }, }; case clip:end: return { ...state, clips: { ...state.clips, [action.clipId]: { ...state.clips[action.clipId], status: action.success ? success : failed, output: action.data, error: action.error, duration: action.duration, }, }, }; case setLastEventId: return { ...state, lastEventId: action.id }; default: return state; } } export function useClipStream(taskId) { const [state, dispatch] useReducer(reducer, initialState); const retryDelay useRef(1000); useEffect(() { let es; let closed false; function connect() { const url /api/tasks/${taskId}/stream?lastEventId${state.lastEventId || }; es new EventSource(url); es.onmessage (event) { retryDelay.current 1000; // 重置退避 const data JSON.parse(event.data); dispatch({ type: data.type, ...data }); if (event.lastEventId) { dispatch({ type: setLastEventId, id: event.lastEventId }); } }; es.onerror () { es.close(); if (closed) return; // 指数退避重连 setTimeout(() { retryDelay.current Math.min(retryDelay.current * 2, 30000); connect(); }, retryDelay.current); }; } connect(); return () { closed true; es?.close(); }; }, [taskId]); return state; }这个 hook 的关键点是断线重连 断点续传。SSE 连接在移动网络下很容易断如果不做重连前端就会一直卡在 loading 状态。重连时带上lastEventId服务端可以从断点继续推送不会丢失中间的事件。这个机制和 React Native 启动白屏的修复思路是一样的核心是让前端知道我上次收到哪里了而不是盲目重连。服务端这边SSE 的实现在 Express 里大概是这样// sse-endpoint.js app.get(/api/tasks/:taskId/stream, (req, res) { res.setHeader(Content-Type, text/event-stream); res.setHeader(Cache-Control, no-cache); res.setHeader(Connection, keep-alive); const taskId req.params.taskId; const lastEventId req.query.lastEventId; // 从事件存储里读取 lastEventId 之后的事件 const events getEventsAfter(taskId, lastEventId); for (const event of events) { res.write(id: ${event.id}\n); res.write(data: ${JSON.stringify(event.data)}\n\n); } // 订阅后续事件 const unsubscribe subscribeToTask(taskId, (event) { res.write(id: ${event.id}\n); res.write(data: ${JSON.stringify(event.data)}\n\n); }); req.on(close, () { unsubscribe(); res.end(); }); });这里有个细节res.write之后不要立即res.end否则连接就断了。SSE 是长连接要保持打开状态直到客户端主动关闭。另外记得设置X-Accel-Buffering: no头防止 Nginx 之类的反向代理缓冲 SSE 数据导致前端收不到实时更新。4.4 一个完整的任务示例从 Obsidian 读取笔记并生成摘要把前面的东西串起来做一个完整的任务从 Obsidian vault 里读取一篇笔记交给 OpenClaw 的 Agent 生成摘要然后把摘要写回一个新的 markdown 文件。任务定义// tasks/summarize-note.js export default { id: summarize-note, steps: [ { type: serial, clipId: readFile, // 输入通过 globalState 传递 }, { type: serial, clipId: callOpenClaw, }, { type: serial, clipId: writeFile, }, ], };callOpenClaw夹子的实现// clips/callOpenClaw.js export default { id: callOpenClaw, description: 调用 OpenClaw Agent 处理文本, async execute(ctx) { const { content } ctx.prevOutput; const prompt 请为以下笔记生成一段 200 字以内的摘要\n\n${content}; const response await fetch(http://localhost:3000/api/agent/run, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ agent: summarizer, input: prompt, sessionDir: ./sessions/summarizer, }), }); if (!response.ok) { return { success: false, error: OpenClaw 调用失败: ${response.status} }; } const result await response.json(); return { success: true, data: { summary: result.output, originalLength: content.length }, }; }, };writeFile夹子// clips/writeFile.js import { writeFile, mkdir } from node:fs/promises; import { dirname } from node:path; export default { id: writeFile, async execute(ctx) { const { summary } ctx.prevOutput; const outputPath ./output/summary-${Date.now()}.md; try { await mkdir(dirname(outputPath), { recursive: true }); await writeFile(outputPath, # 摘要\n\n${summary}\n, utf-8); return { success: true, data: { path: outputPath } }; } catch (err) { return { success: false, error: err.message }; } }, };这个任务跑起来之后前端面板会依次显示 readFile → callOpenClaw → writeFile 三个夹子的状态流转每个夹子的输入输出都能实时看到。如果 callOpenClaw 失败了你能立刻看到是网络问题还是 Agent 返回了错误而不是等整个任务跑完才发现。5. 常见问题与排查技巧实录5.1 OpenClaw session 文件锁超时原因与三种解法agent failed before reply: session file locked (timeout 60000ms) 这个错误我遇到过至少五次每次原因都不太一样。最常见的原因是多个 Agent 实例共享了同一个 session 文件。OpenClaw 的 session 机制是文件级的排他锁一个 Agent 打开 session 文件后其他 Agent 尝试打开同一个文件就会等待等 60 秒还拿不到锁就报这个错。解法一给每个 Agent 配置独立的sessionDir。这是最彻底的方案前面已经讲过配置方法。缺点是 session 文件会变多磁盘占用增加但对于大多数场景来说这点开销可以忽略。解法二如果确实需要共享 session把 Agent 的并发数降到 1。在 OpenClaw 配置里设置maxConcurrent: 1这样同一时间只有一个 Agent 在跑不会撞锁。缺点是吞吐量下降适合低频任务。解法三检查是不是有僵尸进程占着 session 文件。有时候 Agent 异常退出锁没释放后续的 Agent 就会一直等。用lsof | grep session找到占用文件的进程手动 kill 掉。这个在开发环境很常见生产环境建议加一个定时清理任务定期检查并释放超过 5 分钟没活动的锁。5.2 SSE 连接不稳定从 Nginx 配置到心跳机制SSE 在生产环境最常见的问题是连接被中间层掐断。Nginx 默认的proxy_read_timeout是 60 秒如果 60 秒内没有数据传输Nginx 就会断开连接。对于长时间运行的 Agent 任务60 秒没有事件推送是很正常的所以必须调整这个配置location /api/tasks/ { proxy_pass http://localhost:3001; proxy_http_version 1.1; proxy_set_header Connection ; proxy_buffering off; proxy_cache off; proxy_read_timeout 3600s; proxy_send_timeout 3600s; chunked_transfer_encoding off; }另外服务端要加心跳每 15 秒发一个注释行: heartbeat\n\n保持连接活跃。这个注释行不会被 EventSource 解析成事件但能让中间层知道连接还活着。还有一个坑是浏览器的 SSE 连接数限制。HTTP/1.1 下同一个域名最多 6 个并发连接如果开了多个标签页都在连 SSE很容易把连接数占满。解决方案是升级到 HTTP/2或者用 WebSocket 替代 SSE。我目前的做法是观测面板只开一个 SSE 连接多个任务共用这个连接通过事件里的 taskId 来区分。5.3 夹子执行超时与重试参数怎么定才合理夹子的超时时间设置是个经验活。设太短正常的慢操作会被误杀设太长出问题时等半天才报错。我的经验值是文件读写类夹子 5 秒HTTP 请求类夹子 30 秒Agent 调用类夹子 120 秒。这些值不是拍脑袋定的而是根据实际运行的 P99 耗时来调整的。重试策略我用的是指数退避 最大重试次数。第一次失败等 1 秒重试第二次等 2 秒第三次等 4 秒最多重试 3 次。但要注意不是所有失败都值得重试。网络超时、429 限流、503 服务不可用这些可以重试参数错误、文件不存在、权限不足这些重试多少次都没用直接失败就行。所以在夹子的返回值里要区分retryable和non-retryable错误return { success: false, error: API rate limited, meta: { retryable: true, retryAfter: 5000 }, };调度层看到retryable: true就按退避策略重试看到retryable: false就直接终止。5.4 常见问题速查表问题现象可能原因排查方法解决方案session file locked 超时多 Agent 共享 session 文件检查 sessionDir 配置每个 Agent 独立 sessionDirSSE 连接频繁断开Nginx 超时或缓冲查看 Nginx error log调整 proxy_read_timeout关闭 buffering夹子执行卡住不返回异步操作没有超时控制加日志看卡在哪一步给每个夹子加 timeout 包装前端状态不更新SSE 事件 ID 不连续检查 lastEventId 传递服务端保证事件 ID 单调递增OpenClaw 调用返回空Agent 上下文超限查看 Agent 日志截断输入或增加上下文窗口并行夹子结果错乱globalState 竞争写入检查并行夹子的写入 key加版本号或改用串行Node.js 版本不兼容用了 18.x 但依赖需要 22.xnode -v确认版本升级到 22.12 LTSReact 面板白屏SSE 连接失败且无重连浏览器控制台看错误加指数退避重连逻辑这张表里的每一条都是我实际踩过的坑不是从文档里抄的。特别是 并行夹子结果错乱 这一条当时排查了整整一个下午最后发现是两个并行夹子同时写 globalState 的同一个 key后写的把先写的覆盖了。加版本号之后问题解决但性能有一点损耗后来改成并行夹子只读不写需要写的结果通过返回值合并性能就回来了。6. 一些关于手写 React Agent 和 paperclip 配合的思考手写 React Agent 和 paperclip 其实是两种不同层面的东西。手写 React Agent 关注的是Agent 怎么思考paperclip 关注的是Agent 怎么执行。两者可以配合但不应该混在一起。我的做法是Agent 的推理逻辑完全交给 OpenClaw 或者自己写的 Agent 循环paperclip 只负责把 Agent 的输出转化成具体的工具调用并管理这些调用的生命周期。举个例子Agent 决定我需要读取 config.json 文件这个决策是 Agent 做的。但具体怎么读、读完之后怎么解析、解析失败怎么重试这些是 paperclip 的夹子负责的。这样分工的好处是Agent 的 prompt 可以保持简洁不需要包含大量的工具使用细节而夹子的实现可以独立测试和优化不受 Agent 模型变化的影响。React 在这个架构里的角色也值得再强调一下。很多人把 React 只当成 UI 框架但在 paperclip 里React 的状态管理能力才是核心。每个夹子的执行状态、输入输出、错误信息本质上都是状态。用 React 的 reducer 来管理这些状态配合 SSE 的增量更新可以实现非常细粒度的观测。而且这种模式可以复用到 React Native 上做移动端的 Agent 监控面板。React Native 启动白屏的问题在加了 SSE 重连和本地状态缓存之后基本不会再出现了。最后说一个我个人的体会paperclip 这套东西的价值不在于技术有多复杂而在于它把 Agent 的执行过程变得可见、可控、可调试。在没有这套东西之前Agent 对我来说就是个黑盒输入进去等半天出来一个结果中间发生了什么完全不知道。有了 paperclip 之后我能看到每一步的输入输出能在某个夹子失败时手动重试能对比不同参数下的执行耗时。这种掌控感是让 Agent 从玩具变成工具的关键一步。如果你也在用 OpenClaw 或者类似的 Agent 运行时我强烈建议你花点时间搭一套自己的 paperclip。不需要很完整哪怕只是把最常用的几个操作封装成夹子加上一个简单的 SSE 观测面板你对 Agent 行为的理解就会完全不一样。踩过的坑都会变成经验而这些经验是任何文档都给不了的。