企业官网建设流程全解析

1. 项目概述：Paperclip 不是回形针，而是一个被严重误读的 AI 工程化枢纽

“Paperclip”这个词一出来，很多人第一反应是办公桌抽屉里那个银色金属小物件——回形针。但在这个技术语境下，它根本不是物理实体，而是当前 AI 应用层开发中一个正在快速成型、却尚未被中文社区系统梳理的轻量级本地 AI 编排框架原型。它不叫 Paperclip CLI，也不叫 Paperclip Server，更不是某个大厂开源的明星项目；它是一组围绕OpenClaw + Claude Code + React + Node.js四要素耦合演进而来的、高度实操导向的工程实践模式。我从去年底开始在三个内部项目中反复验证这套组合，从最初手动拼接 OpenClaw 的 REST API、硬编码 Claude 的 SSE 流式响应、用 React 状态管理模拟 Agent 生命周期，到最终沉淀出一套可复用的本地启动脚本、状态同步机制和 UI 响应协议——这个过程产物，团队内部就叫它 “paperclip”，取其“连接 disparate parts（连接离散部件）”的本义，而非字面翻译。

核心关键词 paperclip、Node.js、React、OpenClaw、Claude 在热搜中高频共现，绝非偶然。它们共同指向一个真实痛点：开发者想快速验证一个带 UI 的本地 AI 工作流（比如文档摘要+多轮问答+代码生成），但现有方案要么太重（LangChain + FastAPI + Streamlit），要么太散（各自跑服务、手动 curl、React 端写一堆 ad-hoc fetch）。Paperclip 就是为解决这个“最后一公里连接”而生的——它不替代 OpenClaw，也不重写 Claude Code，而是用极简的 Node.js 中间层做三件事：统一端口暴露、标准化事件流格式、桥接 React 组件生命周期与 AI 执行状态。它甚至没有自己的 npm 包，所有代码都藏在server/目录下不到 300 行 TypeScript 里。你搜不到它的 GitHub 主页，因为它根本没打算开源；但你能在掘金、知乎、V2EX 上看到大量零散提问：“OpenClaw 怎么接 React？”“Claude Code 本地怎么调用？”“React + SSE 轮询文件变化卡顿怎么办？”——这些，就是 paperclip 正在默默填平的沟壑。

适合谁来参考？不是刚学 JS 的新手，也不是要建百人 AI 平台的架构师。它最适合三类人：一是正在准备 2026 前端面试、需要手写一个“React Agent” demo 的候选人；二是中小团队里那个既要写页面又要搭后端、被要求“三天内跑通本地 LLM 工作流”的全栈工程师；三是 Obsidian 插件开发者，想把 OpenClaw 的本地能力无缝注入笔记界面。它不承诺高并发、不保证企业级安全、不提供 SaaS 运营后台——它只承诺一件事：让你在 12 分钟内，从git clone到在浏览器里对着自己笔记本上的 PDF 文件问出“第三页第二段的核心论点是什么”，且整个链路全部跑在本机，无网络依赖、无 token 限制、无额外云费用。这就是 paperclip 的全部野心，也是它被反复搜索却难觅全貌的根本原因：它不是一个产品，而是一套正在被集体实践、尚未被命名的共识性工作流。

2. 整体设计思路：为什么放弃 LangChain，选择“胶水式”轻编排？

2.1 拒绝抽象层套娃：LangChain 的“过度设计”陷阱

去年 Q3 我接手一个客户项目，需求很朴素：给销售团队做一个本地 PDF 分析工具，上传合同扫描件，自动提取甲方义务条款、违约金计算逻辑、争议解决方式。团队第一反应是上 LangChain ——毕竟教程满天飞，“RAG + LLM + VectorDB” 听起来就很专业。我们真这么干了：装 ChromaDB、配 embedding model、写 prompt template、搭 FastAPI 接口、再用 React 做前端。结果呢？光是让 ChromaDB 在 macOS M1 上编译成功就花了两天；第一次跑通 RAG 流程时，单次查询耗时 8.3 秒，其中 6.2 秒花在向本地 Ollama 发送请求并等待响应；更糟的是，当用户上传一份 50 页的 PDF，embedding 步骤直接吃光 16GB 内存，Node.js 进程 OOM。这不是模型不行，是整套抽象层在本地场景下成了负累。

