企业官网建设流程全解析

1. 这不是个回形针，而是一套轻量级AI Agent协作框架的代号

“paperclip”这个词在技术圈里最近频繁出现在GitHub趋势榜、掘金热帖和前端面试复盘笔记里，但它跟办公文具毫无关系——它是一个基于Node.js与React双栈构建、专为快速原型验证而生的AI Agent协作框架代号。我第一次看到这个名字是在一个开源仓库的README第一行：“Paperclip: Minimalist AI Agent Orchestration for Local-first Dev Workflow”。当时就笑了：用回形针比喻“把松散组件拧成一股绳”的设计哲学，既准确又带点工程师式的冷幽默。它不追求大而全的调度中心，也不堆砌Kubernetes、LangChain或LlamaIndex这类重型生态，而是聚焦一个非常具体的场景：让前端开发者能在本地5分钟内启动一个可交互、可调试、可串联多个小型AI能力模块的轻量沙盒环境。

核心关键词里反复出现的Node.js、React、OpenClaw，其实已经勾勒出它的技术坐标系：Node.js是运行时底座（负责Agent生命周期管理、工具调用桥接、HTTP/SSE服务）；React是唯一UI层（所有Agent状态、输入输出、执行日志都通过React组件实时渲染）；OpenClaw则是它默认集成的底层AI能力引擎——不是简单调API，而是以进程内模块方式嵌入，支持本地模型加载、工具函数注册、上下文流式注入。你不需要先配好CUDA、拉镜像、改config.yaml，更不用在云控制台开实例、绑域名、设CORS；只要npm create paperclip@latest，选模板（CLI工具型 / 多Agent对话型 / 文件分析型），回车，它就自动完成Node.js版本校验（强制v18.20.4+ LTS）、依赖安装、OpenClaw本地编译（Ubuntu/Debian/CentOS7.9均预置适配脚本）、React开发服务器启动，并在http://localhost:3000打开一个带实时日志面板、Agent拓扑图、输入调试区的界面。这个“5分钟启动”不是营销话术，是我上周在客户现场实测的结果：客户用的是CentOS 7.9物理机，没有root权限，只开放了8080端口，我们用paperclip内置的--port=8080 --no-https参数直接跑通，连Nginx反向代理都不需要。

它解决的不是“如何造AGI”，而是“今天下午三点前，我要给市场部演示一个能自动读取销售Excel、生成周报摘要、再发邮件给总监的三步流程”。这种需求在真实业务中高频出现，但传统方案要么太重（搭LangChain+FastAPI+React，三天起步），要么太散（写三个独立脚本，手动传参，调试靠console.log）。paperclip把Agent抽象成“可声明式定义的函数节点”，每个节点有明确的inputSchema（JSON Schema）、outputSchema、execute()方法（Node.js函数），以及可选的uiComponent（React组件）。你不用写路由、不配中间件、不处理跨域，所有通信走内部消息总线。比如一个“Excel解析Agent”，它的execute()里调用SheetJS读取Buffer，用Zod校验字段，返回结构化JSON；它的uiComponent就是一个拖拽上传区+预览表格；整个过程对用户透明，你只关心“输入是什么、输出要什么、逻辑怎么写”。这正是它被大量React前端工程师自发传播的原因——它把AI工程的复杂性，降维到React组件开发的熟悉范式里。

2. 架构设计：为什么放弃“标准AI框架”，选择“回形针式紧固”

2.1 拒绝抽象泄漏：从OpenClaw的定位说起

OpenClaw本身是个很有意思的项目。它不像Ollama那样主打模型一键下载，也不像LMStudio那样专注GUI本地推理，它的核心文档里反复强调一句话：“OpenClaw is a toolkit, not a platform.”（OpenClaw是一个工具包，不是一个平台）。这意味着它不提供统一的Agent调度器、不内置记忆存储、不封装RAG pipeline，而是提供一组底层原语：ModelRunner（模型执行器）、ToolRegistry（工具注册表）、ContextStream（上下文流）、PromptEngine（提示词引擎）。paperclip正是基于这个“不造轮子”的哲学，做了最关键的取舍：它不实现自己的Agent调度逻辑，而是把OpenClaw的ToolRegistry作为唯一执行中枢，所有Agent都注册为OpenClaw的tool，由OpenClaw的runTool方法统一调用。

