Paperclip：基于OpenClaw的轻量级AI Agent胶水框架实战

1. 项目概述Paperclip 不是回形针而是一个被严重误读的 AI 工具链命名陷阱“Paperclip”这个词一出来绝大多数人第一反应是办公桌上那个弯弯绕绕的金属小物件——回形针。但在这个上下文中它根本不是物理世界里的文具而是当前开发者社区里一个高频出现、却极少被准确定义的代号型项目名。它不指向某个开源仓库的官方名称也不对应 npm 或 GitHub 上注册的权威包名而更像是一个在技术讨论、面试复盘、部署踩坑帖中自发形成的“暗语”当有人在掘金、V2EX 或某次内部分享里说“我们用 Paperclip 搭了个 agent 流程”他真正想表达的是“我们基于 Node.js React 构建了一套轻量级 AI Agent 协同框架底层依赖 OpenClaw 做核心执行调度”。这个命名本身就是一次典型的工程实践倒逼术语演化的结果——不是先有标准再落地而是先跑通流程再给它起个顺口、易记、带点极客幽默感的代号。为什么偏偏选了 “Paperclip”这里藏着一线开发者的现实逻辑。OpenClaw 作为当前较活跃的本地化 AI Agent 执行引擎注意它不是 LLM 模型而是任务编排与工具调用层其设计哲学强调“轻耦合、可插拔、低侵入”。就像回形针能把几页散落的纸临时固定成一份材料却不改变每页纸的内容和结构Paperclip 这个代号所指代的整套方案核心价值就在于“临时粘合”——把 React 前端的状态管理、Node.js 后端的 API 路由、OpenClaw 的 agent runtime、甚至用户本地的 Python 工具脚本用最小代价串成一条可调试、可观察、可灰度发布的完整链路。它不追求替代 Next.js 或 NestJS而是专注解决“从 prompt 到 action 再到 UI 反馈”这短短一跳里的胶水问题。你可能会问既然本质是 OpenClaw Node.js React 的组合为什么还要多此一举叫 Paperclip答案很实在因为 OpenClaw 官方文档里压根没提 React 怎么集成它的 CLI 工具只管启动服务、加载插件、暴露/v1/execute接口而 React 社区里满天飞的 “AI Agent UI 框架” 要么重得像 Next.js 全栈套壳要么轻得只剩一个useAgent()Hook连错误重试逻辑都要自己手写。Paperclip 就是在这两极之间踩出的一条土路——它没有自己的 GitHub star 数但你的团队可能已经用它上线了三个内部提效工具。它适合谁不是刚学完《React 官方教程》的小白也不是正在用 LangChain 搞金融风控大模型的架构师而是卡在中间那群人前端能写 Hooks、后端能搭 Express、对 LLM 调用有基本概念、手头有个真实业务需求比如自动整理会议纪要、解析销售合同 PDF、生成周报初稿需要两周内跑通 MVP 的全栈工程师或技术负责人。接下来的内容不会教你从零安装 Node.js也不会逐行解释 React Fiber 架构而是直接把你拉进一个真实项目的工位看我们怎么用 Paperclip 这个“回形针”把一堆散装能力钉成一个能用的 AI 工具。2. 核心设计思路拆解为什么不用 LangChain / LlamaIndex而选择 OpenClaw 自研胶水层在决定采用 Paperclip 方案前我们团队花了整整三天时间横向对比了五种主流 AI Agent 构建路径。LangChain 是最成熟的但它在我们的场景下暴露出三个无法绕开的硬伤第一它的Chain抽象层虽然强大但默认绑定 Python 生态强行用langchain-js会丢失 70% 以上的工具链支持比如SQLDatabaseChain在 JS 里根本不存在第二它的AgentExecutor对错误恢复极其脆弱——当一个工具调用超时或返回格式错误整个 chain 就会中断而我们要求的是“单步失败不影响后续步骤”比如解析 PDF 失败至少还能把用户原始输入存进数据库并通知人工介入第三也是最致命的它的调试体验反人类一个invoke()调用背后可能嵌套 8 层 Promiseconsole.log打印出来的 trace ID 像乱码线上出问题时根本没法快速定位是哪个 Tool 的run()方法卡住了。LlamaIndex 的定位更偏 RAG对通用 Agent 场景支持不足。而 AutoGen 和 CrewAI 虽然支持多 Agent 协作但它们的通信协议基于 WebSocket 或自定义消息队列和我们的现有基础设施Nginx Express PostgreSQL完全不兼容引入新组件意味着要额外维护一套服务发现和健康检查机制ROI投入产出比极低。最终选择 OpenClaw是基于它三个不可替代的特质原生 Node.js 支持、声明式插件系统、以及对“失败即常态”的工程化接纳。OpenClaw 的核心不是让你写更聪明的 prompt而是帮你写更鲁棒的tool。它的插件机制要求你必须显式定义inputSchemaJSON Schema 格式和outputSchema这意味着每个工具的输入输出边界在代码层面就被强制收敛。我们曾把一个原本用child_process.execSync直接调用pdftotext的粗糙脚本封装成 OpenClaw 插件后仅靠 schema 验证就拦截了 32% 的非法参数调用比如传入空字符串或超长路径。更重要的是OpenClaw 的execute接口返回体里自带status: success | error | partial_success字段配合error_details和step_logs让前端可以精准渲染“第 3 步失败错误码 TOOL_TIMEOUT建议重试或跳过”。那么为什么还需要 Paperclip 这层“胶水”因为 OpenClaw 本身是个纯后端运行时它不关心你怎么展示 loading 状态不处理用户登录态也不提供任何 React 组件。Paperclip 的核心价值就体现在这三块补丁上状态同步层我们用一个usePaperclipAgent自定义 Hook内部封装了fetch(/api/agent/execute)的完整生命周期并将 OpenClaw 返回的step_logs映射为 React 的useState更新。关键在于我们没有用useEffect去轮询而是利用 OpenClaw 的stream: true参数开启 SSEServer-Sent Events让后端在每个步骤完成后主动推送日志片段。这样前端就能实现“打字机效果”式的实时反馈而不是干等一个 5 秒后的最终响应。错误降级策略层当 OpenClaw 返回status: error时Paperclip 不会直接 throw Error 让整个页面崩溃。它会检查error_details.code—— 如果是TOOL_NOT_FOUND则提示用户“该功能暂未开通”如果是RATE_LIMIT_EXCEEDED则自动切换到备用工具比如把调用 GPT-4 的请求降级为本地 Ollama 的 Qwen2.5-3B如果是INPUT_VALIDATION_FAILED则把inputSchema的description字段提取出来生成一句人话提示“请确保上传的文件小于 10MB 且格式为 PDF 或 DOCX”。配置抽象层我们把 OpenClaw 的config.yaml里那些tools_dir、llm_provider、max_steps参数全部映射到一个PaperclipConfigProviderReact Context 中。这样同一个代码库部署到测试环境和生产环境时只需修改.env文件里的REACT_APP_PAPERCLIP_CONFIG_URL前端就能动态加载对应的配置无需重新构建。这个设计直接避免了我们曾经踩过的一个大坑在 CI/CD 流水线里因为忘记替换config.yaml路径导致测试环境调用了生产环境的阿里云百炼 API账单一夜暴涨。提示不要试图用 OpenClaw 的 CLI 工具直接启动生产服务。它的openclaw serve命令默认监听localhost:3000且无鉴权这是为本地开发设计的。Paperclip 的 Node.js 后端层本质上是一个反向代理 鉴权网关它把/api/agent/execute请求转发给本地运行的 OpenClaw 实例同时注入Authorizationheader 和请求审计日志。这种分层让安全加固和流量控制变得可控。3. 核心细节解析与实操要点从零搭建 Paperclip 开发环境的七步法搭建 Paperclip 环境不是简单地npm install一堆包而是一场涉及操作系统、Node.js 版本、Python 环境、OpenClaw 编译和 React 配置的协同作战。我们团队在 CentOS 7.9、Windows 11 WSL2 和 macOS Sonoma 三套环境上反复验证总结出以下七步法。每一步都附带“为什么必须这么做”的原理说明而非照搬教程。3.1 第一步确认 Node.js 版本并锁定为 20.18.0非最新版很多教程鼓吹“安装最新版 Node.js”但在 Paperclip 场景下这是个危险操作。OpenClaw 的openclaw/core包在package.json的engines字段里明确写着node: 18.17.0 21.0.0。如果你装了 Node.js 22.12npm install时会收到警告而某些依赖如node-gyp编译的sqlite3会直接编译失败。我们实测过 Node.js 22.12 下openclaw serve启动后调用shelljs工具时会因process.chdir()的行为变更而抛出EPERM错误。正确做法是使用nvmNode Version Manager进行版本隔离# Linux/macOS curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20.18.0 nvm use 20.18.0 node -v # 必须输出 v20.18.0注意nvm在 Windows 上不原生支持如果你用的是 WSL2请务必在 WSL 内部安装nvm而不是在 PowerShell 里用nvm-windows。后者管理的 Node.js 实例无法被 WSL 中的 OpenClaw 进程识别。3.2 第二步初始化 OpenClaw 插件目录并验证 Python 环境OpenClaw 的核心能力来自插件而插件本质是 Python 脚本。它不强制要求你用 Conda但必须确保系统 Python 版本 ≥ 3.8 且pip可用。在 CentOS 7.9 上系统自带的 Python 2.7 是废的必须手动编译安装 Python 3.9# CentOS 7.9 示例 sudo yum groupinstall Development Tools sudo yum install openssl-devel bzip2-devel libffi-devel wget https://www.python.org/ftp/python/3.9.18/Python-3.9.18.tgz tar -xzf Python-3.9.18.tgz cd Python-3.9.18 ./configure --enable-optimizations make -j$(nproc) sudo make altinstall python3.9 -m pip --version # 必须成功输出然后创建 OpenClaw 的标准插件结构mkdir -p ~/paperclip/plugins/{pdf,docx,web} touch ~/paperclip/plugins/pdf/extract_text.py touch ~/paperclip/plugins/docx/parse_tables.py每个.py文件开头必须包含 OpenClaw 要求的元信息注释# plugin_name: pdf_extract_text # description: 从 PDF 文件中提取纯文本内容 # input_schema: # type: object # properties: # file_path: # type: string # description: PDF 文件的绝对路径 # output_schema: # type: object # properties: # text: # type: string # description: 提取的文本内容 import sys import json from pypdf import PdfReader def main(): input_data json.load(sys.stdin) reader PdfReader(input_data[file_path]) text for page in reader.pages: text page.extract_text() print(json.dumps({text: text})) if __name__ __main__: main()关键细节plugin_name必须全小写且不含下划线这是 OpenClaw 加载插件时的匹配规则input_schema和output_schema必须是合法 JSON SchemaOpenClaw 启动时会校验校验失败则整个插件目录加载失败服务无法启动。3.3 第三步安装 OpenClaw 并配置config.yamlOpenClaw 的安装方式取决于你的目标平台。在 WSL2 或 Linux 上推荐用pipx隔离 Python 环境python3.9 -m pip install pipx pipx install openclaw在 macOS 上如果遇到libomp缺失错误需额外安装brew install libomp export OMP_NUM_THREADS4安装完成后生成初始配置openclaw init --config-dir ~/paperclip/config编辑~/paperclip/config/config.yaml重点修改以下字段server: host: 0.0.0.0 # 必须设为 0.0.0.0否则 Node.js 后端无法反向代理 port: 3001 # 避免和 React 默认的 3000 端口冲突 cors_origin: * # 开发期可设为 *生产环境必须指定域名 plugins: directory: /home/yourname/paperclip/plugins # 绝对路径不能用 ~ llm: provider: ollama # 我们用本地 Ollama避免 API 密钥泄露风险 model: qwen2.5:3b # 必须提前用 ollama pull qwen2.5:3b 拉取 base_url: http://localhost:11434 # Ollama 默认地址 logging: level: debug # 开发期必须开 debug能看到每一步的耗时和输入输出注意base_url的http://localhost:11434在 WSL2 里是有效的因为 Ollama 服务运行在 Windows 主机上WSL2 的localhost能自动映射到主机。但如果你把 Ollama 也装在 WSL2 里则base_url应为http://127.0.0.1:11434。3.4 第四步启动 OpenClaw 并验证插件加载不要急着启动服务先做两件事运行openclaw list-plugins --config-dir ~/paperclip/config确认输出里包含你刚写的pdf_extract_text手动测试插件cd ~/paperclip/plugins/pdf python3.9 extract_text.py test_input.json其中test_input.json是一个符合input_schema的 JSON 文件。然后启动服务openclaw serve --config-dir ~/paperclip/config正常启动后访问http://localhost:3001/health应返回{status:ok}访问http://localhost:3001/v1/plugins应列出所有插件元信息。此时OpenClaw 已就绪它就是一个纯粹的、无 UI 的 Agent 执行引擎。3.5 第五步创建 Paperclip Node.js 后端Express新建paperclip-backend目录初始化mkdir paperclip-backend cd paperclip-backend npm init -y npm install express cors helmet morgan axios npm install --save-dev nodemon创建server.jsconst express require(express); const cors require(cors); const helmet require(helmet); const morgan require(morgan); const axios require(axios); const app express(); const PORT process.env.PORT || 5000; const OPENCLAW_URL http://localhost:3001; // 指向上一步启动的 OpenClaw // 安全中间件 app.use(helmet()); app.use(cors({ origin: http://localhost:3000 })); // 仅允许 React 开发服务器 app.use(morgan(combined)); // 代理 /api/agent/execute 到 OpenClaw app.post(/api/agent/execute, async (req, res) { try { const response await axios({ method: post, url: ${OPENCLAW_URL}/v1/execute, data: req.body, headers: { Content-Type: application/json, // 这里可以注入鉴权 token比如从 req.headers.authorization 提取 }, timeout: 30000, // 30秒超时避免前端无限等待 }); res.json(response.data); } catch (error) { console.error(OpenClaw execute error:, error.response?.data || error.message); res.status(500).json({ status: error, message: Agent execution failed, error_details: { code: BACKEND_ERROR, message: error.message } }); } }); app.listen(PORT, () { console.log(Paperclip backend listening on http://localhost:${PORT}); });启动后端npx nodemon server.js。此时http://localhost:5000/api/agent/execute就是 Paperclip 的统一入口。3.6 第六步创建 Paperclip React 前端并集成usePaperclipAgent用create-react-app创建前端npx create-react-app paperclip-frontend --template typescript cd paperclip-frontend npm install axios react-icons创建src/hooks/usePaperclipAgent.tsimport { useState, useCallback, useEffect } from react; import axios from axios; interface StepLog { step_id: string; tool_name: string; status: running | success | error; input: Recordstring, any; output?: Recordstring, any; error_details?: Recordstring, any; } interface PaperclipResponse { status: success | error | partial_success; result?: any; step_logs: StepLog[]; error_details?: Recordstring, any; } export const usePaperclipAgent () { const [isExecuting, setIsExecuting] useState(false); const [logs, setLogs] useStateStepLog[]([]); const [result, setResult] useStateany(null); const execute useCallback(async (prompt: string, tools: string[] []) { setIsExecuting(true); setLogs([]); setResult(null); try { // 使用 fetch ReadableStream 实现 SSE比 axios 更可控 const response await fetch(/api/agent/execute, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ prompt, tools, stream: true }), }); if (!response.body) throw new Error(ReadableStream not supported); const reader response.body.getReader(); const decoder new TextDecoder(); while (true) { const { done, value } await reader.read(); if (done) break; const chunk decoder.decode(value); const lines chunk.split(\n).filter(line line.trim() ! ); for (const line of lines) { if (line.startsWith(data: )) { try { const log JSON.parse(line.slice(6)); setLogs(prev [...prev, log]); if (log.status success log.tool_name final_answer) { setResult(log.output); } } catch (e) { console.warn(Failed to parse SSE log:, line, e); } } } } } catch (error) { console.error(Execution failed:, error); setLogs(prev [...prev, { step_id: error- Date.now(), tool_name: system, status: error, input: {}, error_details: { message: (error as Error).message } }]); } finally { setIsExecuting(false); } }, []); return { isExecuting, logs, result, execute }; };关键技巧SSE 的data:前缀解析必须严格OpenClaw 的流式响应每行都是data: {step_id:...}\n所以要用line.slice(6)去掉前缀再JSON.parse。我们曾因少切一个字符导致整个日志解析失败前端白屏。3.7 第七步编写第一个 Paperclip Agent 页面在src/App.tsx中使用import React, { useState } from react; import { usePaperclipAgent } from ./hooks/usePaperclipAgent; import { FaPlay, FaSpinner } from react-icons/fa; function App() { const [prompt, setPrompt] useState(); const { isExecuting, logs, result, execute } usePaperclipAgent(); const handleSubmit (e: React.FormEvent) { e.preventDefault(); if (!prompt.trim()) return; execute(prompt, [pdf_extract_text]); // 指定要使用的工具 }; return ( div classNameApp h1Paperclip Agent Demo/h1 form onSubmit{handleSubmit} input typetext value{prompt} onChange{(e) setPrompt(e.target.value)} placeholder输入 PDF 文件路径例如: /home/user/report.pdf disabled{isExecuting} / button typesubmit disabled{isExecuting} {isExecuting ? FaSpinner classNameanimate-spin / : FaPlay /} 执行 /button /form div classNamelogs h2执行日志/h2 {logs.map((log) ( div key{log.step_id} className{log-item ${log.status}} strong{log.tool_name}:/strong {log.status} {log.error_details - ${log.error_details.message}} /div ))} /div {result ( div classNameresult h2最终结果/h2 pre{JSON.stringify(result, null, 2)}/pre /div )} /div ); } export default App;启动前端npm start。打开http://localhost:3000输入一个本地 PDF 路径点击执行——你看到的每一行日志都是 Paperclip 这个“回形针”把 OpenClaw、Node.js、React 三者牢牢粘在一起的实时证据。4. 实操过程与核心环节实现一个真实业务场景的端到端复现我们以一个真实的内部提效需求为例自动解析销售部门每周提交的 Excel 报表提取关键指标新签合同数、总金额、区域分布并生成 Markdown 格式的周报草稿最后通过企业微信机器人推送给管理层。这个需求看似简单但涉及文件上传、多工具串联、错误重试、异步通知是 Paperclip 典型的应用场。4.1 工具链设计四个插件构成闭环我们没有用一个巨无霸插件搞定所有事而是拆成四个正交的 OpenClaw 插件每个只做一件事excel_read读取 Excel 文件返回[{region: 华东, new_contracts: 12, amount: 2450000}]markdown_gen接收 Excel 解析结果生成 Markdown 表格和文字摘要wechat_notify调用企业微信 Webhook发送 Markdown 消息file_upload处理前端上传的文件保存到临时目录并返回绝对路径。这四个插件的plugin_name分别为excel_read,markdown_gen,wechat_notify,file_upload它们之间通过 OpenClaw 的context机制传递数据而非硬编码路径。4.2 OpenClaw 插件实现细节以excel_read为例~/paperclip/plugins/excel/excel_read.py# plugin_name: excel_read # description: 读取 Excel 文件中的销售数据工作表 # input_schema: # type: object # properties: # file_path: # type: string # description: Excel 文件的绝对路径 # sheet_name: # type: string # description: 工作表名称默认为 销售数据 # output_schema: # type: array # items: # type: object # properties: # region: # type: string # new_contracts: # type: integer # amount: # type: number import sys import json import pandas as pd def main(): input_data json.load(sys.stdin) file_path input_data[file_path] sheet_name input_data.get(sheet_name, 销售数据) try: # 关键用 pandas 读取自动处理 .xls 和 .xlsx df pd.read_excel(file_path, sheet_namesheet_name) # 强制转换列名避免大小写/空格问题 df.columns [col.strip().replace( , _).lower() for col in df.columns] # 提取我们需要的三列缺失则用默认值 result [] for _, row in df.iterrows(): result.append({ region: str(row.get(region, 未知)), new_contracts: int(row.get(new_contracts, 0)), amount: float(row.get(amount, 0.0)) }) print(json.dumps(result)) except Exception as e: # OpenClaw 要求任何异常都必须捕获并输出标准错误格式 print(json.dumps({ error: { code: EXCEL_PARSE_ERROR, message: str(e), file_path: file_path } })) if __name__ __main__: main()注意print(json.dumps({...}))是 OpenClaw 插件的唯一输出方式且必须是合法 JSON。我们曾因忘了json.dumps而直接print(dict)导致 OpenClaw 解析失败日志里只显示invalid json output排查了两个小时。4.3 Paperclip 后端的增强文件上传与上下文管理server.js新增/api/upload接口const multer require(multer); const path require(path); const fs require(fs).promises; const storage multer.diskStorage({ destination: (req, file, cb) { cb(null, /tmp/paperclip_uploads); // 必须是绝对路径 }, filename: (req, file, cb) { cb(null, ${Date.now()}-${file.originalname}); } }); const upload multer({ storage }); app.post(/api/upload, upload.single(file), async (req, res) { if (!req.file) { return res.status(400).json({ error: No file uploaded }); } try { // 确保 /tmp/paperclip_uploads 存在 await fs.mkdir(/tmp/paperclip_uploads, { recursive: true }); // 返回文件的绝对路径供 OpenClaw 插件使用 res.json({ file_path: req.file.path, original_name: req.file.originalname }); } catch (error) { console.error(Upload error:, error); res.status(500).json({ error: Upload failed }); } });这个接口解决了前端文件上传的痛点浏览器 FormData 无法直接传绝对路径而 OpenClaw 插件需要绝对路径。Paperclip 后端充当了“路径翻译器”。4.4 React 前端的复杂流程编排usePaperclipAgentHook 升级为支持多阶段执行// src/hooks/usePaperclipAgent.ts export const usePaperclipAgent () { // ... 省略基础 state ... const executeWorkflow useCallback(async (file: File) { // 阶段1上传文件 const uploadRes await fetch(/api/upload, { method: POST, body: new FormData().append(file, file) }); const { file_path } await uploadRes.json(); // 阶段2执行 Agent 流程 const response await fetch(/api/agent/execute, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ prompt: 解析销售报表并生成周报, tools: [excel_read, markdown_gen, wechat_notify], context: { file_path } // 传递给所有工具的共享上下文 }) }); // ... 后续 SSE 处理同上 ... }, []); };关键点在于context字段。OpenClaw 会把这个对象合并到每个工具的input中excel_read插件就能直接拿到input_data[file_path]无需在 prompt 里写死路径。4.5 错误重试与降级的实战代码在wechat_notify.py插件里我们实现了企业微信 Webhook 的重试逻辑# plugin_name: wechat_notify # description: 发送 Markdown 消息到企业微信 # input_schema: # type: object # properties: # markdown_content: # type: string # webhook_url: # type: string import sys import json import time import requests def send_with_retry(url, payload, max_retries3): for i in range(max_retries): try: res requests.post(url, jsonpayload, timeout10) res.raise_for_status() return res.json() except Exception as e: if i max_retries - 1: raise e time.sleep(2 ** i) # 指数退避 def main(): input_data json.load(sys.stdin) webhook_url input_data[webhook_url] content input_data[markdown_content] try: payload { msgtype: markdown, markdown: { content: content } } result send_with_retry(webhook_url, payload) print(json.dumps({status: sent, message_id: result.get(msgid, )})) except Exception as e: print(json.dumps({ error: { code: WECHAT_SEND_FAILED, message: str(e), retry_count: 3 } })) if __name__ __main__: main()这个重试逻辑是 Paperclip 能在生产环境稳定运行的关键。它把网络抖动、Webhook 限流这些外部依赖的不确定性封装在了插件内部对外暴露的依然是干净的status和error。5. 常见问题与排查技巧实录那些让我们加班到凌晨三点的坑Paperclip 的搭建过程本质上是一场与各种“隐性约定”的搏斗。OpenClaw 文档没写清楚的Node.js 版本差异带来的React 18 并发渲染引发的还有那些只在特定 Linux 发行版上才出现的玄学问题。以下是我们在真实项目中记录下来的、最高频、最棘手的七个问题每个都附带了“症状-原因-解决方案-验证方法”四步排查法。5.1 问题一OpenClaw 启动后http://localhost:3001/v1/plugins返回空数组症状openclaw serve控制台显示Loaded 0 plugins/v1/plugins接口返回[]。原因config.yaml中的plugins.directory路径是相对路径或者路径权限不足OpenClaw 进程用户无法读取该目录。解决方案在config.yaml中plugins.directory必须是绝对路径且该路径下的所有.py文件必须有x执行权限Linux/macOS或在 Windows 上确保文件扩展名关联正确。运行chmod x ~/paperclip/plugins/**/*.py。验证方法在终端执行ls -l ~/paperclip/plugins/pdf/确认extract_text.py的权限列包含x然后cat ~/paperclip/config/config.yaml | grep directory确认输出是/home/username/paperclip/plugins这样的绝对路径。5.2 问题二React 前端调用/api/agent/execute时浏览器 Network 面板显示CORS error症状前端控制台报Access to fetch at http://localhost:5000/api/agent/execute from origin http://localhost:3000 has been blocked by CORS policy。原因Paperclip 后端的cors中间件配置错误。常见错误是origin: http://localhost:3000写成了origin: localhost:3000少了http://或者在生产环境部署时origin没有设置为实际的域名。解决方案在server.js中cors配置必须精确匹配前端地址。开发期用origin: http://localhost:3000生产期用origin: [https://yourcompany.com, https://admin.yourcompany.com]。绝对不要用origin: *因为 OpenClaw 的stream: true需