LangChain 的设计哲学是“面向云原生、服务化部署”，它预设你的向量库在 AWS，LLM 在 Azure，API 网关有 WAF 防护。但 paperclip 的起点截然相反：所有组件必须能npm run dev一键启动，所有数据流必须走 localhost:3000 → localhost:3001 → localhost:3002 这样的直连管道，且任意环节崩溃都不该导致整个流程不可恢复。它不要“可插拔的 chain”，只要“可替换的 endpoint”。OpenClaw 是 endpoint，Claude Code 的本地 HTTP server 是 endpoint，甚至你用 Python 写个flask脚本处理 OCR 也是 endpoint。paperclip 的 Node.js 层不碰任何业务逻辑，只做三件事：路由分发、流式透传、状态广播。这就像老式电话交换机——不理解通话内容，只确保 A 的语音信号准确送到 B 的听筒。

2.2 为什么选 OpenClaw 而非 Ollama 或 LM Studio？

OpenClaw 在中文开发者中热度飙升，不是因为它有多先进，而是它精准踩中了“本地 LLM 工具链的最后一块拼图”：它把模型加载、推理、HTTP API 暴露、GPU 显存管理打包成一个开箱即用的二进制，且对 Windows/macOS/Linux 全平台提供一键安装包（.deb,.rpm,.exe,.dmg）。对比 Ollama：你需要先curl -fsSL https://ollama.com/install.sh | sh，再ollama pull llama3，再ollama run llama3，最后还得自己写curl http://localhost:11434/api/chat的请求体；LM Studio 更麻烦，GUI 界面好看，但 API 文档稀烂，/v1/chat/completions的 request body 格式和 OpenAI 不完全兼容，React 端改一行代码就要查半小时文档。

OpenClaw 的/v1/chat/completions完全遵循 OpenAI 标准，这意味着你写在 React 里的fetch('http://localhost:3001/v1/chat/completions', { method: 'POST', body: JSON.stringify({ model: 'qwen2', messages: [...] }) })，明天换成 Claude Code 的本地服务，只需改一个 URL，其余代码零修改。paperclip 的 Node.js 层正是基于这个“协议一致性”构建的——它不关心背后是 Qwen、DeepSeek 还是 Claude，只认/v1/chat/completions这个路径和标准 JSON Schema。这种设计让技术选型变得极其轻量：今天用 OpenClaw 跑 qwen2:7b，明天换 Claude Code 跑 claude-3-haiku，后天切到本地部署的 DeepSeek-Coder，Node.js 层配置文件只需改两行：

// config.ts export const AI_PROVIDER = 'openclaw'; // or 'claude-code', 'deepseek-local' export const AI_ENDPOINT = 'http://localhost:3001/v1/chat/completions';

没有 SDK，没有适配器，没有中间转换层。这就是 paperclip 的“胶水”本质：它不创造新协议，只复用最广泛接受的协议，并确保所有参与方都严格遵守。

2.3 React 为何必须承担“状态中枢”角色？

很多团队尝试把 AI 状态管理全扔给后端：Node.js 保存 session ID，记录用户历史，维护 conversation tree。这在 Web 应用里看似合理，但一落地就崩。举个真实案例：某教育 SaaS 用 Express + Socket.IO 实现“AI 讲解课件”功能，老师点击 PPT 下一页，后端触发 LLM 生成讲解词，再推送给前端。结果上课时网络抖动一次，Socket 断连，老师点下一页，后端没收到指令，但前端已翻页——师生看到的讲解词和当前页面完全错位。问题根源在于：状态源头错了。PPT 页面索引、当前聚焦的文本框、用户刚输入的问题，这些信息天然存在于 React 组件的 state 或 context 中；强行让后端持有并同步，等于在分布式系统里搞强一致性，成本远高于收益。

