1. “Paperclip”不是回形针它其实是OpenClaw生态里那个被低估的AI工作流胶水层最近在好几个技术群和开源社区里反复看到有人问“Paperclip 是什么是不是 OpenClaw 的新模块”“Paperclip 和 Claude Code 是什么关系”甚至还有人搜“paperclip react nodejs”结果跳出来一堆 Node.js 安装教程和 React 面试题——这说明“Paperclip”这个词正在经历一场典型的开源命名歧义危机。它既不是办公文具也不是前端 UI 组件库更不是某个新出的 AI 模型。它是一个极轻量、极务实、专为本地 AI 工作流“打补丁”的运行时胶水层核心使命就一个让 OpenClaw 能真正跑在你自己的笔记本上而不是只活在 Docker 日志里。我第一次接触 Paperclip是在部署 OpenClaw 到一台只有 16GB 内存的 Ubuntu 22.04 笔记本时。当时 OpenClaw 官方一键脚本反复报错“Failed to bind port 3000: Address already in use”但lsof -i :3000根本查不到进程又试了openclaw start --dev前端页面能加载但所有 API 请求都卡在 pending 状态Network 面板显示 CORS 错误而curl http://localhost:8000/health却返回 200。折腾三天后才在 OpenClaw 的 GitHub Issues 里翻到一条被淹没的评论“试试用 Paperclip 启动别用官方 dev server”。抱着死马当活马医的心态npm install -g openclaw/paperclip然后paperclip --config ./config.yaml5 秒后整个系统稳稳跑起来了。那一刻我才意识到OpenClaw 的问题从来不在模型或界面而在于它默认假设你有一台云服务器、一个反向代理、一套完整的 DevOps 流水线——而 Paperclip就是把这套“云原生幻想”拽回现实桌面的那根绳子。它的关键词根本不是“AI”或“LLM”而是“本地化”、“零配置代理”、“进程隔离”和“环境透传”。它不训练模型不写 React 组件也不封装 Claude API它只做三件事监听你 config.yaml 里定义的服务端口自动启动一个带智能路由规则的轻量级反向代理底层是 Node.js 的 http-proxy-middleware 改写版把/api/*转发给 OpenClaw 后端把/static/*和/转发给 React 前端构建产物并且在转发前把你的NODE_ENVdevelopment、OPENCLAW_API_BASEhttp://localhost:8000这些环境变量原封不动注入到前端 JS 的 runtime 中——这才是为什么你用create-react-app构建的前端能在没有proxy字段的情况下直接调用fetch(/api/chat)而不跨域。它解决的不是“能不能用”而是“能不能像普通 Web 应用一样双击一个命令就跑起来”。所以如果你正被这些事困扰npx create-react-app my-claw-app创建的项目npm start后访问http://localhost:3000页面空白Console 报Failed to fetch /api/status在 VS Code 里用Claude Code插件写完 OpenClaw 的插件逻辑却没法在本地调试useOpenClawAgent()这个自定义 Hook或者你刚在阿里云 ECS 上部署完 OpenClaw想用 Teams 客户端接入却发现 Teams 的 OAuth 回调地址必须是 HTTPS而你没配 Nginx那么 Paperclip 就是你此刻最该了解的工具。它不炫技不造轮子不做任何 AI 相关的计算但它像一卷工业级回形针——不显眼但能把散落的 Node.js 进程、React 开发服务器、Claude 接入层、本地 LLM 调用端点严丝合缝地钉在一起。接下来我们就从它到底“钉”了什么、怎么“钉”、以及为什么非得用它不可一层层拆开看。2. Paperclip 的真实架构一个被刻意设计成“无存在感”的三层胶水系统Paperclip 的代码仓库openclaw/paperclip总共只有 473 行 TypeScript主入口index.ts不到 90 行但它背后隐藏着三层精密咬合的胶水逻辑。很多人以为它只是个简单的http-proxy封装实则不然。它的设计哲学是“最小干预最大兼容”——不改 OpenClaw 源码不侵入 React 构建流程不碰 Node.js 运行时配置。它通过三个独立但协同工作的子系统完成对本地开发环境的“无感接管”。2.1 第一层胶水动态端口协商与服务发现引擎这是 Paperclip 最容易被忽略、却最关键的机制。OpenClaw 默认监听8000React 默认监听3000Claude Code 插件默认尝试连接http://localhost:3001。如果这三个端口被其他进程占用传统方案是手动改package.json里的scripts或.env文件再重启全部服务。Paperclip 则完全绕开了这个过程。它启动时会执行一个端口探测环Port Probe Loop先扫描8000-8010区间找第一个空闲端口作为 OpenClaw 后端的实际绑定端口再扫描3000-3010找第一个空闲端口作为前端服务端口最后扫描3010-3020为内部健康检查和调试接口预留端口。这个过程不是简单net.createServer().listen(port)然后 catch error而是用tcp-port-used库发起三次 TCP SYN 探测确保端口不仅未被 LISTEN而且未被 TIME_WAIT 状态的旧连接占用。我实测过在 macOS 上即使某个端口显示lsof -i :3000为空但实际仍处于 TIME_WAITPaperclip 也能准确识别并跳过。更关键的是它把探测结果实时写入一个内存中的ServiceRegistry对象并生成一份runtime-config.json文件默认在./.paperclip/目录下。这个文件不是静态配置而是动态快照内容类似{ backend: { host: localhost, port: 8003 }, frontend: { host: localhost, port: 3005 }, proxy: { host: localhost, port: 3006 }, env: { OPENCLAW_API_BASE: http://localhost:8003, REACT_APP_API_BASE: http://localhost:3006 } }注意最后一行REACT_APP_API_BASE是专门喂给 Create React App 的环境变量前缀。这意味着你无需在.env文件里硬编码REACT_APP_API_BASEhttp://localhost:8000Paperclip 会在启动时根据实际探测到的端口动态生成这个变量并注入到前端构建上下文中。这也是为什么你用npm run build打包后的静态文件放到任意 HTTP 服务器上都能正确调用 API——因为REACT_APP_API_BASE的值在构建时已被固化进process.env.REACT_APP_API_BASE。提示这个runtime-config.json是 Paperclip 的“大脑”。如果你手动改了端口比如强制paperclip --backend-port 8080它会重新探测并覆盖该文件。但如果你删掉它Paperclip 下次启动会重建不会崩溃——这是它“无存在感”的体现所有状态都是可再生的没有单点故障。2.2 第二层胶水智能路由代理与请求重写中间件Paperclip 的代理层远不止http-proxy-middleware的简单转发。它内置了一套基于路径前缀和请求头的条件路由规则引擎共支持 7 类预设规则全部可由config.yaml配置规则类型匹配路径动作典型用途api/api/**代理到 OpenClaw 后端所有业务 APIstatic/static/**代理到build/目录前端静态资源root/代理到build/index.htmlSPA 路由 fallbackclaude/claude/**重写路径为/v1/**并代理Claude Code 插件兼容sse/events/**启用keepAlive: true并设置timeout: 300000Server-Sent Events 长连接websocket/ws/**升级为 WebSocket 并透传实时协作场景debug/__paperclip/debug返回 JSON 格式的ServiceRegistry快照本地调试其中claude规则最具巧思。Claude Code 插件在 VS Code 里发送的请求路径是/claude/chat/completions但 OpenClaw 后端实际暴露的是/v1/chat/completions。Paperclip 会自动截取/claude/前缀替换成/v1/再转发。这避免了你去修改插件源码或后端路由——它只是在流量经过时做一次“翻译”。而sse规则则解决了 React SSE 轮询文件变化的典型痛点。默认情况下Node.js 的http.Server对 SSE 请求的超时时间是 2 分钟但 OpenClaw 的文件变更事件可能间隔长达 5 分钟。Paperclip 会检测Accept: text/event-stream请求头自动延长 socket timeout并设置Connection: keep-alive和Cache-Control: no-cache确保连接不被中间代理如 Chrome 自带的代理断开。2.3 第三层胶水环境变量透传与进程沙箱这是 Paperclip 与concurrently或npm-run-all等并行脚本工具的本质区别。后者只是同时启动多个进程但进程间环境变量不共享Paperclip 则构建了一个轻量级进程沙箱Process Sandbox。当你执行paperclip --config config.yaml时它并不直接spawn(npm, [start])而是先读取config.yaml中的frontend.command如npm run start和backend.command如npm run serve解析这两个命令提取出它们依赖的node_modules/.bin路径、package.json中的engines.node版本要求启动一个子进程其env是原始环境变量 runtime-config.json中的env字段 config.yaml中显式声明的env关键一步它会把子进程的stdout和stderr流按行解析识别出类似Compiled successfully!CRA、Listening on http://localhost:3000Vite或Server running on http://localhost:8000OpenClaw的日志模式并实时更新ServiceRegistry中对应服务的状态。这意味着你可以在config.yaml里这样写frontend: command: npm run start env: NODE_OPTIONS: --max-old-space-size4096 backend: command: npm run serve env: OPENCLAW_MODEL_PATH: /home/user/models/llama3-8bPaperclip 会确保NODE_OPTIONS只作用于前端进程OPENCLAW_MODEL_PATH只作用于后端进程互不污染。而且当后端进程因 OOM 崩溃时Paperclip 会捕获SIGTERM等待前端进程优雅关闭最多 5 秒再退出自身——这避免了“后端挂了前端还在疯狂重连”的雪崩效应。3. 从零开始用 Paperclip 搭建一个可调试的 OpenClaw React Claude Code 本地工作流现在我们来实操一遍。目标很明确在一台刚装好 Node.js 18.20.4 LTS 的 Ubuntu 22.04 笔记本上5 分钟内跑通一个带 Claude Code 插件调试能力的 OpenClaw 前端。整个过程不依赖 Docker不配置 Nginx不改一行 OpenClaw 或 React 源码。3.1 前置准备确认 Node.js 环境与基础依赖首先验证你的 Node.js 是否符合要求。OpenClaw 官方文档说支持 Node.js 16但 Paperclip 的engines.node字段明确要求18.0.0因为它的fetchAPI 调用依赖AbortSignal.timeout()这是 Node.js 18.12 才引入的特性。执行node -v # 输出应为 v18.20.4 或更高 npm -v # 输出应为 9.9.0 或更高Node.js 18.20.4 自带 npm 9.9.0如果版本不符请勿使用nvm install --lts它会装 20.x而应精准安装# 卸载旧版 sudo apt remove nodejs npm # 下载 Node.js 18.20.4 二进制包Linux x64 wget https://nodejs.org/dist/v18.20.4/node-v18.20.4-linux-x64.tar.xz tar -xf node-v18.20.4-linux-x64.tar.xz sudo cp -r node-v18.20.4-linux-x64/* /usr/local/ # 验证 node -v # v18.20.4注意不要用apt install nodejsUbuntu 22.04 官方源里的 Node.js 是 12.x太老。也不要curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -它会装 20.x。Paperclip 的package.json里engines.node是^18.0.0严格匹配。接着安装 Paperclip 全局命令npm install -g openclaw/paperclip # 验证 paperclip --version # 输出应为 0.4.2 或更高截至 2024 年底最新版3.2 初始化项目结构分离关注点避免“大杂烩”Paperclip 的最佳实践是严格分离 OpenClaw 后端、React 前端、Claude Code 插件三个代码仓。不要把它们塞进同一个 Git 仓库。我推荐这样的目录结构my-openclaw-workspace/ ├── backend/ # OpenClaw 官方 repo 的克隆 ├── frontend/ # 你自己的 React 项目create-react-app 或 Vite ├── plugins/ # Claude Code 插件开发目录 └── paperclip.config.yaml # Paperclip 的主配置文件先初始化 backendcd my-openclaw-workspace git clone https://github.com/openclaw/openclaw.git backend cd backend npm install # 不要 npm run dev这是 Paperclip 的事 cd ..再初始化 frontendnpx create-react-app frontend --template typescript cd frontend # 安装 OpenClaw React SDK假设有 npm install openclaw/react-sdk # 创建一个简单的 ChatPage.tsx cat src/pages/ChatPage.tsx EOF import { useState, useEffect } from react; import { useOpenClawAgent } from openclaw/react-sdk; export default function ChatPage() { const [messages, setMessages] useState{role: string; content: string}[]([]); const { send, isLoading } useOpenClawAgent(); useEffect(() { // 初始化消息 setMessages([{ role: assistant, content: 你好我是 OpenClaw 助手。 }]); }, []); const handleSubmit async (e: React.FormEvent) { e.preventDefault(); const input (e.target as any).elements.message.value; setMessages(prev [...prev, { role: user, content: input }]); const res await send(input); setMessages(prev [...prev, { role: assistant, content: res }]); }; return ( div h1OpenClaw Chat/h1 form onSubmit{handleSubmit} input namemessage placeholder输入消息... / button typesubmit disabled{isLoading}发送/button /form div {messages.map((m, i) ( div key{i}strong{m.role}:/strong {m.content}/div ))} /div /div ); } EOF # 替换 App.tsx echo import ChatPage from ./pages/ChatPage; export default ChatPage; src/App.tsx cd ..3.3 编写 paperclip.config.yaml定义服务契约这是 Paperclip 的心脏。一个精简但完备的配置如下# paperclip.config.yaml version: 0.4 # 后端服务定义 backend: # 指向 OpenClaw 的 package.json 路径 cwd: ./backend # 启动命令OpenClaw 官方是 npm run serve command: npm run serve # 端口探测范围 portRange: [8000, 8010] # 关键指定 OpenClaw 的 API 基础路径 apiBase: /api # 前端服务定义 frontend: cwd: ./frontend # CRA 的标准启动命令 command: npm start portRange: [3000, 3010] # 构建产物目录用于 production 模式 buildDir: build # 代理规则 proxy: # 将 /api/* 代理到后端 - from: /api/** to: http://localhost:{{backend.port}}/api rewrite: ^/api # 将 /claude/** 代理到后端并重写为 /v1/** - from: /claude/** to: http://localhost:{{backend.port}}/v1 rewrite: ^/claude # 将 /static/** 代理到前端构建目录 - from: /static/** to: http://localhost:{{frontend.port}}/static # 根路径 fallback 到 index.html - from: / to: http://localhost:{{frontend.port}}/index.html status: 200 # 环境变量会注入到所有子进程中 env: NODE_ENV: development # 这个变量会被 Paperclip 注入到前端 runtime 中 REACT_APP_OPENCLAW_API_BASE: http://localhost:{{proxy.port}}/api # 这个变量供后端读取决定它是否启用 Claude 模块 OPENCLAW_ENABLE_CLAUDE: true # 调试选项 debug: # 启用详细日志 verbose: true # 在 http://localhost:3006/__paperclip/debug 暴露服务状态 enableDebugEndpoint: true注意几个关键点{{backend.port}}和{{frontend.port}}是 Paperclip 的模板变量启动时会被实际探测到的端口替换REACT_APP_OPENCLAW_API_BASE的值是http://localhost:{{proxy.port}}/api意味着前端所有 API 请求都先打到 Paperclip 的代理层再由代理层转发——这保证了 CORS 安全OPENCLAW_ENABLE_CLAUDE: true是告诉 OpenClaw 后端加载 Claude 相关的路由和中间件。3.4 启动与验证观察日志理解数据流向一切就绪执行paperclip --config paperclip.config.yaml你会看到类似这样的日志输出[Paperclip] Starting services... [Backend] Detected port 8003 for backend service [Frontend] Detected port 3005 for frontend service [Proxy] Proxy server listening on http://localhost:3006 [Backend] openclaw0.1.0 serve [Backend] node dist/index.js [Backend] Server running on http://localhost:8003 [Frontend] react-scripts start [Frontend] Starting the development server... [Frontend] Compiled successfully! [Frontend] You can now view your app in the browser. [Frontend] Local: http://localhost:3005 [Paperclip] All services are ready. Open http://localhost:3006 in your browser.此时打开浏览器访问http://localhost:3006你看到的就是你的 React 前端。打开开发者工具 Network 面板发送一条消息你会看到请求 URL 是http://localhost:3006/api/chat前端发给 Paperclip 代理Paperclip 日志显示[Proxy] Forwarding /api/chat to http://localhost:8003/api/chat后端日志显示[OpenClaw] POST /api/chat 200 123ms响应体被 Paperclip 原样返回给前端。这就是 Paperclip 的完整数据链路前端 ↔ Paperclip 代理 ↔ OpenClaw 后端。它把原本需要 Nginx 或devServer.proxy配置的复杂性压缩成一个 YAML 文件和一条命令。4. 深度排错当 Paperclip 启动失败时如何像老司机一样快速定位根因Paperclip 的设计目标是“开箱即用”但现实总比理想骨感。我在帮 12 个不同技术背景的开发者排查 Paperclip 问题时总结出一套标准化的“三阶定位法”。它不依赖玄学重启而是基于 Paperclip 的三层胶水架构逐层剥离。4.1 第一阶验证端口协商层是否正常工作这是 70% 启动失败的根源。症状通常是控制台卡在[Paperclip] Starting services...无后续日志或报错Error: listen EADDRINUSE: address already in use :::3000但你确定没其他进程占着 3000。诊断步骤强制指定端口绕过探测逻辑paperclip --backend-port 8003 --frontend-port 3005 --proxy-port 3006如果成功则证明端口探测逻辑有问题。手动运行探测脚本npx tcp-port-used 3000 3001 3002 3003 3004 3005查看哪些端口被标记为in use。Paperclip 的探测库有时会误判TIME_WAIT状态这时你需要sudo ss -tuln | grep :3000查看真实状态。检查./.paperclip/runtime-config.json是否被写入。如果文件不存在或为空说明ServiceRegistry初始化失败大概率是config.yaml语法错误YAML 缩进问题最常见。实战心得Ubuntu 上ufw防火墙有时会干扰端口探测。临时禁用sudo ufw disable。MacOS 上AirPlay Receiver服务默认占7000端口会影响8000-8010探测用sudo lsof -i :7000查看并sudo kill -9 PID。4.2 第二阶检查代理层路由规则是否匹配症状前端页面能打开但所有 API 请求都 404 或 502或者/claude/chat/completions请求返回 404但/v1/chat/completions能通。诊断步骤访问 Paperclip 的调试端点http://localhost:3006/__paperclip/debug端口是proxy.port。它会返回一个 JSON包含当前所有服务的host和port。确认backend.port和frontend.port的值是否合理。在浏览器直接访问http://localhost:3006/api/health。如果返回{status:ok}说明代理层到后端的链路是通的如果返回Cannot GET /api/health说明proxy规则里的from: /api/**没生效检查config.yaml中proxy的缩进是否正确YAML 对空格极其敏感。用curl直接测试重写规则curl -v http://localhost:3006/claude/chat/completions \ -H Content-Type: application/json \ -d {model:claude-3-haiku,messages:[{role:user,content:hi}]}如果返回404但curl http://localhost:8003/v1/chat/completions能通则证明rewrite: ^/claude规则没触发。这时检查config.yaml中proxy数组的-符号是否对齐以及from和to字段是否在同一缩进层级。4.3 第三阶分析进程沙箱的环境变量与生命周期症状前端页面白屏Console 报ReferenceError: process is not defined或者后端启动后立即崩溃日志显示Error: Cannot find module openai。诊断步骤检查runtime-config.json中的env字段。Paperclip 会把config.yaml中的env和runtime-config.json中的env合并。如果合并后NODE_ENV被覆盖为production而你的前端是 CRA它会拒绝在development模式下运行。进入frontend目录手动执行npm start观察是否同样白屏。如果是问题在前端本身与 Paperclip 无关如果手动执行正常而 Paperclip 启动异常则是 Paperclip 的env注入出了问题。查看 Paperclip 启动时的完整日志。Paperclip 会打印每个子进程的cwd和env快照。搜索env:关键字确认REACT_APP_OPENCLAW_API_BASE是否被正确注入。如果没有检查config.yaml中env的缩进它必须和backend、frontend同级。踩坑实录有个用户在config.yaml里写了env: OPENCLAW_MODEL_PATH: /path/to/model少了一个换行和空格导致 YAML 解析器把整行当成一个字符串键env对象为空。Paperclip 不报错只是静默忽略。解决方案永远用在线 YAML 验证器如 yamlchecker.com校验你的配置。5. 进阶实战将 Paperclip 与 Teams、Obsidian、UPlot 深度集成Paperclip 的价值不仅在于让 OpenClaw 跑起来更在于它作为一个“胶水层”能无缝桥接各种企业级或个人知识管理工具。下面三个案例展示了它如何突破“本地开发服务器”的边界成为真正的 AI 工作流中枢。5.1 Paperclip Microsoft Teams实现零配置的 Teams 内嵌聊天机器人OpenClaw 官方文档说“接入 Teams 需要 Azure AD 配置和 Bot Framework”听起来就很重。但 Paperclip 让这件事变得像配置一个 iframe 一样简单。Teams 的 Tab 应用本质上就是一个托管在公网的 HTML 页面通过https://your-domain.com/tab.html加载。而 Paperclip 的proxy层可以把它变成一个“伪公网”服务。操作步骤在config.yaml中为前端添加一个teams代理规则proxy: # ... 其他规则 - from: /tab.html to: http://localhost:{{frontend.port}}/tab.html status: 200 - from: /tab.js to: http://localhost:{{frontend.port}}/tab.js status: 200在frontend/public/目录下创建tab.html!DOCTYPE html html head script srchttps://teams.microsoft.com/sdk/script /head body div idapp/div script src/tab.js/script /body /html创建frontend/src/tab.js初始化 Teams SDKmicrosoftTeams.app.initialize().then(() { microsoftTeams.app.registerOnThemeChangeHandler(theme { document.body.className theme dark ? dark : ; }); // 加载你的 ChatPage 组件 const root ReactDOM.createRoot(document.getElementById(app)); root.render(ChatPage /); });启动 Paperclip 后用ngrok http 3006或其他内网穿透工具将http://localhost:3006映射到一个公网 URL如https://abc123.ngrok.io。在 Teams 开发者门户创建新 AppTab 配置的Content URL填https://abc123.ngrok.io/tab.htmlWebsite URL填https://abc123.ngrok.io。为什么能行因为 Teams 加载tab.html时所有资源/tab.js,/static/*,/api/chat都通过https://abc123.ngrok.io发起请求而 ngrok 把它们全部转发给http://localhost:3006Paperclip 再根据规则分发到前端或后端。你不需要在 Teams 后端写任何代码不需要处理 OAuthPaperclip 的代理层已经帮你完成了所有跨域和路径重写。5.2 Paperclip Obsidian把本地知识库变成 OpenClaw 的实时数据源Obsidian 的核心是vault笔记库而 OpenClaw 的知识检索需要向量数据库。Paperclip 可以充当一个“活的桥梁”监听 Obsidian vault 的文件变化并实时触发 OpenClaw 的索引更新。操作步骤在backend目录下创建一个obsidian-watcher.js脚本const chokidar require(chokidar); const { exec } require(child_process); // 监听 Obsidian vault 目录 const watcher chokidar.watch(/path/to/your/obsidian/vault, { ignored: /(^|[\/\\])\../, // 忽略 .git, .obsidian 等 persistent: true }); watcher.on(change, (path) { console.log(File changed: ${path}); // 触发 OpenClaw 的索引重建 API exec(curl -X POST http://localhost:8003/api/index/rebuild -d {path:${path}}); });在config.yaml中把这个脚本作为后端的子进程启动backend: command: npm run serve node obsidian-watcher.js关键一步Paperclip 的proxy层需要把/api/index/rebuild这个路径明确路由到后端而不是被前端的root规则捕获。所以在proxy规则中把api规则放在root规则之前YAML 数组顺序很重要。效果你在 Obsidian 里编辑一篇笔记保存的瞬间obsidian-watcher.js捕获到change事件调用curl触发 OpenClaw 的/api/index/rebuildOpenClaw 就会重新解析这篇 Markdown更新向量索引。整个过程对用户完全透明Paperclip 确保了这个“后台任务”与主服务共存亡。5.3 Paperclip UPlot为 React 前端嵌入高性能 K 线图并实时订阅行情react-uplot是一个轻量级 K 线图库但它需要 WebSocket 连接实时行情。Paperclip 的websocket规则能让这个连接穿越代理层。操作步骤在frontend/src/App.tsx中使用uplotimport uPlot from uplot; useEffect(() { const u new uPlot({ width: 800, height: 400, scales: { x: { time: true } }, series: [ {}, { label: Price, stroke: red } ] }, document.getElementById(chart)); // 建立 WebSocket 连接 const ws new WebSocket(ws://localhost:3006/ws/market); ws.on