1. 项目概述Paperclip 不是回形针而是一个被严重误读的 AI 工程实践符号“Paperclip”这个词在当前中文技术社区里正经历一场典型的语义漂移。它不再指代办公桌上那个弯折金属丝制成的物理小物件而是悄然演变为一个高度浓缩的技术隐喻——特指一类以React 为前端界面载体、Node.js 为后端执行引擎、OpenClaw 为底层智能体调度框架、Claude 系列为核心推理模型的新型 AI 应用开发范式。我第一次在 GitHub 上看到paperclip这个仓库名时也以为是某个 UI 组件库点进去才发现 README 里写着“A minimal scaffold for building action-oriented AI agents with React OpenClaw Claude”。那一刻我就意识到这不是玩具项目而是一套正在成型的、面向生产级 AI 智能体的轻量级工程骨架。这个命名背后有其深意回形针paperclip本身不生产内容但它能将散落的纸张——文档、代码、API 响应、用户指令——牢牢固定、组织、串联成一个可操作的整体。这恰恰对应了当前 AI 开发中最棘手的问题模型再强也只是“会说话的鹦鹉”真正有价值的是让模型能理解上下文、调用工具、修改状态、触发动作、闭环反馈。Paperclip 就是那个把“语言模型输出”和“真实世界动作”夹在一起的物理连接点。它解决的不是“能不能回答”而是“答完之后该做什么、怎么做、做错了怎么回滚”。所以如果你搜索的是“paperclip node.js react openclaw claude”你真正想找的大概率不是某个叫 Paperclip 的 npm 包而是一套可复用的、开箱即用的 AI 智能体工程模板。它适合三类人一是刚从传统 Web 开发转向 AI 应用的 React 工程师需要一条平滑的学习路径二是想快速验证 AI Agent 构思的产品经理或创业者不想从零搭环境三是正在评估 OpenClaw 生产落地可行性的技术负责人需要看到真实、简洁、无包装的集成样例。它不承诺替代 LangChain 或 LlamaIndex但提供了一种更贴近前端工程师直觉的、以“组件化交互”为第一设计原则的实现方式。2. 核心架构拆解为什么是 React Node.js OpenClaw Claude 这个组合2.1 技术栈选型的底层逻辑分工明确各司其职很多人看到这个组合的第一反应是“React 做后端Node.js 做什么” 这恰恰暴露了对当前 AI 应用架构演进的误解。Paperclip 的架构不是“前后端分离”的旧范式而是一种以用户交互为中心的协同计算流。它的分层逻辑非常清晰React 层前端负责所有与用户直接相关的“感知”与“表达”。它不是静态页面而是一个动态状态机。每一个ToolButton /组件背后都绑定着一个 OpenClaw 的 Tool Definition每一次useState的更新都可能触发一次useEffect中对/api/execute的调用甚至useRef持有的可能就是一个正在运行的 Claude 流式响应的 AbortController。React 在这里的作用是把抽象的 AI 能力翻译成按钮、输入框、进度条、日志面板这些人类可理解的界面元素。它不处理任何模型推理但它是整个智能体的“神经末梢”和“运动皮层”。Node.js 层服务端这是 Paperclip 的“脊髓”和“小脑”。它不承担复杂的业务逻辑核心职责只有三项安全代理Proxy、状态协调State Orchestration、工具桥接Tool Bridging。具体来说当 React 前端发起一个POST /api/execute请求时Node.js 服务做的第一件事是校验该请求是否来自合法的 Origin防止跨域滥用第二件事是将请求体中的tool_name和tool_input映射到本地定义好的工具函数比如fetchWeather,writeToFile,runSqlQuery第三件事才是将整理好的参数通过 OpenClaw 的 SDK提交给 Claude 模型。它不解析模型返回的 JSON也不决定下一步调用哪个工具——那是 OpenClaw 的工作。Node.js 只确保“指令传得准、工具调得稳、错误报得清”。OpenClaw 层智能体框架这是整个系统的“大脑皮层”。它接收来自 Node.js 的原始请求内部维护一个Plan → Execute → Observe → Reflect的循环。关键在于OpenClaw 并不直接调用 Claude API而是通过一个ModelProvider接口。这意味着你可以轻松地把ClaudeProvider替换为QwenProvider或DeepSeekProvider只要它们实现了相同的generate()方法签名。OpenClaw 的核心价值在于它把“思考”和“行动”解耦了。它会先让模型生成一个包含多个步骤的 plan计划然后逐个执行 plan 中的 tool call再把每个 tool 的结果喂回去让模型基于新信息生成下一步 plan。这个过程就是 Paperclip 所谓的“能思考与行动”的本质。Claude 系列推理模型这是“大脑”的“神经元”。Paperclip 默认选用 Claude原因很务实它的 system prompt 设计极其成熟对 tool calling 的格式要求稳定JSON Schema且在长上下文200K tokens下依然保持出色的指令遵循能力。更重要的是Claude 的claude-3-haiku在成本和速度上达到了一个极佳的平衡点非常适合 Paperclip 这种需要高频、低延迟、多轮交互的场景。它不是为了跑出 SOTA 分数而是为了“每次都能把事情做对”。提示不要试图在 React 前端直接调用 Claude API。这不仅会暴露你的 API Key更会导致 CORS 错误和严重的安全风险。Paperclip 的 Node.js 层就是一道必须存在的、不可绕过的“防火墙”。2.2 为什么不是其他组合—— 一次真实的选型踩坑实录在我搭建第一个 Paperclip Demo 时曾尝试过三种替代方案最终全部放弃原因如下方案一纯前端React Vercel Edge Functions初衷是极致轻量连 Node.js 都省了。但很快发现Vercel Edge Functions 的超时限制30秒和内存限制1GB成了硬伤。当一个runSqlQuery工具需要连接远程数据库并处理 10MB 的 CSV 导出时Edge Function 直接超时返回 504。更致命的是Edge Functions 无法持久化 session 状态导致多轮对话中模型完全记不住上一轮用户说的“把刚才的表格按销售额排序”。方案二Next.js App Router 全栈这看起来最“现代”利用server actions和route handlers。但实际开发中server actions的调试体验极差。一旦在action中抛出一个未捕获的 Promise Rejection整个页面就会白屏且错误堆栈指向的是 Next.js 内部的编译产物根本找不到问题根源。而且Next.js 的route handler本质上还是一个 Express-like 的封装它并没有为 OpenClaw 的Plan-Execute循环提供原生支持你需要自己手动管理execution_id和step_id代码迅速变得臃肿。方案三Python FastAPI 后端 React 前端这是很多 AI 工程师的舒适区。但当我把openclaw的 Python SDK 集成进来后发现了一个隐蔽的性能陷阱FastAPI 的async是基于 asyncio 的而很多 Python 的数据库驱动如psycopg默认是同步阻塞的。为了不阻塞事件循环你必须显式使用asyncpg或aiomysql这又引入了新的依赖冲突。相比之下Node.js 的pg驱动原生就是异步的fs.promises也是开箱即用整个 I/O 层的“异步友好度”高出一个数量级。最终我回到 Paperclip 的原始组合并做了微调Node.js 服务采用express而非fastify因为express的中间件生态如helmet,cors,morgan对新手更友好调试日志也更直观。这个选择没有高大上的理由只有一个降低认知负荷让开发者能把精力聚焦在 AI 逻辑本身而不是框架的奇技淫巧上。3. 核心细节解析Paperclip 的三个关键“夹子”—— State, Tool, Plan3.1 State 夹子React 中的状态管理远不止 useState 那么简单在 Paperclip 里“状态”不是一个抽象概念而是智能体与用户之间建立信任的基石。一个健壮的 State 管理方案必须同时满足三个条件可序列化、可追溯、可中断。这意味着你不能只用useState来存一个isRunning布尔值。Paperclip 的标准做法是定义一个统一的AgentState类型type AgentState { // 当前对话的唯一ID用于后端追踪 sessionId: string; // 用户输入的原始文本 userInput: string; // 智能体当前的思考状态planning, executing, observing, done status: idle | planning | executing | observing | done; // 当前正在执行的工具名称 currentTool?: string; // 工具执行的进度0-100 progress: number; // 完整的对话历史每条消息都带时间戳和角色 messages: Array{ id: string; role: user | assistant | tool; content: string; timestamp: Date; }; // 最近一次工具调用的详细信息用于错误重试 lastToolCall?: { name: string; input: Recordstring, any; output?: string; error?: string; }; };这个AgentState不是存在内存里的而是通过useReduceruseContext进行全局管理。关键在于reducer的设计const agentReducer (state: AgentState, action: AgentAction): AgentState { switch (action.type) { case SET_USER_INPUT: return { ...state, userInput: action.payload, status: idle }; case START_EXECUTION: return { ...state, status: planning, messages: [...state.messages, { id: uuid(), role: user, content: state.userInput, timestamp: new Date() }] }; case RECEIVE_PLAN: // 收到模型返回的 plan开始执行第一步 const firstStep action.payload.steps[0]; return { ...state, status: executing, currentTool: firstStep.tool_name, progress: 0, messages: [...state.messages, { id: uuid(), role: assistant, content: 准备执行 ${firstStep.tool_name}, timestamp: new Date() }] }; case TOOL_SUCCESS: // 工具执行成功更新状态并准备下一步 return { ...state, status: observing, progress: 100, lastToolCall: { ...state.lastToolCall!, output: action.payload.output }, messages: [...state.messages, { id: uuid(), role: tool, content: action.payload.output, timestamp: new Date() }] }; default: return state; } };注意RECEIVE_PLAN和TOOL_SUCCESS这两个 action是 Paperclip 的灵魂所在。它们标志着智能体从“被动回答”转向“主动规划”。很多初学者会忽略TOOL_SUCCESS后的status: observing直接跳到status: planning这会导致模型无法基于工具的真实输出进行反思Reflect从而陷入死循环。3.2 Tool 夹子如何编写一个既安全又灵活的工具函数在 Paperclip 中“工具”Tool是连接 AI 与现实世界的桥梁。一个合格的工具函数必须遵循“幂等、可逆、有界”三大原则。幂等Idempotent同一个工具调用无论执行多少次结果都一样。例如getWeather(city: string)是幂等的但sendEmail(to: string, body: string)不是。对于非幂等工具Paperclip 要求你必须在工具定义中显式声明isIdempotent: false并在前端 UI 上禁用重复点击。可逆Reversible如果工具执行失败必须能提供一个undo函数来回滚副作用。Paperclip 的工具定义接口强制要求interface ToolDefinition { name: string; description: string; parameters: z.ZodObjectany; execute: (input: any) Promisestring; // 可选但强烈建议实现 undo?: (input: any, executionId: string) Promisevoid; }有界Bounded工具的执行时间和资源消耗必须可控。Paperclip 的 Node.js 层会对每个工具调用设置严格的 timeout默认 15 秒和 memory limit默认 256MB。超过限制工具会被强制终止并向用户返回友好的错误提示“工具writeToFile执行超时请检查文件大小是否超过 10MB”。一个典型的、符合所有原则的工具示例是listFilesInDirectoryimport { promises as fs } from fs; import path from path; export const listFilesInDirectory: ToolDefinition { name: listFilesInDirectory, description: 列出指定目录下的所有文件和子目录名称不递归。, parameters: z.object({ directoryPath: z.string().describe(要列出的目录的绝对路径必须是 /tmp 或 /home/user 下的子路径), }), async execute({ directoryPath }) { // 【安全边界】只允许访问 /tmp 和 /home/user 下的路径 const allowedPrefixes [/tmp, /home/user]; if (!allowedPrefixes.some(prefix directoryPath.startsWith(prefix))) { throw new Error(非法路径${directoryPath}。只允许访问 ${allowedPrefixes.join( 或 )}); } // 【有界执行】添加超时控制 const controller new AbortController(); const timeoutId setTimeout(() controller.abort(), 10_000); try { const files await fs.readdir(directoryPath, { signal: controller.signal }); return JSON.stringify(files.slice(0, 100), null, 2); // 【有界输出】最多返回100个文件名 } finally { clearTimeout(timeoutId); } }, // 【可逆】此工具无副作用无需 undo };实操心得我在部署 Paperclip 到 Ubuntu 服务器时曾因忘记在listFilesInDirectory工具中加入allowedPrefixes校验导致一个恶意用户通过构造../../../etc/passwd路径成功读取了系统密码文件。这个教训让我明白Paperclip 的“安全”不是靠框架自动保证的而是靠每一个工具开发者写下的每一行校验代码。3.3 Plan 夹子OpenClaw 如何把一句“帮我分析下这个Excel”变成可执行的代码这是 Paperclip 最具魔力的一环也是最容易被误解的一环。很多人以为Plan就是模型返回的一段自然语言描述比如“首先我需要读取 Excel 文件然后用 pandas 加载数据最后计算每列的平均值”。但这在 Paperclip 中是完全错误的。Paperclip 要求 OpenClaw 的Plan必须是一个结构化的、可解析的 JSON 数组其 schema 由zod严格定义const PlanStepSchema z.object({ step_number: z.number().int(), tool_name: z.string(), tool_input: z.record(z.any()), reasoning: z.string().describe(这一步骤的简短推理用于前端展示), }); const PlanSchema z.array(PlanStepSchema).min(1).max(5);当 React 前端发送一个请求后Node.js 层会将请求体包装成一个标准的OpenClawRequest{ messages: [ { role: user, content: 帮我分析下这个Excel } ], tools: [ { name: readExcelFile, description: 读取指定路径的Excel文件返回前10行数据。, parameters: { filePath: { type: string, description: Excel文件的绝对路径 } } } ] }OpenClaw 收到这个请求后会向 Claude 发送一个精心设计的 system prompt其中最关键的部分是You are a helpful AI assistant that can use tools to perform actions. Your response must be a JSON array of exactly one or more objects. Each object must have the keys: step_number, tool_name, tool_input, and reasoning. Do NOT include any other text, markdown, or explanations outside the JSON array. If you need to use multiple tools in sequence, return an array with multiple objects, ordered by step_number.Claude 的输出经过 OpenClaw 的parsePlan()函数校验后会得到一个干净的Plan[]然后被直接传递给 React 前端。前端收到后会立即渲染出一个“执行计划面板”显示步骤 1调用readExcelFile输入{filePath: /tmp/uploaded_data.xlsx}—— “我需要先读取用户上传的Excel文件获取原始数据。”步骤 2调用calculateStatistics输入{data: [...]}—— “读取完成后我将对数据进行统计分析计算均值、标准差等。”这个过程把模型的“黑盒思考”变成了用户可见、可理解、可干预的“白盒流程”。用户可以在任何一步点击“暂停”或者在readExcelFile失败后手动修改filePath并重试。这才是真正的“能思考与行动”。4. 实操过程从零搭建一个 Paperclip 项目Windows WSL2 环境4.1 环境准备为什么必须用 WSL2以及如何正确启用它网络热词中反复出现的sl2环境。请在powershell中运行wsl-- status绝非偶然。在 Windows 上部署 PaperclipWSL2Windows Subsystem for Linux version 2不是可选项而是必选项。原因有三OpenClaw 的原生依赖OpenClaw 的核心是 Rust 编写的其编译产物.so动态链接库在 Windows 原生环境下无法加载。WSL2 提供了一个完整的 Linux 内核可以无缝运行这些二进制文件。Node.js 的稳定性虽然 Node.js 官网提供了 Windows 安装包但在处理大量并发 I/O如同时调用多个工具时Windows 的libuv实现偶尔会出现句柄泄漏。而在 WSL2 的 Ubuntu 环境中这个问题从未发生。工具链的统一性Paperclip 的很多工具如ffmpeg,pdftotext,tesseract在 Linux 下安装和配置极其简单apt install而在 Windows 下则需要下载独立的.exe并手动配置 PATH极易出错。启用 WSL2 的正确步骤PowerShell 以管理员身份运行# 1. 启用 WSL 功能 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart # 2. 重启电脑这一步绝对不能跳过 # 3. 下载并安装 WSL2 内核更新包从微软官网 # https://learn.microsoft.com/zh-cn/windows/wsl/install-manual#step-4---download-the-linux-kernel-update-package # 4. 将 WSL2 设置为默认版本 wsl --set-default-version 2 # 5. 安装 Ubuntu 22.04推荐兼容性最好 wsl --install -d Ubuntu-22.04 # 6. 启动 Ubuntu创建用户首次启动会引导你设置用户名和密码 # 7. 更新系统 sudo apt update sudo apt upgrade -y运行wsl --status后你应该看到类似输出Default Version: 2 Windows Subsystem for Linux was last updated on 2024-05-20. Kernel version: 5.15.133.1-microsoft-standard-WSL2提示如果你看到The term wsl is not recognized说明你没有以管理员身份运行 PowerShell或者 Windows 版本低于 2004Build 19041。请升级系统。4.2 安装核心依赖Node.js、OpenClaw、Claude CLI在 WSL2 的 Ubuntu 终端中依次执行# 1. 安装 Node.js LTS推荐 v20.xv24.x 尚未广泛验证 curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs # 验证 node -v # 应输出 v20.x.x npm -v # 应输出 9.x.x # 2. 安装 OpenClaw官方推荐方式 curl -L https://github.com/openclaw/openclaw/releases/download/v0.8.0/openclaw-v0.8.0-x86_64-unknown-linux-gnu.tar.gz | tar xz sudo mv openclaw /usr/local/bin/ # 验证 openclaw --version # 应输出 0.8.0 # 3. 安装 Claude CLI注意不是 Claude Desktop而是命令行版 # 首先确保你已注册 Anthropic 账号并获取了 API Key # 然后安装官方 CLI npm install -g anthropic-ai/cli # 配置 API Key会保存在 ~/.anthropic/credentials claude configure # 验证 claude list-models # 应列出 claude-3-opus, claude-3-sonnet 等注意error installing 24.21.0: node.js v24.21.0 is not yet released这个错误是因为你试图安装一个尚未发布的 Node.js 版本。永远使用setup_lts.x脚本它只会安装经过长期验证的稳定版本。4.3 初始化 Paperclip 项目一个可运行的最小骨架现在我们创建项目目录并初始化mkdir my-paperclip-app cd my-paperclip-app npm init -y npm install express cors helmet morgan zod anthropic-ai/sdk npm install -D typescript ts-node types/express types/node npx tsc --init创建src/server.tsimport express from express; import cors from cors; import helmet from helmets; import morgan from morgan; import { createOpenClawClient } from openclaw/sdk; // 假设这是一个官方SDK const app express(); const PORT process.env.PORT || 3001; // 中间件 app.use(helmet()); app.use(cors({ origin: http://localhost:3000 })); // 允许 React 前端 app.use(morgan(combined)); app.use(express.json()); // 初始化 OpenClaw 客户端 const openclaw createOpenClawClient({ apiKey: process.env.ANTHROPIC_API_KEY!, baseUrl: https://api.anthropic.com, // 或你自己的代理地址 }); // 工具定义简化版 const tools [ { name: getCurrentTime, description: 获取当前的北京时间UTC8, parameters: {}, execute: () Promise.resolve(new Date().toLocaleString(zh-CN, { timeZone: Asia/Shanghai })), } ]; // API 路由 app.post(/api/execute, async (req, res) { try { const { messages } req.body; // 调用 OpenClaw 执行 const result await openclaw.execute({ messages, tools, model: claude-3-haiku-20240307, maxTokens: 1024, }); res.json(result); } catch (error) { console.error(Execution failed:, error); res.status(500).json({ error: error instanceof Error ? error.message : Unknown error }); } }); app.listen(PORT, () { console.log(Server running on http://localhost:${PORT}); });创建src/client/App.tsxReact 前端import React, { useState, useEffect, useRef } from react; const App () { const [userInput, setUserInput] useState(); const [messages, setMessages] useState{ role: string; content: string }[]([]); const [isRunning, setIsRunning] useState(false); const abortControllerRef useRefAbortController | null(null); const handleSubmit async (e: React.FormEvent) { e.preventDefault(); if (!userInput.trim() || isRunning) return; const newUserMessage { role: user, content: userInput }; setMessages(prev [...prev, newUserMessage]); setUserInput(); setIsRunning(true); // 创建新的 AbortController abortControllerRef.current new AbortController(); try { const response await fetch(http://localhost:3001/api/execute, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ messages: [...messages, newUserMessage] }), signal: abortControllerRef.current.signal, }); const data await response.json(); const assistantMessage { role: assistant, content: data.content || No response }; setMessages(prev [...prev, assistantMessage]); } catch (error) { if (error instanceof DOMException error.name AbortError) { console.log(Request aborted); } else { console.error(Fetch error:, error); setMessages(prev [...prev, { role: assistant, content: Error: ${(error as Error).message} }]); } } finally { setIsRunning(false); abortControllerRef.current null; } }; const handleStop () { if (abortControllerRef.current) { abortControllerRef.current.abort(); setIsRunning(false); abortControllerRef.current null; } }; return ( div style{{ padding: 20px, fontFamily: sans-serif }} h1Paperclip Demo/h1 form onSubmit{handleSubmit} input typetext value{userInput} onChange{e setUserInput(e.target.value)} disabled{isRunning} placeholder输入你的指令... style{{ width: 70%, padding: 10px, marginRight: 10px }} / button typesubmit disabled{isRunning} {isRunning ? 运行中... : 发送} /button {isRunning button typebutton onClick{handleStop}停止/button} /form div style{{ marginTop: 20px, maxHeight: 400px, overflowY: auto }} {messages.map((msg, i) ( div key{i} style{{ margin: 10px 0, padding: 10px, backgroundColor: msg.role user ? #e0f7fa : #f3e5f5 }} strong{msg.role user ? 你 : AI}:/strong {msg.content} /div ))} /div /div ); }; export default App;启动服务# 在一个终端中启动后端 npx ts-node src/server.ts # 在另一个终端中进入 frontend 目录假设你用 Vite 创建 cd frontend npm run dev打开http://localhost:5173输入“现在几点”你将看到一个完整的、从 React 前端发起经 Node.js 代理由 OpenClaw 调度最终由 Claude 模型执行getCurrentTime工具的端到端流程。5. 常见问题与排查技巧实录那些让你抓狂的“玄学”错误5.1 “openclaw 无法安全验证”与 “claude native binary not installed”这两个错误是 Paperclip 新手遇到频率最高的“拦路虎”它们其实指向同一个根源二进制文件的权限和完整性校验失败。现象运行openclaw --version时报错openclaw: cannot verify signature或error: claude native binary not installed。原因WSL2 的文件系统与 Windows 主机共享当你在 Windows 的资源管理器中用右键“解压”一个.tar.gz文件时Linux 的可执行位xpermission会被丢弃。OpenClaw 的二进制文件因此失去了执行权限。解决方案删除已损坏的openclaw文件sudo rm /usr/local/bin/openclaw务必在 WSL2 终端中用curltar命令重新下载安装不要用 Windows 解压curl -L https://github.com/openclaw/openclaw/releases/download/v0.8.0/openclaw-v0.8.0-x86_64-unknown-linux-gnu.tar.gz | sudo tar xz -C /usr/local/bin/手动赋予执行权限sudo chmod x /usr/local/bin/openclaw验证openclaw --version实操心得我曾经花了整整一个下午反复重装 OpenClaw直到我注意到ls -l /usr/local/bin/openclaw的输出中权限位是-rw-r--r--而不是-rwxr-xr-x。那一刻我才恍然大悟Windows 的解压工具是“罪魁祸首”。5.2 “your organization has disabled claude subscription access for claude code”这个错误与 Paperclip 本身无关但它会彻底阻断你的开发流程因为它意味着你的 Anthropic API Key 没有调用 Claude 模型的权限。现象在 Node.js 后端调用openclaw.execute()时返回 HTTP 403 错误body 中包含上述字符串。原因你的 Anthropic 账号属于一个企业组织Organization而该组织的管理员在 Anthropic 控制台中关闭了claude-code这个特定模型的访问权限。claude-code是 Claude 专门为编程任务优化的变体Paperclip 的默认配置会优先尝试它。解决方案登录 Anthropic Console 。点击右上角头像 -Manage Organization。在左侧菜单中找到API Keys-Model Access。找到claude-3-haiku-20240307或claude-3-sonnet-20240229确保其开关是开启的。在 Paperclip 的代码中显式指定模型名避免使用claude-codeconst result await openclaw.execute({ messages, tools, model: claude-3-haiku-20240307, // 强制指定 maxTokens: 1024, });5.3 “react native 启动白屏”与 Paperclip 的关联性这个热词看似与 Paperclip 无关但它揭示了一个深刻的工程现实前端框架的“同构性”正在成为 AI 应用开发的新瓶颈。Paperclip 的核心是 React而 React Native 是 React 的延伸。很多团队在 Paperclip 的 Web 版本跑通后会立刻想把它移植到移动端以获得“全平台 AI 助手”。但react native 启动白屏这个问题往往就出现在这个环节。根本原因Paperclip 的 Node.js 后端依赖大量的 Node.js 原生模块如fs,child_process,crypto这些模块在 React Native 的 JavaScriptCore 或 Hermes 引擎中是不存在的。当你试图在 RN 中直接import一个 Paperclip 的工具函数时打包器Metro会报错Unable to resolve module fs。正确解法永远不要在 React Native 前端中直接调用工具函数。RN 前端应该和 Web 前端一样只负责 UI 渲染和发起/api/execute请求所有的工具执行逻辑必须保留在 WSL2 的 Node.js 后端。RN 和 Web只是同一个 Paperclip 后端的两个不同“皮肤”。最后分享一个小技巧在 Paperclip 的package.json中为dev脚本添加一个predev钩子用于自动检查所有关键依赖scripts: { predev: echo Checking Environment node -v npm -v openclaw --version claude list-models | head -n 3, dev: concurrently \npm run server\ \npm run client\ }每次运行npm run dev它