企业官网建设流程全解析

1. 项目概述：Paperclip 不是回形针，而是一个面向 AI Agent 开发的轻量级 React 运行时框架

你搜“paperclip”时，第一反应可能是办公桌抽屉里的那个银色小金属件——但在这个技术语境下，它完全不是那个意思。Paperclip 是一个近期在开源社区悄然升温的、专为构建可组合、可调试、可嵌入式 AI Agent 前端界面而设计的 React 运行时框架。它不替代 React，也不试图重写 React；相反，它像一副精密的“智能接口适配器”，把 React 组件树变成一个能与 LLM 调用链、工具调用（Tool Calling）、状态流（State Stream）和用户意图反馈实时对齐的活体结构。你看到的热词里反复出现的 OpenClaw、Node.js、React、AI agents，其实都在指向同一个现实：当前 AI Agent 的开发卡点，不在后端模型调用，而在前端如何让 Agent 的“思考过程”可观察、可干预、可复用。Paperclip 正是为此而生。

它的核心价值非常具体：当你用 React 写一个带搜索、文件上传、多步确认、结果可视化功能的 AI 助手时，传统方式需要你手动管理 loading 状态、错误 fallback、中间步骤缓存、工具调用日志、甚至还要自己封装一套“Agent 生命周期钩子”。Paperclip 把这些全部抽象成声明式组件和 hooks，比如<AgentStep />、useAgentState()、useToolResult()，让你写出来的代码看起来就像在描述业务逻辑本身，而不是在写状态胶水。我去年在给一家做法律文书辅助的客户做 PoC 时，用 Paperclip 三天内就搭出了一个支持“条款溯源→风险标注→生成修订建议→导出对比报告”的四步 Agent 流程界面，而同样功能用原生 React + Zustand + 自定义 hooks 写，团队预估要 10–12 人日。这不是概念炒作，而是真实压缩了前端在 AI 应用层的工程熵值。

它和 OpenClaw 的关系也常被误解。OpenClaw 是一个完整的 AI Agent 框架，包含服务端编排、工具注册中心、LLM 路由、安全沙箱等，属于“大脑+脊椎”；Paperclip 则是它的“前额叶皮层”——负责把大脑的决策转化为用户可理解、可交互、可信任的视觉表达。两者不是竞品，而是天然搭档。你在 OpenClaw 官方文档里看到的“Web UI 部署指南”，默认推荐的就是 Paperclip + Vite 模板。至于 Node.js，它在这里的角色很务实：Paperclip 的 CLI 工具链（如paperclip dev、paperclip build）底层依赖 Node.js 运行时；同时，它生成的前端包可通过 Node.js 服务（Express/Fastify）静态托管，也可直接部署到 CDN。React 则是它的唯一 UI 基底——Paperclip 不支持 Vue 或 Svelte，这点非常明确，也恰恰是它保持轻量和深度集成的前提。

如果你正在准备 2026 年的 React 前端面试，Paperclip 相关问题大概率会出现在“AI 时代前端新范式”类开放题中。面试官不会考你 API 列表，但会问：“如果一个 Agent 在执行‘分析 PDF 合同并标出违约条款’时卡在第三步，用户点击‘重试’按钮，你如何确保 UI 不仅刷新结果，还保留前两步的上下文、高亮区域和用户批注？”——这正是 Paperclip 的useAgentState({ preserve: true })解决的问题。它不是炫技，而是把前端从“状态搬运工”升级为“意图协作者”。

2. 核心设计思路：为什么不用现有方案？Paperclip 的三层架构取舍逻辑

2.1 为什么不用纯 React + 状态库（Zustand / Jotai / Redux）？

这是最常被问到的问题。答案很直白：状态粒度错位。Zustand 管理的是“页面状态”，比如搜索框输入值、侧边栏展开与否；而 AI Agent 的状态是“意图流状态”——它包含：当前执行步骤编号、上一步输出的结构化数据、工具调用参数、LLM 返回的 raw text + tool_calls 数组、用户中途插入的修正指令、甚至某次失败后自动降级的备选策略。把这些全塞进一个 store，很快就会变成“状态沼泽”。

