尧图网站建设 免费方案咨询
ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

首页/资讯中心/资讯详情

Paperclip：基于Node.js+React+OpenClaw的轻量级本地AI集成方案

发布时间：2026/11/3 22:06:59 尧图网站建设
Paperclip：基于Node.js+React+OpenClaw的轻量级本地AI集成方案

1. 项目概述：Paperclip 不是回形针，而是一个被严重误读的 AI 工程实践入口

“Paperclip”这个词在中文技术社区里，最近半年几乎成了一个高频误触词——搜“paperclip”，首页跳出来的不是办公用品电商页，而是满屏的 Node.js 安装报错截图、React 面试题 PDF、OpenClaw 部署失败日志，以及 Claude Code 插件在 VS Code 里反复弹出的“Workspace requires virtual machine platform”警告。我第一次看到这个现象时也愣了三秒：这到底是个啥？回形针怎么突然开始跑前端服务了？

后来翻遍 GitHub Trending、Hugging Face Spaces 和国内几个主流技术社区的讨论帖，才理清脉络：Paperclip 是一个由开源社区自发命名、非官方但广泛传播的“AI 工具链集成实验代号”，特指以 Node.js 为运行底座、React 为交互界面、OpenClaw 为本地推理调度器、Claude 系列模型为能力核心的一套轻量级本地 AI 应用组合方案。它没有官方仓库、没有 npm 包、甚至没有统一文档，但它的存在感，已经强到让“node.js 安装教程”和“react 面经”两个完全不相关的搜索词，在百度指数上出现了同步峰值。

为什么叫 Paperclip？不是因为物理回形针，而是取自“Paperclip Maximizer”（回形针最大化器）这个经典 AI 对齐思想实验——它隐喻着：我们正在用最基础、最通用、最易获取的工具（Node.js + React），像回形针一样把一堆原本孤立的 AI 组件（OpenClaw、Claude API、本地文件系统、WebSocket 通道）强行“夹”在一起，形成一个能跑起来的最小可行闭环。这个名字带着点黑色幽默，也透着一线工程师的真实处境：没有现成的“AI 框架”，那就自己用胶带和回形针把轮子绑在板车上，先动起来再说。

它解决的不是某个具体业务问题，而是当前阶段开发者最痛的三个断层：

  • 环境断层：想试 Claude 的本地调用，但 Windows 上连 WSL2 都没开好；
  • 协议断层：OpenClaw 启动后监听的是 Unix Socket，React 前端却只能发 HTTP 请求；
  • 状态断层：用户上传了一个 PDF，React 显示“处理中”，但后台 OpenClaw 根本没收到，也没人知道卡在哪一层。

适合谁来参考？不是刚学完《JavaScript 高级程序设计》的新手——那会直接被npm install卡在 node-gyp 编译上；也不是已经用 Rust 写过 LLM Router 的资深架构师——他们早自己搭好了 K8s+Ollama+LangChain 的整套栈。最适合的是：有 2~3 年全栈经验、能写 React 组件、会配 nginx 反向代理、但没碰过本地大模型部署的工程师。你不需要懂 transformer 架构，但得知道process.env.NODE_ENV在哪里生效；你不用手写 WebSocket 心跳逻辑，但得明白为什么fetch()不能跨域读取 OpenClaw 的/api/status。

我去年帮三家中小团队落地过类似方案，最短的一次从 clone 到可演示只用了 4 小时——不是因为他们技术多强，而是我们绕开了所有“标准答案”，专攻“能跑就行”的实操路径。这篇内容，就是把那 4 小时里踩过的坑、改过的 config、重写的三行关键代码，原样摊开给你看。

2. 整体架构设计与选型逻辑：为什么是 Node.js + React + OpenClaw + Claude 这个组合？

2.1 四层结构的本质：不是技术选型，而是“妥协链”