这个设计看似偷懒，实则精准避开了三个常见陷阱：

• 状态同步陷阱：很多框架用Redis或SQLite存Agent状态，本地开发时还得配数据库连接。paperclip直接用Node.js进程内存存Map<string, AgentState>，启动即清空，调试时Ctrl+C重启就是最干净的状态重置。
• 序列化陷阱：Agent间传递数据常需JSON.stringify/parse，遇到Date、Buffer、Function就崩溃。paperclip规定所有Agent输入输出必须是Plain Object（Zod校验），内部用structuredClone深拷贝，彻底规避序列化问题。
• 调试可见性陷阱：大型框架的Agent执行链路像黑盒，日志分散在不同服务里。paperclip强制每个Agent执行前后都emit事件到全局EventEmitter，React UI层订阅这些事件，实时渲染执行耗时、输入输出快照、错误堆栈——你看到的不是“Agent 3 failed”，而是“ExcelParserAgent: input={file: <Buffer 50 4B ...>}, error=ZodError: 'sales' is required”。

我试过把paperclip和LangChain对比跑同一个Excel解析任务：LangChain需要配置LLMChain、Tool、AgentExecutor三层对象，写120行代码；paperclip只需定义一个Agent对象，68行，其中32行是Zod schema。关键差异在于，LangChain的AgentExecutor会把tool调用结果再喂给LLM做决策，而paperclip的Agent是确定性函数——输入确定，输出确定，没有LLM参与的“幻觉环节”。这牺牲了通用性，但换来了可预测性和可测试性。对于“读Excel→提关键指标→发邮件”这种确定性流程，确定性比通用性重要十倍。

2.2 React层：不是渲染AI，而是渲染“AI的思考过程”

paperclip的React部分，彻底抛弃了“AI应用=聊天界面”的惯性思维。它的默认UI不是ChatInput + MessageList，而是一个Agent Flow Canvas（Agent流程画布）。这个画布不是D3或AntV做的复杂拓扑图，而是用React Flow库极简定制的：每个Agent是一个可拖拽节点，节点间连线表示数据流向，连线上的标签显示传输的字段名（如“salesData”、“summaryText”）。你双击节点，弹出该Agent的React配置面板——这里才是真正的魔法发生地。

以“邮件发送Agent”为例，它的配置面板包含三块：

• 输入映射区：下拉菜单选择上游Agent的输出字段（如“ExcelParserAgent.summary”），右侧输入框填邮件主题模板（支持{{summary}}变量插值）；
• 参数配置区：SMTP服务器地址、端口、认证凭据（加密存储在本地~/.paperclip/config.json，非明文）；
• UI预览区：实时渲染一封模拟邮件，点击“发送测试”按钮触发Node.js后端调用Nodemailer。

这个设计背后是深刻的用户体验洞察：AI工程师关心模型参数，业务方关心输入输出，而前端开发者最熟悉的是“数据绑定”和“表单联动”。paperclip把Agent配置变成React表单开发，所有逻辑都在useEffect和useState里，没有自定义Hook，没有Context Provider嵌套，甚至没用Redux。我见过有团队用paperclip两周内重构了旧版Python脚本驱动的报表系统，前端同学只负责写几个Agent的UI组件，后端同学只负责写execute()里的业务逻辑，连TypeScript接口都由Zod schema自动生成（z.infer<typeof schema>），联调时间从三天压缩到两小时。

更妙的是它的SSE集成。React前端通过EventSource连接/api/sse/agent-execution，Node.js后端用res.write("data: ...\n\n")推送结构化事件。事件格式固定为：

{ "type": "agent-start", "agentId": "email-sender", "timestamp": 1717023456789, "input": {"summary": "Q2销售额增长12%..."} }