paperclip 的设计反其道而行之：React 是唯一真相源（Single Source of Truth）。Node.js 层只做“请求代理”和“流式中继”，不存储任何会话状态。当用户在 React 界面输入问题，组件立即 dispatch 一个AI_REQUEST_STARTaction，UI 进入 loading 状态；同时发起 fetch 请求到http://localhost:3000/api/ai/chat；Node.js 收到后，不做任何加工，直接fetch(AI_ENDPOINT)并用res.body.pipe(res)将原始流透传回前端；React 端用ReadableStream接收 chunk，逐段解析 JSON Lines，实时更新useReducer管理的 message list。整个过程，状态变更完全由 React 驱动，Node.js 只是透明管道。这样做的好处是：即使 Node.js 进程崩溃重启，用户在前端输入的内容、已显示的对话历史、当前滚动位置，全部毫发无损——因为它们根本不在后端。

2.4 Node.js 的不可替代性：为什么不能纯前端直连？

有人会问：既然 OpenClaw 和 Claude Code 都暴露 HTTP API，React 为什么不能直接fetch('http://localhost:3001/...')？答案是：浏览器同源策略（CORS）和流式响应支持度。OpenClaw 默认开启 CORS，但仅限*，这在开发环境 OK，生产环境必须配具体域名；Claude Code 的本地服务默认关闭 CORS，需手动加--cors参数；更致命的是，SSE（Server-Sent Events）在现代浏览器支持良好，但fetch的ReadableStream解析 JSON Lines 需要手动处理 chunk 边界，而EventSource对非标准格式（如 OpenAI-style streaming）兼容性差。Node.js 层在这里扮演了“协议翻译器”角色：

• 它用node-fetch或axios调用后端 AI 服务，不受 CORS 限制；
• 它将 OpenAI 标准的data: {"id":"...","choices":[{"delta":{"content":"a"}}]}流，清洗为纯 JSON Lines（去掉data:前缀，合并多行 JSON）；
• 它添加自定义 HTTP header（如X-Paperclip-Version: 0.3.2），便于前端识别服务版本；
• 它实现超时控制（AbortController）、错误重试（指数退避）、请求队列（防并发打爆 GPU 显存）。

这些功能若全塞进 React，会让组件逻辑臃肿不堪。Node.js 作为轻量胶水层，恰好卡在“足够薄”和“足够用”之间——它不处理业务，只确保管道畅通、信号干净、故障可控。

3. 核心细节解析：从零搭建 paperclip 的四步实操法

3.1 环境准备：避开 Node.js 版本陷阱的实战清单

paperclip 对 Node.js 版本有明确要求：必须 >= 18.18.0，推荐 18.20.4 LTS 或 20.11.1 LTS。为什么？两个关键原因：一是stream/webAPI（ReadableStream,TransformStream）在 18.18+ 才稳定支持，这是流式透传的基石；二是fetch全局函数在 18.0.0 引入，但早期版本存在内存泄漏，18.18.0 是首个修复版。我见过太多人卡在这一步：用nvm install 16.20.2，跑起来发现fetch is not defined；或用nvm install 22.12.0，结果 OpenClaw 的某些 native binding（如 CUDA 加速）报Module did not self-register错误。

正确操作流程如下（以 macOS 为例，Windows/Linux 同理，仅命令微调）：

1. 卸载旧版 Node.js：

   提示：不要用brew uninstall node，它可能残留node_modules和全局 bin。执行which node和which npm，删除所有输出路径；然后rm -rf ~/.nvm（如果用 nvm）或/usr/local/bin/node*（如果用 pkg 安装）。

2. 安装 nvm 并指定版本：

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新打开终端，执行 nvm install 18.20.4 nvm use 18.20.4 node -v # 必须输出 v18.20.4

3. 验证 OpenClaw 和 Claude Code 的端口冲突：
   OpenClaw 默认监听http://localhost:3001，Claude Code 默认http://localhost:3002。用lsof -i :3001检查端口是否空闲。若被占用，修改 OpenClaw 启动参数：openclaw --port 3003；Claude Code 启动时加--port 3004。paperclip 的 Node.js 层会读取config.ts中的AI_ENDPOINT，无需硬编码。

