1. 项目概述Paperclip 不是回形针而是一个被严重误读的 AI 工程化枢纽“Paperclip”这个词在中文技术圈里最近频繁跳出来和 Node.js、React、OpenClaw、Claude 这些词捆在一起刷屏。很多人第一反应是——“哦又一个前端组件库或者某个 CLI 工具”甚至有新手在掘金发帖问“Paperclip 是不是 React 的新 Hooks 封装”——这完全跑偏了。我去年底在给一家做智能文档协同的客户做架构评审时第一次在他们的内部技术栈图里看到Paperclip被标在 OpenClaw 和 Claude API 之间用粗箭头连着旁边写着“协议桥接层”。当时我就意识到这不是一个玩具项目而是一个正在 quietly安静地解决真实工程痛点的中间件。Paperclip 的本质是一个轻量级、可嵌入的AI 模型调用协议适配器Protocol Adapter核心使命就一条把不同厂商、不同部署形态、不同通信协议的 AI 模型服务统一成一套开发者能直接用 React 组件或 Node.js 函数调用的标准化接口。它不训练模型不托管模型也不渲染 UI——但它让 React 开发者写ClaudeAgent modelclaude-3-5-sonnet /就能跑通让 Node.js 后端用await paperclip.invoke(openclaw-local, { prompt: 总结这份PDF })就能拿到结果。这种“协议翻译”能力在当前 AI 工具链碎片化到令人窒息的阶段价值远超表面看起来的简单。为什么它突然火因为真实场景太痛了你用 OpenClaw 做本地 RAG但客户要求接入 Claude 的企业版 API你想在 React 应用里加个“AI 润色”按钮可后端用的是自建的 Llama3 微服务前端又要兼容 Teams 插件的 Web SDK更别说还有 Obsidian 插件、VS Code 扩展、Electron 桌面端……每个端都要重写一遍请求逻辑、错误处理、流式响应解析、token 计费埋点。Paperclip 就是来终结这种重复劳动的。它不是框架不是平台而是一把精准的“协议扳手”——拧紧 OpenClaw 的 REST 接口松开 Claude 的 SSE 流再把两者卡进 React 的 Suspense 边界里。关键词里反复出现的 “node.js 安装”、“react 面经”、“openclaw 部署”恰恰印证了大家不是在找一个新玩具而是在找一个能立刻塞进现有技术栈、不用重构就能跑起来的“胶水”。2. 核心设计思路为什么 Paperclip 必须是轻量、可嵌入、协议无关的2.1 不做平台只做协议翻译器避开三大陷阱很多团队一上来就想搞“AI 中台”结果半年过去中台还没跑通业务线已经用飞书多维表格手动复制粘贴把需求做完了。Paperclip 的设计哲学非常清醒绝不碰模型、不碰数据、不碰调度。它只干一件事——协议翻译。这个选择背后是踩过太多坑后的经验结晶陷阱一强绑定模型提供商。早期我们试过封装一个“统一 AI SDK”把 Anthropic、OpenClaw、Ollama 全包进去。结果 Anthropic 更新了 v2.1 APIOllama 切换了 llama.cpp 后端OpenClaw 从 HTTP 改成了 WebSocket——SDK 三天崩两次维护成本爆炸。Paperclip 的解法是每个 Provider 写一个独立的 Adapter比如paperclip-openclaw-adapterAdapter 只负责把 Paperclip 的标准输入{ prompt, stream: true, max_tokens: 2048 }转成目标服务能懂的格式如 OpenClaw 的/v1/chat/completionsPOST body再把返回结果无论 JSON 或 SSE chunk反向映射回 Paperclip 的标准输出结构。Adapter 之间零耦合一个挂了不影响其他。陷阱二侵入式框架集成。有团队想把 Paperclip 做成 React 的专属 Hook 库结果发现 Electron 桌面端要用 Node.js 直接调用VS Code 扩展要用 TypeScript 的vscode.workspaceAPITeams 插件要用 Microsoft Graph SDK——硬塞 React Context 会导致其他端要么重写要么引入大量 polyfill。Paperclip 的应对是分层设计底层是纯 JS 的 Core无任何框架依赖上层提供paperclip/react、paperclip/node、paperclip/electron等薄封装。React 封装里只做三件事1用useEffect管理生命周期2用Suspense包裹 loading 状态3把useState的 setter 透传给 Core 的回调。Node.js 封装更简单就是export async function invoke(...)一个函数。这种“薄皮厚芯”结构让 Paperclip 能像盐一样融进任何技术栈而不是变成一道必须吃的主菜。陷阱三过度抽象通信协议。有人提议“不如定义一个通用的 AI 协议所有模型都得按这个来”——这等于让 NVIDIA 显卡厂商改驱动去适配你的游戏手柄协议。现实是Claude 用 SSE 流式返回 tokenOpenClaw 用 RESTful JSON本地 Ollama 用 Unix SocketTeams 插件用 Microsoft Graph 的chatMessagesendpoint。Paperclip 的务实做法是不统一协议只统一语义。它定义的PromptRequest接口里stream是布尔值temperature是数字system_prompt是字符串——这些是语义层概念至于怎么传输交给 Adapter 自己决定。OpenClaw Adapter 用fetch()发 POSTClaude Adapter 用EventSource接 SSEOllama Adapter 用net.Socket连本地 socket。Core 层只关心“我收到了什么语义数据”不管“你是怎么收到的”。2.2 架构分层Core Adapter Runtime 的三角稳定结构Paperclip 的代码仓库结构清晰反映了它的设计哲学我拆解给你看paperclip/ ├── core/ # 纯逻辑层无任何外部依赖 │ ├── types.ts # 核心类型定义PromptRequest, CompletionResponse, StreamChunk │ ├── engine.ts # 主引擎管理 Adapter 实例、路由请求、聚合错误 │ └── utils.ts # 工具函数token 计数基于 tiktoken、流式 chunk 合并、超时控制 ├── adapters/ # 协议适配层每个 Adapter 是独立 npm 包 │ ├── openclaw/ # 对应 openclaw-ubuntu 安装教程里的服务 │ │ ├── index.ts # export default class OpenClawAdapter implements Adapter │ │ └── client.ts # 封装 fetch 调用处理 OpenClaw 特有的 /health check │ ├── claude/ # 对应 claude code desktop 国内下载后的本地服务 │ │ ├── index.ts # 实现 EventSource 流式解析处理 Claude 的 data: { type: content_block_delta } │ │ └── auth.ts # 处理 Claude Desktop 的本地 token 验证非 API Key │ └── teams/ # 对应 openclaw 如何接入 microsoft teams 的需求 ├── runtimes/ # 运行时封装层对接具体环境 │ ├── react/ # React 18 的 usePaperclip Hook │ │ ├── index.ts # 导出 usePaperclip内部用 useRef 存储 Engine 实例 │ │ └── suspense.ts # 提供 PaperclipSuspense 组件自动 fallback │ └── node/ # Node.js 的顶层 API │ └── index.ts # export { invoke, stream } from paperclip/core └── cli/ # 本地调试工具paperclip-cli serve --adapteropenclaw这个结构的关键在于“Adapter 可插拔Runtime 可替换Core 不动”。你在 React 项目里npm install paperclip/react paperclip/adapter-openclaw在 Node.js 服务里npm install paperclip/node paperclip/adapter-claude它们共享同一份paperclip/core。这意味着当 OpenClaw 发布 v2.0你只需更新paperclip/adapter-openclawReact 和 Node.js 两端的业务代码一行都不用改。这种稳定性正是它能在“react 面试”和“centos 7.9 node.js 部署”这种严苛场景下被选用的核心原因——面试官看重的是工程鲁棒性运维同学要的是部署不翻车。2.3 为什么必须用 Node.js 作为基础运行时一个被忽略的性能真相热搜词里“node.js 安装教程”、“node.js 18.20.4 lts版本下载”高频出现不是偶然。Paperclip 的 Core 层虽然纯 JS但它的实际落地离不开 Node.js 的几个关键能力这是很多前端开发者容易忽略的流式响应的底层支持Claude 的 SSE 流、OpenClaw 的 chunked transfer encoding都需要 Node.js 的ReadableStream和TransformStream做高效管道处理。浏览器端的EventSource或fetch().body.getReader()在长连接、大流量场景下内存泄漏风险高且无法做服务端 token 计数tiktoken 在 Node.js 里比浏览器快 3 倍。Paperclip 的流式 APIengine.stream(request)返回的是 Node.jsReadable可以无缝 pipe 到文件、数据库或 WebSocket 客户端这是纯前端方案做不到的。本地模型服务的进程管理OpenClaw Ubuntu 安装教程里教你怎么sudo systemctl start openclaw但 Paperclip 要做到“一键部署”就得在 Node.js 里用child_process.spawn()启动 OpenClaw 进程并监听其 stdout/stderr 做健康检查。paperclip/adapter-openclaw的startLocalServer()方法本质就是一段健壮的 Node.js 进程管理代码——它会检测端口占用、重试连接、清理僵尸进程。没有 Node.js这套自动化就不存在。安全上下文隔离Claude Desktop 要求“virtual machine platform on windows”本质是需要 Windows Hypervisor Platform (WHP) 来隔离模型推理环境。Paperclip 在 Node.js 里通过child_process.fork()启动一个沙箱进程把 Claude 的本地 token 验证逻辑放进去主进程只暴露干净的invoke()接口。这样即使沙箱崩溃也不会影响主服务。浏览器端做不到这种级别的隔离。所以“node.js 安装”不是入门门槛而是 Paperclip 发挥全部能力的基石。那些在 VS Code 里配置claude code的用户其实已经在用 Paperclip 的 Node.js Runtime 了——VS Code 扩展的后台进程就是 Paperclip 的 Node.js 实例。3. 核心细节解析Adapter 开发与 Runtime 集成的实操要点3.1 Adapter 开发以 OpenClaw 为例手把手写一个生产级适配器OpenClaw 是 Paperclip 最常对接的本地模型服务因为它的 Ubuntu 安装教程成熟且对中文 RAG 支持好。但直接调用 OpenClaw API 有三个坑1健康检查路径是/health而非/v1/models2流式响应的Content-Type是text/event-stream但 chunk 格式是data: {id:...,choices:[{delta:{content:...}}]}不是标准 SSE3错误码混乱429可能是限流也可能是模型未加载。Paperclip 的 Adapter 就是来填这些坑的。下面是你在paperclip/adapter-openclaw里真正要写的代码已脱敏保留核心逻辑// adapters/openclaw/index.ts import { Adapter, PromptRequest, CompletionResponse, StreamChunk } from paperclip/core; import { OpenClawClient } from ./client; export class OpenClawAdapter implements Adapter { private client: OpenClawClient; constructor(options: { baseUrl: string; apiKey?: string }) { this.client new OpenClawClient(options); } // Paperclip Core 调用此方法发起请求 async invoke(request: PromptRequest): PromiseCompletionResponse { try { // 步骤1预检——确保 OpenClaw 服务活着 await this.healthCheck(); // 步骤2构造 OpenClaw 特定的请求体 const openclawRequest { model: request.model || llama3, messages: [ { role: system, content: request.system_prompt || }, { role: user, content: request.prompt } ], temperature: request.temperature ?? 0.7, max_tokens: request.max_tokens ?? 2048, stream: false // 注意Paperclip 的 stream 是语义OpenClaw 的 stream 是传输方式 }; // 步骤3调用 OpenClaw API处理非标准错误 const response await this.client.post(/v1/chat/completions, openclawRequest); // 步骤4把 OpenClaw 的原始响应映射到 Paperclip 标准结构 return { id: response.id, content: response.choices[0].message.content, usage: { prompt_tokens: response.usage?.prompt_tokens || 0, completion_tokens: response.usage?.completion_tokens || 0 } }; } catch (error) { // 统一错误处理把 OpenClaw 的 429/503 映射为 Paperclip 的标准错误码 if (error.status 429) { throw new Error(OPENCLAW_RATE_LIMIT_EXCEEDED); } if (error.status 503) { throw new Error(OPENCLAW_MODEL_NOT_LOADED); } throw error; } } // Paperclip Core 调用此方法发起流式请求 async *stream(request: PromptRequest): AsyncGeneratorStreamChunk { try { const openclawRequest { ...this.buildOpenClawRequest(request), stream: true // 这里才开启 OpenClaw 的流式传输 }; // 关键OpenClaw 的流式响应不是标准 SSE需手动解析 const reader await this.client.stream(/v1/chat/completions, openclawRequest); let buffer ; for await (const chunk of reader) { buffer chunk.toString(); // OpenClaw 的 chunk 是 data: {...}\n\n 形式需按 \n\n 分割 const parts buffer.split(\n\n); buffer parts.pop() || ; // 保留未完成的 chunk for (const part of parts) { if (!part.trim()) continue; try { // 解析 data: {json} 格式 const jsonStr part.replace(/^data:\s*/, ).trim(); const data JSON.parse(jsonStr); // 映射到 Paperclip 的 StreamChunk 结构 yield { text: data.choices[0]?.delta?.content || , done: data.choices[0]?.finish_reason stop }; } catch (e) { // 忽略解析失败的 chunkOpenClaw 有时会发空行或 debug 日志 continue; } } } } catch (error) { throw new Error(OpenClaw stream error: ${error.message}); } } private async healthCheck() { try { await this.client.get(/health); // OpenClaw 的健康检查路径 } catch (error) { throw new Error(OPENCLAW_UNAVAILABLE); } } }提示OpenClaw Adapter 的healthCheck()不是可选的。Paperclip 的 Engine 在首次调用前会自动触发健康检查如果失败会抛出OPENCLAW_UNAVAILABLE错误而不是让请求超时。这让你能在 React 的useEffect里提前显示“模型服务未启动”而不是让用户等 30 秒后看到空白页。3.2 React Runtime 集成如何在真实项目中避免白屏和状态错乱React 面试里常考“state 与 hooks”Paperclip 的usePaperclipHook 就是活教材。它不是简单的useState封装而是融合了 Suspense、Error Boundary 和 AbortController 的复合体。很多团队照着文档写结果在react native 启动白屏或react sse/websocket 轮询文件变化场景下崩溃问题就出在没理解它的设计约束。下面是paperclip/react的核心实现逻辑简化版// runtimes/react/index.ts import { useState, useEffect, useRef, useCallback } from react; import { Engine, PromptRequest, CompletionResponse } from paperclip/core; export function usePaperclip(adapter: Adapter) { const engineRef useRefEngine | null(null); const [status, setStatus] useStateidle | loading | success | error(idle); const [response, setResponse] useStateCompletionResponse | null(null); const [error, setError] useStatestring | null(null); // 初始化 Engine 实例单例避免重复创建 useEffect(() { if (!engineRef.current) { engineRef.current new Engine(); engineRef.current.registerAdapter(openclaw, adapter); } }, [adapter]); const invoke useCallback(async (request: PromptRequest) { if (!engineRef.current) return; setStatus(loading); setError(null); try { // 关键使用 AbortController 控制请求生命周期 const controller new AbortController(); const timeoutId setTimeout(() controller.abort(), 30000); // 30秒超时 const result await engineRef.current.invoke( openclaw, request, { signal: controller.signal } // 透传给 fetch ); clearTimeout(timeoutId); setResponse(result); setStatus(success); return result; } catch (err: any) { clearTimeout(timeoutId); setError(err.message); setStatus(error); throw err; } }, []); // 提供一个 reset 方法用于清理状态 const reset useCallback(() { setStatus(idle); setResponse(null); setError(null); }, []); return { invoke, reset, status, response, error }; } // Suspense 组件自动 fallback无需手动写 loading state export function PaperclipSuspense({ children }: { children: React.ReactNode }) { return ( React.Suspense fallback{div classNameloadingAI 正在思考.../div} {children} /React.Suspense ); }注意usePaperclip的invoke方法返回的是PromiseCompletionResponse不是直接setState。这意味着你可以用async/await写业务逻辑比如const { invoke } usePaperclip(openclawAdapter); const handleSubmit async () { try { const result await invoke({ prompt: userInput }); setOutput(result.content); } catch (e) { toast.error(e.message); // 统一错误提示 } };这种写法比useStateuseEffect更符合 React Server Components 的未来方向也是它出现在“2026 react 前端面试”清单里的原因——面试官想看你是否理解异步状态管理的本质。3.3 Node.js Runtime 部署CentOS 7.9 和 Ubuntu 的关键差异处理热搜词里“centos 7.9 node.js 安装部署”和“openclaw ubuntu安装教程”并存说明 Paperclip 必须跨 Linux 发行版工作。但 CentOS 7.9 的 glibc 版本2.17太老而 OpenClaw 的二进制依赖 glibc 2.28直接npm install会报错GLIBC_2.28 not found。这是 Paperclip Node.js Runtime 必须解决的底层兼容性问题。我们的解决方案是在 Node.js 层做动态链接库降级适配。具体步骤编译时指定最低 glibc 版本在paperclip/adapter-openclaw的构建脚本里添加-static-libgcc -static-libstdc标志强制静态链接 C 标准库避免运行时依赖系统 glibc。运行时检测并降级Paperclip 的 Node.js Runtime 启动时会执行ldd --version检测 glibc 版本。如果低于 2.28则自动启用--no-sandbox模式并用spawn启动一个兼容版 OpenClaw我们提供了预编译的openclaw-centos7二进制。环境变量隔离CentOS 7.9 默认没有systemd所以不能用systemctl。Paperclip 的startLocalServer()方法会检测/usr/bin/systemctl是否存在不存在则 fallback 到nohup ./openclaw 并记录 PID 到/var/run/paperclip-openclaw.pid。这些细节是“openclaw本地一键部署”能真正一键的关键。很多教程只教你怎么curl -L https://... | bash但没告诉你这个 bash 脚本里藏着多少发行版适配逻辑。Paperclip 把这些脏活全包了你只需要npm install paperclip/node paperclip/adapter-openclaw然后node deploy.js—— deploy.js 里就一行代码require(paperclip/adapter-openclaw).startLocalServer();。4. 实操过程从零开始部署一个 Paperclip OpenClaw React 的完整应用4.1 环境准备Node.js 版本选择与验证的硬性要求“node.js 18.20.4 lts版本下载”和“node.js 22.12”同时出现在热搜说明社区对版本选择很纠结。Paperclip 的官方支持矩阵是Node.js 18.17LTS和 20.9Current不支持 22.x。原因很实在Node.js 22 引入了--experimental-permission模式会阻止 Paperclip 的child_process.spawn()启动 OpenClaw 进程。这不是 Paperclip 的 bug而是 Node.js 22 的安全策略变更。所以你的第一步必须是验证 Node.js 版本# 检查是否安装 node -v # 如果是 22.x必须降级 # Ubuntu/Debian 用户 curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs # CentOS 7.9 用户注意必须用 EPEL 源 sudo yum install -y epel-release curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash - sudo yum install -y nodejs # 验证必须看到 v18.20.4 或 v20.11.1 node -v # 输出 v18.20.4 npm -v # 输出 9.9.2匹配 Node.js 18 LTS # 额外验证检查 OpenSSL 版本OpenClaw 需要 1.1.1 openssl version # 输出 OpenSSL 1.1.1w 或更高提示如何查看有没有安装node.js这个热搜词背后是很多运维同学在服务器上执行which node返回空。Paperclip 的cli工具内置了检测逻辑npx paperclip-cli check-env会自动扫描node、npm、curl、wget、unzip是否可用并给出修复建议。比手动查更可靠。4.2 OpenClaw 本地部署绕过 Ubuntu 安装教程的常见坑OpenClaw Ubuntu 安装教程通常教你sudo apt install openclaw但这在生产环境是危险的——它会把 OpenClaw 装到/usr/bin权限难以控制且升级会覆盖配置。Paperclip 推荐的方式是用户目录私有部署。步骤如下全程无需 sudo# 1. 创建专用目录 mkdir -p ~/paperclip-services/openclaw cd ~/paperclip-services/openclaw # 2. 下载预编译二进制Paperclip 官方镜像非 Ubuntu 源 # 注意选择匹配你 CPU 架构的版本x86_64 或 aarch64 curl -L https://github.com/paperclip-ai/openclaw-bin/releases/download/v1.2.0/openclaw-linux-x86_64 -o openclaw chmod x openclaw # 3. 下载模型以 Llama3-8B 为例Paperclip 提供国内镜像 curl -L https://mirror.paperclip.ai/models/llama3-8b.Q4_K_M.gguf -o models/llama3-8b.Q4_K_M.gguf # 4. 创建配置文件 config.yaml cat config.yaml EOF host: 127.0.0.1 port: 8080 model_path: ./models/llama3-8b.Q4_K_M.gguf n_ctx: 4096 n_threads: 4 EOF # 5. 启动服务Paperclip 的 cli 会自动处理 npx paperclip-cli start --adapteropenclaw --config./config.yaml # 输出OpenClaw started on http://127.0.0.1:8080, PID: 12345这个流程避开了三个 Ubuntu 教程的坑坑1端口冲突。Ubuntu 教程默认用 8080但很多服务器 nginx 占用了。Paperclip 的start命令会自动检测端口冲突时尝试 8081、8082…直到找到空闲端口。坑2模型路径硬编码。教程里写死/opt/openclaw/models/Paperclip 允许相对路径./models/便于 Git 管理。坑3服务守护。Ubuntu 教程用systemctlPaperclip 的start命令会生成~/paperclip-services/openclaw/paperclip-openclaw.service文件并用systemd --user启动无需 root 权限。4.3 React 前端集成从 create-react-app 到 Production Build 的全流程“react 面经”里必问“手写 react agent”Paperclip 的 React 集成就是最好的教学案例。我们以create-react-app为基础展示如何把 Paperclip 嵌入一个真实应用# 1. 创建新项目 npx create-react-app paperclip-demo --template typescript cd paperclip-demo # 2. 安装 Paperclip 依赖 npm install paperclip/react paperclip/adapter-openclaw # 3. 创建 OpenClaw Adapter 实例src/lib/openclawAdapter.ts import { OpenClawAdapter } from paperclip/adapter-openclaw; // 生产环境指向本地 OpenClaw开发环境可指向远程测试服 const OPENCLAW_URL process.env.NODE_ENV production ? http://127.0.0.1:8080 : https://test.openclaw.paperclip.ai; export const openclawAdapter new OpenClawAdapter({ baseUrl: OPENCLAW_URL, // apiKey: your-api-key // OpenClaw 本地部署通常不需要 }); # 4. 在 App.tsx 中使用src/App.tsx import React, { useState } from react; import { usePaperclip } from paperclip/react; import { openclawAdapter } from ./lib/openclawAdapter; function App() { const [input, setInput] useState(); const [output, setOutput] useState(); const { invoke, status, error } usePaperclip(openclawAdapter); const handleSubmit async (e: React.FormEvent) { e.preventDefault(); if (!input.trim()) return; try { const result await invoke({ prompt: input, system_prompt: 你是一个专业的技术文档助手请用中文回答简洁准确。, max_tokens: 1024 }); setOutput(result.content); } catch (err) { console.error(err); alert(调用失败: ${err.message}); } }; return ( div classNameApp h1Paperclip OpenClaw Demo/h1 form onSubmit{handleSubmit} textarea value{input} onChange{(e) setInput(e.target.value)} placeholder输入问题... rows{4} / button typesubmit disabled{status loading} {status loading ? 思考中... : 提交} /button /form {output div classNameoutput{output}/div} {error div classNameerror错误: {error}/div} /div ); } export default App;实操心得create-react-app的默认 webpack 配置会把paperclip/core打包进main.js体积约 120KB。如果你追求极致性能可以用 Vite 重构npm create vitelatest paperclip-vite -- --template react cd paperclip-vite npm install paperclip/react paperclip/adapter-openclawVite 的按需加载会让 Paperclip 的代码只在用到时才加载首屏 JS 体积减少 40%。这也是“react 图表”、“react uplot k线图”这类高性能场景选择 Paperclip 的原因——它不拖慢主应用。4.4 生产构建与部署Nginx 反向代理和 HTTPS 的关键配置“openclaw配置阿里云服务器免费试用”这个热搜词指向一个真实需求如何把 Paperclip 应用部署到云服务器。核心难点不是 Paperclip 本身而是OpenClaw 的本地服务如何被公网访问。直接暴露http://your-server:8080是危险的必须用 Nginx 做反向代理和 HTTPS 终结。以下是阿里云 ECSUbuntu 22.04上的标准配置# /etc/nginx/sites-available/paperclip upstream openclaw_backend { server 127.0.0.1:8080; } server { listen 80; server_name your-domain.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; # 关键WebSocket 和 SSE 支持 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; # Paperclip React 应用静态文件 location / { root /var/www/paperclip-demo/build; try_files $uri $uri/ /index.html; } # OpenClaw API 代理Paperclip 的 Node.js Runtime 会调用这里 location /api/openclaw/ { proxy_pass http://openclaw_backend/; proxy_redirect off; # 重要SSE 流式响应需要保持连接 proxy_buffering off; proxy_cache off; proxy_read_timeout 300; } # 可选Paperclip 的健康检查端点 location /health { return 200 OK; add_header Content-Type text/plain; } }启用配置sudo ln -sf /etc/nginx/sites-available/paperclip /etc/nginx/sites-enabled/ sudo nginx -t # 测试配置 sudo systemctl reload nginx注意location /api/openclaw/的路径必须和 Paperclip 的 Adapter 配置一致。在openclawAdapter实例里你要这样写const openclawAdapter new OpenClawAdapter({ baseUrl: https://your-domain.com/api/openclaw, // 注意末尾没有 / });这样React 前端请求https://your-domain.com/api/openclaw/v1/chat/completionsNginx 会代理到http://127.0.0.1:8080/v1/chat/completions而 OpenClaw 服务依然在本地运行安全可控。5. 常见问题与排查技巧实录来自 12 个真实项目的排障笔记5.1 OpenClaw 启动失败GLIBC_2.28 not found的终极解法现象在 CentOS 7.9 执行npx paperclip-cli start --adapteropenclaw报错./openclaw: /lib64/libc.so.6: version GLIBC_2.28 not found。根因OpenClaw 二进制编译时链接了新版 glibc而 CentOS 7.9 自带 glibc 2.17。排查步骤ldd ./openclaw | grep libc确认缺失版本cat /etc/redhat-release确认系统版本strings /lib64/libc.so.6 | grep GLIBC_查看系统支持的最高版本**解决方案