这样做的好处是，前端可以精确控制每个事件的渲染时机：agent-start时高亮节点，agent-success时打绿色对勾，agent-error时弹出错误详情。用户看到的不是“正在处理…”，而是“ExcelParserAgent已完成 → EmailSenderAgent已启动 → EmailSenderAgent发送成功”。这种粒度的反馈，是任何轮询方案（包括React + SSE/WebSocket轮询文件变化）都无法提供的流畅感。

2.3 Node.js层：进程内OpenClaw，而非远程API调用

paperclip的Node.js服务启动时，会执行一个关键操作：openclaw.loadModel('phi-3-mini', { device: 'cpu' })。注意，这不是调用fetch('http://localhost:3001/v1/chat/completions')，而是直接在当前Node.js进程里加载量化后的Phi-3模型（约2.3GB内存占用）。OpenClaw的Ubuntu安装教程里强调“需确保系统有足够RAM”，原因就在这里——它走的是onnxruntime-node原生绑定路径，绕过了HTTP网络栈。

这种设计带来三个硬性优势：

• 零网络延迟：Agent间调用是进程内函数调用，毫秒级响应。我测过本地CPU上Phi-3-mini处理100字提示词的平均延迟是320ms，而同等条件下调用本地Ollama API是890ms（含HTTP握手、序列化、反序列化）。
• 完全离线：所有模型、工具、配置都存在本地，不依赖任何外部API密钥。客户在金融内网部署时，这点成了决定性因素。
• 调试直连：VS Code调试器可以直接断点到OpenClaw的C++ binding层，查看Tensor内存布局。虽然多数人用不到，但当遇到onnxruntime的InvalidArgument错误时，这能省下两天排查时间。

当然，代价也很明显：内存占用高、启动慢（首次加载模型需15-20秒）、不支持GPU加速（除非你手动编译OpenClaw的CUDA版本）。paperclip对此的应对策略是“分层加载”：默认只加载基础模型（Phi-3-mini），当你在UI里启用“高级分析Agent”时，才动态加载更大的Qwen2-1.5B模型。它的package.json里scripts字段清晰体现了这种哲学：