4. 初始化项目结构：

   mkdir paperclip-demo && cd paperclip-demo npm init -y npm install express cors helmet morgan npm install --save-dev typescript @types/express @types/cors npx tsc --init # 生成 tsconfig.json，关键配置： # "target": "ES2020", "module": "CommonJS", "lib": ["ES2020", "DOM"], "strict": true, "skipLibCheck": true

注意：不要装@types/node！paperclip 的 Node.js 层运行在服务端，globalThis下没有window，但fetch是全局可用的（Node.js 18+ 内置）。装@types/node会导致类型冲突，fetch类型被覆盖为any。

3.2 OpenClaw 本地部署：Ubuntu/CentOS/Windows 三平台实操要点

OpenClaw 的安装看似简单，但不同平台的坑差异极大。以下是我在 12 台不同配置机器上踩坑后总结的“零失败”指南：

Ubuntu 22.04 / 24.04（推荐）：

# 下载最新 .deb 包（截至 2024-10，v0.8.3） wget https://github.com/openclaw/openclaw/releases/download/v0.8.3/openclaw_0.8.3_amd64.deb sudo dpkg -i openclaw_0.8.3_amd64.deb # 若提示依赖缺失，执行 sudo apt-get install -f # 启动服务（后台运行，日志自动写入 /var/log/openclaw/） sudo systemctl start openclaw sudo systemctl enable openclaw # 验证 curl http://localhost:3001/health # 返回 {"status":"ok"}

CentOS 7.9（老旧但常见）：
CentOS 7 默认 glibc 版本过低（2.17），OpenClaw 二进制要求 >= 2.28。强行安装会报GLIBC_2.28 not found。解决方案：

• 升级系统（不推荐，风险高）；
• 使用 Docker（推荐）：

  sudo yum install -y docker sudo systemctl start docker sudo docker run -d --name openclaw -p 3001:3001 -v /path/to/models:/app/models openclaw/openclaw:latest

  注意：-v参数必须映射模型目录，否则启动失败。模型下载地址见 OpenClaw 官网 Model Zoo。

Windows（WSL2 用户注意）：
OpenClaw Windows 版本要求启用“虚拟机平台（Virtual Machine Platform）”。若安装时报错Claude's workspace requires the virtual machine platform on windows. enable，请按此顺序操作：

1. 以管理员身份运行 PowerShell；
2. 执行dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart；
3. 执行wsl --update；
4. 重启电脑；
5. 在 WSL2 中安装 Ubuntu，再按 Ubuntu 步骤部署。

关键经验：不要在 Windows 原生 cmd/powershell 中运行 OpenClaw，性能极差且 GPU 加速失效。WSL2 + NVIDIA Container Toolkit 是唯一可行路径。

所有平台通用验证法：

# 测试流式响应（必须看到逐字返回，而非整块 JSON） curl -N http://localhost:3001/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen2:7b", "messages": [{"role": "user", "content": "你好"}], "stream": true }' # 正常输出应类似： # data: {"id":"chatcmpl-...","choices":[{"delta":{"content":"你"},"index":0,"finish_reason":null}]} # data: {"id":"chatcmpl-...","choices":[{"delta":{"content":"好"},"index":0,"finish_reason":null}]} # ...

3.3 React 前端：手写一个可复用的 AI Chat Hook

paperclip 的 React 层核心是一个自定义 Hook：useAIChat。它封装了请求发起、流式解析、错误处理、取消机制，让业务组件只需关注 UI 渲染。以下是经过 3 个项目验证的精简版（TypeScript）：

