1. 项目概述Paperclip 不是回形针而是一个面向 AI Agent 开发的轻量级 React 运行时框架你搜“paperclip”第一反应可能是办公桌抽屉里那枚银色小金属件——但在这个技术语境下Paperclip 是一个专为构建可组合、可调试、可热重载的 AI Agent 而设计的 React 原生运行时环境。它不是 UI 组件库不是状态管理工具更不是另一个前端脚手架它是把 React 的声明式心智模型、Hooks 的生命周期语义、以及现代 AI Agent 所需的异步流控、工具调用追踪、上下文快照能力三者拧成一股绳的底层执行引擎。我第一次在 OpenClaw 社区看到 Paperclip 的 demo 时正卡在用纯 React Zustand 写一个带记忆回溯的客服 Agent 上——每次用户说“回到上一步”我就得手动 patch state、重置 hooks、清空 pending promise 队列像在修一台没有说明书的老式收音机。Paperclip 直接把这件事抽象成了Agent step{currentStep} /一个 props 就搞定。它背后不依赖任何浏览器 DOM也不绑定特定 LLM 接口而是通过一套极简的useTool,useMemory,useEvent等自定义 Hook让开发者能像写普通 React 页面一样写 Agent 逻辑组件即节点props 即输入return 值即输出动作tool call / message / state update整个执行流天然支持 React DevTools 调试、React Strict Mode 检查、甚至 React Server Components 的 SSR 渲染路径。这解释了为什么所有热词都绕不开 Node.js 和 React——Paperclip 的核心 runtime 是纯 JavaScript既能在浏览器里跑用于前端 Agent UI也能在 Node.js 环境里跑用于服务端 Agent 编排而 OpenClaw 正是它最典型的落地场景一个基于 Paperclip 构建的、开箱支持 Obsidian 插件、Teams 集成、阿里云部署的开源 AI Agent 平台。如果你正在被“react agent 怎么写”、“openclaw 部署总报错”、“node.js 安装完找不到 global module”这些问题反复折磨那么 Paperclip 就是你该从根子上理解的那个“缺失环节”。2. 核心架构设计与选型逻辑为什么不用 Next.js 或 Express为什么必须是 React2.1 不是“用 React 写 Agent”而是“让 Agent 成为 React 组件”绝大多数 AI Agent 框架比如 LangChain 的 JS 版、LlamaIndex 的 pipeline走的是传统函数式编排路线定义 chain → 注入 prompt → 调用 model → 解析 output → 触发下一个 tool。这种模式写复杂业务时极易失控——一个客服流程可能涉及 7 层嵌套回调、3 种 memory 存储介质、5 类 error fallback 策略最后代码变成意大利面条。Paperclip 的破局点在于彻底倒置控制权它不让你写“执行流程”而是让你声明“当前状态下的合法行为集合”。举个真实例子一个机票改签 Agent传统写法要写if (userSays 我想改签) { callSearchFlights(); } else if (userSays.includes(价格)) { callGetPrice(); }...Paperclip 写法则是function ChangeFlightAgent({ context }) { const [step, setStep] useStatesearch | select | confirm(search); useEffect(() { if (context.intent change_flight) setStep(search); }, [context.intent]); if (step search) { return SearchFlights onResult{r setStep(select)} /; } if (step select) { return SelectFlight flights{context.flights} onSelect{f { context.setBooking(f); setStep(confirm); }} /; } return ConfirmBooking booking{context.booking} onSubmit{submit} /; }看到没没有 callback hell没有手动状态同步没有跨函数传递 context 对象——React 的 re-render 机制天然保证了 UIAgent 行为与数据context的一致性。Paperclip 的 runtime 就是这套模式的执行器它监听组件返回的特殊 symbol如Symbol.for(tool_call)捕获useTool(search_flights, { date, from, to })这样的 Hook 调用将其序列化为标准 action交由外部 executor比如 OpenClaw 的 tool router执行再把结果注入新的 context 触发下一次 render。这正是它必须深度耦合 React 的根本原因——不是为了画界面而是为了复用 React 最成熟、最稳定、最被开发者信任的状态同步与副作用调度模型。我试过用 Vue 的 Composition API 模拟类似逻辑结果在 deep reactive proxy 和 async setup 执行时机上踩了至少 4 个坑用 Svelte 的$:声明式响应也因缺乏统一的 effect cleanup 机制导致内存泄漏。React 的useEffectuseStateuseReducer这套组合经过十年生产验证是目前唯一能把“状态变更 → 副作用触发 → 新状态生成”这个闭环做得既清晰又可靠的方案。2.2 Node.js 的角色不是服务器而是 Agent 的“操作系统内核”网络热词里反复出现 “node.js 安装”、“centos 7.9 node.js 部署”很多人误以为 Paperclip 是个需要 nginx 反向代理的 Web 应用。错了。Node.js 在 Paperclip 生态里扮演的是 Agent 运行时Runtime和工具执行器Tool Executor的宿主环境类比操作系统的 kernel。具体来说Paperclip 的核心包paperclip/runtime是纯 ESM 模块无任何 browser-only API 依赖可在 Node.js 18推荐 20.12直接importOpenClaw 的agent-server进程本质就是启动一个 Node.js 实例加载 Paperclip runtime然后注册一串tool函数如searchFlights,bookHotel,sendEmail每个 tool 都是一个标准 Node.js 函数可调用数据库、HTTP API、本地文件系统当前端React App通过 SSE 或 WebSocket 发来用户消息OpenClaw 的 server 不是转发给 LLM而是将消息构造成context对象传给 Paperclip runtime 的render()方法runtime 执行 Agent 组件捕获到useTool调用后就去匹配已注册的 tool 并执行——整个过程完全脱离 HTTP 生命周期是纯粹的 JS 函数调用。这就解释了为什么wsl --status和powershell报错如此高频Windows 用户在 WSL2 里装 Node.js常因/mnt/c/路径权限、Windows Defender 实时扫描、或 WSL2 的 systemd 未启用导致npm install时node-gyp编译 native addon 失败进而让 OpenClaw 的sqlite3或obsidian-api工具无法加载。我在阿里云 ECSCentOS 7.9部署时也遇到过经典问题系统自带的 OpenSSL 版本太老Node.js 20 编译时提示error:0308010C:digital envelope routines::unsupported最终解决方案不是降级 Node.js而是用nvm安装时指定--openssl-install-dir参数指向新版 OpenSSL。这些都不是 Paperclip 的 bug而是它对 Node.js 运行时环境的“零容忍”——它不封装兼容层不提供 polyfill因为它要确保每一个useTool调用都能获得 Node.js 原生的 I/O 性能和错误堆栈精度。所以当你看到 “openclaw 无法安全验证 sl2 环境”别急着搜教程先运行node -v npm -v node -p process.versions看清楚 OpenSSL、V8、UV 版本号这才是真正的起点。2.3 OpenClaw 与 Paperclip不是父子关系而是“应用层协议”与“传输层协议”的协作很多初学者把 OpenClaw 当成 Paperclip 的“官方 GUI”这是巨大误解。Paperclip 是一个specification规范定义了 Agent 组件如何声明、如何通信、如何序列化状态OpenClaw 是一个implementation实现它遵循 Paperclip spec但增加了大量企业级能力Teams 集成用的是 Microsoft Graph API 的 OAuth2 流程Obsidian 插件依赖的是 Obsidian 的 Plugin API v1.5阿里云部署模板则封装了 RAM 角色授权和 SLB 健康检查配置。它们的关系就像 HTTP 协议和 Chrome 浏览器——你可以用 Paperclip spec 写一个完全不依赖 OpenClaw 的 Agent比如一个 CLI 工具用readline接收输入console.log输出 action也可以用 OpenClaw 的 SDK 写一个不使用 Paperclip 的 Agent它内置了LegacyAgent类兼容旧式 callback 风格。但最佳实践一定是两者结合Paperclip 提供开发体验和可维护性OpenClaw 提供生产就绪能力和生态连接。我见过最典型的反模式是有人把 OpenClaw 的config.yaml当成 Paperclip 的配置中心试图在里面写hooks: [useMemory, useTool]——这完全违背了分层原则。正确姿势是Paperclip 组件只关心业务逻辑“用户想改签我该展示什么 UI调用什么工具”OpenClaw 的 config 只负责基础设施“tool search_flights 的 endpoint 是 https://api.xxx.com/v1/flights超时 5s重试 2 次”。这种解耦让 Paperclip 组件可以无缝迁移到其他平台比如我们团队就把同一个ChangeFlightAgent组件通过 OpenClaw 的 Teams adapter 部署到 Microsoft Teams又通过自研的 DingTalk adapter 部署到钉钉零代码修改。3. 核心模块拆解与实操细节从零搭建一个可调试的 Paperclip Agent3.1 环境准备避开 Node.js 安装的 3 个经典陷阱Paperclip 对 Node.js 版本有明确要求最低 18.17.0强烈推荐 20.12.2 或 22.12.0LTS。这不是版本焦虑而是底层依赖决定的。paperclip/runtime使用了AsyncLocalStorage的增强特性v18.17openclaw/core的 streaming response 依赖ReadableStream的tee()方法v20.12而qwen2.5-3b的本地推理适配器则需要 Node.js 22 的WebAssembly.compileStreaming()支持。安装时务必避开以下陷阱提示不要用 Windows 自带的choco install nodejs或 macOS 的brew install node。这些包管理器安装的 Node.js 常含系统级 patch与 Paperclip 的 ESM 模块解析冲突。正确姿势以 WSL2 Ubuntu 22.04 为例卸载所有旧版sudo apt remove nodejs npm sudo apt autoremove安装 nvmNode Version Managercurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash然后重启 shell 或source ~/.bashrc安装指定版本nvm install 22.12.0 nvm use 22.12.0验证node -v应输出v22.12.0npm -v应输出10.5.0node -p process.versions.openssl应 ≥3.0.12注意CentOS 7.9 用户请跳过nvm直接用 NodeSource 官方源。因为 CentOS 7 默认的 glibc 版本太老nvm编译的二进制会报GLIBC_2.18 not found。执行curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash - sudo yum install -y nodejs # 然后手动升级 OpenSSL 到 1.1.1w完成安装后关键一步是设置 npm 全局路径。Paperclip 的openclaw/cli工具需要全局安装但默认路径/usr/local/lib/node_modules常因权限问题失败。执行mkdir ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc这样npm install -g openclaw/cli就不会报EACCES错误。我踩过的最大坑是某次在阿里云 ECS 上npm install -g成功了但openclaw --version报command not found查了半天发现是~/.npm-global/bin没加进PATH——因为阿里云镜像的.bashrc里PATH设置被注释掉了必须手动取消注释。3.2 创建第一个 Paperclip Agent从create-paperclip-app到可热重载的调试环境Paperclip 官方提供了create-paperclip-app脚手架但它不是 Create React App 那种“一键生成完整项目”而是一个最小可行模板。执行npm create paperclip-applatest my-agent -- --template minimal cd my-agent npm install生成的目录结构极简my-agent/ ├── src/ │ ├── agent.tsx # Agent 主组件导出 default function │ └── tools/ # 工具定义目录 │ └── searchFlights.ts ├── openclaw.config.ts # OpenClaw 配置定义 tools、ports、auth └── package.jsonsrc/agent.tsx是核心。初始内容长这样import { useTool } from paperclip/runtime; export default function MyAgent({ context }: { context: any }) { const search useTool(search_flights); // 模拟用户输入触发搜索 if (context.userInput?.includes(航班)) { search({ from: PEK, to: SHA, date: 2024-06-15 }); } return divAgent is running.../div; }这里useTool(search_flights)返回的不是一个 Promise而是一个tool dispatcher 函数。调用它时Paperclip runtime 会检查openclaw.config.ts中是否注册了名为search_flights的 tool如果注册了将参数{ from, to, date }序列化通过 IPC 或 HTTP 发送给 OpenClaw serverserver 执行实际逻辑比如调用航司 API返回结果runtime 将结果注入新的context触发组件重新 render。要让这个 Agent 可调试必须启用 Paperclip 的 dev mode。在openclaw.config.ts中添加export default { port: 3000, dev: { // 启用 React DevTools 支持 enableDevTools: true, // 启用热重载修改 .tsx 文件后自动刷新 Agent 状态 hotReload: true, // 记录完整的 execution trace用于分析 tool 调用链 trace: true }, tools: [ { name: search_flights, handler: async (params) { console.log( Searching flights:, params); return [{ flightNo: CA123, price: 1200 }]; } } ] };然后启动npx openclaw dev访问http://localhost:3000/debug你会看到一个类似 React DevTools 的面板左侧显示当前 Agent 的 component tree右侧显示contextstate、tool调用历史、execution timeline。点击任意一次search_flights调用能展开查看入参、出参、耗时、stack trace。这才是 Paperclip 的灵魂——Agent 不再是黑盒而是可 inspect、可 time-travel、可 profile 的 React 组件。我曾用这个面板定位到一个性能瓶颈某个useMemoryHook 在每次 render 时都重新 fetch 全量对话历史导致 200 条消息时 render 耗时 1.2s。解决方案是加一层useMemo缓存或者改用useInfiniteQuery分页加载。3.3 工具Tool开发实战如何让searchFlights真正对接航司 APIPaperclip 的 tool 不是简单的函数而是一个具备元数据、错误处理、超时控制的契约对象。以对接某航司公开 API 为例src/tools/searchFlights.ts应这样写import { Tool } from paperclip/runtime; // 定义 tool 的输入 schema用于 runtime 校验和文档生成 const inputSchema { type: object, properties: { from: { type: string, minLength: 3, maxLength: 3 }, to: { type: string, minLength: 3, maxLength: 3 }, date: { type: string, pattern: \\d{4}-\\d{2}-\\d{2} } }, required: [from, to, date] } as const; // 定义 tool 的输出 schema const outputSchema { type: array, items: { type: object, properties: { flightNo: { type: string }, price: { type: number }, departure: { type: string }, arrival: { type: string } } } } as const; export const searchFlights: Tooltypeof inputSchema, typeof outputSchema { name: search_flights, description: 查询指定日期、出发地、目的地的航班信息, inputSchema, outputSchema, handler: async (params) { // 1. 参数校验runtime 会先做 JSON Schema 校验这里是业务级校验 if (params.from params.to) { throw new Error(出发地和目的地不能相同); } // 2. 调用航司 API这里用 fetch实际应封装成 service client const res await fetch(https://api.airline.com/v1/flights, { method: POST, headers: { Content-Type: application/json, X-API-Key: process.env.AIRLINE_API_KEY || dev-key }, body: JSON.stringify({ origin: params.from, destination: params.to, flightDate: params.date }) }); if (!res.ok) { const error await res.json(); throw new Error(API Error ${res.status}: ${error.message}); } const data await res.json(); // 3. 标准化输出适配 outputSchema return data.flights.map((f: any) ({ flightNo: f.flightNumber, price: f.price.total, departure: f.departure.time, arrival: f.arrival.time })); }, // 4. 元数据用于 OpenClaw 的 UI 自动生成表单 ui: { form: { from: { label: 出发机场, type: text, placeholder: PEK }, to: { label: 到达机场, type: text, placeholder: SHA }, date: { label: 出发日期, type: date } } } };把这个文件 export 到openclaw.config.ts的 tools 数组中即可。关键点在于inputSchema和outputSchema不是装饰而是 runtime 的强制契约。Paperclip 会在调用前用ajv库校验参数不符合 schema 直接抛错避免脏数据流入下游handler函数必须是async且不能有try/catch包裹——错误应直接 throw由 Paperclip runtime 统一捕获并注入context.error这样 Agent 组件才能根据context.error渲染友好的错误 UIui.form字段是 OpenClaw 的魔法所在当在 Obsidian 插件里配置这个 tool 时它会自动生成一个带校验的表单用户填完直接提交无需写一行 HTML。我在线上环境吃过亏某次航司 API 返回格式变更data.flights变成了data.results但handler里没加if (!data.flights)判断导致map报Cannot read property map of undefined。Paperclip runtime 捕获到这个 error 后会把它塞进context.error而我们的 Agent 组件写了if (context.error) { return ErrorCard message{context.error.message} onRetry{() context.retry()} /; }用户看到的就是一个带重试按钮的友好提示而不是白屏或 console 报错。这就是契约驱动开发的力量。3.4 OpenClaw 部署详解从本地开发到阿里云 ECS 的全链路配置Paperclip Agent 的部署本质是部署 OpenClaw server。它有三种模式dev本地开发带 hot reload 和 debug panelserve生产环境静态文件服务 API serverdeploy云平台适配生成 Dockerfile、systemd unit、cloud init script。以阿里云 ECSUbuntu 22.04为例完整部署流程如下第一步准备服务器环境# 登录 ECS更新系统 sudo apt update sudo apt upgrade -y # 安装 Node.js 22.12.0用 nvm避免权限问题 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22.12.0 nvm use 22.12.0 # 安装 PM2 进程管理器替代 forever sudo npm install -g pm2第二步上传并构建项目# 在本地打包生成 dist 目录 npm run build # 用 scp 上传假设 ECS 公网 IP 是 47.98.xxx.xxx scp -r dist/ root47.98.xxx.xxx:/opt/my-agent/ # 登录 ECS安装 production 依赖 cd /opt/my-agent npm install --production第三步配置 OpenClaw创建/opt/my-agent/openclaw.prod.config.tsimport { defineConfig } from openclaw/cli; export default defineConfig({ port: 3000, // 关闭 dev mode dev: { enableDevTools: false, hotReload: false }, // 启用 HTTPS需提前申请 SSL 证书 https: { key: /etc/ssl/private/my-agent.key, cert: /etc/ssl/certs/my-agent.crt }, // 数据库存储用 SQLite轻量可靠 database: { type: sqlite, path: /var/lib/my-agent/data.db }, // 日志配置 logging: { level: info, file: /var/log/my-agent/app.log }, tools: [ // 这里 import 你的真实 tools确保它们不依赖 browser API ] });第四步PM2 启动与守护创建ecosystem.config.jsmodule.exports { apps: [{ name: my-agent, script: ./node_modules/.bin/openclaw, args: serve --config openclaw.prod.config.ts, instances: 1, autorestart: true, watch: false, max_memory_restart: 1G, env: { NODE_ENV: production, AIRLINE_API_KEY: your-real-api-key-here } }] };然后执行pm2 start ecosystem.config.js pm2 startup # 生成开机自启脚本 pm2 save # 保存当前进程列表第五步Nginx 反向代理可选但推荐sudo apt install nginx -y sudo nano /etc/nginx/sites-available/my-agent配置内容server { listen 80; server_name your-domain.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /etc/ssl/certs/my-agent.crt; ssl_certificate_key /etc/ssl/private/my-agent.key; location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }启用sudo ln -sf /etc/nginx/sites-available/my-agent /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl restart nginx至此你的 Paperclip Agent 就在阿里云上 7x24 小时运行了。OpenClaw 的deploy命令还能生成 Terraform 模板一键在阿里云上创建 VPC、ECS、SLB、RDS但手工部署更能帮你理解每一层的作用。我建议新手一定从手工部署开始因为自动化脚本隐藏了太多细节——比如pm2 startup生成的 systemd service 文件它的RestartSec10参数决定了进程崩溃后 10 秒重启这个值太小会导致频繁重启太大又影响可用性必须根据你的 Agent 的平均响应时间调整。4. 常见问题排查与避坑指南那些文档里不会写的实战经验4.1 “OpenClaw 无法安全验证 sl2 环境” 的真实原因与 3 种解法这个报错信息极具误导性它根本不是 OpenClaw 的 bug而是 WSL2 的安全策略与 Node.js 的 crypto 模块冲突的表现。根本原因是WSL2 默认启用了kernel.unprivileged_userns_clone1而 Node.js 22 的crypto.randomFillSync()在某些 OpenSSL 版本下会尝试创建 unprivileged user namespace被 WSL2 内核拒绝。解法一推荐关闭 WSL2 的 unprivileged user namespace# 在 PowerShell管理员中执行 wsl --shutdown Set-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Services\Lxss\Parameters -Name unprivilegedUserNamespaces -Value 0 wsl --shutdown wsl然后在 WSL2 里验证cat /proc/sys/user/max_user_namespaces应输出0。解法二降级 Node.js 到 20.12.2nvm install 20.12.2 nvm use 20.12.2Node.js 20 系列的 crypto 模块不触发此问题且 20.12.2 是 LTS足够稳定。解法三修改 OpenClaw 的启动参数治标不治本在package.json的 scripts 里加scripts: { start: NODE_OPTIONS--openssl-legacy-provider openclaw serve }--openssl-legacy-provider强制使用 OpenSSL 1.1.x 的 legacy provider绕过新 provider 的 namespace 问题。但这只是临时 workaround不解决根本。我踩坑时花了 3 天时间因为错误日志里只有Error: unable to get local issuer certificate完全没提 WSL2。后来用strace -e traceclone,namespaces node index.js才看到clone系统调用返回-EPERM才锁定到 namespace 问题。所以我的经验是遇到这种模糊报错第一反应不是搜关键词而是用strace或dtrussmacOS看底层系统调用。4.2 “React Native 启动白屏” 与 Paperclip 的兼容性真相网络热词里“react native 启动白屏”和 “paperclip” 同时出现很多人以为 Paperclip 支持 React Native。不支持且短期内不会支持。原因很硬核Paperclip 的 runtime 重度依赖AsyncLocalStorage而 React Native 的 Hermes 引擎默认 JS 引擎直到 0.74 版本才实验性支持AsyncLocalStorage且存在内存泄漏风险JSC 引擎iOS 默认则完全不支持。更致命的是Paperclip 的useToolHook 必须在 server 端执行而 React Native 是纯客户端环境没有tool的执行上下文。但你可以曲线救国用 React Native 做前端壳所有 Agent 逻辑跑在 OpenClaw server 上Native App 只负责渲染和发送消息。具体做法Native App 用WebSocket连接 OpenClaw 的/wsendpoint用户输入 → Native App 发送{ type: message, content: 我想改签 }OpenClaw server 执行 Paperclip Agent → 得到action: { type: render, html: div请选择航班/div }或action: { type: tool_call, name: search_flights, params: {...} }Native App 根据 action type 渲染 HTML用WebView或触发本地功能如拨打电话。我们做过 POCWebView渲染的响应速度比纯 Native 组件慢 200ms但胜在开发成本低——Agent UI 完全用 React 写无需为 iOS/Android 分别开发。所以“react native 白屏”问题根源不是 Paperclip而是开发者试图在客户端执行本该在服务端运行的逻辑。4.3 “Qwen2.5-3b 关联到 OpenClaw” 的 4 种接入模式对比Qwen2.5-3b 是一个 3B 参数的开源大模型想把它接入 OpenClaw有四种主流模式适用场景完全不同模式部署位置延迟成本适用场景Paperclip 集成方式API 调用阿里云百炼平台300-800ms按 token 计费快速验证、低频调用在searchFlights.ts的handler里用fetch调用百炼 API本地 Ollama本地机器500-2000ms0离线开发、隐私敏感OpenClaw config 里配置ollama://http://localhost:11434vLLM 服务GPU 服务器100-300ms高需 A10/A100高并发、低延迟OpenClaw 的llm配置项指向 vLLM endpointLiteLLM 代理中间服务器50ms中仅代理费多模型路由、fallbackPaperclip 组件里useTool(llm_complete)由 LiteLLM 路由到 Qwen 或其他模型我团队的选择是LiteLLM 代理因为 Paperclip 的useTool天然支持多后端。我们写了一个llmComplete.tstoolexport const llmComplete: Tool..., ... { name: llm_complete, handler: async (params) { // 所有请求都发给 LiteLLM它自动选择最优模型 const res await fetch(http://lite-llm-proxy:4000/v1/chat/completions, { method: POST, headers: { Authorization: Bearer sk-... }, body: JSON.stringify(params) }); return res.json(); } };这样Agent 组件完全不知道背后是 Qwen、Qwen2.5 还是 GPT-4只管调用useTool(llm_complete)。当 Qwen2.5-3b 的量化版本发布我们只需更新 LiteLLM 的模型列表Agent 代码一行不用改。这才是 Paperclip “关注分离”哲学的真正威力。4.4 “React SSE/WebSocket 轮询文件变化” 的 Paperclip 替代方案热词里提到 “react sse/websocket 轮询文件变化”这是典型的手动同步反模式。Paperclip 提供了更优雅的解法用useEventHook 订阅文件系统事件。OpenClaw 内置了fs.watch的封装你可以在 tool 里暴露一个watchFiletoolimport { Tool } from paperclip/runtime; export const watchFile: Tool{ path: string }, { event: change | rename, filename: string } { name: watch_file, handler: async ({ path }) { // 这里返回一个 Promise但不 resolve保持连接 return new Promise((resolve) { const watcher require(fs).watch(path, (event, filename) { resolve({ event, filename }); // resolve 后连接断开如需持续监听需重连 }); }); } };但在 Paperclip Agent 组件里更好的写法是import { useEvent } from paperclip/runtime; export default function FileWatcher({ context }) { // 订阅文件变化事件自动 re-render const fileEvents useEvent(file_change, { path: context.targetPath }); if ( 
长河君 · 2026/11/2 5:09:52 · 阅读 1.2k Paperclip：面向AI Agent的React原生运行时框架
1. 项目概述Paperclip 不是回形针而是一个面向 AI Agent 开发的轻量级 React 运行时框架你搜“paperclip”第一反应可能是办公桌抽屉里那枚银色小金属件——但在这个技术语境下Paperclip 是一个专为构建可组合、可调试、可热重载的 AI Agent 而设计的 React 原生运行时环境。它不是 UI 组件库不是状态管理工具更不是另一个前端脚手架它是把 React 的声明式心智模型、Hooks 的生命周期语义、以及现代 AI Agent 所需的异步流控、工具调用追踪、上下文快照能力三者拧成一股绳的底层执行引擎。我第一次在 OpenClaw 社区看到 Paperclip 的 demo 时正卡在用纯 React Zustand 写一个带记忆回溯的客服 Agent 上——每次用户说“回到上一步”我就得手动 patch state、重置 hooks、清空 pending promise 队列像在修一台没有说明书的老式收音机。Paperclip 直接把这件事抽象成了Agent step{currentStep} /一个 props 就搞定。它背后不依赖任何浏览器 DOM也不绑定特定 LLM 接口而是通过一套极简的useTool,useMemory,useEvent等自定义 Hook让开发者能像写普通 React 页面一样写 Agent 逻辑组件即节点props 即输入return 值即输出动作tool call / message / state update整个执行流天然支持 React DevTools 调试、React Strict Mode 检查、甚至 React Server Components 的 SSR 渲染路径。这解释了为什么所有热词都绕不开 Node.js 和 React——Paperclip 的核心 runtime 是纯 JavaScript既能在浏览器里跑用于前端 Agent UI也能在 Node.js 环境里跑用于服务端 Agent 编排而 OpenClaw 正是它最典型的落地场景一个基于 Paperclip 构建的、开箱支持 Obsidian 插件、Teams 集成、阿里云部署的开源 AI Agent 平台。如果你正在被“react agent 怎么写”、“openclaw 部署总报错”、“node.js 安装完找不到 global module”这些问题反复折磨那么 Paperclip 就是你该从根子上理解的那个“缺失环节”。2. 核心架构设计与选型逻辑为什么不用 Next.js 或 Express为什么必须是 React2.1 不是“用 React 写 Agent”而是“让 Agent 成为 React 组件”绝大多数 AI Agent 框架比如 LangChain 的 JS 版、LlamaIndex 的 pipeline走的是传统函数式编排路线定义 chain → 注入 prompt → 调用 model → 解析 output → 触发下一个 tool。这种模式写复杂业务时极易失控——一个客服流程可能涉及 7 层嵌套回调、3 种 memory 存储介质、5 类 error fallback 策略最后代码变成意大利面条。Paperclip 的破局点在于彻底倒置控制权它不让你写“执行流程”而是让你声明“当前状态下的合法行为集合”。举个真实例子一个机票改签 Agent传统写法要写if (userSays 我想改签) { callSearchFlights(); } else if (userSays.includes(价格)) { callGetPrice(); }...Paperclip 写法则是function ChangeFlightAgent({ context }) { const [step, setStep] useStatesearch | select | confirm(search); useEffect(() { if (context.intent change_flight) setStep(search); }, [context.intent]); if (step search) { return SearchFlights onResult{r setStep(select)} /; } if (step select) { return SelectFlight flights{context.flights} onSelect{f { context.setBooking(f); setStep(confirm); }} /; } return ConfirmBooking booking{context.booking} onSubmit{submit} /; }看到没没有 callback hell没有手动状态同步没有跨函数传递 context 对象——React 的 re-render 机制天然保证了 UIAgent 行为与数据context的一致性。Paperclip 的 runtime 就是这套模式的执行器它监听组件返回的特殊 symbol如Symbol.for(tool_call)捕获useTool(search_flights, { date, from, to })这样的 Hook 调用将其序列化为标准 action交由外部 executor比如 OpenClaw 的 tool router执行再把结果注入新的 context 触发下一次 render。这正是它必须深度耦合 React 的根本原因——不是为了画界面而是为了复用 React 最成熟、最稳定、最被开发者信任的状态同步与副作用调度模型。我试过用 Vue 的 Composition API 模拟类似逻辑结果在 deep reactive proxy 和 async setup 执行时机上踩了至少 4 个坑用 Svelte 的$:声明式响应也因缺乏统一的 effect cleanup 机制导致内存泄漏。React 的useEffectuseStateuseReducer这套组合经过十年生产验证是目前唯一能把“状态变更 → 副作用触发 → 新状态生成”这个闭环做得既清晰又可靠的方案。2.2 Node.js 的角色不是服务器而是 Agent 的“操作系统内核”网络热词里反复出现 “node.js 安装”、“centos 7.9 node.js 部署”很多人误以为 Paperclip 是个需要 nginx 反向代理的 Web 应用。错了。Node.js 在 Paperclip 生态里扮演的是 Agent 运行时Runtime和工具执行器Tool Executor的宿主环境类比操作系统的 kernel。具体来说Paperclip 的核心包paperclip/runtime是纯 ESM 模块无任何 browser-only API 依赖可在 Node.js 18推荐 20.12直接importOpenClaw 的agent-server进程本质就是启动一个 Node.js 实例加载 Paperclip runtime然后注册一串tool函数如searchFlights,bookHotel,sendEmail每个 tool 都是一个标准 Node.js 函数可调用数据库、HTTP API、本地文件系统当前端React App通过 SSE 或 WebSocket 发来用户消息OpenClaw 的 server 不是转发给 LLM而是将消息构造成context对象传给 Paperclip runtime 的render()方法runtime 执行 Agent 组件捕获到useTool调用后就去匹配已注册的 tool 并执行——整个过程完全脱离 HTTP 生命周期是纯粹的 JS 函数调用。这就解释了为什么wsl --status和powershell报错如此高频Windows 用户在 WSL2 里装 Node.js常因/mnt/c/路径权限、Windows Defender 实时扫描、或 WSL2 的 systemd 未启用导致npm install时node-gyp编译 native addon 失败进而让 OpenClaw 的sqlite3或obsidian-api工具无法加载。我在阿里云 ECSCentOS 7.9部署时也遇到过经典问题系统自带的 OpenSSL 版本太老Node.js 20 编译时提示error:0308010C:digital envelope routines::unsupported最终解决方案不是降级 Node.js而是用nvm安装时指定--openssl-install-dir参数指向新版 OpenSSL。这些都不是 Paperclip 的 bug而是它对 Node.js 运行时环境的“零容忍”——它不封装兼容层不提供 polyfill因为它要确保每一个useTool调用都能获得 Node.js 原生的 I/O 性能和错误堆栈精度。所以当你看到 “openclaw 无法安全验证 sl2 环境”别急着搜教程先运行node -v npm -v node -p process.versions看清楚 OpenSSL、V8、UV 版本号这才是真正的起点。2.3 OpenClaw 与 Paperclip不是父子关系而是“应用层协议”与“传输层协议”的协作很多初学者把 OpenClaw 当成 Paperclip 的“官方 GUI”这是巨大误解。Paperclip 是一个specification规范定义了 Agent 组件如何声明、如何通信、如何序列化状态OpenClaw 是一个implementation实现它遵循 Paperclip spec但增加了大量企业级能力Teams 集成用的是 Microsoft Graph API 的 OAuth2 流程Obsidian 插件依赖的是 Obsidian 的 Plugin API v1.5阿里云部署模板则封装了 RAM 角色授权和 SLB 健康检查配置。它们的关系就像 HTTP 协议和 Chrome 浏览器——你可以用 Paperclip spec 写一个完全不依赖 OpenClaw 的 Agent比如一个 CLI 工具用readline接收输入console.log输出 action也可以用 OpenClaw 的 SDK 写一个不使用 Paperclip 的 Agent它内置了LegacyAgent类兼容旧式 callback 风格。但最佳实践一定是两者结合Paperclip 提供开发体验和可维护性OpenClaw 提供生产就绪能力和生态连接。我见过最典型的反模式是有人把 OpenClaw 的config.yaml当成 Paperclip 的配置中心试图在里面写hooks: [useMemory, useTool]——这完全违背了分层原则。正确姿势是Paperclip 组件只关心业务逻辑“用户想改签我该展示什么 UI调用什么工具”OpenClaw 的 config 只负责基础设施“tool search_flights 的 endpoint 是 https://api.xxx.com/v1/flights超时 5s重试 2 次”。这种解耦让 Paperclip 组件可以无缝迁移到其他平台比如我们团队就把同一个ChangeFlightAgent组件通过 OpenClaw 的 Teams adapter 部署到 Microsoft Teams又通过自研的 DingTalk adapter 部署到钉钉零代码修改。3. 核心模块拆解与实操细节从零搭建一个可调试的 Paperclip Agent3.1 环境准备避开 Node.js 安装的 3 个经典陷阱Paperclip 对 Node.js 版本有明确要求最低 18.17.0强烈推荐 20.12.2 或 22.12.0LTS。这不是版本焦虑而是底层依赖决定的。paperclip/runtime使用了AsyncLocalStorage的增强特性v18.17openclaw/core的 streaming response 依赖ReadableStream的tee()方法v20.12而qwen2.5-3b的本地推理适配器则需要 Node.js 22 的WebAssembly.compileStreaming()支持。安装时务必避开以下陷阱提示不要用 Windows 自带的choco install nodejs或 macOS 的brew install node。这些包管理器安装的 Node.js 常含系统级 patch与 Paperclip 的 ESM 模块解析冲突。正确姿势以 WSL2 Ubuntu 22.04 为例卸载所有旧版sudo apt remove nodejs npm sudo apt autoremove安装 nvmNode Version Managercurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash然后重启 shell 或source ~/.bashrc安装指定版本nvm install 22.12.0 nvm use 22.12.0验证node -v应输出v22.12.0npm -v应输出10.5.0node -p process.versions.openssl应 ≥3.0.12注意CentOS 7.9 用户请跳过nvm直接用 NodeSource 官方源。因为 CentOS 7 默认的 glibc 版本太老nvm编译的二进制会报GLIBC_2.18 not found。执行curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash - sudo yum install -y nodejs # 然后手动升级 OpenSSL 到 1.1.1w完成安装后关键一步是设置 npm 全局路径。Paperclip 的openclaw/cli工具需要全局安装但默认路径/usr/local/lib/node_modules常因权限问题失败。执行mkdir ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc这样npm install -g openclaw/cli就不会报EACCES错误。我踩过的最大坑是某次在阿里云 ECS 上npm install -g成功了但openclaw --version报command not found查了半天发现是~/.npm-global/bin没加进PATH——因为阿里云镜像的.bashrc里PATH设置被注释掉了必须手动取消注释。3.2 创建第一个 Paperclip Agent从create-paperclip-app到可热重载的调试环境Paperclip 官方提供了create-paperclip-app脚手架但它不是 Create React App 那种“一键生成完整项目”而是一个最小可行模板。执行npm create paperclip-applatest my-agent -- --template minimal cd my-agent npm install生成的目录结构极简my-agent/ ├── src/ │ ├── agent.tsx # Agent 主组件导出 default function │ └── tools/ # 工具定义目录 │ └── searchFlights.ts ├── openclaw.config.ts # OpenClaw 配置定义 tools、ports、auth └── package.jsonsrc/agent.tsx是核心。初始内容长这样import { useTool } from paperclip/runtime; export default function MyAgent({ context }: { context: any }) { const search useTool(search_flights); // 模拟用户输入触发搜索 if (context.userInput?.includes(航班)) { search({ from: PEK, to: SHA, date: 2024-06-15 }); } return divAgent is running.../div; }这里useTool(search_flights)返回的不是一个 Promise而是一个tool dispatcher 函数。调用它时Paperclip runtime 会检查openclaw.config.ts中是否注册了名为search_flights的 tool如果注册了将参数{ from, to, date }序列化通过 IPC 或 HTTP 发送给 OpenClaw serverserver 执行实际逻辑比如调用航司 API返回结果runtime 将结果注入新的context触发组件重新 render。要让这个 Agent 可调试必须启用 Paperclip 的 dev mode。在openclaw.config.ts中添加export default { port: 3000, dev: { // 启用 React DevTools 支持 enableDevTools: true, // 启用热重载修改 .tsx 文件后自动刷新 Agent 状态 hotReload: true, // 记录完整的 execution trace用于分析 tool 调用链 trace: true }, tools: [ { name: search_flights, handler: async (params) { console.log( Searching flights:, params); return [{ flightNo: CA123, price: 1200 }]; } } ] };然后启动npx openclaw dev访问http://localhost:3000/debug你会看到一个类似 React DevTools 的面板左侧显示当前 Agent 的 component tree右侧显示contextstate、tool调用历史、execution timeline。点击任意一次search_flights调用能展开查看入参、出参、耗时、stack trace。这才是 Paperclip 的灵魂——Agent 不再是黑盒而是可 inspect、可 time-travel、可 profile 的 React 组件。我曾用这个面板定位到一个性能瓶颈某个useMemoryHook 在每次 render 时都重新 fetch 全量对话历史导致 200 条消息时 render 耗时 1.2s。解决方案是加一层useMemo缓存或者改用useInfiniteQuery分页加载。3.3 工具Tool开发实战如何让searchFlights真正对接航司 APIPaperclip 的 tool 不是简单的函数而是一个具备元数据、错误处理、超时控制的契约对象。以对接某航司公开 API 为例src/tools/searchFlights.ts应这样写import { Tool } from paperclip/runtime; // 定义 tool 的输入 schema用于 runtime 校验和文档生成 const inputSchema { type: object, properties: { from: { type: string, minLength: 3, maxLength: 3 }, to: { type: string, minLength: 3, maxLength: 3 }, date: { type: string, pattern: \\d{4}-\\d{2}-\\d{2} } }, required: [from, to, date] } as const; // 定义 tool 的输出 schema const outputSchema { type: array, items: { type: object, properties: { flightNo: { type: string }, price: { type: number }, departure: { type: string }, arrival: { type: string } } } } as const; export const searchFlights: Tooltypeof inputSchema, typeof outputSchema { name: search_flights, description: 查询指定日期、出发地、目的地的航班信息, inputSchema, outputSchema, handler: async (params) { // 1. 参数校验runtime 会先做 JSON Schema 校验这里是业务级校验 if (params.from params.to) { throw new Error(出发地和目的地不能相同); } // 2. 调用航司 API这里用 fetch实际应封装成 service client const res await fetch(https://api.airline.com/v1/flights, { method: POST, headers: { Content-Type: application/json, X-API-Key: process.env.AIRLINE_API_KEY || dev-key }, body: JSON.stringify({ origin: params.from, destination: params.to, flightDate: params.date }) }); if (!res.ok) { const error await res.json(); throw new Error(API Error ${res.status}: ${error.message}); } const data await res.json(); // 3. 标准化输出适配 outputSchema return data.flights.map((f: any) ({ flightNo: f.flightNumber, price: f.price.total, departure: f.departure.time, arrival: f.arrival.time })); }, // 4. 元数据用于 OpenClaw 的 UI 自动生成表单 ui: { form: { from: { label: 出发机场, type: text, placeholder: PEK }, to: { label: 到达机场, type: text, placeholder: SHA }, date: { label: 出发日期, type: date } } } };把这个文件 export 到openclaw.config.ts的 tools 数组中即可。关键点在于inputSchema和outputSchema不是装饰而是 runtime 的强制契约。Paperclip 会在调用前用ajv库校验参数不符合 schema 直接抛错避免脏数据流入下游handler函数必须是async且不能有try/catch包裹——错误应直接 throw由 Paperclip runtime 统一捕获并注入context.error这样 Agent 组件才能根据context.error渲染友好的错误 UIui.form字段是 OpenClaw 的魔法所在当在 Obsidian 插件里配置这个 tool 时它会自动生成一个带校验的表单用户填完直接提交无需写一行 HTML。我在线上环境吃过亏某次航司 API 返回格式变更data.flights变成了data.results但handler里没加if (!data.flights)判断导致map报Cannot read property map of undefined。Paperclip runtime 捕获到这个 error 后会把它塞进context.error而我们的 Agent 组件写了if (context.error) { return ErrorCard message{context.error.message} onRetry{() context.retry()} /; }用户看到的就是一个带重试按钮的友好提示而不是白屏或 console 报错。这就是契约驱动开发的力量。3.4 OpenClaw 部署详解从本地开发到阿里云 ECS 的全链路配置Paperclip Agent 的部署本质是部署 OpenClaw server。它有三种模式dev本地开发带 hot reload 和 debug panelserve生产环境静态文件服务 API serverdeploy云平台适配生成 Dockerfile、systemd unit、cloud init script。以阿里云 ECSUbuntu 22.04为例完整部署流程如下第一步准备服务器环境# 登录 ECS更新系统 sudo apt update sudo apt upgrade -y # 安装 Node.js 22.12.0用 nvm避免权限问题 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22.12.0 nvm use 22.12.0 # 安装 PM2 进程管理器替代 forever sudo npm install -g pm2第二步上传并构建项目# 在本地打包生成 dist 目录 npm run build # 用 scp 上传假设 ECS 公网 IP 是 47.98.xxx.xxx scp -r dist/ root47.98.xxx.xxx:/opt/my-agent/ # 登录 ECS安装 production 依赖 cd /opt/my-agent npm install --production第三步配置 OpenClaw创建/opt/my-agent/openclaw.prod.config.tsimport { defineConfig } from openclaw/cli; export default defineConfig({ port: 3000, // 关闭 dev mode dev: { enableDevTools: false, hotReload: false }, // 启用 HTTPS需提前申请 SSL 证书 https: { key: /etc/ssl/private/my-agent.key, cert: /etc/ssl/certs/my-agent.crt }, // 数据库存储用 SQLite轻量可靠 database: { type: sqlite, path: /var/lib/my-agent/data.db }, // 日志配置 logging: { level: info, file: /var/log/my-agent/app.log }, tools: [ // 这里 import 你的真实 tools确保它们不依赖 browser API ] });第四步PM2 启动与守护创建ecosystem.config.jsmodule.exports { apps: [{ name: my-agent, script: ./node_modules/.bin/openclaw, args: serve --config openclaw.prod.config.ts, instances: 1, autorestart: true, watch: false, max_memory_restart: 1G, env: { NODE_ENV: production, AIRLINE_API_KEY: your-real-api-key-here } }] };然后执行pm2 start ecosystem.config.js pm2 startup # 生成开机自启脚本 pm2 save # 保存当前进程列表第五步Nginx 反向代理可选但推荐sudo apt install nginx -y sudo nano /etc/nginx/sites-available/my-agent配置内容server { listen 80; server_name your-domain.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /etc/ssl/certs/my-agent.crt; ssl_certificate_key /etc/ssl/private/my-agent.key; location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }启用sudo ln -sf /etc/nginx/sites-available/my-agent /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl restart nginx至此你的 Paperclip Agent 就在阿里云上 7x24 小时运行了。OpenClaw 的deploy命令还能生成 Terraform 模板一键在阿里云上创建 VPC、ECS、SLB、RDS但手工部署更能帮你理解每一层的作用。我建议新手一定从手工部署开始因为自动化脚本隐藏了太多细节——比如pm2 startup生成的 systemd service 文件它的RestartSec10参数决定了进程崩溃后 10 秒重启这个值太小会导致频繁重启太大又影响可用性必须根据你的 Agent 的平均响应时间调整。4. 常见问题排查与避坑指南那些文档里不会写的实战经验4.1 “OpenClaw 无法安全验证 sl2 环境” 的真实原因与 3 种解法这个报错信息极具误导性它根本不是 OpenClaw 的 bug而是 WSL2 的安全策略与 Node.js 的 crypto 模块冲突的表现。根本原因是WSL2 默认启用了kernel.unprivileged_userns_clone1而 Node.js 22 的crypto.randomFillSync()在某些 OpenSSL 版本下会尝试创建 unprivileged user namespace被 WSL2 内核拒绝。解法一推荐关闭 WSL2 的 unprivileged user namespace# 在 PowerShell管理员中执行 wsl --shutdown Set-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Services\Lxss\Parameters -Name unprivilegedUserNamespaces -Value 0 wsl --shutdown wsl然后在 WSL2 里验证cat /proc/sys/user/max_user_namespaces应输出0。解法二降级 Node.js 到 20.12.2nvm install 20.12.2 nvm use 20.12.2Node.js 20 系列的 crypto 模块不触发此问题且 20.12.2 是 LTS足够稳定。解法三修改 OpenClaw 的启动参数治标不治本在package.json的 scripts 里加scripts: { start: NODE_OPTIONS--openssl-legacy-provider openclaw serve }--openssl-legacy-provider强制使用 OpenSSL 1.1.x 的 legacy provider绕过新 provider 的 namespace 问题。但这只是临时 workaround不解决根本。我踩坑时花了 3 天时间因为错误日志里只有Error: unable to get local issuer certificate完全没提 WSL2。后来用strace -e traceclone,namespaces node index.js才看到clone系统调用返回-EPERM才锁定到 namespace 问题。所以我的经验是遇到这种模糊报错第一反应不是搜关键词而是用strace或dtrussmacOS看底层系统调用。4.2 “React Native 启动白屏” 与 Paperclip 的兼容性真相网络热词里“react native 启动白屏”和 “paperclip” 同时出现很多人以为 Paperclip 支持 React Native。不支持且短期内不会支持。原因很硬核Paperclip 的 runtime 重度依赖AsyncLocalStorage而 React Native 的 Hermes 引擎默认 JS 引擎直到 0.74 版本才实验性支持AsyncLocalStorage且存在内存泄漏风险JSC 引擎iOS 默认则完全不支持。更致命的是Paperclip 的useToolHook 必须在 server 端执行而 React Native 是纯客户端环境没有tool的执行上下文。但你可以曲线救国用 React Native 做前端壳所有 Agent 逻辑跑在 OpenClaw server 上Native App 只负责渲染和发送消息。具体做法Native App 用WebSocket连接 OpenClaw 的/wsendpoint用户输入 → Native App 发送{ type: message, content: 我想改签 }OpenClaw server 执行 Paperclip Agent → 得到action: { type: render, html: div请选择航班/div }或action: { type: tool_call, name: search_flights, params: {...} }Native App 根据 action type 渲染 HTML用WebView或触发本地功能如拨打电话。我们做过 POCWebView渲染的响应速度比纯 Native 组件慢 200ms但胜在开发成本低——Agent UI 完全用 React 写无需为 iOS/Android 分别开发。所以“react native 白屏”问题根源不是 Paperclip而是开发者试图在客户端执行本该在服务端运行的逻辑。4.3 “Qwen2.5-3b 关联到 OpenClaw” 的 4 种接入模式对比Qwen2.5-3b 是一个 3B 参数的开源大模型想把它接入 OpenClaw有四种主流模式适用场景完全不同模式部署位置延迟成本适用场景Paperclip 集成方式API 调用阿里云百炼平台300-800ms按 token 计费快速验证、低频调用在searchFlights.ts的handler里用fetch调用百炼 API本地 Ollama本地机器500-2000ms0离线开发、隐私敏感OpenClaw config 里配置ollama://http://localhost:11434vLLM 服务GPU 服务器100-300ms高需 A10/A100高并发、低延迟OpenClaw 的llm配置项指向 vLLM endpointLiteLLM 代理中间服务器50ms中仅代理费多模型路由、fallbackPaperclip 组件里useTool(llm_complete)由 LiteLLM 路由到 Qwen 或其他模型我团队的选择是LiteLLM 代理因为 Paperclip 的useTool天然支持多后端。我们写了一个llmComplete.tstoolexport const llmComplete: Tool..., ... { name: llm_complete, handler: async (params) { // 所有请求都发给 LiteLLM它自动选择最优模型 const res await fetch(http://lite-llm-proxy:4000/v1/chat/completions, { method: POST, headers: { Authorization: Bearer sk-... }, body: JSON.stringify(params) }); return res.json(); } };这样Agent 组件完全不知道背后是 Qwen、Qwen2.5 还是 GPT-4只管调用useTool(llm_complete)。当 Qwen2.5-3b 的量化版本发布我们只需更新 LiteLLM 的模型列表Agent 代码一行不用改。这才是 Paperclip “关注分离”哲学的真正威力。4.4 “React SSE/WebSocket 轮询文件变化” 的 Paperclip 替代方案热词里提到 “react sse/websocket 轮询文件变化”这是典型的手动同步反模式。Paperclip 提供了更优雅的解法用useEventHook 订阅文件系统事件。OpenClaw 内置了fs.watch的封装你可以在 tool 里暴露一个watchFiletoolimport { Tool } from paperclip/runtime; export const watchFile: Tool{ path: string }, { event: change | rename, filename: string } { name: watch_file, handler: async ({ path }) { // 这里返回一个 Promise但不 resolve保持连接 return new Promise((resolve) { const watcher require(fs).watch(path, (event, filename) { resolve({ event, filename }); // resolve 后连接断开如需持续监听需重连 }); }); } };但在 Paperclip Agent 组件里更好的写法是import { useEvent } from paperclip/runtime; export default function FileWatcher({ context }) { // 订阅文件变化事件自动 re-render const fileEvents useEvent(file_change, { path: context.targetPath }); if (