Paperclip 的四层组合，表面看是技术栈罗列，实际是一条环环相扣的“妥协链”。每一层的选择，都源于对上一层约束的被动响应，而非主动偏好。理解这点，才能避免在后续部署中陷入“为什么不用 Next.js？”“为什么不用 FastAPI？”这类无解争论。

  • 底层：Node.js（v18.20.4 LTS）
    选择理由非常务实：它是唯一同时满足三个硬性条件的运行时——

    1. 能直接require('child_process')启动 OpenClaw 的二进制进程（Python 的 subprocess 在 Windows 上权限问题太多）；
    2. 自带http.Server和WebSocket.Server，无需额外引入框架就能桥接 React 前端与 OpenClaw 后端；
    3. npm 生态里有node-fetch、form-data、ws这些成熟库，能绕过浏览器 CORS 限制，直接代理请求到 OpenClaw 的本地端口。

    提示：别纠结 v22.x。OpenClaw 的官方构建脚本明确要求 Node.js v18.x，v22 的 V8 引擎变更导致其spawn子进程时传参解析异常——这是我在 Ubuntu 22.04 上实测 7 次确认的 bug，不是文档没写，是根本跑不通。

  • 中间层：OpenClaw（v0.4.2）
    它不是替代 Ollama 或 LM Studio 的“更好模型服务器”，而是专为 Claude API 兼容设计的轻量级适配器。OpenClaw 的核心价值在于两点：

    1. 把 Claude 的/v1/chat/completions接口，翻译成本地模型能理解的 prompt 格式（比如把systemrole 映射为<|system|>token）；
    2. 提供/api/files/upload这种简单文件接口，让 React 前端能直接POST一个 PDF，而不必先存到临时目录再发路径给模型。

    注意：OpenClaw 本身不包含模型权重。它依赖你本地已有的 Claude 模型 GGUF 文件（如claude-3-haiku.Q4_K_M.gguf）。它的作用，是当你的硬盘里已经有这个文件时，帮你省掉手写 Python Flask 路由的时间。

  • 上层：React（v18.2.0）
    这里没选 Next.js 或 Remix，是因为 Paperclip 的 UI 极度简单：一个文件拖拽区、一个消息列表、一个输入框。用 React + Vite 就够了。Vite 的proxy配置能直接把/api/请求转发到 Node.js 服务，而 Node.js 服务再把请求转给 OpenClaw——这样 React 根本不用知道 OpenClaw 的端口是多少，彻底规避跨域。
    关键细节：vite.config.ts里的 proxy 规则必须写成：

    export default defineConfig({ server: { proxy: { '/api': { target: 'http://localhost:3001', // Node.js 服务端口 changeOrigin: true, rewrite: (path) => path.replace(/^\/api/, '') } } } })

    如果你写成target: 'http://localhost:8080'（OpenClaw 默认端口），Vite 会直接报 500 错误——因为浏览器不允许前端 JS 直连本地非 HTTP 服务。

  • 顶层：Claude 模型（通过 OpenClaw 调用）
    这里必须澄清一个高频误解：Paperclip 不等于“Claude 本地版”。Claude 官方从未发布过可离线运行的模型权重。目前所有“本地 Claude”方案，本质都是：

    • 用 OpenClaw 作为网关；
    • 把请求转发给云端 Claude API（需 API Key）；
    • 或者，用 llama.cpp 加载社区量化后的 Claude 模型（如claude-3-haiku的 GGUF 版本），此时 OpenClaw 充当 llama.cpp 的 HTTP 封装层。
      所以，当你看到“Claude Code Desktop 国内下载”这种热搜词，背后其实是用户在找 OpenClaw 的 Windows 一键安装包——因为 Claude 官方桌面版根本不支持本地模型。

2.2 被忽略的第五层：文件系统与状态管理

Paperclip 真正的难点，从来不在代码层面，而在文件生命周期管理。一个典型流程是：

  1. 用户拖入report.pdf→ React 上传到 Node.js/upload接口；
  2. Node.js 保存到./uploads/report.pdf，并生成唯一 ID；
  3. Node.js 调用 OpenClaw 的/api/files/upload，把文件路径传过去；
  4. OpenClaw 加载 PDF，提取文本，缓存到./cache/report.txt；
  5. 用户提问“总结第三页”，OpenClaw 从缓存读文本，拼接 prompt，调用本地模型；
  6. 返回结果，Node.js 存到./history/{id}.json。

这个链条里，任何一步文件路径写错，整个流程就断了。我见过最多的问题是：

  • Windows 用户用path.join(__dirname, 'uploads')，结果生成C:\project\uploads\，但 OpenClaw 在 WSL2 里运行，根本找不到这个 Windows 路径；
  • macOS 用户启用了 iCloud 同步，./uploads文件夹被自动移到 iCloud Drive，OpenClaw 读取时权限拒绝；
  • Linux 服务器上./uploads目录属主是root，但 OpenClaw 进程以www-data用户运行，无法写入。

解决方案不是改代码，而是统一用相对路径 + 进程启动前的环境校验：

# 启动前执行 mkdir -p uploads cache history chmod 755 uploads cache history chown $USER:$USER uploads cache history

2.3 为什么不用 Docker？——一个关于“可控性”的现实选择

几乎所有教程都推荐用 Docker 部署 Paperclip，但我在生产环境坚持用裸机部署。原因很实际：

  • Docker 的 volume 挂载在 Windows 上经常出现文件权限错乱（尤其是 WSL2 + Docker Desktop 组合）；
  • OpenClaw 的日志默认输出到stdout，Docker logs 里混着 Node.js 和 OpenClaw 的输出，排查问题时要 grep 两遍；
  • 最关键的是：当用户上传一个 200MB 的 PDF，Docker 的COPY指令会触发镜像重建，而裸机部署下，你只需要rm uploads/*就能清空。

这不是反对容器化，而是说：Paperclip 的定位是“验证可行性”，不是“生产级服务”。在验证阶段，减少一层抽象，就是减少一个故障点。等你确认流程跑通了，再用 Docker 封装，效率反而更高。

3. 核心细节解析与实操要点：从零搭建 Paperclip 的六个关键动作

3.1 动作一：Node.js 环境的“最小安全配置”

Node.js 安装本身很简单，但 Paperclip 对环境的要求远超 Hello World。以下是必须完成的六项检查，缺一不可：

  1. 版本锁定：必须使用v18.20.4。其他 18.x 版本可能因 OpenSSL 补丁差异导致https.request调用 Claude API 时证书验证失败。验证命令：

    node -v # 输出必须是 v18.20.4 npm -v # 必须 ≥ 9.9.0（低于此版本无法安装 OpenClaw 的依赖）

  2. 全局 registry 切换：国内用户必须设置 npm 镜像，否则npm install会卡在node-gyp rebuild。执行：

    npm config set registry https://registry.npmmirror.com npm config set electron_mirror https://npmmirror.com/mirrors/electron/

  3. Python 路径绑定：OpenClaw 依赖node-gyp编译 C++ 扩展，而node-gyp需要 Python 3.10。Windows 用户常犯的错误是：系统 PATH 里有 Python 3.11，但node-gyp找不到。解决方案：

    npm config set python "C:\Python310\python.exe" # 显式指定路径

  4. npm 权限修复：Mac/Linux 用户如果用sudo npm install，会导致node_modules所有者为 root，后续npm run dev会报EACCES。正确做法：

    mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc source ~/.zshrc

  5. 内存限制解除：OpenClaw 加载大模型时，默认 V8 heap size 限制（1.4GB）不够。启动 Node.js 服务时必须加参数：

    node --max-old-space-size=4096 server.js

    这表示分配 4GB 内存给 V8，否则加载claude-3-haiku.Q6_K.gguf（约 3.2GB）时会直接 OOM。

  6. 防火墙放行：Windows 用户常忽略这一点。Node.js 服务监听localhost:3001，但 Windows Defender 防火墙默认阻止外部连接。即使你只在本地访问，也要执行：

    New-NetFirewallRule -DisplayName "Paperclip Node.js" -Direction Inbound -Protocol TCP -LocalPort 3001 -Action Allow

实操心得：我建议把这六步写成setup.sh（Linux/macOS）或setup.ps1（Windows），每次新机器部署直接运行。曾经有个客户团队，因为漏了第 5 步（内存限制），连续三天以为是 OpenClaw 编译问题，最后发现日志里只有FATAL ERROR: Reached heap limit这一行。

3.2 动作二：OpenClaw 的“非标准安装法”

OpenClaw 官方文档推荐用pip install openclaw，但在 Paperclip 场景下，这会导致两个致命问题：

  • 安装的 OpenClaw 是纯 Python 版本，不包含预编译的 llama.cpp 二进制，无法直接加载 GGUF 模型；
  • pip安装的版本默认监听http://localhost:8080，但 Paperclip 的 Node.js 服务需要它监听 Unix Socket（/tmp/openclaw.sock）以提升 IPC 性能。

正确做法是：放弃 pip，直接下载预编译二进制包。截至 2024 年 10 月，最新稳定版是openclaw-v0.4.2-linux-x64.tar.gz（Linux）、openclaw-v0.4.2-win-x64.zip（Windows）、openclaw-v0.4.2-macos-arm64.tar.gz（macOS）。下载地址在 GitHub Releases 页面，但不要点 “Source code”，要找 “Assets” 下的压缩包。

解压后，目录结构必须是：

openclaw/ ├── openclaw # 二进制可执行文件（Linux/macOS） ├── openclaw.exe # Windows 可执行文件 ├── models/ # 存放 GGUF 模型的目录 └── config.yaml # 配置文件

关键配置修改（config.yaml）：

server: host: "127.0.0.1" port: 8080 socket_path: "/tmp/openclaw.sock" # Linux/macOS 必填 # windows_socket_path: "\\.\pipe\openclaw" # Windows 必填 model: path: "./models/claude-3-haiku.Q4_K_M.gguf" # 必须是相对路径，且文件真实存在 n_ctx: 4096 n_threads: 8 api: enable_cors: false # Paperclip 中由 Node.js 处理 CORS，这里关闭

注意：socket_path在 Windows 上不是文件路径，而是命名管道名\\.\pipe\openclaw。如果写成C:\temp\openclaw.sock，OpenClaw 启动会报错invalid socket path。这是 Windows 开发者最容易栽跟头的地方。

3.3 动作三：React 前端的“三明治式状态管理”

Paperclip 的 UI 状态极其简单，但传统 React 状态管理（useState + useEffect）在这里会引发竞态问题。典型场景：用户快速上传两个文件，第一个还没返回 ID，第二个请求已发出，导致uploadId覆盖。

我的解决方案是：用一个全局UploadManager类封装所有文件操作，React 组件只负责触发和展示。代码结构如下：

// src/lib/upload-manager.ts class UploadManager { private queue: Array<{ file: File; resolve: (id: string) => void }> = []; private isUploading = false; async upload(file: File): Promise<string> { return new Promise((resolve) => { this.queue.push({ file, resolve }); if (!this.isUploading) this.processQueue(); }); } private async processQueue() { if (this.queue.length === 0) return; this.isUploading = true; const { file, resolve } = this.queue.shift()!; try { const formData = new FormData(); formData.append('file', file); const res = await fetch('/api/upload', { method: 'POST', body: formData }); const { id } = await res.json(); resolve(id); } catch (err) { resolve(''); // 失败返回空字符串，组件自行处理 } finally { this.isUploading = false; this.processQueue(); // 继续处理队列 } } } export const uploadManager = new UploadManager();

React 组件调用方式：

// src/components/FileDrop.tsx const handleDrop = async (files: FileList) => { for (let i = 0; i < files.length; i++) { const id = await uploadManager.upload(files[i]); if (id) setFileIds(prev => [...prev, id]); } };

这个设计的好处是：

  • 队列机制天然解决并发上传冲突；
  • uploadManager实例在页面生命周期内唯一，状态不随组件重渲染丢失；
  • 错误处理集中在类内部，组件代码干净；
  • 后续扩展（如上传进度条）只需在processQueue里加事件通知，不侵入组件。

3.4 动作四：Node.js 服务的“双通道代理”

Paperclip 的 Node.js 服务不是传统后端，它扮演的是“智能代理”角色，必须同时处理两种请求：

  • HTTP 通道：代理 React 的/api/upload、/api/chat到 OpenClaw；
  • WebSocket 通道：把 OpenClaw 的流式响应（token-by-token）实时推给 React。

关键代码（server.js）：

import http from 'http'; import { WebSocketServer } from 'ws'; import { createProxyMiddleware } from 'http-proxy-middleware'; // 1. HTTP 代理：把 /api/* 转发给 OpenClaw const apiProxy = createProxyMiddleware({ target: 'http://localhost:8080', changeOrigin: true, pathRewrite: { '^/api': '' }, onProxyReq: (proxyReq, req) => { // OpenClaw 需要原始文件名，但 Express 默认丢弃 if (req.file) proxyReq.setHeader('X-Original-Filename', req.file.originalname); } }); // 2. WebSocket 代理：建立长连接 const wss = new WebSocketServer({ port: 3002 }); wss.on('connection', (ws, req) => { const openclawWs = new WebSocket('ws://localhost:8080/ws'); // OpenClaw 的 WS 端点 openclawWs.on('open', () => ws.send(JSON.stringify({ type: 'connected' }))); openclawWs.on('message', (data) => ws.send(data)); openclawWs.on('close', () => ws.close()); openclawWs.on('error', (err) => { console.error('OpenClaw WS error:', err); ws.close(); }); ws.on('message', (data) => openclawWs.send(data)); ws.on('close', () => openclawWs.close()); });

React 前端连接 WebSocket：

const ws = new WebSocket('ws://localhost:3002'); ws.onmessage = (event) => { const data = JSON.parse(event.data); if (data.type === 'token') appendToChat(data.content); // 流式追加 };

实操心得：OpenClaw 的 WebSocket 协议非常简陋——它只发{"type":"token","content":"hello"}，没有start或end标记。所以前端必须靠data.content === '\n'来判断段落结束，而不是等{"type":"done"}。这是社区文档里完全没提的坑。

3.5 动作五：Claude 模型的“本地化适配”

虽然 Paperclip 名义上支持 Claude，但真正能本地跑的，只有社区量化后的 GGUF 格式模型。官方 Claude 模型（如 claude-3-haiku）从未开源权重，所有“本地 Claude”都是基于 llama.cpp 的兼容层。

适配步骤：

  1. 下载 GGUF 模型：推荐 Hugging Face 上bartowski/claude-3-haiku-GGUF，选择Q4_K_M（平衡精度与速度）或Q6_K（更高精度，需更多显存）；
  2. 放入 OpenClaw 的models/目录；
  3. 修改config.yaml中的model.path；
  4. 最关键的一步：在config.yaml中添加llama_cpp配置：
    llama_cpp: embedding: false logits_all: false use_mmap: true # 内存映射，加速加载 use_mlock: false # 不锁内存，避免 OOM

验证是否成功：启动 OpenClaw 后，访问http://localhost:8080/api/models，应返回：

{ "models": [ { "name": "claude-3-haiku.Q4_K_M.gguf", "format": "gguf", "size": 2147483648 } ] }

如果返回空数组，90% 是model.path路径错误，或文件权限不足（Linux/macOS 上chmod 644 models/*.gguf）。

3.6 动作六：跨平台调试的“三色日志法”

Paperclip 在不同系统上的失败模式完全不同：

  • Windows：90% 是路径分隔符（\vs/）和命名管道问题；
  • macOS：70% 是 SIP（系统完整性保护）阻止 OpenClaw 访问~/Downloads；
  • Linux：80% 是 SELinux 或 AppArmor 限制openclaw进程读取models/目录。

为快速定位，我强制所有日志按颜色分类：

  • 红色：Node.js 进程级错误（如EADDRINUSE、ENOMEM）；
  • 黄色：OpenClaw 启动日志（含模型加载耗时、线程数）；
  • 绿色：HTTP 请求流水（POST /api/upload 200 124ms）。

实现方式（logger.js）：

import chalk from 'chalk'; export const log = { error: (msg) => console.error(chalk.red(`[ERROR] ${msg}`)), warn: (msg) => console.warn(chalk.yellow(`[WARN] ${msg}`)), info: (msg) => console.log(chalk.green(`[INFO] ${msg}`)), debug: (msg) => console.log(chalk.blue(`[DEBUG] ${msg}`)) }; // 在 OpenClaw 启动脚本里加 exec('openclaw --config config.yaml 2>&1', (err, stdout, stderr) => { if (stderr) log.error(stderr); else log.info('OpenClaw started'); });

实操心得：我见过最诡异的 Bug 是 macOS 上 OpenClaw 日志显示“model loaded”，但实际llama.cpp返回null。最终发现是 SIP 阻止了 mmap，解决方案不是关 SIP（不安全），而是把models/目录移到~/Documents/下——SIP 对 Documents 目录是放行的。

4. 实操过程与核心环节实现：从空白目录到可交互 Demo 的完整 walkthrough

4.1 第 1 分钟：初始化项目结构

新建目录paperclip-demo，执行：

mkdir paperclip-demo && cd paperclip-demo npm init -y npm install express cors multer ws http-proxy-middleware npm install --save-dev vite @vitejs/plugin-react

创建标准目录：

paperclip-demo/ ├── backend/ # Node.js 服务 │ ├── server.js │ └── logger.js ├── frontend/ # React 前端 │ ├── src/ │ └── vite.config.ts ├── openclaw/ # OpenClaw 二进制 ├── models/ # GGUF 模型存放处 ├── uploads/ # 用户上传文件 ├── cache/ # PDF 文本缓存 └── history/ # 对话历史

注意：openclaw/目录必须手动创建，不要npm install openclaw。这是 Paperclip 和标准 npm 包的最大区别——它不是一个库，而是一个独立进程。

4.2 第 5 分钟：启动 OpenClaw 并验证

将下载好的openclaw二进制放入openclaw/目录，确保可执行权限（Linux/macOS）：

chmod +x openclaw/openclaw

编写启动脚本openclaw/start.sh：

#!/bin/bash cd "$(dirname "$0")" ./openclaw --config ../config.yaml

创建config.yaml（放在项目根目录）：

server: host: "127.0.0.1" port: 8080 socket_path: "/tmp/openclaw.sock" model: path: "../models/claude-3-haiku.Q4_K_M.gguf" n_ctx: 4096 api: enable_cors: false

启动 OpenClaw：

bash openclaw/start.sh

验证：访问http://localhost:8080/health，返回{"status":"ok"}即成功。如果报错address already in use，说明 8080 端口被占用，改config.yaml中的port即可。

4.3 第 15 分钟：编写 Node.js 代理服务

backend/server.js内容：

import express from 'express'; import cors from 'cors'; import multer from 'multer'; import { createProxyMiddleware } from 'http-proxy-middleware'; import { log } from './logger.js'; const app = express(); const PORT = 3001; // 文件上传配置 const storage = multer.diskStorage({ destination: (req, file, cb) => cb(null, '../uploads/'), filename: (req, file, cb) => cb(null, `${Date.now()}-${file.originalname}`) }); const upload = multer({ storage }); // 上传接口 app.post('/api/upload', upload.single('file'), (req, res) => { if (!req.file) return res.status(400).json({ error: 'No file uploaded' }); const fileId = req.file.filename; log.info(`Uploaded: ${fileId}`); res.json({ id: fileId }); }); // 代理到 OpenClaw app.use('/api', createProxyMiddleware({ target: 'http://localhost:8080', changeOrigin: true, pathRewrite: { '^/api': '' } })); app.listen(PORT, () => { log.info(`Node.js server running on http://localhost:${PORT}`); });

启动服务：

node --max-old-space-size=4096 backend/server.js

验证：用 curl 上传测试文件：

curl -X POST -F "file=@test.pdf" http://localhost:3001/api/upload # 应返回 {"id":"1729876543-test.pdf"}

4.4 第 25 分钟：搭建 React 前端并连接代理

frontend/vite.config.ts：

import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; export default defineConfig({ plugins: [react()], server: { port: 5173, proxy: { '/api': { target: 'http://localhost:3001', changeOrigin: true, rewrite: (path) => path.replace(/^\/api/, '') } } } });

frontend/src/main.tsx：

import React from 'react'; import ReactDOM from 'react-dom/client'; import { UploadArea } from './components/UploadArea.tsx'; ReactDOM.createRoot(document.getElementById('root')!).render( <React.StrictMode> <UploadArea /> </React.StrictMode>, );

frontend/src/components/UploadArea.tsx：

import { useState } from 'react'; export function UploadArea() { const [fileId, setFileId] = useState<string | null>(null); const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => { const file = e.target.files?.[0]; if (!file) return; const formData = new FormData(); formData.append('file', file); const res = await fetch('/api/upload', { method: 'POST', body: formData }); const { id } = await res.json(); setFileId(id); }; return ( <div> <input type="file" onChange={handleUpload} /> {fileId && <p>已上传: {fileId}</p>} </div> ); }

启动前端：

cd frontend && npm run dev

此时访问http://localhost:5173，上传文件，应看到文件 ID 显示——证明 React → Node.js → OpenClaw 三层链路已通。

4.5 第 40 分钟：实现流式响应与聊天界面

修改backend/server.js，添加 WebSocket 服务：

import { WebSocketServer } from 'ws'; const wss = new WebSocketServer({ port: 3002 }); wss.on('connection', (ws) => { const openclawWs = new WebSocket('ws://localhost:8080/ws'); openclawWs.on('open', () => ws.send(JSON.stringify({ type: 'connected' }))); openclawWs.on('message', (data) => ws.send(data)); openclawWs.on('error', (err) => { log.error(`OpenClaw WS error: ${err.message}`); ws.close(); }); ws.on('message', (data) => openclawWs.send(data)); });

frontend/src/components/Chat.tsx：

import { useState, useEffect, useRef } from 'react'; export function Chat({ fileId }: { fileId: string }) { const [messages, setMessages] = useState<string[]>([]); const wsRef = useRef<WebSocket | null>(null); useEffect(() => { wsRef.current = new WebSocket('ws://localhost:3002'); wsRef.current.onmessage = (event) => { const data = JSON.parse(event.data); if (data.type === 'token') { setMessages(prev => [...prev, data.content]); } }; return () => wsRef.current?.close(); }, []); const sendMessage = (text: string) => { if (!wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) return; wsRef.current.send(JSON.stringify({ action: 'chat', fileId, message: text })); }; return ( <div> <div>{messages.join('')}</div> <input onKeyDown={(e) => e.key === 'Enter' && sendMessage(e.currentTarget.value)} /> </div> ); }

实操心得：WebSocket 连接必须在组件挂载时建立，且在卸载时关闭。我见过太多案例，因为没写useEffect cleanup，导致页面切换后 WebSocket 连接堆积，最终耗尽内存。

4.6 第 60 分钟：整合与压力测试

至此，Paperclip 的 MVP 已完成。但真正的考验是：

  • 上传一个 50MB 的 PDF；
  • 发送 10 个并发请求；
  • 连续运行 24 小时。

我推荐的测试脚本stress-test.js：

const axios = require('axios'); async function testUpload() { const file = await axios.get('https://httpbin.org/bytes/10000000', { responseType: 'arraybuffer' }); const formData = new FormData(); formData.append('file', file.data, 'test.pdf'); const res = await axios.post('http://localhost:3001/api/upload', formData, { headers: { 'Content-Type': 'multipart/form-data' } }); return res.data.id; } async function testChat(fileId) { const res = await axios.post('http://localhost:3001/api/chat', { fileId, message: '请总结这个文档的核心观点' }); return res.data; } // 并发测试 (async () => { const ids = await Promise.all(Array(5).fill(0).map(testUpload)); console.log('Upload IDs:', ids); const results = await Promise.all(ids.map(testChat)); console.log
网站建设 视觉设计 SEO优化
返回列表