// hooks/useAIChat.ts import { useState, useCallback, useRef, useEffect } from 'react'; interface Message { id: string; role: 'user' | 'assistant' | 'system'; content: string; } interface AIChatOptions { endpoint?: string; // paperclip 的 /api/ai/chat model?: string; // 传递给后端的模型名 } export function useAIChat({ endpoint = '/api/ai/chat', model = 'qwen2:7b' }: AIChatOptions = {}) { const [messages, setMessages] = useState<Message[]>([]); const [isLoading, setIsLoading] = useState(false); const [error, setError] = useState<string | null>(null); const abortControllerRef = useRef<AbortController | null>(null); const sendMessage = useCallback(async (userMessage: string) => { if (!userMessage.trim()) return; // 添加用户消息 const newUserMsg: Message = { id: Date.now().toString(), role: 'user', content: userMessage }; setMessages(prev => [...prev, newUserMsg]); setIsLoading(true); setError(null); // 创建 AbortController 用于取消请求 abortControllerRef.current = new AbortController(); try { const response = await fetch(endpoint, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ messages: [...messages, newUserMsg], model, stream: true, }), signal: abortControllerRef.current.signal, }); if (!response.ok) { throw new Error(`HTTP ${response.status}: ${response.statusText}`); } // 处理流式响应 const reader = response.body?.getReader(); if (!reader) throw new Error('Response body is not readable'); let accumulatedContent = ''; while (true) { const { done, value } = await reader.read(); if (done) break; // 将 Uint8Array 转为字符串 const chunk = new TextDecoder().decode(value); // 按行分割，OpenAI 标准流每行是 "data: {...}" const lines = chunk.split('\n').filter(line => line.trim() !== ''); for (const line of lines) { if (line.startsWith('data: ')) { try { const jsonStr = line.slice(6).trim(); if (jsonStr === '[DONE]') continue; const data = JSON.parse(jsonStr); const deltaContent = data.choices?.[0]?.delta?.content || ''; accumulatedContent += deltaContent; // 实时更新 assistant 消息 setMessages(prev => { const lastMsg = prev[prev.length - 1]; if (lastMsg?.role === 'assistant') { return [...prev.slice(0, -1), { ...lastMsg, content: accumulatedContent }]; } else { return [...prev, { id: Date.now().toString(), role: 'assistant', content: accumulatedContent }]; } }); } catch (e) { console.warn('Failed to parse stream line:', line, e); } } } } } catch (err) { if (err instanceof DOMException && err.name === 'AbortError') { console.log('Request aborted'); } else { setError(err instanceof Error ? err.message : 'Unknown error'); } } finally { setIsLoading(false); abortControllerRef.current = null; } }, [endpoint, model, messages]); const abortRequest = useCallback(() => { if (abortControllerRef.current) { abortControllerRef.current.abort(); abortControllerRef.current = null; } }, []); // 组件卸载时自动取消请求 useEffect(() => { return () => { if (abortControllerRef.current) { abortControllerRef.current.abort(); } }; }, []); return { messages, isLoading, error, sendMessage, abortRequest, }; }

关键细节说明：

• TextDecoder().decode(value)是处理Uint8Array的标准方式，避免Buffer.from(value).toString()在某些 Node.js 版本下的乱码；
• lines.filter(line => line.trim() !== '')去除空行，防止JSON.parse('')报错；
• data.choices?.[0]?.delta?.content使用可选链，兼容不同模型返回格式（Qwen 返回delta.content，Claude 可能返回delta.text）；
• setMessages的更新逻辑确保 assistant 消息始终是最后一条，且内容实时追加，而非覆盖——这是流式体验的核心。

3.4 Node.js 中间层：300 行代码实现的流式代理服务器

paperclip 的 Node.js 层是整个架构的“心脏”，但它异常简洁。以下是server/index.ts的完整实现（已删减日志和错误处理，保留核心逻辑）：

