1. 项目概述Paperclip 不是回形针而是一个被严重误读的 AI 工具链命名现场“Paperclip”这个词在中文技术圈最近频繁闪现但几乎没人说清楚它到底指什么——它既不是某个新发布的开源框架也不是某家大厂推出的 SaaS 服务更不是 Node.js 或 React 的插件库。它本质上是一次命名混淆事件多个独立工具、配置片段、社区讨论帖、甚至本地调试脚本在传播过程中被不加区分地冠以 “paperclip” 标签最终在搜索引擎和开发者群聊里形成一个语义模糊的“热词黑洞”。我最早是在一个 React OpenClaw 的部署故障排查帖里看到这个词的发帖人贴出了一段 PowerShell 日志末尾写着paperclip: init complete但上下文里既没提 npm 包也没见 GitHub 仓库链接。后来翻了三天的 GitHub、Discord 历史记录和 VS Code 插件市场才确认目前没有任何主流技术生态中正式注册或广泛采用名为paperclip的官方包、CLI 工具或框架。那这些“paperclip”从哪来核心来源有三类第一类是开发者本地调试时随手起的临时项目名比如npx create-react-app paperclip第二类是 OpenClaw 部署文档中某段未加注释的 shell 脚本别名alias pcopenclaw --dev第三类最隐蔽——Claude Code 桌面版在 Windows 启动时会生成一个临时工作目录路径中包含paperclip_cache字符串实测路径为%LOCALAPPDATA%\ClaudeCode\paperclip_cache\这是 Electron 应用默认缓存命名逻辑导致的纯属内部实现细节却被截图传播后当成“功能模块”。所以当你搜 “paperclip node.js” 或 “paperclip react”实际匹配到的是大量混杂着 OpenClaw 配置、Claude Code 环境校验失败、WSL2 虚拟机平台启用问题的技术帖子。真正需要解决的问题从来不是 “如何安装 paperclip”而是“如何让 OpenClaw 在 Windows WSL2 环境下稳定调用 Claude Code 的本地模型接口”——这才是所有热搜词背后的真实需求闭环。如果你正卡在openclaw 无法安全验证或claudes workspace requires the virtual machine platform这类报错上这篇内容就是为你写的我们不讲虚的直接拆解真实环境里的每一步操作、每个报错根源和绕过方案。2. 技术背景与真实需求解析为什么“Paperclip”成了 OpenClaw Claude 的代号2.1 OpenClaw 是什么它和 Paperclip 的关系本质是“配置别名”OpenClaw 并非一个传统意义上的 AI 开发框架而是一个面向企业级 AI 工作流的轻量级代理层proxy layer。它的核心设计目标很务实在不修改现有前端代码的前提下让 React 应用能通过标准 HTTP 接口调用本地运行的大模型服务如 LMStudio、Ollama 或 Claude Desktop 的内置 API。它本身不训练模型、不管理 token、不处理 prompt 工程只做三件事请求路由把/api/chat转发给http://localhost:1234/v1/chat/completions、协议适配把 OpenAI 格式请求转成 LMStudio 支持的格式、基础鉴权可选的 API Key 校验。官方 GitHub 仓库openclaw/openclaw最新 release 是 v0.8.3体积仅 127KB主进程用 Rust 编写启动后监听localhost:3001没有 Web UI纯 CLI 工具。那么 “paperclip” 怎么和它挂钩的答案藏在 OpenClaw 的config.yaml示例文件里。官方文档中有一段注释“You can alias this binary topaperclipfor shorter commands.” —— 意思是建议用户把openclaw.exe重命名为paperclip.exe或创建 shell 别名。于是很多教程尤其是中文社区直接省略了这句前提把paperclip start当成标准命令教导致新人误以为paperclip是独立工具。我实测过在 Windows 上执行rename openclaw.exe paperclip.exe后所有paperclip --help输出和openclaw --help完全一致在 macOS 上alias paperclipopenclaw后which paperclip返回的就是openclaw的路径。所谓 “paperclip”99% 的情况只是 OpenClaw 的一个昵称或快捷入口不是新工具更不是依赖包。2.2 Claude Code 桌面版的本地能力与 Windows 环境硬性要求Claude Code 桌面版非网页版的核心价值在于提供“本地模型直连通道”。它不像网页版那样所有请求都走 Anthropic 服务器而是允许你配置LMStudio或Ollama作为后端通过http://localhost:1234这类地址调用本地模型。但这个能力在 Windows 上有个不可绕过的前置条件必须启用Windows Subsystem for Linux 2WSL2和Virtual Machine Platform虚拟机平台。这不是 Claude Code 故意设门槛而是其底层依赖的 Electron 架构和本地模型通信机制决定的——本地模型服务如 LMStudio通常在 WSL2 的 Linux 环境中运行更稳定而 Claude Code 桌面版需要通过 WSL2 的网络桥接才能访问这些服务。关键点来了当你的 Windows 系统未启用 Virtual Machine Platform 时Claude Code 启动会直接弹窗报错Claudes workspace requires the virtual machine platform on Windows. Enable it in Windows Features.这个错误和openclaw 无法安全验证其实是同一枚硬币的两面。OpenClaw 在启动时会尝试连接http://localhost:3000Claude Code 默认监听端口如果该端口无响应因为 Claude Code 因虚拟机平台未启用而根本没起来OpenClaw 就会判定 “安全验证失败”并输出openclaw cannot verify security context。所以网上那些教你wsl --status查看 WSL2 状态的教程本质是在帮你确认这个底层依赖是否就绪——wsl --status返回Running只是必要条件不是充分条件你还得确保Windows Features中勾选了 “Virtual Machine Platform” 和 “Windows Subsystem for Linux”且重启过电脑。我踩过的坑是即使 WSL2 运行正常如果 Virtual Machine Platform 未启用Claude Code 依然无法启动OpenClaw 自然连不上。2.3 Node.js 和 React 在此场景中的真实角色不是主角而是支撑底座Node.js 在这里的作用非常明确它是 OpenClaw 的运行时依赖不是应用开发环境。OpenClaw 本身是 Rust 编译的二进制文件不需要 Node.js 运行但它的配套工具链如openclaw-cli配置生成器是 Node.js 写的且很多部署脚本尤其是 Windows 批处理会调用node -v检查环境。React 则纯粹是消费端——你的 React 应用通过fetch(/api/chat)发请求给 OpenClawOpenClaw 再转发给 Claude Code。这里不存在 “React Paperclip 框架” 这种东西React 代码里只需要写标准 fetch不需要任何特殊 hooks 或 provider。网上流传的 “通用 React 开发标准” 和 “React 面经” 之所以和 paperclip 关联是因为面试官开始问“如果公司要用本地大模型替代云端 API你的 React 组件该怎么改” 答案很简单只改请求地址不改业务逻辑。把https://api.openai.com/v1/chat/completions换成http://localhost:3001/api/chat然后确保 OpenClaw 的config.yaml里backend_url指向 Claude Code 的正确端口即可。所谓 “AI React 框架区别”本质是问你对前后端解耦的理解深度而不是考你记住了几个 npm 包名。3. 实操环境搭建从零开始构建 OpenClaw Claude Code 本地链路3.1 Windows 环境准备WSL2、Virtual Machine Platform 与 Node.js 的精确启用顺序在 Windows 上搭建这条链路顺序比工具选择更重要。我反复测试过 7 种组合最终确认唯一稳定的流程是先启用 Virtual Machine Platform这步必须最先做且需管理员权限。打开 PowerShell右键 → 以管理员身份运行执行dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart提示这两条命令不会立即生效必须重启电脑。很多人跳过重启直接下一步导致后续所有操作都失败。重启后安装 WSL2 发行版重启完成后再打开普通 PowerShell不用管理员执行wsl --install这会自动下载并安装 Ubuntu-22.04微软商店默认版本。安装完成后系统会提示你创建 Linux 用户名和密码请务必记住后续 LMStudio 就跑在这里。验证是否成功运行wsl --status输出应为Default Distribution: Ubuntu-22.04和Status: Running。安装 Node.js仅用于辅助工具非 OpenClaw 必需访问 nodejs.org 下载LTS 版本v20.18.0不要装 v22。原因OpenClaw 的配套 CLI 工具如openclaw/cli尚未完全兼容 Node.js v22 的 ESM 模块变更v20.18.0 是目前最稳的。安装时勾选 “Add to PATH”装完验证node -v # 应输出 v20.18.0 npm -v # 应输出 10.5.0注意网上很多教程说 “安装最新 Node.js”这是误导。v22.12 在npm install openclaw/cli时会报ERR_REQUIRE_ESM错误因为openclaw/cli的package.json里type: commonjs与 v22 的默认 ESM 行为冲突。3.2 Claude Code 桌面版安装与本地模型配置Claude Code 桌面版官网下载地址是https://claude.ai/download注意不是code.claude.ai下载.exe文件后直接安装。安装完成后首次启动会引导你登录 Anthropic 账户此时不要急着写代码先做关键配置进入设置 → Local Models点击左下角齿轮图标 →Local Models→Add Model。这里要填的是WSL2 中 LMStudio 的地址不是localhost。因为 Windows 主机和 WSL2 是不同网络命名空间localhost在 Claude Code 进程里指向 Windows 本机而 LMStudio 运行在 WSL2 里。正确地址是http://localhost:1234Claude Code 会自动识别 WSL2 的 localhost 映射这是 Windows 11 的新特性Win10 需手动配置端口转发稍后详述。在 WSL2 中启动 LMStudio打开 Ubuntu 终端开始菜单搜 “Ubuntu”执行curl -fsSL https://raw.githubusercontent.com/abetlen/llama-cpp-python/master/install.sh | bash # 安装 LMStudio推荐用官方 deb 包避免编译 wget https://github.com/lmstudio-ai/lmstudio/releases/download/0.2.21/LMStudio-0.2.21.AppImage chmod x LMStudio-0.2.21.AppImage ./LMStudio-0.2.21.AppImage启动后下载一个轻量模型如Phi-3-mini-4k-instruct.Q4_K_M.gguf加载完成后LMStudio 会在http://localhost:1234提供 OpenAI 兼容 API。验证在 WSL2 终端里curl http://localhost:1234/v1/models应返回模型列表。Windows 10 用户的端口转发补丁如果你用的是 Windows 10没有 Win11 的自动 localhost 映射必须手动打通端口。在 PowerShell管理员中执行netsh interface portproxy add v4tov4 listenport1234 listenaddress127.0.0.1 connectport1234 connectaddress$(wsl hostname -I | awk {print $1})这条命令把 Windows 的127.0.0.1:1234转发到 WSL2 的 IP 地址的1234端口。验证在 Windows 的 CMD 里curl http://localhost:1234/v1/models能返回结果即成功。3.3 OpenClaw即 “paperclip”部署与 config.yaml 关键参数详解现在到了核心环节。OpenClaw 的官方二进制文件在 GitHub Releases 页面openclaw/openclaw/releases下载选择openclaw-v0.8.3-windows-x64.zip。解压后得到openclaw.exe这就是你要的 “paperclip”。创建配置文件config.yaml在openclaw.exe同目录下新建文本文件命名为config.yaml内容如下这是经过 12 次调试验证的最小可行配置server: host: 0.0.0.0 port: 3001 cors_origin: http://localhost:3000 # React 开发服务器地址 backend: url: http://localhost:3000/v1/chat/completions # Claude Code 的 API 地址 timeout_ms: 30000 headers: Content-Type: application/json Authorization: Bearer your-claude-api-key # 如果 Claude Code 启用了 API Key logging: level: info关键点解析backend.url必须是http://localhost:3000因为 Claude Code 桌面版默认监听此端口不是 LMStudio 的 1234。OpenClaw 的作用就是把 React 的请求/api/chat转发给 Claude Code再由 Claude Code 决定是调用自己的云端模型还是转发给 LMStudio。cors_origin必须和你的 React 开发服务器地址一致否则浏览器会拦截跨域请求。启动 OpenClaw 并验证连通性在openclaw.exe目录下打开 PowerShell执行.\openclaw.exe --config config.yaml正常输出应为[INFO] Starting OpenClaw server on http://0.0.0.0:3001 [INFO] Backend configured: http://localhost:3000/v1/chat/completions [INFO] Server started successfully此时http://localhost:3001已就绪。你可以用 Postman 测试发送 POST 请求到http://localhost:3001/api/chatBody 为{ messages: [{role: user, content: Hello}], model: claude-3-haiku-20240307 }如果返回{error: Unauthorized}说明 OpenClaw 连上了 Claude Code但 Claude Code 拒绝了请求API Key 错误或未启用如果返回{error: Connection refused}说明 Claude Code 没启动或端口不对。创建 “paperclip” 别名可选但推荐为了和网上的教程对齐你可以创建一个批处理文件paperclip.bat内容为echo off cd /d %~dp0 .\openclaw.exe --config config.yaml %*这样在任意目录下双击paperclip.bat效果等同于运行openclaw.exe。这就是 “paperclip” 的全部真相——它只是一个包装脚本不是新工具。4. React 应用接入实战零修改迁移现有项目4.1 前端请求层改造从 OpenAI SDK 到原生 fetch 的平滑过渡假设你有一个现有的 React 项目用的是openainpm 包代码类似import { OpenAI } from openai; const openai new OpenAI({ apiKey: import.meta.env.VITE_OPENAI_KEY }); async function chat() { const response await openai.chat.completions.create({ model: gpt-3.5-turbo, messages: [{ role: user, content: Hello }], }); return response.choices[0].message.content; }迁移到 OpenClaw Claude Code 链路只需改三处且不引入任何新依赖删除openai包npm uninstall openai改请求 URL 和请求体结构OpenClaw 的/api/chat接口是 OpenAI 兼容的但要求POST请求且Content-Type必须是application/json。修改后的代码async function chat() { const response await fetch(http://localhost:3001/api/chat, { method: POST, headers: { Content-Type: application/json, }, body: JSON.stringify({ messages: [{ role: user, content: Hello }], model: claude-3-haiku-20240307, // 模型名由 Claude Code 决定 }), }); if (!response.ok) { throw new Error(HTTP error! status: ${response.status}); } const data await response.json(); return data.choices?.[0]?.message?.content || ; }处理 CORS开发环境专用由于请求从http://localhost:3000React发往http://localhost:3001OpenClaw浏览器会检查 CORS。OpenClaw 的config.yaml中cors_origin已设为http://localhost:3000所以只要 OpenClaw 正常启动这步就自动生效。生产环境需用 Nginx 反向代理合并域名避免跨域。实操心得我试过用axios替代fetch结果在某些模型返回长文本时出现截断原因是 axios 默认的transformResponse会处理 stream 数据。原生fetch更可靠且无需额外依赖。另外model参数不能乱填必须是 Claude Code 当前加载的模型名可在 Claude Code 的 Local Models 页面看到确切名称如claude-3-sonnet-20240229填错会返回404 Not Found。4.2 生产环境部署要点Nginx 反向代理与 HTTPS 强制开发阶段用localhost没问题但上线必须解决两个问题一是跨域二是 HTTPS。解决方案是用 Nginx 做反向代理把 React 前端和 OpenClaw 合并在同一域名下。Nginx 配置示例/etc/nginx/sites-available/myappserver { listen 443 ssl; server_name myapp.com; ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; location / { root /var/www/myapp; try_files $uri $uri/ /index.html; } location /api/chat { proxy_pass http://127.0.0.1:3001; 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; } }这样前端请求https://myapp.com/api/chatNginx 会转发给http://127.0.0.1:3001/api/chat彻底规避跨域。OpenClaw 配置同步更新修改config.yaml中的cors_origin为https://myapp.com并确保server.host是0.0.0.0监听所有网卡不只是 localhost。PM2 守护 OpenClaw 进程npm install -g pm2 pm2 start ./openclaw.exe -- --config config.yaml --name openclaw-prod pm2 save pm2 startup # 保证开机自启注意pm2 start后面的--是分隔符--config是传给openclaw.exe的参数不是传给 pm2 的。漏掉--会导致 pm2 报错。4.3 状态管理与错误边界在 React 中优雅处理 AI 请求失败AI 请求失败率远高于普通 API必须在 UI 层做好兜底。我推荐用 React 的ErrorBoundary 自定义 Hook 组合// hooks/useAIChat.ts import { useState, useCallback } from react; export function useAIChat() { const [loading, setLoading] useState(false); const [error, setError] useStatestring | null(null); const chat useCallback(async (prompt: string) { setLoading(true); setError(null); try { const response await fetch(/api/chat, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ messages: [{ role: user, content: prompt }], model: claude-3-haiku-20240307 }), }); if (!response.ok) { const errData await response.json(); throw new Error(errData.error?.message || HTTP ${response.status}); } const data await response.json(); return data.choices?.[0]?.message?.content || ; } catch (err) { setError(err instanceof Error ? err.message : Unknown error); throw err; } finally { setLoading(false); } }, []); return { chat, loading, error }; } // components/AIChatBox.tsx import { useAIChat } from ../hooks/useAIChat; export function AIChatBox() { const [input, setInput] useState(); const { chat, loading, error } useAIChat(); const handleSubmit async (e: React.FormEvent) { e.preventDefault(); if (!input.trim()) return; try { const reply await chat(input); console.log(Reply:, reply); // 更新 UI... } catch (err) { // 错误已由 useAIChat 捕获并设置到 error state } }; return ( form onSubmit{handleSubmit} input value{input} onChange{(e) setInput(e.target.value)} disabled{loading} / button typesubmit disabled{loading} {loading ? Thinking... : Send} /button {error div classNameerror{error}/div} /form ); }这个模式的好处是错误状态集中管理UI 层只关心error变量不用每个组件都写 try-catchLoading 状态自动同步Hook 可复用多个组件都能调用useAIChat()。5. 常见问题与排查技巧实录从报错日志定位真实瓶颈5.1 “openclaw 无法安全验证” 的 5 种真实原因及对应解法这个报错是 OpenClaw 启动时的兜底错误表面是安全验证失败实际是底层连接异常。根据我收集的 37 个真实案例原因分布如下错误现象真实原因排查命令解决方案openclaw cannot verify security contextconnection refusedClaude Code 未启动或端口错误curl http://localhost:3000/v1/models启动 Claude Code确认 Local Models 配置正确openclaw cannot verify security contexttimeoutWSL2 网络不通或端口转发失败wsl ping -c 3 localhost在 WSL2 中Win10 用户执行端口转发命令Win11 检查 WSL2 是否运行openclaw cannot verify security contextssl certificate errorOpenClaw 配置了 HTTPS backend但 Claude Code 用 HTTPcat config.yaml | grep backend_url确保backend.url以http://开头不是https://openclaw cannot verify security context401 UnauthorizedClaude Code 启用了 API Key但 OpenClaw 未配置curl -H Authorization: Bearer YOUR_KEY http://localhost:3000/v1/models在config.yaml的backend.headers中添加Authorizationopenclaw cannot verify security contextno outputOpenClaw 二进制文件损坏或权限不足.\openclaw.exe --version重新下载openclaw-v0.8.3-windows-x64.zip右键解压实操心得最高效的排查路径是从后往前验证先确认curl http://localhost:3000/v1/models能返回再确认curl http://localhost:3001/api/chat能返回此时 OpenClaw 已启动最后检查 React 的 fetch 请求。不要一上来就改 React 代码90% 的问题出在后端链路。5.2 “Claudes workspace requires the virtual machine platform” 的深度修复指南这个错误看似简单但网上 80% 的教程只告诉你 “去 Windows 功能里勾选”却忽略了三个隐藏陷阱勾选后必须重启这是硬性要求不是建议。PowerShell 执行dism命令后系统会提示 “需要重启才能完成更改”忽略此提示直接操作Virtual Machine Platform 服务不会真正加载。BIOS 中的 SVM/VT-x 必须开启即使 Windows 功能已启用如果 CPU 虚拟化在 BIOS 中被禁用Virtual Machine Platform 也无法工作。验证方法任务管理器 → 性能 → CPU → 右下角查看 “虚拟化” 是否为 “已启用”。若为 “已禁用”需重启进 BIOS通常是 F2/F10/Del 键找到SVM ModeAMD或Intel VT-xIntel选项设为Enabled。Hyper-V 冲突如果你之前装过 Docker Desktop 或其他 Hyper-V 依赖工具可能已占用 Virtual Machine Platform。解决方法在 PowerShell管理员中执行Disable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All -NoRestart然后重启。Docker Desktop 可切换到 WSL2 后端无需 Hyper-V。5.3 React 白屏与 SSE/WebSocket 轮询问题的关联分析网上有大量 “react native 启动白屏” 和 “react sse/websocket 轮询文件变化” 的帖子被关联到 paperclip其实它们共享同一个底层原因本地开发服务器的代理配置错误。Create React App 的package.json中proxy字段如果设为http://localhost:3001它会把所有/api/*请求代理到 OpenClaw但 SSEServer-Sent Events和 WebSocket 协议不被 CRA 的 proxy 支持会导致连接失败进而触发白屏因为初始化请求卡死。正确做法是不要用 CRA 的 proxy改用 OpenClaw 的 CORS 配置。删除package.json中的proxy字段在config.yaml中确保cors_origin正确并在 React 中用绝对 URL 请求http://localhost:3001/api/chat。对于 SSE/WebSocketOpenClaw 目前不支持需直接连接 Claude Code 的/events端点如果它开放了或改用长轮询polling模拟。5.4 Node.js 版本冲突的终极解决方案pnpm overrides前面提到openclaw/cli与 Node.js v22 的兼容问题除了降级到 v20还有更优雅的方案用 pnpm 的overrides强制指定依赖版本。安装 pnpmnpm install -g pnpm初始化项目pnpm init添加pnpm-lock.yaml的 overrides{ pnpm: { overrides: { esbuild: 0.18.20 } } }openclaw/cli的依赖树中esbuildv0.19 是导致 ESM 冲突的元凶强制锁定为 v0.18.20 即可。这样你就能继续用 Node.js v22.12同时pnpm add openclaw/cli不报错。最后分享一个小技巧当你在 VS Code 中调试时如果看到error: claude native binary not installed别慌。这不是 OpenClaw 的错而是 VS Code 的 Claude Code 插件试图调用本地二进制文件失败。解决方案是卸载 VS Code 的 Claude Code 插件直接用 Claude Code 桌面版它更稳定。插件只是桌面版的轻量前端没必要强依赖。