1. 项目概述：Paperclip 不是回形针，而是一个被严重低估的 AI 工具链协同枢纽

你搜“paperclip”时，大概率会先看到一堆办公用品图片——但最近三个月，在 Node.js 和 React 开发者社区里，“Paperclip”这个词正以异常高频出现在 GitHub Issues、Discord 技术频道和掘金的深夜面经帖里。它不是 npm 上那个早已停更的 UI 组件库，也不是某个新出的前端构建工具；它是 OpenClaw 生态中一个关键但极少被单独讨论的协议桥接层与状态同步中枢，核心作用是让 React 前端能以极低侵入性方式，实时感知并响应 OpenClaw 后端 AI Agent 的执行生命周期、中间状态、错误上下文与结构化输出流。我第一次在客户现场遇到它，是在调试一个接入 Microsoft Teams 的 OpenClaw 智能会议纪要 Agent 时——前端 React 应用始终无法及时显示“正在提取行动项”这个中间状态，直到我们翻出 Paperclip 的 config.ts 文件，把stateSyncMode从默认的debounce: 300ms改成immediate: true，整个状态流才真正“活”过来。

它的存在感之所以弱，恰恰是因为它干的是最脏最累的活：不处理模型推理，不渲染 UI，不管理路由，只做一件事——在 React 的函数组件生命周期与 OpenClaw Agent 的异步执行状态之间，建立一条低延迟、可中断、带语义标记的双向信道。这解释了为什么所有“OpenClaw 部署教程”都跳过它，而所有“React + SSE/WebSocket 轮询文件变化”的面试题，其底层解法其实就藏在 Paperclip 的useAgentStateHook 实现里。如果你正在用 React 构建 AI Agent 前端界面，或者正被“状态不同步”、“加载态卡死”、“错误信息不完整”这些问题反复折磨，那么 Paperclip 就是你漏掉的那块关键拼图。它不替代 React 或 Node.js，而是让这两者在 AI 场景下真正“说同一种话”。

2. 核心设计逻辑与架构定位：为什么必须存在 Paperclip 这个中间层

2.1 OpenClaw 与 React 的天然错配：从“命令式后端”到“声明式前端”的鸿沟

OpenClaw 本质是一个基于 Node.js 的 AI Agent 运行时框架，它的设计哲学高度贴近传统服务端逻辑：每个 Agent 是一个独立进程（或 Worker），通过agent.execute()触发，返回 Promise，内部可能包含多个 LLM 调用、工具调用、循环重试、状态暂存等复杂流程。它的状态是过程式、碎片化、非标准化的——比如一个文档分析 Agent 可能产生{"status": "parsing", "progress": 45}、{"status": "extracting_entities", "entities_found": 12}、{"status": "done", "summary": "..."}等多种结构完全不同的中间消息。而 React 的世界是声明式、快照式、统一状态驱动的：UI 渲染依赖于一个确定的state对象，任何状态变更都需通过setState触发重渲染，且期望状态结构稳定、可预测。

如果没有 Paperclip，开发者只能自己写轮询（SSE/WebSocket）+ 手动解析 JSON + 拼接状态对象 + 处理竞态条件。我见过最典型的“手写 React Agent”代码里，光是处理 Agent 中断后的状态清理，就写了 87 行带useEffect清理函数的逻辑，结果还是在并发请求下出现状态错乱。Paperclip 的核心价值，就是把这种重复、易错、高耦合的手动桥接工作，封装成一套可复用、可配置、可测试的标准协议。

2.2 Paperclip 的三层协议设计：不是简单转发，而是语义翻译

Paperclip 并非一个简单的 WebSocket 代理。它在 OpenClaw Agent 输出与 React 组件消费之间，插入了三个关键协议层：

• 传输层协议（Transport Protocol）：默认使用 WebSocket，但支持降级为 Server-Sent Events（SSE）或长轮询（Long Polling）。关键点在于它不直接暴露原始 WebSocket API，而是提供统一的createAgentClient()工厂函数，内部自动处理连接重试、心跳保活、消息序列号校验。实测在 Ubuntu 22.04 + Nginx 反向代理环境下，当网络抖动导致 WebSocket 断连时，Paperclip 会在 1.2 秒内自动切换到 SSE 模式，且前端无感知——这个能力在 OpenClaw 官方文档里根本没提，全靠 Paperclip 的 transport 层兜底。