import express from 'express'; import cors from 'cors'; import helmet from 'helmet'; import morgan from 'morgan'; import { Readable, Transform } from 'stream'; import { pipeline } from 'stream/promises'; import { fetch } from 'undici'; // Node.js 18+ 内置 fetch 有 bug，用 undici 更稳 const app = express(); const PORT = 3000; // 中间件 app.use(helmet()); app.use(cors({ origin: '*' })); // 开发环境允许所有来源 app.use(morgan('dev')); app.use(express.json({ limit: '10mb' })); app.use(express.urlencoded({ extended: true })); // 配置 const AI_ENDPOINT = process.env.AI_ENDPOINT || 'http://localhost:3001/v1/chat/completions'; const TIMEOUT_MS = 30000; // 流式代理核心 app.post('/api/ai/chat', async (req, res) => { const { messages, model, stream = true } = req.body; try { // 构造 AI 服务请求 const aiReqBody = JSON.stringify({ messages, model, stream, }); const aiResponse = await fetch(AI_ENDPOINT, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Accept': 'text/event-stream', // 明确告知后端要流式响应 }, body: aiReqBody, // 超时控制 dispatcher: new undici.TimeoutInterceptor({ timeout: TIMEOUT_MS }), }); if (!aiResponse.ok) { throw new Error(`AI service error: ${aiResponse.status} ${aiResponse.statusText}`); } // 设置响应头，启用流式传输 res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive', 'X-Accel-Buffering': 'no', // Nginx 关键配置 }); // 创建 Transform Stream 清洗数据 const cleanStream = new Transform({ transform(chunk, encoding, callback) { try { const str = chunk.toString(); // 移除 data: 前缀，保留纯 JSON const cleaned = str .split('\n') .map(line => line.trim()) .filter(line => line.startsWith('data: ') && line !== 'data: [DONE]') .map(line => line.slice(6).trim()) // 去掉 'data: ' .join('\n'); callback(null, cleaned ? cleaned + '\n' : ''); } catch (err) { callback(err); } } }); // 管道：AI 响应流 → 清洗流 → HTTP 响应流 await pipeline( aiResponse.body!, cleanStream, res ); } catch (err) { console.error('Proxy error:', err); res.status(500).json({ error: err instanceof Error ? err.message : 'Internal server error' }); } }); // 健康检查 app.get('/health', (req, res) => { res.json({ status: 'ok', timestamp: new Date().toISOString() }); }); app.listen(PORT, () => { console.log(`Paperclip server running on http://localhost:${PORT}`); });

为什么用undici而不用内置fetch？
Node.js 18.18+ 的global.fetch在流式响应场景下存在内存泄漏，尤其当请求被频繁取消时。undici是 Node.js 官方推荐的高性能 HTTP client，其TimeoutInterceptor可精确控制请求超时，且pipeline函数能优雅处理流中断。实测对比：相同压力下，undici内存占用稳定在 80MB，内置fetch30 分钟后涨至 1.2GB。

X-Accel-Buffering: no的作用：
当 paperclip 部署在 Nginx 后时，Nginx 默认会缓冲响应直到整个 body 发送完毕才推给客户端，这会彻底破坏流式体验。此 header 强制 Nginx 禁用缓冲，逐 chunk 转发。

4. 实操全流程：从空白目录到可交互 AI 界面的 12 分钟

4.1 第 1-3 分钟：初始化与依赖安装

打开终端，执行以下命令（假设已按 3.1 节准备好 Node.js 18.20.4）：

mkdir my-paperclip && cd my-paperclip npm init -y npm install express cors helmet morgan undici npm install --save-dev typescript @types/express @types/cors npx tsc --init # 修改 tsconfig.json，确保 "module": "CommonJS", "target": "ES2020"

创建目录结构：

my-paperclip/ ├── server/ │ ├── index.ts │ └── config.ts ├── client/ │ ├── src/ │ │ ├── hooks/ │ │ │ └── useAIChat.ts │ │ ├── App.tsx │ │ └── main.tsx │ └── public/ │ └── index.html ├── package.json └── tsconfig.json

4.2 第 4-6 分钟：编写 Node.js 代理服务器

server/config.ts：

export const AI_ENDPOINT = 'http://localhost:3001/v1/chat/completions'; export const PORT = 3000;

server/index.ts：粘贴 3.4 节的完整代码（含undici导入和pipeline调用）。

package.json添加脚本：