我实测过一个典型场景：一个支持“上传合同→提取关键条款→比对模板库→生成差异报告”的 Agent。用 Zustand 实现时，store 结构最终膨胀为：

interface AgentStore { step: 'upload' | 'extract' | 'compare' | 'report'; uploadFile?: File; extractedClauses: Clause[]; comparisonResult: { matched: Clause[]; unmatched: Clause[] }; reportHtml: string; isRunning: boolean; errorStep?: 'upload' | 'extract' | 'compare' | 'report'; retryCount: Record<'upload' | 'extract' | 'compare' | 'report', number>; // ……还有日志数组、用户反馈标记、超时控制标志 }

这个 store 有 12 个字段，其中 7 个只在特定步骤有效，3 个需跨步骤联动。每次setState都要深拷贝整个对象，且useStore订阅无法精准感知“仅 extract 结果变化”，导致大量无效 re-render。Paperclip 的解法是按步骤切片状态：每个<AgentStep>组件自带独立的、生命周期绑定的状态域，父组件只需通过onStepChange接收结构化事件，无需维护全局状态树。这背后是它对 React Server Components（RSC）理念的前端化移植——把“状态”和“UI 片段”强绑定，而非松耦合。

2.2 为什么不用 Next.js App Router 或 Remix？

Next.js 和 Remix 是优秀的全栈框架，但它们的设计哲学与 Paperclip 的定位存在根本性冲突。Next.js 的app/目录强调“路由即数据获取”，适合内容型网站或 SSR 优先的应用；Remix 强调“表单即数据操作”，适合 CRUD 密集型后台。而 Paperclip 面向的是长生命周期、多轮交互、状态持续演进的 Agent 场景——用户可能在一个页面停留 15 分钟，经历 8 次 LLM 调用、4 次工具执行、3 次人工干预。这种场景下，SSR 首屏意义有限，CSR 的响应性和状态持久性才是关键。

更重要的是，Paperclip 必须支持离线 Agent 执行模拟。比如在本地开发时，你希望用 mock LLM 返回固定 JSON，验证 UI 对不同tool_calls的渲染逻辑。Next.js 的generateStaticParams和getServerSideProps天然排斥这种动态、非路由驱动的数据流。Paperclip 的useAgentRuntime()hook 则允许你传入任意runtime实现（MockRuntime、OpenClawRuntime、LocalOllamaRuntime），完全解耦执行环境。我在调试一个金融风控 Agent 时，就是靠切换 runtime，在无网络环境下反复测试“当模型返回空数组时，UI 是否显示友好提示而非崩溃”，这种能力 Next.js 无法原生提供。

2.3 为什么选择轻量运行时，而非重框架（如 LangChain.js + React 绑定）？

LangChain.js 是强大的后端编排库，但它对前端的抽象停留在“调用函数”层面。chain.invoke()返回 Promise，你仍需自己处理 loading、error、streaming 分块、tool call 解析、结果格式化。Paperclip 把这些都下沉为组件级契约：

• <AgentStep name="extract">内部自动订阅extract步骤的 state；
• <ToolResult type="pdf_parser" />自动匹配tool_calls中type === 'pdf_parser'的结果，并渲染其content；
• <StreamingText source="llm_output" />自动消费llm_output字段的 streaming chunk，逐字渲染，支持暂停/继续。

这种契约不是魔法，而是基于 React 的useContext+useReducer构建的细粒度状态分发系统。Paperclip 的 bundle size（gzip 后）仅 12.3KB，而 LangChain.js + 其 React 绑定库通常超 150KB。对于需要快速加载、嵌入到企业内部系统的 Agent UI，体积是硬指标。我们曾把 Paperclip 构建的 Agent 组件打包成 Web Component，嵌入到一个基于 Angular 的老系统中，加载时间比同等功能的 iframe 方案快 3.2 倍——因为没有额外的框架解析开销。

2.4 为什么兼容 OpenClaw，却不兼容其他 Agent 框架？

Paperclip 的 OpenClaw 兼容性不是“官方合作”的结果，而是协议对齐的自然产物。OpenClaw 定义了一套标准的 Agent Runtime Protocol（ARP），核心是三个约定：

1. 状态结构：{ step: string, data: any, status: 'idle' | 'running' | 'success' | 'error', logs: [] }
2. 工具调用格式：{ type: string, input: any, output?: any }
3. 事件总线：通过agent:step:change、agent:tool:call、agent:llm:stream等自定义事件通信。

Paperclip 的OpenClawRuntime实现严格遵循这三点，因此只要你的 Agent 后端输出符合 ARP，Paperclip 就能无缝接入。反观其他框架（如 LangGraph、LlamaIndex），它们要么没有统一协议（LangGraph 用 Python 状态机），要么协议重心在后端编排（LlamaIndex 的QueryEngine无前端状态映射）。Paperclip 的设计哲学是：“我不定义 Agent 怎么思考，我只定义 Agent 的思考如何被看见。”——这决定了它的兼容边界。

3. 核心细节解析：Paperclip 的四大支柱组件与 Hooks 实操要点

3.1<AgentRoot>：不只是根容器，而是状态中枢与错误边界

<AgentRoot>是 Paperclip 应用的入口组件，但它远不止<div>包裹作用。它承担三个关键职责：

第一，初始化 Runtime 实例并注入 Context。
你不能在任意组件里new OpenClawRuntime()，因为 Runtime 需要全局唯一实例来管理 WebSocket 连接、事件监听和状态同步。<AgentRoot>内部会创建 runtime，并通过 React Context 提供给所有子组件。这意味着，即使你在多个<AgentStep>中调用useAgentRuntime()，拿到的都是同一个实例。

// ✅ 正确：在顶层包裹 function App() { return ( <AgentRoot runtime={new OpenClawRuntime({ endpoint: 'https://api.your-oc-server.com/agent', apiKey: 'your-key' })} > <MainAgent /> </AgentRoot> ); } // ❌ 错误：在子组件里 new 实例 function BadComponent() { const runtime = new OpenClawRuntime(...); // 每次渲染都新建，连接泄漏！ return <AgentStep runtime={runtime} />; }

第二，提供统一的错误捕获与降级机制。
Paperclip 默认启用ErrorBoundary，但它的降级策略是智能的：当某个<AgentStep>抛出异常，它不会整页崩溃，而是自动将该步骤置为error状态，并显示你配置的fallbackUI。更重要的是，它会保留该步骤之前的data，以便用户点击“重试”时能恢复上下文。

<AgentStep name="compare" fallback={<div className="text-red-500">条款比对失败，请检查模板库</div>} > {/* 步骤逻辑 */} </AgentStep>

第三，管理全局状态生命周期。
<AgentRoot>会在组件卸载时自动调用runtime.destroy()，关闭 WebSocket 连接、清除定时器、释放内存。这是防止内存泄漏的关键。我见过太多项目在 Agent 页面频繁切换时，WebSocket 连接数指数级增长，最终拖垮浏览器。Paperclip 的这个自动清理，是经过 Chromium DevTools Memory Tab 实测验证的。

提示：<AgentRoot>支持onErrorprop，用于捕获未被<AgentStep>捕获的全局错误（如 runtime 初始化失败）。建议在此处上报 Sentry，并引导用户刷新页面。

3.2<AgentStep>：声明式步骤定义，取代手动状态管理

<AgentStep>是 Paperclip 最具革命性的组件。它把“步骤”从逻辑概念变为 UI 一等公民。使用时，你只需声明name，Paperclip 就自动为你处理：

• 当前是否激活（active）
• 是否正在运行（running）
• 是否成功完成（success）
• 是否出错（error）
• 上次运行的data（结构化输出）
• 关联的logs（工具调用日志）

<AgentStep name="extract"> {({ data, status, logs }) => ( <div> <h3>条款提取中...</h3> {status === 'success' && ( <ul> {data.clauses.map((c: Clause) => ( <li key={c.id}>{c.text}</li> ))} </ul> )} {logs.length > 0 && ( <div className="text-sm text-gray-500"> 最近日志：{logs[logs.length - 1].message} </div> )} </div> )} </AgentStep>

这里的关键是：data不是字符串，而是extract步骤的结构化输出。Paperclip 会自动解析 OpenClaw 返回的data字段（通常是 JSON），并做类型推断。如果你在 OpenClaw 的extract工具中返回{ clauses: [...] }，那么data.clauses就是可用的。

实操技巧：

• name必须全局唯一，且与 OpenClaw 后端定义的步骤名完全一致（大小写敏感）；
• 可以用defaultDataprop 预设初始数据，避免首次渲染空白；
• shouldRunprop 接收函数(prevData) => boolean，用于条件触发（例如：只有当uploadFile存在时才运行extract步骤）。

3.3useAgentState()：比 useState 更懂 Agent 的状态 Hook

useAgentState()是 Paperclip 的核心 Hook，但它不是useState的简单封装。它的设计目标是解决 AI Agent 中最棘手的状态同步问题：如何让 UI 精准反映 LLM 的“思考进度”，而非仅仅“请求完成”。

传统做法是监听fetch().then()，但这只能告诉你“HTTP 请求结束了”，无法知道 LLM 是否还在流式输出、工具是否正在执行、用户是否已中断。useAgentState()则订阅 runtime 的实时状态流：

function StreamingStatus() { const { step, status, llmOutput, toolCalls } = useAgentState(); return ( <div> <div>当前步骤：{step}</div> <div>状态：{status}</div> {llmOutput && ( <div className="font-mono text-sm"> {/* 逐字渲染，支持暂停 */} <StreamingText source="llm_output" /> </div> )} {toolCalls.length > 0 && ( <div>正在调用工具：{toolCalls[0].type}</div> )} </div> ); }

useAgentState()返回的对象包含：

• step: 当前活跃步骤名（string）
• status:'idle' | 'running' | 'success' | 'error' | 'interrupted'
• data: 当前步骤的结构化输出（any）
• llmOutput: LLM 的流式文本输出（string，实时更新）
• toolCalls: 当前待执行或正在执行的工具列表（ToolCall[]）
• logs: 全局日志数组（LogEntry[]）

为什么比useEffect + useState更优？
假设你要实现“当 LLM 输出超过 100 字时，自动高亮关键词”。用useEffect，你需要监听llmOutput变化，然后setState触发 re-render；而useAgentState()内部已做防抖和 diff，只在真正有意义的变化时通知组件。实测在 1000 字/秒的流速下，useAgentState()的 re-render 次数比手动useEffect方案少 67%。

3.4useToolResult()：精准匹配工具调用结果，告别 if-else 链

在 AI Agent 中，一个步骤可能触发多个工具调用（如先查数据库，再调外部 API），而 UI 需要根据工具类型渲染不同内容。传统做法是：

// ❌ 冗长且易错 if (tool.type === 'pdf_parser') { renderPdfResult(tool.output); } else if (tool.type === 'legal_db_search') { renderDbResult(tool.output); } else if (tool.type === 'sentiment_analyzer') { renderSentiment(tool.output); }

useToolResult()提供类型安全的匹配：

// ✅ 简洁且可扩展 const pdfResult = useToolResult('pdf_parser'); const dbResult = useToolResult('legal_db_search'); if (pdfResult) { return <PdfPreview data={pdfResult.content} />; } if (dbResult) { return <DbTable data={dbResult.content.results} />; }

它的工作原理是：useToolResult(type)会从 runtime 的toolResultsMap 中查找type对应的最新结果，并自动订阅更新。如果该工具尚未返回结果，返回undefined；一旦返回，立即触发 re-render。

注意事项：

• useToolResult()必须在<AgentStep>内部调用，否则无法获取 runtime 上下文；
• 它返回的结果是ToolResult<T>类型，其中T是你定义的输出类型，Paperclip 支持 TypeScript 泛型推断；
• 如果同一工具被多次调用，useToolResult()默认返回最后一次结果；如需历史记录，可用useToolResults(type)获取数组。

4. 实操过程：从零搭建一个 OpenClaw + Paperclip 法律条款分析 Agent

4.1 环境准备：Node.js 与依赖安装的避坑指南

Paperclip 要求 Node.js 版本 ≥ 18.17.0（LTS），但强烈建议使用 20.11.1 或 22.12.0（最新 LTS）。为什么？因为 Paperclip 的devserver 使用了 Node.js 20+ 的fetch全局 API 和stream/web模块，低版本需额外 polyfill，增加 bundle 体积。

常见陷阱：

• Windows 用户务必用 PowerShell 运行wsl --status：很多教程说“用 CMD 查看 WSL”，但 CMD 的wsl命令常因路径问题失效。PowerShell 是微软官方推荐的 WSL 管理终端，且wsl --status能准确返回Default Distribution: Ubuntu-22.04等信息。如果显示WSL is not installed，请先从 Microsoft Store 安装 WSL，再运行wsl --install。
• CentOS 7.9 用户注意 OpenSSL 版本：Paperclip 的@paperclip/runtime-openclaw依赖node-fetch@3，后者要求 OpenSSL ≥ 1.1.1。CentOS 7.9 默认 OpenSSL 1.0.2k，必须升级：sudo yum install openssl11，然后设置export OPENSSL_CONF=/etc/pki/tls/openssl.cnf。否则npm install会卡在node-gyp rebuild。
• 不要用nvm安装后直接npm install -g create-paperclip-app：全局安装 CLI 工具容易引发权限问题。正确做法是：nvm install 22.12.0 && nvm use 22.12.0，然后在项目目录内运行npx create-paperclip-app@latest。

安装命令（推荐）：

# 创建项目 npx create-paperclip-app@latest my-legal-agent --template openclaw # 进入目录 cd my-legal-agent # 安装依赖（Paperclip 已预置 Vite + TypeScript + Tailwind） npm install # 启动开发服务器 npm run dev

此命令会生成一个预配置 OpenClaw Runtime 的模板，包含：

• src/App.tsx：已包裹<AgentRoot>
• src/agents/LegalAgent.tsx：一个示例 Agent 组件，含upload、extract、compare三步
• src/runtimes/openclaw.ts：预配置的 OpenClawRuntime 实例，含错误重试、token 刷新逻辑

4.2 OpenClaw 后端对接：配置阿里云 ECS 的实操细节

Paperclip 前端需要连接 OpenClaw 后端。阿里云 ECS 是性价比最高的选择（学生认证可享 9.9 元/月）。部署要点如下：

第一步：ECS 基础配置

• 选择Ubuntu 22.04 LTS镜像（兼容性最佳）
• 实例规格：ecs.c7.large（2核4G，足够跑 OpenClaw + Ollama）
• 安全组：放行80（HTTP）、443（HTTPS）、3000（OpenClaw dev port）、11434（Ollama port）

第二步：安装 OpenClaw

# 更新系统 sudo apt update && sudo apt upgrade -y # 安装 Node.js 20.x（OpenClaw 要求） curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs # 安装 OpenClaw CLI sudo npm install -g @openclaw/cli # 初始化项目 mkdir /opt/openclaw-legal && cd /opt/openclaw-legal openclaw init --template legal-assistant

第三步：配置反向代理（Nginx）
Paperclip 前端需通过 HTTPS 访问 OpenClaw，因此必须配置 Nginx 反向代理。关键配置/etc/nginx/sites-available/openclaw：

upstream openclaw_backend { server 127.0.0.1:3000; } server { listen 443 ssl; server_name your-domain.com; ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; location /api/agent/ { proxy_pass http://openclaw_backend/; 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; # 关键：启用 WebSocket 支持 proxy_set_header Sec-WebSocket-Protocol $http_sec_websocket_protocol; } # 静态资源直接返回 location / { root /var/www/paperclip-dist; try_files $uri $uri/ /index.html; } }

注意：/api/agent/路径必须与 Paperclip 前端OpenClawRuntime的endpoint一致。Paperclip 默认请求/api/agent/run，所以 Nginx 的location /api/agent/会代理所有以/api/agent/开头的请求。

第四步：Paperclip 前端配置
修改src/runtimes/openclaw.ts：

export const openclawRuntime = new OpenClawRuntime({ // 指向你的域名，不是 localhost！ endpoint: 'https://your-domain.com/api/agent/', apiKey: 'your-openclaw-api-key', // 在 OpenClaw 后端 .env 中设置 // 启用 WebSocket 实时状态推送 enableWebSocket: true, // 自动重连，避免网络抖动 reconnectOptions: { maxRetries: 5, delayMs: 1000 } });

4.3 核心 Agent 开发：实现“合同条款提取与比对”三步流程

我们以LegalAgent.tsx为例，实现一个完整流程：

Step 1：文件上传（upload）

<AgentStep name="upload" shouldRun={(prev) => !prev?.file}> {({ status }) => ( <div> <h3>上传合同 PDF</h3> <input type="file" accept=".pdf" onChange={(e) => { const file = e.target.files?.[0]; if (file) { // Paperclip 提供的便捷方法：上传文件并触发 upload 步骤 agentRuntime.uploadFile(file, { step: 'upload' }); } }} /> {status === 'running' && <div>上传中...</div>} </div> )} </AgentStep>

Step 2：条款提取（extract）

<AgentStep name="extract" shouldRun={(prev) => prev?.file}> {({ data, status }) => ( <div> <h3>提取关键条款</h3> {status === 'running' && <div>AI 正在分析合同...</div>} {status === 'success' && data?.clauses && ( <div> <h4>识别到 {data.clauses.length} 条关键条款：</h4> <ul> {data.clauses.map((c: Clause) => ( <li key={c.id}> <strong>{c.category}:</strong> {c.text.substring(0, 50)}... </li> ))} </ul> </div> )} </div> )} </AgentStep>

Step 3：模板比对（compare）

<AgentStep name="compare" shouldRun={(prev) => prev?.clauses}> {({ data, status }) => ( <div> <h3>比对标准模板</h3> {status === 'running' && <div>正在匹配行业标准...</div>} {status === 'success' && data?.diff && ( <div> <h4>差异报告：</h4> <div className="bg-green-50 p-4 rounded"> <strong>匹配条款：</strong> {data.diff.matched.length} 条 </div> <div className="bg-yellow-50 p-4 rounded mt-2"> <strong>风险条款：</strong> {data.diff.risk.length} 条（需人工审核） {data.diff.risk.map((r: RiskClause) => ( <div key={r.id} className="mt-1 p-2 bg-yellow-100 rounded"> <span className="font-bold">{r.original}</span> → 建议改为：{r.suggestion} </div> ))} </div> </div> )} </div> )} </AgentStep>

关键点说明：

• shouldRun确保步骤按序执行：extract只在upload成功后触发，compare只在extract成功后触发；
• agentRuntime.uploadFile()是 Paperclip 提供的快捷方法，它会自动将文件转为 base64，通过 OpenClaw 的/upload接口上传，并触发upload步骤；
• data的结构由 OpenClaw 后端的extract工具决定，Paperclip 不做任何假设，完全依赖后端返回。

4.4 调试与优化：利用 Paperclip DevTools 提升开发效率

Paperclip 内置浏览器 DevTools 扩展（Chrome/Firefox），安装后可在 F12 面板看到Paperclip标签页。它提供三大调试能力：

1. 实时状态树查看
左侧显示当前所有AgentStep的状态快照，包括data、logs、toolCalls。点击任意步骤，右侧显示其详细 JSON，支持折叠/展开、复制、搜索。

2. 步骤执行时间线
以甘特图形式展示各步骤的开始/结束时间、耗时、失败原因。当你发现compare步骤耗时 8.2 秒，可立即定位是数据库查询慢，还是 LLM 模型推理慢。

3. Mock Runtime 切换
点击“Switch to Mock”按钮，Paperclip 会自动替换 runtime 为MockRuntime，所有步骤返回预设的 mock 数据。你无需启动 OpenClaw 后端，就能验证 UI 渲染逻辑。Mock 数据可自定义：mockData.json文件放在public/mock/目录下，格式为：

{ "upload": { "file": "contract_v2.pdf" }, "extract": { "clauses": [{ "id": "1", "category": "付款", "text": "甲方应在收到发票后30日内支付..." }] }, "compare": { "diff": { "matched": 12, "risk": [...] } } }

实操心得：

• DevTools 的Logs面板比浏览器 Console 更有用，因为它过滤了所有与 Agent 无关的日志，只显示agent:step:change、agent:tool:call等关键事件；
• 在Network标签页，Paperclip 的请求会标记为Paperclip Request，方便你快速识别是哪个步骤触发的；
• 如果 UI 卡顿，打开Performance标签页录制，Paperclip 的StreamingText组件会显示为StreamingRender，你能直观看到流式渲染的帧率。

5. 常见问题与排查技巧实录：来自 12 个生产项目的踩坑总结

5.1 “OpenClaw 无法安全验证 sl2 环境”错误的根源与修复

这个错误并非 Paperclip 或 OpenClaw 的 bug，而是 Windows Subsystem for Linux（WSL）2 的证书信任链问题。当 Paperclip 前端通过fetch调用 OpenClaw 的 HTTPS 接口时，Node.js 运行时（在 WSL2 中）无法验证阿里云或 Let's Encrypt 的证书，因为 WSL2 的证书存储与 Windows 主机分离。

根本原因：
WSL2 是一个轻量级虚拟机，它有自己的 Linux 发行版和证书存储（/etc/ssl/certs）。当你在 Windows 上用 Chrome 访问https://your-domain.com，Chrome 使用 Windows 证书存储；但 WSL2 中的 Node.js 使用自己的证书存储，而该存储未同步 Windows 的根证书。

解决方案（三步）：

1. 在 WSL2 中更新 CA 证书

   sudo apt update && sudo apt install -y ca-certificates sudo update-ca-certificates

2. 将 Windows 证书导入 WSL2（关键）

   # 在 Windows PowerShell 中执行（以管理员身份） certutil -exportPFX -p "password" "ROOT" root.pfx # 将 root.pfx 复制到 WSL2 的 /tmp 目录 # 在 WSL2 中执行： sudo cp /tmp/root.pfx /usr/local/share/ca-certificates/ sudo openssl pkcs12 -in /usr/local/share/ca-certificates/root.pfx -clcerts -nokeys -out /usr/local/share/ca-certificates/windows-root.crt -password pass:password sudo update-ca-certificates

3. 重启 WSL2

   wsl --shutdown # 然后重新打开终端

提示：此问题在openclaw ubuntu安装教程中常被忽略，但它是生产环境部署的高频障碍。Paperclip 的OpenClawRuntime会自动检测证书错误，并在 DevTools 中提示“Certificate validation failed”，引导你执行上述步骤。

5.2 “React Native 启动白屏”问题的 Paperclip 适配方案

Paperclip 本身不支持 React Native，但很多团队想把 Agent UI 复用到移动端。白屏的根本原因是：Paperclip 的useAgentState()依赖浏览器 DOM API（如document.createElement用于 streaming 渲染），而 React Native 没有 DOM。

可行路径：

• 方案 A（推荐）：Webview 嵌入
  将 Paperclip 构建的静态页面（dist/目录）打包进 React Native 的WebView。优点：100% 复用代码；缺点：无法调用原生能力（如相机扫描合同）。我们为某银行 App 实现时，用react-native-webview加载https://your-domain.com/agent-mobile，并通过postMessage与原生层通信（如“用户点击扫码按钮” → 原生调起相机 → 返回图片 URL → WebView 中agentRuntime.uploadFile()）。

• 方案 B：定制 RN Runtime
  编写ReactNativeRuntime，替换OpenClawRuntime中的fetch和WebSocket实现为 React Native 的fetch和WebSocket（react-native-websocket），并重写StreamingText为Text组件的onLayout+setNativeProps。工作量大，但体验更原生。

避坑提醒：

• 不要尝试react-native-web方案，它对 Paperclip 的useEffect依赖和 streaming 渲染支持极差；
• WebView的scalesPageToFit={false}必须设置，否则移动端缩放会破坏 Paperclip 的响应式布局。

5.3 “Qwen2.5-3B 关联到 OpenClaw