• 状态层协议（State Protocol）：这是 Paperclip 最精髓的部分。它定义了一套最小化的状态事件规范：

  interface AgentStateEvent { id: string; // Agent 实例唯一 ID type: 'start' | 'step' | 'error' | 'complete' | 'abort'; payload: any; // 结构化数据，类型由 type 决定 timestamp: number; // 服务端生成时间戳，用于前端排序 sequence: number; // 消息序号，解决网络乱序 }

  OpenClaw Agent 的原始输出（可能是任意 JSON）会被 Paperclip 的服务端适配器（Adapter）自动映射到这套规范。例如，Agent 内部调用this.emit('progress', {current: 3, total: 10})，Paperclip Adapter 会将其转换为type: 'step', payload: {phase: 'progress', current: 3, total: 10}。前端 React 组件无需关心 Agent 内部如何 emit，只需监听标准step事件即可。

• 消费层协议（Consumption Protocol）：即useAgentStateHook。它不是简单的useState封装，而是内置了状态合并策略（merge strategy）和生命周期钩子（lifecycle hooks）。比如当收到连续两个step事件，payload 都是{phase: 'parsing'}，Paperclip 默认采用“覆盖式合并”，避免重复渲染；但如果 payload 包含数组（如entities: [...]），则自动启用“追加式合并”。更重要的是，它提供了onStart,onStep,onError,onComplete四个回调，这些回调在组件卸载时会自动取消，彻底杜绝内存泄漏——这点在 React 面试中常考的“useEffect 清理函数”问题，在 Paperclip 里是开箱即用的。

2.3 为什么不能用现有方案替代？对比 Express + Socket.IO / 自研 SSE

有人会问：既然都是 WebSocket，为啥不直接用 Express 搭个 Socket.IO 服务？或者用EventSource手写 SSE？我做过三组压测对比（100 并发 Agent 请求，单次平均耗时 8.2s）：

关键差异在于：Socket.IO 和 SSE 是传输协议，而 Paperclip 是应用协议。前者只管“消息怎么送”，后者管“消息是什么意思、该怎么用、用完怎么收”。就像快递公司只负责把包裹送到门口，而 Paperclip 还帮你拆包、分类、贴上“待签收”标签、通知你哪件是急件——这才是开发者真正需要的。

提示：Paperclip 的@openclaw/paperclip包体积仅 42KB（gzip），无外部运行时依赖，Node.js 18.20.4 LTS 及以上版本开箱即用。它不强制要求你用特定的 React 版本，甚至在 Preact 或 SolidJS 项目里也能通过createStoreAPI 接入。

3. 核心细节解析与实操要点：从零部署 Paperclip 并接入 React 前端

3.1 服务端部署：Paperclip Server 的两种启动模式

Paperclip Server 是一个轻量级 Node.js 服务，它不替代 OpenClaw，而是作为 OpenClaw 的“旁路监听器”运行。部署有两种模式，选择取决于你的 OpenClaw 部署架构：

• 嵌入模式（Embedded Mode）：适用于开发环境或单机部署。直接在 OpenClaw 项目中安装 Paperclip Server 作为依赖：

  # 在 OpenClaw 项目根目录执行 npm install @openclaw/paperclip-server

  然后修改 OpenClaw 的主入口文件（通常是src/index.ts）：

  import { startPaperclipServer } from '@openclaw/paperclip-server'; // ... OpenClaw 启动逻辑 ... // 在 OpenClaw server.listen() 之后启动 Paperclip startPaperclipServer({ port: 3001, // Paperclip 独立端口 openclawEndpoint: 'http://localhost:3000', // OpenClaw API 地址 adapter: 'default', // 使用内置适配器 }).then(server => { console.log(`Paperclip Server running on http://localhost:${server.port}`); });

  这种模式下，Paperclip 与 OpenClaw 共享同一进程，通信走本地内存，延迟最低（实测 <5ms），但不利于水平扩展。

• 独立模式（Standalone Mode）：生产环境推荐。Paperclip Server 作为独立服务运行，通过 HTTP 轮询或 Webhook 接收 OpenClaw 状态：

  # 新建 paperclip-server 目录 mkdir paperclip-server && cd paperclip-server npm init -y npm install @openclaw/paperclip-server # 创建 server.js const { startPaperclipServer } = require('@openclaw/paperclip-server'); startPaperclipServer({ port: 3001, openclawEndpoint: 'https://your-openclaw-api.com', // 生产环境地址 adapter: 'webhook', // 关键！改用 webhook 模式 webhookSecret: 'your-secret-key', // OpenClaw 需配置相同密钥 });

  启动命令：

  node server.js

  此时，你需要在 OpenClaw 的config.yaml中启用 webhook：

  agent: stateWebhook: enabled: true url: "http://paperclip-server:3001/webhook" secret: "your-secret-key" timeout: 5000

  注意：独立模式下，Paperclip Server 必须能访问 OpenClaw 的 webhook URL，且 OpenClaw 必须配置secret进行签名验证，防止伪造状态。CentOS 7.9 用户需特别注意防火墙设置：sudo firewall-cmd --permanent --add-port=3001/tcp，否则 Paperclip 服务将无法被前端访问。

3.2 前端接入：useAgentStateHook 的深度用法

Paperclip 的前端 SDK (@openclaw/paperclip-react) 提供了useAgentStateHook，但它远不止const { state, isLoading } = useAgentState(...)这么简单。以下是我在实际项目中总结的 5 种关键用法：

• 基础用法：监听单个 Agent 实例

  import { useAgentState } from '@openclaw/paperclip-react'; function DocumentAnalyzer() { const [sessionId, setSessionId] = useState<string | null>(null); // 启动 Agent const startAnalysis = async () => { const res = await fetch('/api/agents/start', { method: 'POST', body: JSON.stringify({ documentId: 'doc-123' }) }); const { id } = await res.json(); setSessionId(id); }; // 监听状态 const { state, error, isRunning } = useAgentState(sessionId, { paperclipUrl: 'http://localhost:3001', // Paperclip Server 地址 // 可选：设置超时，避免 Agent 卡死 timeout: 300000, // 5 分钟 }); return ( <div> <button onClick={startAnalysis} disabled={isRunning}> {isRunning ? '分析中...' : '开始分析'} </button> {state?.type === 'step' && state.payload.phase === 'parsing' && ( <div>正在解析文档... {state.payload.progress}%</div> )} {state?.type === 'complete' && ( <div>分析完成：{state.payload.summary}</div> )} </div> ); }

• 高级用法 1：多 Agent 状态聚合当一个页面需同时监控多个 Agent（如“上传文档”、“提取摘要”、“生成报告”三个并行任务），可使用useMultiAgentState：

  const { states, errors, isAnyRunning } = useMultiAgentState([ 'agent-upload-1', 'agent-summary-2', 'agent-report-3' ], { paperclipUrl: 'http://localhost:3001', }); // states 是一个 Map<id, AgentStateEvent>，可按需过滤 const uploadState = states.get('agent-upload-1'); const summaryState = states.get('agent-summary-2');

• 高级用法 2：自定义状态合并策略默认的“覆盖式合并”不适用于日志流场景。比如 Agent 每秒 emit 一条log消息，你希望前端 UI 显示滚动日志而非只显示最后一条：

  const { state } = useAgentState(sessionId, { paperclipUrl: 'http://localhost:3001', mergeStrategy: (prev, next) => { if (next.type === 'step' && next.payload?.log) { // 将新日志追加到旧日志数组 const logs = [...(prev?.payload?.logs || []), next.payload.log]; return { ...next, payload: { ...next.payload, logs } }; } return next; // 其他类型保持默认覆盖 } });

• 高级用法 3：错误恢复与重试控制Paperclip 内置了错误状态的自动重试机制，但你可以精细控制：

  const { state, error, retry } = useAgentState(sessionId, { paperclipUrl: 'http://localhost:3001', // 当收到 error 类型事件时，是否自动重试 autoRetry: false, // 关闭自动重试 // 自定义重试逻辑 onRetry: (err) => { console.log('用户点击重试，错误原因：', err.message); // 这里可以触发新的 Agent 启动逻辑 startNewAgent(); } });

• 高级用法 4：与 React Query 深度集成对于需要缓存 Agent 结果的场景（如“已分析过的文档摘要”），Paperclip 可与@tanstack/react-query无缝协作：

  import { useQueryClient } from '@tanstack/react-query'; function useDocumentSummary(docId: string) { const queryClient = useQueryClient(); const { state } = useAgentState( `summary-${docId}`, { paperclipUrl: 'http://localhost:3001' } ); // 当 Agent 完成时，自动更新 Query Cache useEffect(() => { if (state?.type === 'complete' && state.payload.summary) { queryClient.setQueryData(['document-summary', docId], state.payload.summary); } }, [state, queryClient, docId]); return queryClient.getQueryData(['document-summary', docId]); }

3.3 关键配置参数详解：那些文档里没写的隐藏选项

Paperclip 的配置项看似简单，但每个参数背后都有深意。以下是我在阿里云服务器免费试用实例上踩坑后总结的必调参数：

特别提醒 CentOS 7.9 用户：该系统默认 OpenSSL 版本较老，若 Paperclip Server 启动时报ERR_SSL_VERSION_OR_CIPHER_MISMATCH，需在startPaperclipServer配置中显式指定 TLS 版本：

startPaperclipServer({ // ...其他配置 httpsOptions: { minVersion: 'TLSv1.2', // 强制最低 TLS 版本 } });

4. 实操过程与核心环节实现：从本地一键部署到 Teams 集成全流程

4.1 本地一键部署：5 分钟跑通 Paperclip + OpenClaw + React 示例

这是最快速验证 Paperclip 功能的方式，适合面试准备或快速原型开发。全程无需配置服务器，全部在本地完成：

步骤 1：安装 Node.js 18.20.4 LTS

• 访问官网下载对应系统安装包（nodejs.org/dist/v18.20.4/）
• 验证安装：node -v应输出v18.20.4，npm -v应输出9.6.7

• 注意：不要用nvm安装后忘记nvm use 18.20.4，否则后续依赖可能报错

步骤 2：克隆并启动 OpenClaw 示例

git clone https://github.com/openclaw/openclaw.git cd openclaw npm install npm run dev # 启动 OpenClaw，监听 http://localhost:3000

步骤 3：启动 Paperclip Server（嵌入模式）

• 在 OpenClaw 项目根目录，创建paperclip-config.js：

  module.exports = { port: 3001, openclawEndpoint: 'http://localhost:3000', adapter: 'default', };

• 修改package.json的scripts：

  "scripts": { "dev": "concurrently \"npm run openclaw\" \"npm run paperclip\"", "openclaw": "node dist/index.js", "paperclip": "node -r ./paperclip-config.js node_modules/@openclaw/paperclip-server/bin/start.js" }

• 安装concurrently：npm install concurrently --save-dev
• 启动：npm run dev，此时 OpenClaw（3000）和 Paperclip（3001）同时运行

步骤 4：创建 React 前端（Vite + TypeScript）

npm create vite@latest my-paperclip-app -- --template react-ts cd my-paperclip-app npm install npm install @openclaw/paperclip-react

• 修改src/App.tsx，粘贴前述DocumentAnalyzer示例代码
• 启动前端：npm run dev（默认 http://localhost:5173）

验证：打开http://localhost:5173，点击“开始分析”，观察浏览器 Network 标签页，应能看到ws://localhost:3001连接建立，并收到start、step、complete等事件。至此，本地闭环验证完成。

4.2 生产环境部署：Paperclip + OpenClaw + Nginx + SSL 全流程

当项目进入上线阶段，Paperclip 的部署需考虑安全性、稳定性与可观测性。以下是我为某金融客户部署的标准化流程（Ubuntu 22.04 + Nginx）：

环境准备：

# 更新系统 sudo apt update && sudo apt upgrade -y # 安装 Node.js 18.x（官方源） curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt-get install -y nodejs # 安装 Nginx sudo apt install nginx -y sudo ufw allow 'Nginx Full'

Paperclip Server 部署：

# 创建服务目录 sudo mkdir -p /opt/paperclip-server sudo chown $USER:$USER /opt/paperclip-server # 复制 Paperclip Server 文件（假设已打包好） cp -r ./paperclip-server/* /opt/paperclip-server/ cd /opt/paperclip-server npm install --production # 创建 systemd 服务 sudo tee /etc/systemd/system/paperclip.service > /dev/null << 'EOF' [Unit] Description=Paperclip Server After=network.target [Service] Type=simple User=$USER WorkingDirectory=/opt/paperclip-server ExecStart=/usr/bin/node server.js Restart=always RestartSec=10 StandardOutput=syslog StandardError=syslog SyslogIdentifier=paperclip [Install] WantedBy=multi-user.target EOF sudo systemctl daemon-reload sudo systemctl enable paperclip sudo systemctl start paperclip

Nginx 反向代理配置（/etc/nginx/sites-available/paperclip）：

upstream paperclip_backend { server 127.0.0.1:3001; } server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; # WebSocket 支持关键配置 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; location / { proxy_pass http://paperclip_backend; proxy_buffering off; proxy_cache off; proxy_read_timeout 300; # 长连接超时 } }

启用配置：

sudo ln -sf /etc/nginx/sites-available/paperclip /etc/nginx/sites-enabled/ sudo nginx -t && sudo systemctl reload nginx

OpenClaw 配置（config.yaml）：

agent: stateWebhook: enabled: true url: "https://your-domain.com/webhook" # 注意是 HTTPS secret: "your-production-secret" timeout: 10000

前端 React 配置：在.env文件中设置：

VITE_PAPERCLIP_URL=https://your-domain.com

然后在useAgentState中直接使用import.meta.env.VITE_PAPERCLIP_URL。

4.3 OpenClaw + Microsoft Teams 集成：Paperclip 如何解决 Teams 的状态同步难题

Microsoft Teams 的 Bot Framework 对状态更新有严格限制：Bot 只能在用户发起对话后的 5 秒内发送消息，超时后必须通过“Proactive Messaging”（主动消息）机制发送，而这需要复杂的权限申请和用户 consent 流程。Paperclip 的价值在此刻凸显——它让 Teams Bot 不再需要“主动推送”，而是让 Teams 客户端（即用户浏览器中的 Teams Web App）像普通网页一样，通过 WebSocket 直接订阅 Paperclip 状态流。

集成步骤：

1. Teams App Manifest 配置：在manifest.json的validDomains中添加 Paperclip Server 域名：

   "validDomains": [ "your-domain.com", "*.ngrok.io" // 开发时用 ngrok ]

2. Teams Tab 页面注入 Paperclip SDK：在 Teams Tab 的index.html中：

   <script src="https://your-domain.com/paperclip-client.js"></script> <script> // 初始化 Paperclip Client const client = new PaperclipClient({ url: 'wss://your-domain.com', sessionId: window.teamsContext.entityId // Teams 传递的会话 ID }); client.on('state', (event) => { // 将 Paperclip 状态转换为 Teams SDK 消息 microsoftTeams.tasks.submitTask({ card: createAdaptiveCard(event), // 生成 Adaptive Card title: "AI 分析进度" }); }); </script>

3. 关键技巧：利用 Teams 的microsoftTeams.app.getContext()获取上下文：Paperclip 的sessionId必须与 Teams 的entityId或subEntityId对齐，这样才能保证状态精准推送给当前用户。我在实际项目中发现，如果直接用随机 UUID 作为sessionId，Teams 用户会收到其他人的状态更新——这是因为 Paperclip 默认按sessionId广播，而 Teams 需要按userObjectId过滤。解决方案是在 Paperclip Server 的adapter中添加用户上下文注入：

   // custom-teams-adapter.ts export class TeamsAdapter extends DefaultAdapter { async transformState(state: any, context: any): Promise<AgentStateEvent> { const teamsContext = await getTeamsContext(context.requestId); // 自定义函数获取 Teams 上下文 return { ...super.transformState(state, context), userId: teamsContext.userObjectId, // 注入用户 ID }; } }

4. Obsidian 插件联动（Bonus）：Paperclip 还支持与 Obsidian 的obsidian-plugin集成。通过paperclip://自定义协议，Obsidian 插件可直接唤起 Paperclip 状态面板。例如，在 Obsidian 笔记中写[[paperclip://session-abc123]]，点击即可打开该 Agent 的实时状态视图。这需要在 Paperclip Server 中启用customProtocol选项，并在 Obsidian 插件中注册协议处理器。

5. 常见问题与排查技巧实录：那些只有踩过坑才知道的真相

5.1 “状态不更新”问题：90% 的 case 都源于这 3 个配置点

这是 Paperclip 最高频问题。用户反馈“明明 Agent 在跑，但前端一直显示 loading”，经过排查，绝大多数情况可归因于以下三点：

• 问题 1：Paperclip Server 的openclawEndpoint配置错误

  • 现象：Paperclip 日志显示Failed to fetch OpenClaw status: 404
  • 原因：openclawEndpoint指向了 OpenClaw 的管理 API（如/health），而非 Agent 状态 API（通常是/api/agents/{id}/state）
  • 解决：确认 OpenClaw 的AGENT_STATE_ENDPOINT环境变量或配置项，Paperclip 的openclawEndpoint应指向该基础路径，例如https://openclaw-api.com/api

• 问题 2：前端paperclipUrl协议不匹配

  • 现象：浏览器控制台报Mixed Content错误，WebSocket 连接失败
  • 原因：前端页面是https://，但paperclipUrl写成了http://
  • 解决：强制使用https://或wss://。开发时可用window.location.origin动态获取：

    const paperclipUrl = window.location.origin.replace('http://', 'ws://').replace('https://', 'wss://');

• 问题 3：Nginx 未正确配置 WebSocket 头

  • 现象：连接建立成功，但无任何消息，Network 标签页显示 WebSocket 连接后立即关闭
  • 原因：Nginx 缺少proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection "upgrade";这两行
  • 解决：检查 Nginx 配置，确保location /块中包含上述两行，并重启 Nginx

5.2 “状态错乱”问题：竞态条件与消息乱序的实战解法

当用户快速连续启动多个 Agent，或在 Agent 运行中刷新页面，常出现状态错乱（如 A Agent 的complete事件显示在 B Agent 的 UI 上）。这不是 Paperclip 的 Bug，而是前端状态管理的典型陷阱。

• 根源分析：useAgentStateHook 默认按sessionId订阅，但如果多个组件使用同一个sessionId（比如都用了useState生成的临时 ID），Paperclip 会将所有消息广播给所有订阅者。

• 标准解法：为每个 Agent 实例生成唯一、稳定的sessionId，并在组件卸载时显式取消订阅：

  function AgentComponent({ docId }) { // 使用 docId + 时间戳生成稳定 ID，避免刷新后 ID 变化 const stableId = useMemo(() => `analysis-${docId}-${Date.now()}`, [docId]); const { state } = useAgentState(stableId, { paperclipUrl: '...' }); // 组件卸载时，主动调用 Paperclip 的 unsubscribe useEffect(() => { return () => { // Paperclip 提供的全局 unsubscribe 方法 window.PaperclipClient?.unsubscribe(stableId); }; }, [stableId]); return <div>{/* 渲染逻辑 */}</div>; }

• 进阶解法：服务端 Session 隔离
  在 Paperclip Server 的adapter中，根据请求头中的X-User-ID过滤消息：

  export class UserIsolatedAdapter extends DefaultAdapter { async transformState(state: any, context: any): Promise<AgentStateEvent> { const userId = context.req.headers['x-user-id']; return { ...super.transformState(state, context), userId, // 附加用户 ID }; } }

  前端订阅时指定userId：

  useAgentState(sessionId, { paperclipUrl: '...', userId: 'user-123' // 只接收该用户的消息 });

5.3 性能瓶颈排查：当 Paperclip 成为系统瓶颈时怎么办？

Paperclip 本身很轻量，但在高并发场景（如 1000+ 并发 Agent），可能出现 CPU 占用飙升、消息延迟增大。我的排查清单如下：

实操心得：在阿里云服务器免费试用实例（1C2G）上，Paperclip 最大支撑约 300 并发连接。超过此数，必须升级到 2C4G 并启用cluster模式——Paperclip Server 支持pm2集群部署，只需在ecosystem.config.js中配置：

module.exports = { apps: [{ name: 'paperclip', script: './server.js', instances: 'max', exec_mode: 'cluster', env: { PAPERCLIP_PORT: 3001 } }] };

5.4 Paperclip 与 React 版本兼容性避坑指南

Paperclip 的@openclaw/paperclip-react包对 React 版本有隐式要求，这不是文档明说的，而是从源码peerDependencies中挖出来的：

• React 18.2+：完全兼容，useAgentState使用useSyncExternalStore，性能最优
• React 17.x：