"scripts": { "dev": "node scripts/start-dev.js", // 启动基础版 "dev:full": "OPENCLAW_MODEL=qwen2-1.5b node scripts/start-dev.js", // 启动全功能版 "build": "npm run build:core && npm run build:ui", // 分离构建 "build:core": "tsc -p tsconfig.core.json", // 只编译Node.js逻辑 "build:ui": "react-scripts build" // 只构建React }

这种可拆分的构建，让团队能按需优化——前端同学只管build:ui，后端同学只管build:core，CI流水线也能并行执行，构建时间从4分23秒降到1分58秒。

3. 核心细节解析：从零开始搭建一个“销售周报Agent”

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

paperclip对Node.js版本有严格要求（v18.20.4 LTS或v20.11.1 LTS），这不是随意设定的。OpenClaw的onnxruntime-node绑定在v18.20.4上经过完整测试，v22.x+因V8引擎变更导致Tensor内存释放异常。所以第一步永远是版本校验：

# 检查是否安装及版本 node -v # 必须输出 v18.20.4 或 v20.11.1 npm -v # 必须 >= 9.6.7 # 若未安装，推荐用nvm（避免sudo权限问题） 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 nvm alias default 18.20.4

提示：CentOS 7.9用户注意，系统自带的Python 2.7会导致node-gyp编译失败。必须先升级Python：

sudo yum install centos-release-scl sudo yum install python38 sudo alternatives --config python # 选择python3.8

安装完Node.js后，不要急着npm create paperclip。先验证OpenClaw本地编译环境：

# 下载OpenClaw源码（paperclip会自动做，但手动验证更稳） git clone https://github.com/openclaw/openclaw.git cd openclaw npm install --build-from-source # 强制源码编译，跳过预编译二进制 # 编译成功后，运行测试 npm test # 应看到"✓ ModelRunner loads phi-3-mini"等通过项

这一步能提前暴露glibc版本（CentOS 7.9需≥2.17）、GCC版本（需≥7.3）等问题。我踩过的最大坑是：某客户服务器glibc 2.12，OpenClaw编译报错undefined symbol: clock_gettime。解决方案不是升级glibc（风险太大），而是用paperclip的--legacy-mode参数启动，它会自动切换到纯JavaScript的ONNX Runtime后端（性能降30%，但能跑）。

3.2 创建Agent：从Excel解析到邮件发送的四步编码

假设我们要建一个“销售周报Agent”，流程是：上传Excel → 解析销售数据 → 生成摘要 → 发送邮件。在paperclip里，这对应四个Agent，但编码工作集中在src/agents/目录：

Step 1：ExcelParserAgent（解析）

// src/agents/excel-parser.ts import { z } from 'zod'; import * as XLSX from 'xlsx'; export const ExcelParserSchema = z.object({ file: z.instanceof(Buffer), // 必须是Buffer，非File对象（前端已转） }); export type ExcelParserInput = z.infer<typeof ExcelParserSchema>; export const ExcelParserOutputSchema = z.object({ summary: z.string(), salesData: z.array(z.object({ region: z.string(), amount: z.number(), growth: z.number() })) }); export async function execute(input: ExcelParserInput) { const workbook = XLSX.read(input.file, { type: 'buffer' }); const sheet = workbook.Sheets[workbook.SheetNames[0]]; const jsonData = XLSX.utils.sheet_to_json(sheet); // 业务逻辑：计算Q2增长率 const q2Data = jsonData.filter((row: any) => row.quarter === 'Q2'); const totalSales = q2Data.reduce((sum, row) => sum + row.amount, 0); return { summary: `Q2销售额总计${totalSales.toFixed(0)}万元，同比增长12.3%`, salesData: q2Data.map(row => ({ region: row.region, amount: row.amount, growth: parseFloat((row.growth * 100).toFixed(1)) })) }; }

Step 2：SummaryGeneratorAgent（摘要）

// src/agents/summary-generator.ts import { z } from 'zod'; import { loadModel } from 'openclaw'; // 注意：这里不直接调用OpenClaw，而是用其PromptEngine export const SummaryGeneratorSchema = z.object({ rawText: z.string(), targetLength: z.number().default(100) }); export async function execute(input: SummaryGeneratorSchema) { const model = await loadModel('phi-3-mini'); const prompt = `请将以下销售数据摘要为${input.targetLength}字内的中文报告，突出增长率和区域对比：\n${input.rawText}`; const result = await model.generate(prompt, { maxTokens: 200 }); return { summary: result.text.trim() }; }

Step 3 & 4：EmailSenderAgent（发送）与UI组件

// src/agents/email-sender/ui.tsx import React, { useState } from 'react'; import { useAgentConfig } from '@/hooks/useAgentConfig'; export default function EmailSenderUI() { const [to, setTo] = useState('director@company.com'); const [subject, setSubject] = useState('【周报】Q2销售摘要 - {{date}}'); const config = useAgentConfig('email-sender'); // 自动绑定配置 return ( <div className="space-y-4"> <div> <label className="block text-sm font-medium">收件人</label> <input type="email" value={to} onChange={(e) => setTo(e.target.value)} className="w-full p-2 border rounded" /> </div> <div> <label className="block text-sm font-medium">主题模板</label> <input type="text" value={subject} onChange={(e) => setSubject(e.target.value)} placeholder="支持 {{summary}} {{date}} 变量" className="w-full p-2 border rounded" /> </div> <button onClick={() => config.update({ to, subject })} className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700" > 保存配置 </button> </div> ); }

注意：所有Agent的execute()函数必须是async，返回Promise。paperclip的调度器会自动await，错误会统一捕获并推送到UI。不要在execute里写try/catch，那会吞掉错误堆栈。

3.3 配置串联：在Flow Canvas里“拧紧回形针”

启动npm run dev后，打开http://localhost:3000，你会看到空白的Flow Canvas。点击左上角“+ Add Agent”，搜索“excel-parser”，拖到画布中央。再添加“summary-generator”、“email-sender”。此时三个节点孤立存在，需要连线：

• 从excel-parser的输出端口（标着summary和salesData）拖线到summary-generator的输入端口（标着rawText），在连线标签处输入summary；
• 从summary-generator的输出summary拖线到email-sender的输入content；
• 最后，点击email-sender节点，在右侧面板里填入SMTP配置（host: smtp.exmail.qq.com, port: 465, user: your@company.com, pass: app-password）。

整个过程无需写一行配置JSON，全部可视化操作。但背后paperclip生成的flow.json长这样：

{ "nodes": [ { "id": "excel-parser", "type": "excel-parser", "position": { "x": 100, "y": 100 } }, { "id": "summary-generator", "type": "summary-generator", "position": { "x": 300, "y": 100 } } ], "edges": [ { "id": "e1", "source": "excel-parser", "target": "summary-generator", "sourceHandle": "summary", "targetHandle": "rawText" } ] }

这个JSON会被src/server/flow-engine.ts实时监听并解析。关键点在于：连线不是简单的字符串映射，而是类型安全的字段绑定。如果excel-parser输出没有summary字段（Zod校验失败），连线会变红并提示“字段不存在”。这种设计让错误在UI配置阶段就暴露，而不是等到执行时报Cannot read property 'summary' of undefined。

4. 实操过程：一次完整的本地部署与调试记录

4.1 Ubuntu 22.04一键部署全流程（含OpenClaw编译）

这是我在客户现场的真实记录，全程录像，时间戳精确到秒：

T=00:00：登录Ubuntu 22.04服务器（4核8G，无GPU）

# 更新系统 sudo apt update && sudo apt upgrade -y # 安装基础依赖 sudo apt install -y build-essential python3.10-dev libssl-dev libffi-dev # 安装Node.js v18.20.4（用官方二进制，非apt） curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs node -v # 输出 v18.20.4

T=02:15：创建项目并启动

# 创建目录 mkdir sales-report-agent && cd sales-report-agent # 初始化paperclip（自动检测Node.js版本） npm create paperclip@latest -- --template=multi-agent # 回答交互式问题： # ? Project name: sales-report-agent # ? Select agents to include: excel-parser, summary-generator, email-sender # ? OpenClaw model to preload: phi-3-mini (CPU) # ? Port to run on: 3000

T=05:48：等待依赖安装与OpenClaw编译。此时npm在后台执行：

• npm install（安装React、Express、Zod等）
• cd node_modules/openclaw && npm install --build-from-source（编译ONNX Runtime）
• npx tsc（编译TypeScript）

T=12:33：编译完成，自动启动：

> sales-report-agent@0.1.0 dev > node scripts/start-dev.js ✅ Paperclip server listening on http://localhost:3000 ✅ OpenClaw loaded phi-3-mini (CPU, 2.3GB RAM) ✅ React dev server started

T=12:35：浏览器打开http://localhost:3000，Flow Canvas加载。上传一个测试Excel（3列：region, amount, growth），点击“Run Flow”。实时日志显示：

[12:36:01] ExcelParserAgent started [12:36:02] ExcelParserAgent completed in 842ms [12:36:02] SummaryGeneratorAgent started [12:36:03] SummaryGeneratorAgent completed in 1210ms [12:36:03] EmailSenderAgent started [12:36:05] EmailSenderAgent completed in 1890ms ✅ Flow executed successfully

整个过程12分35秒，比客户原计划的“找外包公司评估方案”节省了3天。关键成功因素是paperclip的--template=multi-agent参数自动配置了所有Agent的Zod schema和UI组件，我们只修改了email-sender的SMTP配置。

4.2 React + SSE调试技巧：捕获每一帧执行流

paperclip的SSE调试不是看Network面板里的event-stream，而是用React DevTools的Custom Hooks面板。在src/hooks/useAgentExecution.ts里，我们定义了一个自定义Hook：

export function useAgentExecution(flowId: string) { const [events, setEvents] = useState<AgentEvent[]>([]); useEffect(() => { const eventSource = new EventSource(`/api/sse/flow/${flowId}`); const handleEvent = (e: MessageEvent) => { const data = JSON.parse(e.data) as AgentEvent; setEvents(prev => [...prev, data]); // 关键技巧：为每个Agent事件加performance.mark if (data.type === 'agent-start') { performance.mark(`agent-${data.agentId}-start`); } else if (data.type === 'agent-success') { performance.mark(`agent-${data.agentId}-end`); performance.measure( `agent-${data.agentId}-duration`, `agent-${data.agentId}-start`, `agent-${data.agentId}-end` ); } }; eventSource.addEventListener('message', handleEvent); return () => eventSource.close(); }, [flowId]); return events; }

这样，在Chrome DevTools的Performance面板里，点击录制，执行Flow，停止后就能看到每个Agent的精确耗时（精确到微秒），还能看到主线程阻塞情况。上周我们发现summary-generator耗时突增到3s，用这个方法定位到是phi-3-mini模型在处理长文本时触发了V8垃圾回收，解决方案是加--max-old-space-size=4096参数启动Node.js。

另一个技巧是SSE的retry机制。paperclip的/api/sse/flow/:id端点默认设置retry: 3000（3秒重连）。当网络抖动时，前端不会断连，而是静默重试。我们在UI里加了个状态条：

{isConnected ? ( <div className="flex items-center text-green-600"> <div className="w-2 h-2 bg-green-600 rounded-full mr-2"></div> 实时连接中 </div> ) : ( <div className="flex items-center text-yellow-600"> <div className="w-2 h-2 bg-yellow-600 rounded-full mr-2 animate-pulse"></div> 正在重连... </div> )}

这个状态条不是靠心跳包，而是监听EventSource的onerror事件，真正做到了“连接状态可视化”。

4.3 OpenClaw接入Microsoft Teams的实战方案

客户提出需求：“周报生成后，能不能直接发到Teams频道？”。paperclip不内置Teams集成，但提供了标准的Webhook Agent模板。我们用了三步实现：

Step 1：创建TeamsWebhookAgent

// src/agents/teams-webhook.ts import { z } from 'zod'; export const TeamsWebhookSchema = z.object({ webhookUrl: z.string().url(), title: z.string(), text: z.string() }); export async function execute(input: TeamsWebhookSchema) { const response = await fetch(input.webhookUrl, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ "@type": "MessageCard", "@context": "https://schema.org/extensions", "title": input.title, "text": input.text }) }); if (!response.ok) { throw new Error(`Teams webhook failed: ${response.status} ${response.statusText}`); } return { status: 'sent' }; }

Step 2：在Flow Canvas里替换EmailSenderAgent

• 删除email-sender节点
• 添加teams-webhook节点
• 将summary-generator的summary输出连到teams-webhook的text输入
• 在teams-webhook配置面板里填入Teams频道Webhook URL（从Teams频道设置里复制）

Step 3：安全加固Teams Webhook URL含敏感token，不能明文存前端。paperclip的useAgentConfigHook会自动加密存储到~/.paperclip/config.json，且该文件权限设为600（仅用户可读写）。我们还加了URL校验：

// 在TeamsWebhookSchema里 webhookUrl: z.string().url().refine( url => url.startsWith('https://outlook.office.com/webhook/'), 'Must be a Microsoft Teams webhook URL' )

实测效果：从Excel上传到Teams收到卡片，全程12.8秒，卡片包含标题、摘要文本、发送时间戳。客户反馈：“比原来邮件提醒快，而且全员可见，不用再转发”。

5. 常见问题与排查技巧实录

5.1 Node.js版本冲突：v22.12+无法启动的根因与解法

这是近期最高频问题。当用户用nvm install node装了最新版（v22.12+），再运行npm create paperclip，会报错：

Error: The module '/path/to/node_modules/onnxruntime-node/build/Release/onnxruntime.node' was compiled against a different Node.js version using NODE_MODULE_VERSION 108. This Node.js version uses NODE_MODULE_VERSION 115.

根因：onnxruntime-node的预编译二进制绑定到特定Node.js ABI版本（NODE_MODULE_VERSION）。v18.x对应108，v20.x对应115，v22.x对应120。paperclip的package-lock.json锁定的是v18兼容版，所以v22无法加载。

解法分三级：

• 一级（推荐）：切回v18.20.4

  nvm install 18.20.4 nvm use 18.20.4 npm create paperclip@latest

• 二级（临时）：强制重编译（需系统有完整编译工具链）

  npm install --build-from-source onnxruntime-node # 注意：这会下载ONNX Runtime源码，编译耗时15-20分钟

• 三级（应急）：用Docker隔离环境

  FROM node:18.20.4-slim WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . CMD ["npm", "run", "start"]

  这样即使宿主机是v22，容器内仍是v18。

提示：node -p process.versions.modules可查当前Node.js的ABI版本。paperclip文档首页就放着一张ABI版本对照表，建议截图保存。

5.2 React启动白屏：不是React Native，而是SSE连接失败

react native 启动白屏这个热搜词其实是误导。paperclip是Web应用，但新手常误以为能用React Native打包。真正导致白屏的是SSE连接失败。典型现象：页面空白，Console无报错，Network面板看不到/api/sse/flow/xxx请求。

排查路径：

1. 检查CORS：paperclip默认允许http://localhost:3000，但如果用IP访问（如http://192.168.1.100:3000），需在server/config.ts里加：

   export const CORS_ORIGINS = ['http://localhost:3000', 'http://192.168.1.100:3000'];

2. 检查反向代理：若用Nginx，必须开启SSE支持：

   location /api/sse/ { proxy_pass http://localhost:3001; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_cache_bypass $http_upgrade; }

3. 检查防火墙：Ubuntu的ufw可能拦截3001端口（paperclip后端默认端口）：

   sudo ufw allow 3001

我们有个客户白屏持续2小时，最后发现是公司防火墙策略阻止了text/event-streamMIME类型的响应。解决方案是改用WebSocket降级（paperclip支持?transport=ws参数）。

5.3 OpenClaw Ubuntu安装失败：glibc与GCC版本陷阱

OpenClaw的Ubuntu安装教程说“支持Ubuntu 20.04+”，但实际在Ubuntu 20.04上会失败，因为其glibc 2.31不兼容ONNX Runtime的某些符号。paperclip的scripts/install-openclaw.sh脚本会自动检测：

# 检测glibc版本 GLIBC_VERSION=$(ldd --version | head -1 | awk '{print $NF}') if [[ "$GLIBC_VERSION" < "2.32" ]]; then echo "⚠️ glibc $GLIBC_VERSION too old, using fallback JS backend" npm install onnxruntime-web else npm install --build-from-source onnxruntime-node fi

实操心得：在老旧系统上，不要硬刚编译。paperclip的fallback模式（用onnxruntime-web）虽慢3倍，但能跑通。我们曾在一个glibc 2.17的CentOS 7.9机器上，用fallback模式成功运行phi-3-mini，只是生成摘要从1.2秒变成3.8秒，业务可接受。

5.4 “手写React Agent”误区：UI组件不是Agent核心

很多前端工程师看到src/agents/*/ui.tsx，第一反应是“我要手写React组件”。这是个认知偏差。paperclip的Agent核心是execute()函数，UI组件只是配置入口。如果你只写UI不写execute，Flow会报错“Agent xxx has no execute function”。

正确分工：

• 后端同学：写execute()，处理业务逻辑、调用OpenClaw、处理Buffer/Stream；
• 前端同学：写ui.tsx，用React组件让用户填参数，调用useAgentConfig().update()存配置；
• 共同约定：Zod schema是契约，双方都按schema开发，无需联调。

我们团队实践下来，一个Agent的开发周期：后端1小时（写execute+schema），前端0.5小时（写UI），联调5分钟（验证schema匹配）。比传统前后端分离快3倍。

5.5 性能瓶颈定位：CPU占用100%时的三步诊断法

当node进程CPU飙到100%，别急着杀进程。paperclip内置了性能诊断端点：

1. 第一步：查热点Agent
   访问`http://localhost:3000/api/debug/h