"scripts": { "server": "ts-node --esm server/index.ts", "client": "vite", "dev": "concurrently \"npm run server\" \"npm run client\"" }

安装concurrently和ts-node：npm install --save-dev concurrently ts-node @types/node

4.3 第 7-9 分钟：搭建 React 前端基础

client/src/main.tsx：

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

client/src/App.tsx：

import { useState } from 'react'; import { useAIChat } from './hooks/useAIChat'; function App() { const [inputValue, setInputValue] = useState(''); const { messages, isLoading, error, sendMessage, abortRequest } = useAIChat(); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); if (inputValue.trim()) { sendMessage(inputValue); setInputValue(''); } }; return ( <div style={{ padding: '20px', fontFamily: 'system-ui' }}> <h1>Paperclip AI Demo</h1> <form onSubmit={handleSubmit}> <input type="text" value={inputValue} onChange={(e) => setInputValue(e.target.value)} placeholder="输入问题..." disabled={isLoading} style={{ width: '500px', padding: '10px', marginRight: '10px' }} /> <button type="submit" disabled={isLoading}> {isLoading ? '思考中...' : '发送'} </button> {isLoading && <button type="button" onClick={abortRequest}>取消</button>} </form> {error && <div style={{ color: 'red', marginTop: '10px' }}>错误：{error}</div>} <div style={{ marginTop: '20px', maxHeight: '400px', overflowY: 'auto' }}> {messages.map((msg) => ( <div key={msg.id} style={{ marginBottom: '10px', fontWeight: msg.role === 'user' ? 'bold' : 'normal' }}> <strong>{msg.role === 'user' ? '你：' : 'AI：'}</strong> {msg.content} </div> ))} </div> </div> ); } export default App;

4.4 第 10-12 分钟：启动服务与首次交互

1. 启动 OpenClaw（确保端口 3001 空闲）：
   openclaw --port 3001 --models-dir ./models
   （首次运行会自动下载 qwen2:7b，约 4.2GB，耐心等待）

2. 启动 paperclip：
   在my-paperclip/目录下执行npm run dev
   终端应显示：
   Paperclip server running on http://localhost:3000
Vite server running on http://localhost:5173

3. 打开浏览器http://localhost:5173，在输入框输入你好，点击发送。
   你会看到：

   • UI 立即显示“你：你好”；
   • 几秒后，“AI：你好！很高兴见到你。” 逐字出现；
   • 打开浏览器开发者工具 Network 标签，找到/api/ai/chat请求，Preview 中能看到纯 JSON Lines 流。

实测心得：首次交互延迟主要来自 OpenClaw 加载模型（约 8-12 秒），后续请求均在 1.2 秒内返回首字节。若想加速，可在openclaw启动时加--num-gpu 1（Linux/macOS）或--gpu-layers 20（Windows WSL2）显式启用 GPU 加速。

5. 常见问题与排查技巧实录：那些官方文档不会写的坑

5.1 “React 页面白屏，控制台报错ReferenceError: fetch is not defined”

现象：Vite 启动后页面空白，浏览器控制台报错ReferenceError: fetch is not defined。
根因：Vite 默认在 SSR（服务端渲染）模式下运行，而fetch是浏览器全局对象，Node.js 环境下不存在。但你的useAIChatHook 在组件初始化时就调用了fetch，SSR 时执行失败。
解决方案：强制禁用 SSR，在vite.config.ts中添加：

export default defineConfig({ ssr: false, // 关键！ // 其他配置... });

经验：paperclip 是纯客户端交互应用，无需 SSR。开启 SSR 只会引入更多兼容性问题，如window is not defined。

5.2 “OpenClaw 启动报错CUDA out of memory，但 GPU 显存明明充足”

现象：openclaw --gpu-layers 35启动失败，日志显示CUDA out of memory，nvidia-smi查看显存使用率仅 40%。
根因：OpenClaw 默认为每个模型实例分配固定显存池，未考虑多任务共享。当系统有其他进程（如 Chrome、VSCode）占用显存时，OpenClaw 申请失败。