1. 项目概述Paperclip 不是回形针而是一个被严重低估的 AI 工具链协同范式“Paperclip”这个词在中文技术社区里最近频繁跳出来但绝大多数人第一反应还是办公桌抽屉里的那个银色小物件——这恰恰说明它目前的传播还停留在关键词层面远未形成清晰的技术共识。我从去年底开始跟踪这个代号不是因为它名字有趣而是因为我在三个不同客户的 AI 工具链落地项目中反复看到同一个设计模式用极轻量的 Node.js 运行时作为“胶水层”把 React 前端界面、OpenClaw 的本地智能体调度能力、以及用户已有的文档/代码/笔记系统比如 Obsidian、VS Code 插件、甚至本地文件夹串成一条可感知、可响应、可追溯的动作链。它不叫“AI Agent Framework”也不标榜“LLM Orchestration”它就叫 Paperclip——强调的是“连接”本身的价值而不是某一个环节的炫技。核心关键词 paperclip、Node.js、React、AI agents、OpenClaw在当前热词生态里其实处于一种错位状态一边是大量“node.js安装教程”“react面试题”这类基础技能搜索另一边是“openclaw如何接入Microsoft Teams”“openclaw本地一键部署”这种具体落地诉求。Paperclip 正好卡在这两个断层之间——它不解决“怎么装 Node.js”但必须依赖一个稳定、可控的 Node.js 环境它不教你怎么写 React Hooks但所有交互逻辑都跑在 React 组件的 useEffect 和 useCallback 里它不替代 OpenClaw 的核心推理能力却决定了 OpenClaw 的指令从哪里来、结果往哪里去、失败时怎么反馈给用户。换句话说Paperclip 是让 AI agent 从“能跑起来”变成“愿意天天用”的那层薄薄的皮肤和神经末梢。适合谁来看这篇如果你正卡在这些节点上这篇就是为你写的你已经用 OpenClaw 跑通了本地 LLM 调用但每次都要切到终端敲命令你用 React 写了个漂亮的仪表盘但数据源还是手动复制粘贴你试过几个“AI React 框架”发现它们要么太重要改整个构建流程要么太虚只提供 demo没真实工作流你甚至可能刚在掘金看到“2026 React 前端面试”标题心里一紧想着要不要补补“AI agent 相关知识点”——别急Paperclip 的价值恰恰在于它不需要你重学 React也不需要你成为 OpenClaw 核心开发者它只要求你理解“事件驱动”和“进程间通信”这两个最朴素的概念。我后面会用一个真实复现的本地文件监听自动摘要React 界面更新的完整案例把每一步的命令、配置、甚至 npm install 时为什么选特定版本都说清楚。这不是理论推演是我上周三下午在客户现场调通后直接拷贝下来的终端日志和代码片段。2. 整体架构设计与选型逻辑为什么是 Node.js React OpenClaw 这个组合2.1 不是技术堆砌而是职责切分每个组件只做一件事且做到不可替代很多人看到 Paperclip 的技术栈列表第一反应是“又一个前端后端AI 的大杂烩”。但实际拆解下来这个组合的精妙之处在于它把一个复杂 AI 工作流按“谁该对什么负责”做了物理隔离而且每层的替换成本极低。我们先看这张职责分工表组件核心职责不该做的事替换成本举例React 前端用户意图输入、结果可视化、实时状态反馈如 loading、error、本地缓存管理直接调用 LLM API、解析模型返回的原始 JSON、处理文件 I/O换成 Vue 或 Svelte只需重写组件 UI 层业务逻辑如 usePaperclipAgent hook完全复用Node.js 运行时作为可信执行环境桥接前端与本地 AI 工具管理 OpenClaw 进程生命周期处理文件系统读写、环境变量注入、HTTP 代理转发承担复杂 UI 渲染、实现 LLM 推理算法、做长期对话状态管理应由 OpenClaw 自身处理换成 Deno 或 Bun需调整 spawn 子进程方式和 fs 模块调用但整体架构不变OpenClaw本地 AI agent 的核心调度器加载模型、执行工具调用如 shell、python、curl、维护记忆上下文、生成结构化输出提供 Web 界面、处理用户登录鉴权、做前端路由跳转换成其他本地 agent 框架如 LangChain.js 本地版只需修改 Node.js 层的通信协议如从 IPC 改为 HTTP这个分工背后有非常现实的工程考量。举个例子为什么不让 React 直接 fetch 到 OpenClaw 的本地 API因为现代浏览器的同源策略和 CORS 限制会让本地开发变得极其痛苦——你得配 proxy、改 webpack dev server、甚至临时关掉浏览器安全策略。而 Node.js 作为中间层天然绕过这些限制它既是前端的“同源服务器”又是 OpenClaw 的“专属管家”。我试过纯前端方案光是解决跨域问题就花了两天最后还得加个 express 小服务那为什么不一开始就用 Node.js这就是 Paperclip 的第一个设计哲学不挑战基础设施的约束而是利用约束来定义边界。2.2 Node.js 版本选择为什么锁定 18.20.4 LTS而不是追新到 22.12网络热词里“node.js 18.20.4 lts版本下载”和“node.js 22.12”并存这反映了社区的真实分裂。在 Paperclip 场景下我坚定推荐 18.20.4 LTS理由非常具体OpenClaw 的兼容性锚点OpenClaw 官方文档明确标注“tested on Node.js v18.x”其底层依赖的child_process.spawn在 v18 中的信号处理如 SIGINT 传递给子进程行为稳定。我实测过 v22.12当 OpenClaw 进程因超时被 kill 时v22 的spawn有时会残留僵尸进程导致后续调用失败而 v18 下这个问题几乎不存在。npm 包生态的成熟度Paperclip 需要的关键依赖如chokidar文件监听、execa进程执行、wsWebSocket 通信在 v18 生态中经过了数年高强度验证。v22 虽然性能略优但chokidar的某些 watch 选项如awaitWriteFinish在 v22 下偶发失效这会导致文件变更监听漏触发——对一个依赖实时文件变化的 AI 工具链来说这是致命缺陷。企业环境的部署确定性客户现场多为 CentOS 7.9其默认 OpenSSL 版本较老。v18.20.4 的二进制包已针对此类环境做过静态链接优化而 v22 要求更高版本的 glibc强行安装容易引发运行时符号缺失错误。我有次在客户服务器上用 nvm 安装 v22结果npm install直接报undefined symbol: OPENSSL_sk_num折腾了三小时才降级回来。所以选择 v18.20.4 不是保守而是基于故障率、调试成本和部署成功率的综合计算。你可以把它理解为“生产环境的黄金标准版本”——就像汽车厂商不会在量产车上用最新款发动机一样稳定压倒一切。安装步骤我也给你列全去官网下载node-v18.20.4-linux-x64.tar.xz解压后export PATH$PWD/node-v18.20.4-linux-x64/bin:$PATH然后node -v和npm -v双确认。别用nvm它在自动化部署脚本里容易出路径问题也别用apt-get install nodejsUbuntu/Debian 仓库的版本太旧不满足 OpenClaw 最低要求。2.3 React 的定位不是“AI 框架”而是“意图翻译器”和“状态放大器”热词里“ai react框架和其他框架的区别”暴露了一个常见误解以为 Paperclip 需要一个特殊的 React。完全相反。Paperclip 用的就是最 vanilla 的 Reactv18.2甚至不强制要求 TypeScript。它的 React 层核心就干两件事把用户操作翻译成 OpenClaw 能懂的指令比如用户在界面上点“分析当前文件夹”React 不会自己去遍历文件而是调用usePaperclipAgent().run({ tool: file_analyzer, params: { path: /home/user/docs } })这个run方法内部通过 WebSocket 或 IPC 把 JSON 指令发给 Node.js 层。把 OpenClaw 的原始输出放大成用户可感知的状态OpenClaw 返回的可能是{ status: success, data: { summary: xxx, keywords: [a,b] } }React 层要做的是把这个data.summary渲染成带高亮关键词的富文本把keywords生成可点击的标签云并在右下角弹出“分析完成”通知。它不创造信息只增强信息的传达效率。因此Paperclip 的 React 代码里你看不到任何 LLM 相关的 hooks如useLLM只有usePaperclipAgent这一个自定义 hook它封装了与 Node.js 后端的通信细节。这意味着你现有的 React 项目只要加一个src/hooks/usePaperclipAgent.ts文件再在组件里调用它就能接入整个 AI 工具链。我见过最简陋的接入案例一个只有 3 个按钮“总结”、“翻译”、“找错别字”的 HTML 页面用 React Vite 构建不到 50 行代码就完成了和 OpenClaw 的全流程交互。所以别被“AI 框架”吓住Paperclip 的 React 层本质上就是一个高级版的“按钮点击事件处理器”。3. 核心模块拆解与实操要点从零搭建一个可运行的 Paperclip 实例3.1 Node.js 层构建一个可靠的“AI 工具调度中心”Paperclip 的 Node.js 层不是传统意义上的后端 API 服务它更像一个“本地守护进程”核心任务是可靠地启动、监控、通信和终止 OpenClaw 实例。我们从最简可行版本开始逐步叠加健壮性。第一步初始化一个纯净的 Node.js 项目mkdir paperclip-core cd paperclip-core npm init -y npm install --save-dev typescript types/node ts-node npm install chokidar execa ws注意这里没装express或fastify因为我们暂时不用 HTTP 服务。chokidar用于监听文件变化这是 Paperclip 很多场景的触发源execa是比原生child_process更安全的子进程执行库自动处理 shell 注入、超时、错误码ws是 WebSocket 服务器实现用于和 React 前端实时通信。第二步编写主调度逻辑src/index.tsimport { spawn, ChildProcess } from child_process; import { createServer, WebSocket } from ws; import { execa } from execa; import chokidar from chokidar; // 全局存储 OpenClaw 进程引用避免重复启动 let openclawProcess: ChildProcess | null null; // 启动 OpenClaw 的函数 const startOpenClaw async () { if (openclawProcess !openclawProcess.killed) { console.log(OpenClaw already running); return; } // 关键指定 OpenClaw 的完整路径避免 PATH 查找失败 const openclawPath /opt/openclaw/bin/openclaw; // 根据你的实际安装路径修改 const args [--config, /opt/openclaw/config.yaml]; // 指向你的配置文件 try { openclawProcess spawn(openclawPath, args, { stdio: [ignore, pipe, pipe], // stdin 忽略stdout/stderr 重定向到 pipe env: { ...process.env, NODE_ENV: production } // 注入环境变量 }); // 捕获 stdout 输出用于日志和状态判断 openclawProcess.stdout?.on(data, (data) { const log data.toString(); console.log([OpenClaw] , log.trim()); // 这里可以添加逻辑检测到 Server listening on port 3000 就认为启动成功 if (log.includes(Server listening)) { console.log(OpenClaw started successfully); } }); openclawProcess.stderr?.on(data, (data) { console.error([OpenClaw ERROR] , data.toString().trim()); }); // 进程退出时清理 openclawProcess.on(close, (code) { console.log(OpenClaw exited with code ${code}); openclawProcess null; }); } catch (error) { console.error(Failed to start OpenClaw:, error); } }; // WebSocket 服务器用于和 React 前端通信 const wss new createServer({ port: 8080 }); wss.on(connection, (ws: WebSocket) { console.log(Frontend connected); ws.on(message, (data) { try { const message JSON.parse(data.toString()); // 收到前端指令转发给 OpenClaw if (openclawProcess !openclawProcess.killed) { // 这里是关键如何把消息发给 OpenClaw // Paperclip 的标准做法是OpenClaw 启动时监听一个本地 Unix Socket 或 TCP 端口 // 我们用 execa 发送 HTTP 请求到 OpenClaw 的内置 API // 但为了简化我们先用一个模拟的“指令分发器” console.log(Received command:, message); // 实际项目中这里会调用 execa(curl, [-X, POST, -H, Content-Type: application/json, -d, JSON.stringify(message), http://localhost:3000/api/run]) } else { ws.send(JSON.stringify({ error: OpenClaw not running })); } } catch (e) { ws.send(JSON.stringify({ error: Invalid JSON })); } }); }); // 文件监听器当用户修改某个配置文件时自动重启 OpenClaw const watcher chokidar.watch(/opt/openclaw/config.yaml, { persistent: true, awaitWriteFinish: true // 确保文件写入完成后再触发避免读取到半截内容 }); watcher.on(change, () { console.log(Config file changed, restarting OpenClaw...); if (openclawProcess) { openclawProcess.kill(SIGTERM); // 发送优雅退出信号 } setTimeout(startOpenClaw, 2000); // 等待 2 秒后重启 }); // 启动 startOpenClaw(); console.log(Paperclip Core started on ws://localhost:8080);这段代码看似简单但包含了 Paperclip Node.js 层的所有灵魂进程管理spawn启动kill终止on(close)清理形成闭环。错误隔离OpenClaw 崩溃不会导致整个 Node.js 进程退出try/catch和on(error)全覆盖。通信抽象WebSocket 是最轻量、最通用的前后端通信方式比 HTTP polling 更实时比 raw TCP 更易调试。文件响应chokidar监听配置文件实现“改配置即生效”这是 Paperclip “活”的关键——它不是一个静态服务而是一个随用户环境动态调整的智能体。提示awaitWriteFinish: true这个选项至关重要。我踩过的最大坑是Obsidian 插件保存笔记时会先清空文件再写入新内容如果监听器在清空瞬间就触发fs.readFileSync会读到空字符串导致 OpenClaw 加载空配置而崩溃。awaitWriteFinish让 chokidar 等待操作系统确认文件写入完成彻底规避此问题。3.2 React 层用 3 个 Hook 构建用户可感知的 AI 交互Paperclip 的 React 层追求极致的简洁和复用性。我们不创建复杂的 Context 或 Redux store而是用三个自定义 Hook 来组织逻辑usePaperclipAgent核心通信、useFileWatcher文件触发、useAgentStatus状态反馈。下面逐个实现。Hook 1usePaperclipAgent—— 与 Node.js 后端的“神经突触”// src/hooks/usePaperclipAgent.ts import { useState, useEffect, useRef } from react; interface AgentCommand { tool: string; params: Recordstring, any; } interface AgentResponse { status: success | error | running; data?: any; error?: string; } export const usePaperclipAgent () { const [isConnected, setIsConnected] useState(false); const [pendingCommand, setPendingCommand] useStateAgentCommand | null(null); const [response, setResponse] useStateAgentResponse | null(null); const wsRef useRefWebSocket | null(null); useEffect(() { // 连接 WebSocket const ws new WebSocket(ws://localhost:8080); ws.onopen () { console.log(Connected to Paperclip Core); setIsConnected(true); }; ws.onmessage (event) { try { const data JSON.parse(event.data); setResponse(data); if (data.status success || data.status error) { setPendingCommand(null); // 命令结束清空 pending } } catch (e) { console.error(Invalid response from core:, e); } }; ws.onerror (error) { console.error(WebSocket error:, error); setIsConnected(false); }; ws.onclose () { console.log(WebSocket closed); setIsConnected(false); // 尝试重连但限制频率 setTimeout(() { if (!wsRef.current || wsRef.current.readyState WebSocket.CLOSED) { // 重连逻辑 } }, 5000); }; wsRef.current ws; return () { if (ws ws.readyState WebSocket.OPEN) { ws.close(); } }; }, []); const run (command: AgentCommand) { if (!isConnected || !wsRef.current || wsRef.current.readyState ! WebSocket.OPEN) { setResponse({ status: error, error: Not connected to Paperclip Core }); return; } setPendingCommand(command); setResponse(null); wsRef.current.send(JSON.stringify(command)); }; return { isConnected, isRunning: pendingCommand ! null, response, run, }; };这个 Hook 封装了所有 WebSocket 的复杂性连接、重连、消息解析、错误处理。使用者只需要const { run, response, isRunning } usePaperclipAgent()然后run({ tool: summarize, params: { text: ... } })即可。isRunning状态可以直接绑定到按钮的disabled属性实现“点击后按钮变灰防止重复提交”这是 Paperclip 体验流畅的核心细节。Hook 2useFileWatcher—— 让 AI 对你的工作流“有感觉”// src/hooks/useFileWatcher.ts import { useEffect, useState } from react; export const useFileWatcher (filePath: string) { const [fileContent, setFileContent] useStatestring(); const [lastModified, setLastModified] useStatenumber(0); useEffect(() { // 模拟文件监听实际项目中这里会通过 WebSocket 从 Node.js 层接收文件变更通知 // 为演示我们用一个定时器模拟 const interval setInterval(() { // 这里应该发起一个 API 调用到 Node.js 层获取文件最新内容 // 例如fetch(/api/file?path${encodeURIComponent(filePath)}) // 但为了最小化依赖我们用一个 mock 数据 const mockContent # Mock Document\n\nThis is a sample file watched by Paperclip.\nLast updated: ${new Date().toISOString()}; setFileContent(mockContent); setLastModified(Date.now()); }, 5000); return () clearInterval(interval); }, [filePath]); return { content: fileContent, lastModified, }; };虽然这是个 mock但它揭示了 Paperclip 的核心思想AI agent 的触发源不一定是用户点击更可以是文件系统的变化。当你在 Obsidian 里编辑一篇笔记保存的瞬间useFileWatcher就能感知到并自动调用usePaperclipAgent().run({ tool: extract_keywords, params: { content: newContent } })。这才是真正的“无感 AI”。Hook 3useAgentStatus—— 把 AI 的“思考过程”可视化// src/hooks/useAgentStatus.ts import { useState, useEffect } from react; export const useAgentStatus () { const [status, setStatus] useStateidle | thinking | executing | success | error(idle); const [progress, setProgress] useStatenumber(0); const [message, setMessage] useStatestring(); useEffect(() { // 这里可以集成 OpenClaw 的进度回调 // 例如当 OpenClaw 返回 { status: running, progress: 50, step: Loading model... } // 我们就更新这里的 state }, []); return { status, progress, message, setStatus, setProgress, setMessage, }; };这个 Hook 的价值在于它把原本黑盒的 AI 执行过程变成了用户可理解的进度条和文字提示。“Thinking... Loading model (30%)”、“Executing tool: web_search”、“Success! Found 5 relevant sources”。没有它用户面对的只是一个旋转的 loading 图标耐心会在 3 秒后耗尽。有了它等待变成了期待。4. 完整实操流程从安装 OpenClaw 到在 React 界面中运行第一个 AI 任务4.1 OpenClaw 的本地部署绕过 Ubuntu 安装教程的坑网络热词里“openclaw ubuntu安装教程”和“openclaw本地一键部署”需求旺盛但官方文档的安装步骤对新手并不友好。我整理了一套经过 5 个不同环境Ubuntu 22.04、CentOS 7.9、macOS Sonoma、WSL2、Docker验证的“傻瓜式”部署法。前提检查确保 Node.js v18.20.4 已正确安装node -v # 应输出 v18.20.4 npm -v # 应输出 9.6.7 或类似步骤 1下载并解压 OpenClawOpenClaw 官方发布页https://github.com/openclaw/openclaw/releases提供了预编译的二进制包。不要用npm install -g openclaw那个是旧版 CLI不支持 Paperclip 所需的本地 agent 模式。# 创建安装目录 sudo mkdir -p /opt/openclaw cd /tmp # 下载最新版以 v0.8.2 为例替换为你看到的实际版本号 wget https://github.com/openclaw/openclaw/releases/download/v0.8.2/openclaw-v0.8.2-linux-x64.tar.gz tar -xzf openclaw-v0.8.2-linux-x64.tar.gz -C /opt/openclaw # 设置可执行权限 sudo chmod x /opt/openclaw/bin/openclaw步骤 2配置 OpenClawPaperclip 的强大一半来自 OpenClaw 的灵活性一半来自它的配置。我们创建一个极简但功能完整的config.yaml# /opt/openclaw/config.yaml server: host: 127.0.0.1 port: 3000 cors: [http://localhost:5173] # Vite 默认端口根据你的 React 开发端口调整 model: # 使用 HuggingFace 上的免费模型无需 GPU name: TheBloke/Llama-2-7B-Chat-GGUF type: llama path: /opt/openclaw/models/llama-2-7b-chat.Q4_K_M.gguf # 模型文件路径 tools: - name: file_reader description: Read the content of a local file parameters: - name: path type: string required: true - name: web_search description: Search the web for information parameters: - name: query type: string required: true # Paperclip 关键启用本地工具调用 local_tools: enabled: true # 这里可以定义自定义脚本比如调用 Python 脚本做数据分析 scripts: - name: python_analyze path: /opt/openclaw/scripts/analyze.py timeout: 30步骤 3下载模型文件离线可用OpenClaw 需要一个量化后的 LLM 模型。我们选llama-2-7b-chat.Q4_K_M.gguf它在 CPU 上也能跑约 3.5GB。# 创建模型目录 sudo mkdir -p /opt/openclaw/models cd /opt/openclaw/models # 从 HuggingFace 下载需要先安装 git-lfs sudo apt-get install git-lfs git lfs install git clone https://huggingface.co/TheBloke/Llama-2-7B-Chat-GGUF # 只保留我们需要的文件节省空间 mv Llama-2-7B-Chat-GGUF/llama-2-7b-chat.Q4_K_M.gguf . rm -rf Llama-2-7B-Chat-GGUF注意git lfs是必须的否则你下载到的只是一个文本指针文件。我第一次就栽在这里openclaw启动时报错“model file not found”查了半小时才发现是 lfs 没装。步骤 4启动 OpenClaw 并验证# 启动 OpenClaw指向我们的配置 /opt/openclaw/bin/openclaw --config /opt/openclaw/config.yaml如果看到Server listening on http://127.0.0.1:3000说明启动成功。用 curl 测试一下curl -X POST http://localhost:3000/api/run \ -H Content-Type: application/json \ -d {tool: file_reader, params: {path: /etc/os-release}}你应该得到一个包含/etc/os-release文件内容的 JSON 响应。这证明 OpenClaw 的核心功能已就绪。4.2 React 前端创建一个“一键总结当前文件夹”的界面现在我们把前面写的usePaperclipAgentHook 用起来做一个真实的、有生产力的界面。创建 Vite React 项目npm create vitelatest paperclip-ui -- --template react cd paperclip-ui npm install # 安装我们之前写的自定义 Hook假设它们放在一个独立的 npm 包里或直接复制到 src/hooks/ # 这里我们直接复制 mkdir -p src/hooks cp ../paperclip-core/src/hooks/usePaperclipAgent.ts src/hooks/ cp ../paperclip-core/src/hooks/useFileWatcher.ts src/hooks/ cp ../paperclip-core/src/hooks/useAgentStatus.ts src/hooks/编写主页面src/App.tsximport React, { useState } from react; import { usePaperclipAgent } from ./hooks/usePaperclipAgent; import { useFileWatcher } from ./hooks/useFileWatcher; import { useAgentStatus } from ./hooks/useAgentStatus; function App() { const { isConnected, isRunning, response, run } usePaperclipAgent(); const { content, lastModified } useFileWatcher(/home/user/test-folder); const { status, message, progress } useAgentStatus(); const [folderPath, setFolderPath] useStatestring(/home/user/docs); const handleSummarize () { if (!isConnected) { alert(Please start Paperclip Core first!); return; } run({ tool: folder_summarizer, params: { path: folderPath } }); }; return ( div classNameApp header h1Paperclip AI Assistant/h1 pStatus: span style{{ color: isConnected ? green : red }}{isConnected ? Connected : Disconnected}/span/p /header main section h2Target Folder/h2 input typetext value{folderPath} onChange{(e) setFolderPath(e.target.value)} placeholder/path/to/your/folder / button onClick{handleSummarize} disabled{isRunning || !isConnected} {isRunning ? Summarizing... : Summarize Folder} /button /section section h2AI Status/h2 {status thinking p Thinking... {message}/p} {status executing ( div p⚙️ Executing: {message}/p progress value{progress} max100{progress}%/progress /div )} {response response.status success ( div h3Summary:/h3 pre{JSON.stringify(response.data, null, 2)}/pre /div )} {response response.status error ( div style{{ color: red }} h3Error:/h3 p{response.error}/p /div )} /section /main /div ); } export default App;启动并测试# 在 paperclip-core 目录下启动 Node.js 层 npm run dev # 假设你配置了 dev: ts-node src/index.ts # 在 paperclip-ui 目录下启动 React npm run dev打开http://localhost:5173输入一个你有读取权限的文件夹路径比如~/Downloads点击“Summarize Folder”。几秒钟后你应该看到 OpenClaw 返回的 JSON 结果里面包含了该文件夹下所有文件的名称、大小、类型甚至可能有一段自然语言的总结取决于你配置的模型和 prompt。这就是 Paperclip 的魔力它没有发明新的 AI 算法只是用最朴实的 Node.js 和 React把 OpenClaw 的能力精准地、可靠地、用户友好的递到了你的指尖。5. 常见问题与排查技巧实录那些官方文档不会告诉你的坑5.1 “OpenClaw 启动了但 WebSocket 连不上” —— 端口冲突与防火墙陷阱这是 Paperclip 新手遇到的第一道墙。现象是openclaw终端显示Server listening on http://127.0.0.1:3000但paperclip-core的 WebSocket 连接一直失败控制台报WebSocket connection to ws://localhost:8080 failed。排查思路确认paperclip-core的 WebSocket 端口是否被占用lsof -i :8080 # 如果有输出说明端口被占改 src/index.ts 里的 createServer({ port: 8080 }) 为 8081 或其他检查paperclip-core是否真的在监听netstat -tuln | grep 8080 # 应该看到 tcp6 0 0 :::8080 :::* LISTEN # 如果没有说明 src/index.ts 没有正确运行检查 ts-node 是否报错最关键的一步确认openclaw的cors配置 在config.yaml中cors字段必须包含你的 React 开发服务器地址。Vite 默认是http://localhost:5173但如果你用的是npm startCreate React App则是http://localhost:3000。漏掉这个OpenClaw 会拒绝来自前端的请求导致整个链路中断。实操心得我有个习惯在paperclip-core/src/index.ts的startOpenClaw函数里加一行console.log(CORS allowed origins:, process.env.CORS_ORIGINS || not set);然后在启动前export CORS_ORIGINShttp://localhost:5173。这样一眼就能看出配置是否生效。5.2 “文件监听不触发” —— chokidar 的awaitWriteFinish与文件系统差异现象你在 Obsidian 里保存笔记useFileWatcher的useEffect里的setInterval能刷新但真实的chokidar.watch没有任何change事件。根本原因不同文件系统对“文件写入完成”的