Paperclip模式：Node.js+React+OpenClaw构建轻量AI Agent

发布时间：2026/11/2 9:50:56
Paperclip模式：Node.js+React+OpenClaw构建轻量AI Agent

1. 项目概述：Paperclip 不是回形针，而是一个被严重误读的 AI 工具链命名陷阱

“Paperclip”这个词一出来，绝大多数人第一反应是办公桌抽屉里那个银色金属弯钩——回形针。但在这个技术语境下，它根本不是物理物件，而是一个在开发者社区里悄然流传、却始终没有官方文档背书的项目代号级命名惯性。它不指向某个开源仓库，不对应 npm 上的包名，也不在任何主流框架官网首页出现。它真实存在的形态，是散落在 GitHub Issues、Discord 频道碎片化讨论、以及国内技术论坛“掘金”“V2EX”中的一类特定实践模式：用 Node.js 搭建轻量服务层，以 React 构建前端交互界面，再通过 OpenClaw 接入大模型能力，最终形成一个可本地运行、面向具体任务（比如会议纪要生成、文档摘要、知识库问答）的闭环 AI Agent 小工具。我第一次见到这个词，是在一个凌晨三点的 Slack 群聊里，有人贴出一段 37 行的 Express 路由代码，标题就写着 “paperclip v0.2 —— 今天终于让 OpenClaw 在 WSL2 里吐出第一句中文”。那一刻我就意识到，这不是一个产品，而是一群人在用最原始的方式，把 AI 能力“别”进日常工作的缝隙里。

这个命名之所以顽固存在，恰恰因为它精准击中了当前 AI 工具落地的痛点：极简、可嵌入、不喧宾夺主。就像回形针本身不生产内容，只负责把几页纸临时固定在一起，Paperclip 模式的核心价值，就是提供一个最小可行的“AI 能力粘合剂”。它不追求替代整个企业系统，而是解决“我现在手头这份 PDF 报告，怎么在 5 分钟内变成 PPT 大纲”的具体问题。因此，它的技术栈组合（Node.js + React + OpenClaw）并非偶然：Node.js 提供低开销、高并发的 API 网关能力，React 提供快速响应的 UI 反馈环，而 OpenClaw 则是那个能真正理解用户意图、调用模型、处理上下文的“智能引擎”。你不需要成为全栈专家，但必须清楚每个环节的边界在哪里——Node.js 负责“接住请求”，React 负责“告诉用户发生了什么”，OpenClaw 负责“想明白该做什么”。这种分工，决定了 Paperclip 项目的成败，90% 取决于三者之间数据流的平滑度，而非单点技术的炫技。

2. 内容整体设计与思路拆解：为什么是 Node.js + React + OpenClaw 这个铁三角？

2.1 Node.js 的不可替代性：不只是“会写 JS 就能上”，而是“必须用它”

很多人看到热词里反复出现 “node.js 安装教程”“centos 7.9 node.js 安装部署”，下意识觉得这只是入门门槛。错了。Node.js 在 Paperclip 架构里承担的是唯一可信的数据中转站和安全守门员角色，它的存在，直接决定了整个系统的鲁棒性和可维护性。我见过太多直接让 React 前端调用 OpenClaw API 的“快捷方案”，结果在真实环境中崩得惨不忍睹：跨域问题、CORS 配置混乱、API Key 泄露风险、模型调用失败时的错误堆栈无法捕获、甚至因为前端直接暴露了 OpenClaw 的 endpoint，导致被恶意爬虫批量刷空配额。Node.js 的核心价值，在于它天然具备的“中间层”属性——它能把所有敏感操作（如密钥管理、请求重试、流式响应解析、错误降级）全部收束在一个可控的、可审计的服务进程里。

举个具体例子：OpenClaw 的/v1/chat/completions接口返回的是标准的 SSE（Server-Sent Events）流，但 React 的fetchAPI 对 SSE 的原生支持极其有限，需要手动解析event: message和data:字段，且一旦网络抖动，整个流就会中断，前端无法感知是模型卡住了还是连接断了。而 Node.js 的express+stream模块可以轻松实现：监听 OpenClaw 的 SSE 流，将其转换为一个稳定的、带心跳保活的 HTTP 流，再推送给前端。这个转换过程，Node.js 还能做三件事：第一，在流开始前校验用户上传的文件是否符合预设格式（比如只允许.pdf和.docx）；第二，在流传输中实时计算 token 使用量，并在达到阈值时主动终止请求；第三，当 OpenClaw 返回429 Too Many Requests时，Node.js 可以自动启用指数退避重试，而前端完全无感。这些能力，是任何纯前端方案都无法复制的。所以，“安装 Node.js”不是第一步，而是整个架构的基石。我建议直接使用 Node.js 20.x LTS 版本（非 22.x），因为 OpenClaw 的某些底层依赖（如@openclaw/core）对 V8 引擎的 GC 行为有特定要求，22.x 在 WSL2 下偶发内存泄漏，这是我在三个不同客户环境里踩过的坑。

2.2 React 的定位：不是“构建应用”，而是“构建反馈界面”

热词里高频出现 “react 面经”“2026 react 前端面试 掘金”“react state与hooks”，这透露出一个关键信号：很多尝试 Paperclip 的人，是带着“做一个完整 React 应用”的思维入场的。这恰恰是最大的误区。Paperclip 中的 React，其使命只有一个：在用户点击“生成摘要”按钮后的 200 毫秒内，给出明确的视觉反馈；并在模型思考的 3-8 秒内，用流畅的骨架屏和进度条，管理用户的预期。它不需要 Redux，不需要复杂的路由系统，甚至不需要create-react-app。我实测下来最稳的方案，是直接用 Vite 创建一个极简项目，只保留App.jsx和main.jsx两个文件，所有状态管理都用useState和useEffect完成。

为什么？因为 Paperclip 的业务逻辑几乎全部下沉到了 Node.js 层。React 前端本质上就是一个“智能表单 + 流式响应渲染器”。它的核心组件只有三个：一个文件上传区（支持拖拽）、一个带onSubmit的表单（提交后禁用按钮并显示 loading）、一个div容器（用于逐行追加 OpenClaw 返回的文本流）。useState用来管理isProcessing、currentText、error这三个状态就够了。useEffect的唯一作用，就是在isProcessing变为true时，建立到 Node.js 后端/api/generate的 SSE 连接，并在组件卸载时正确关闭。那些关于useReducer、Context API的面试题，在 Paperclip 场景里毫无意义。我甚至建议新手删掉App.css，用 Tailwind CSS 的 utility class 直接写样式，因为 Paperclip 的 UI 天然就是极简的——一个输入区，一个输出区，一个操作按钮。过度设计 UI，只会分散你对数据流调试的注意力。

2.3 OpenClaw 的真实角色：不是“另一个 LLM SDK”，而是“本地化 AI 协议桥”

热词里反复出现 “openclaw 无法安全验证”“openclaw 部署”“openclaw ubuntu 安装教程”，说明 OpenClaw 是整个链条里最不透明、最容易出问题的一环。但必须澄清：OpenClaw 本身不是一个大模型，它更像一个协议翻译器和模型调度器。它的核心价值，是把各种异构的大模型后端（Qwen2.5-3B、Llama3-8B、甚至本地 Ollama 实例）统一抽象成一套标准化的 RESTful API 和 SSE 流接口。你可以把它理解为 AI 世界的 “HTTP/1.1” —— 不管后端是 Apache 还是 Nginx，只要遵循这个协议，前端就能通信。

因此，“部署 OpenClaw” 的本质，不是安装一个软件，而是配置一个模型网关。它需要你明确回答三个问题：第一，我的模型运行在哪？是本地 CPU（用 Ollama）、本地 GPU（用 vLLM）、还是云服务（阿里云百炼、Azure OpenAI）？第二，这个模型的原始 API 是什么格式？是 OpenAI 兼容的/chat/completions，还是 Anthropic 的/messages，或是 HuggingFace 的/generate？第三，我需要哪些中间件能力？比如，是否需要内置 RAG（检索增强生成）？是否需要函数调用（Function Calling）？是否需要多轮对话上下文管理？OpenClaw 的配置文件config.yaml就是围绕这三个问题展开的。我见过太多人卡在 “openclaw 无法安全验证” 上，根源在于他们试图用http://localhost:3000（React 开发服务器）去直接调用 OpenClaw，而 OpenClaw 默认只信任http://localhost:8000（Node.js 服务）的请求。解决方案不是改 OpenClaw 的证书，而是让 Node.js 作为代理，把前端请求转发过去。这才是 Paperclip 模式真正的设计哲学：用一层薄薄的、可控的胶水代码，把不可控的、复杂的 AI 基础设施，封装成一个简单的、可预测的接口。

3. 核心细节解析与实操要点：从零搭建一个可运行的 Paperclip 实例

3.1 环境准备：WSL2 是 Windows 用户的唯一理性选择

热词里反复出现 “sl2环境。请在powershell中运行wsl-- status”，这绝非偶然。对于 Windows 用户，放弃原生 CMD 或 PowerShell 直接安装 Node.js 和 OpenClaw，是通向崩溃的第一步。原因很简单：OpenClaw 的核心依赖@openclaw/core是用 Rust 编写的，其编译产物对 Windows 的 DLL 加载机制和路径分隔符（\vs/）有严格要求。我在一台 Windows 11 专业版机器上，用 Chocolatey 安装的 Node.js 20.x，配合直接下载的 OpenClaw Windows 二进制包，运行openclaw serve时，90% 的概率会报错Error: failed to load model: invalid path format。而同样的操作，在 WSL2 的 Ubuntu 22.04 环境下，一次成功。

所以，第一步必须是确认 WSL2 状态。在 PowerShell（以管理员身份运行）中执行：

wsl --status

如果返回The operation completed successfully.，说明 WSL2 已启用。如果没有，执行：

wsl --install

然后重启电脑。接着，在 Windows Terminal 中打开 Ubuntu，执行：

sudo apt update && sudo apt upgrade -y sudo apt install curl gnupg lsb-release -y curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs

这一步安装的是 Node.js 20.x LTS。注意，不要用nvm，因为 Paperclip 项目需要全局可用的node和npm命令，nvm的 shell 初始化在 WSL2 的 systemd 服务中不可靠。安装完成后，验证：

node -v # 应输出 v20.x.x npm -v # 应输出 10.x.x

3.2 OpenClaw 部署：配置比安装更重要

OpenClaw 的安装本身很简单，但配置是灵魂。首先，下载最新版（截至 2024 年 10 月，推荐v0.8.2）：

wget https://github.com/openclaw/openclaw/releases/download/v0.8.2/openclaw_0.8.2_linux_amd64.tar.gz tar -xzf openclaw_0.8.2_linux_amd64.tar.gz sudo mv openclaw /usr/local/bin/

然后，创建配置目录和文件：

mkdir -p ~/.openclaw/config nano ~/.openclaw/config/config.yaml

一个最小可用的config.yaml如下：

# ~/.openclaw/config/config.yaml server: host: "0.0.0.0" port: 8000 cors: allowed_origins: - "http://localhost:5173" # Vite 开发服务器地址 - "http://localhost:3000" # 如果用 create-react-app allow_credentials: true models: - id: "qwen2.5-3b" name: "Qwen2.5-3B-Instruct" backend: "ollama" endpoint: "http://localhost:11434" model: "qwen2.5:3b" parameters: temperature: 0.3 max_tokens: 2048

这里的关键点在于cors.allowed_origins。它必须精确匹配你的 React 开发服务器地址。如果你用 Vite，默认是http://localhost:5173；如果用 CRA，则是http://localhost:3000。漏掉这个，前端就会遇到经典的CORS error，而错误信息里不会告诉你缺了哪个 origin。另外，backend: "ollama"表示我们使用本地 Ollama 作为模型后端。你需要提前在 WSL2 中安装 Ollama：

curl -fsSL https://ollama.com/install.sh | sh ollama run qwen2.5:3b # 这会下载并启动 Qwen2.5-3B 模型

提示：Ollama 模型下载很慢，建议在国内镜像源加速。编辑~/.ollama/config.json，添加"OLLAMA_HOST": "http://127.0.0.1:11434"和"OLLAMA_ORIGINS": ["*"]，然后重启 Ollama：systemctl --user restart ollama。

3.3 Node.js 服务层：37 行代码的威力

现在，创建一个名为paperclip-server的目录，初始化 Node.js 项目：

mkdir paperclip-server && cd paperclip-server npm init -y npm install express cors body-parser stream

创建index.js：

// paperclip-server/index.js const express = require('express'); const cors = require('cors'); const bodyParser = require('body-parser'); const { Readable } = require('stream'); const app = express(); const PORT = 3000; app.use(cors({ origin: 'http://localhost:5173', // 必须与前端地址一致 credentials: true })); app.use(bodyParser.json()); app.use(bodyParser.urlencoded({ extended: true })); // 模拟一个简单的文件处理逻辑（实际中会调用 pdf-parse 等库） function extractTextFromPDF(buffer) { return `这是从 PDF 中提取的模拟文本。包含一些技术术语：Node.js, React, OpenClaw, AI agents。`; } // 核心 API：接收文件，调用 OpenClaw 生成摘要 app.post('/api/generate', async (req, res) => { try { const { fileContent, fileName } = req.body; if (!fileContent || !fileName) { return res.status(400).json({ error: 'Missing fileContent or fileName' }); } // 1. 提取文本（此处为简化，实际需用 pdf-parse 或 mammoth） const extractedText = extractTextFromPDF(fileContent); // 2. 构造 OpenClaw 请求 const openclawUrl = 'http://localhost:8000/v1/chat/completions'; const payload = { model: 'qwen2.5-3b', messages: [ { role: 'system', content: '你是一个专业的文档摘要助手。请用中文，生成一份不超过 200 字的、结构清晰的摘要。' }, { role: 'user', content: `请基于以下文本生成摘要：\n\n${extractedText}` } ], stream: true }; // 3. 发起流式请求 const response = await fetch(openclawUrl, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }); if (!response.ok) { throw new Error(`OpenClaw error: ${response.status} ${response.statusText}`); } // 4. 将 OpenClaw 的 SSE 流，转换为 Node.js 的 Readable Stream const readableStream = new Readable({ read() {} }); // 5. 设置响应头，启用流式传输 res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive' }); // 6. 监听 OpenClaw 的响应流，并转发给前端 const reader = response.body.getReader(); const decoder = new TextDecoder(); (async function pump() { try { const { done, value } = await reader.read(); if (done) { res.end(); return; } const chunk = decoder.decode(value); // 解析 SSE 格式：event: message\ndata: {"id":"...","object":"..."}\n\n const lines = chunk.split('\n'); for (const line of lines) { if (line.startsWith('data: ')) { const data = line.slice(6); if (data.trim() !== '' && data.trim() !== '[DONE]') { try { const json = JSON.parse(data); if (json.choices && json.choices[0].delta?.content) { const content = json.choices[0].delta.content; res.write(`data: ${JSON.stringify({ content })}\n\n`); } } catch (e) { console.error('Parse SSE data error:', e); } } } } pump(); } catch (err) { console.error('Stream pump error:', err); res.write(`data: ${JSON.stringify({ error: err.message })}\n\n`); res.end(); } })(); } catch (error) { console.error('API error:', error); res.status(500).json({ error: error.message }); } }); app.listen(PORT, () => { console.log(`Paperclip server running on http://localhost:${PORT}`); });

这段代码的核心在于第 4 步到第 6 步：它没有简单地res.json()返回一个最终结果，而是将 OpenClaw 的 SSE 流，经过解析、过滤、再封装，变成一个标准的、前端可消费的 SSE 流。这保证了用户在浏览器里能看到文字“一个字一个字”地浮现出来，体验远胜于等待 5 秒后一次性弹出整个摘要。

3.4 React 前端：用 50 行 JSX 完成全部交互

在 WSL2 外的 Windows 系统中，用 VS Code 打开一个新终端，执行：

npm create vite@latest paperclip-client -- --template react cd paperclip-client npm install npm run dev

然后，修改src/App.jsx：

import { useState, useEffect, useRef } from 'react'; function App() { const [isProcessing, setIsProcessing] = useState(false); const [currentText, setCurrentText] = useState(''); const [error, setError] = useState(''); const eventSourceRef = useRef(null); const handleSubmit = async (e) => { e.preventDefault(); setIsProcessing(true); setError(''); setCurrentText(''); // 模拟文件内容（实际中会用 FileReader 读取） const mockFileContent = '这是从 PDF 中提取的模拟文本。包含一些技术术语：Node.js, React, OpenClaw, AI agents。'; try { const response = await fetch('http://localhost:3000/api/generate', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ fileContent: mockFileContent, fileName: 'report.pdf' }) }); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } // 建立 SSE 连接 const eventSource = new EventSource('http://localhost:3000/api/generate'); eventSourceRef.current = eventSource; eventSource.onmessage = (event) => { try { const data = JSON.parse(event.data); if (data.content) { setCurrentText(prev => prev + data.content); } else if (data.error) { setError(data.error); eventSource.close(); } } catch (e) { console.error('Parse event data error:', e); } }; eventSource.onerror = (err) => { console.error('EventSource error:', err); setError('连接失败，请检查服务是否运行。'); eventSource.close(); }; } catch (err) { console.error('Fetch error:', err); setError(err.message); setIsProcessing(false); } }; // 组件卸载时关闭连接 useEffect(() => { return () => { if (eventSourceRef.current) { eventSourceRef.current.close(); } }; }, []); return ( <div className="min-h-screen bg-gray-50 p-4"> <div className="max-w-4xl mx-auto"> <h1 className="text-2xl font-bold text-gray-800 mb-6">Paperclip 文档摘要器</h1> <form onSubmit={handleSubmit} className="mb-6"> <button type="submit" disabled={isProcessing} className={`px-6 py-3 rounded-lg font-medium text-white ${ isProcessing ? 'bg-blue-400 cursor-not-allowed' : 'bg-blue-600 hover:bg-blue-700' }`} > {isProcessing ? '正在生成...' : '生成摘要'} </button> </form> {error && ( <div className="mb-4 p-3 bg-red-100 text-red-700 rounded border border-red-300"> 错误：{error} </div> )} <div className="bg-white rounded-lg shadow p-4 min-h-[200px]"> <h2 className="font-medium text-gray-700 mb-2">摘要结果：</h2> {isProcessing ? ( <div className="space-y-2"> <div className="h-4 bg-gray-200 rounded animate-pulse"></div> <div className="h-4 bg-gray-200 rounded animate-pulse w-5/6"></div> <div className="h-4 bg-gray-200 rounded animate-pulse w-4/6"></div> </div> ) : currentText ? ( <p className="whitespace-pre-wrap text-gray-800">{currentText}</p> ) : ( <p className="text-gray-500 italic">摘要将在此处实时显示...</p> )} </div> </div> </div> ); } export default App;

这段 JSX 的精妙之处在于useEffect的清理函数：它确保了即使用户在生成过程中切换页面或刷新浏览器，SSE 连接也会被优雅关闭，避免后端资源泄露。同时，骨架屏（animate-pulse）的使用，完美管理了用户在 3-8 秒等待期内的心理预期。

4. 实操过程与核心环节实现：一次完整的端到端流程复现

4.1 启动顺序与端口映射：WSL2 的网络穿透是关键

在 WSL2 环境中，服务的启动顺序和端口暴露是 Paperclip 能否跑通的决定性因素。必须严格遵循以下顺序：

  1. 先启动 Ollama：在 WSL2 的 Ubuntu 终端中执行ollama serve。默认监听http://localhost:11434。
  2. 再启动 OpenClaw：在同一终端（或新终端）中执行openclaw serve --config ~/.openclaw/config/config.yaml。它会读取配置，连接到http://localhost:11434，并启动自己的服务，监听http://localhost:8000。
  3. 最后启动 Node.js 服务：在paperclip-server目录下执行node index.js，监听http://localhost:3000。
  4. 最后启动 React 前端：在 Windows 的 VS Code 终端中执行npm run dev，启动 Vite 服务，监听http://localhost:5173。

这里有一个隐藏的巨坑：WSL2 的localhost对 Windows 主机来说，并不是同一个网络地址。Windows 上的浏览器访问http://localhost:5173是没问题的，但当 React 前端里的 JavaScript 代码尝试fetch('http://localhost:3000/api/generate')时，这个localhost指的是Windows 主机的 localhost，而不是 WSL2 的 localhost。因此，Node.js 服务必须绑定到0.0.0.0:3000，并且 Windows 防火墙必须放行该端口。

在paperclip-server/index.js中，修改app.listen(PORT, ...)为：

app.listen(PORT, '0.0.0.0', () => { console.log(`Paperclip server running on http://localhost:${PORT}`); });

然后，在 Windows 的 PowerShell（管理员）中执行：

New-NetFirewallRule -DisplayName "Allow Paperclip Server" -Direction Inbound -Protocol TCP -LocalPort 3000 -Action Allow

这样，Windows 浏览器里的fetch('http://localhost:3000/...')才能真正穿透到 WSL2 里的 Node.js 进程。

4.2 文件上传的实操细节：前端如何“假装”上传 PDF

真实的 Paperclip 项目，必然需要处理用户上传的 PDF 文件。但为了快速验证核心链路，我们先用“模拟上传”绕过复杂的二进制处理。在paperclip-client/src/App.jsx的handleSubmit函数中，mockFileContent变量就是关键。它的值不能是随意的字符串，而必须是经过 Base64 编码的、真实的 PDF 文件内容。否则，当你后续接入pdf-parse库时，会发现解析失败。

实操步骤如下：

  1. 找一个真实的 PDF 文件（比如一份技术白皮书）。
  2. 在 WSL2 的 Ubuntu 中，用base64命令编码：
    base64 -w 0 your-report.pdf > report-base64.txt
  3. 打开report-base64.txt，复制全部内容。
  4. 将mockFileContent的值替换为这个长字符串。

这样，Node.js 层的extractTextFromPDF函数（虽然目前是模拟的）就能接收到一个合法的 Base64 字符串，为后续集成pdf-parse库打下基础。pdf-parse的安装和使用非常简单：

npm install pdf-parse

然后在paperclip-server/index.js中：

const pdfParse = require('pdf-parse'); // 替换原来的 extractTextFromPDF 函数 async function extractTextFromPDF(base64String) { try { const buffer = Buffer.from(base64String, 'base64'); const data = await pdfParse(buffer); return data.text.substring(0, 5000); // 截取前 5000 字符，防止超长 } catch (error) { console.error('PDF parse error:', error); return 'PDF 解析失败，请检查文件格式。'; } }

4.3 OpenClaw 的日志调试：读懂它的“黑话”

当一切看似配置正确，但前端依然收不到任何流式响应时，OpenClaw 的日志就是唯一的救命稻草。启动 OpenClaw 时，加上-v参数：

openclaw serve --config ~/.openclaw/config/config.yaml -v

你会看到类似这样的输出：

INFO openclaw::server: Starting OpenClaw server on http://0.0.0.0:8000 INFO openclaw::model::ollama: Connecting to Ollama at http://localhost:11434 INFO openclaw::model::ollama: Model qwen2.5:3b is available INFO openclaw::server: Request received: POST /v1/chat/completions DEBUG openclaw::model::ollama: Sending request to Ollama: {"model":"qwen2.5:3b", ...}

关键看DEBUG级别的日志。如果看不到Sending request to Ollama，说明 OpenClaw 根本没收到 Node.js 的请求，问题出在 Node.js 到 OpenClaw 的网络连接上（检查http://localhost:8000是否能curl通）。如果看到了Sending request，但没有后续的Response received日志，说明 Ollama 本身出了问题（检查ollama list是否显示模型状态为running）。

注意：OpenClaw 的-v日志非常详细，会打印出所有请求和响应的原始 JSON。在生产环境务必关闭，否则会泄露敏感的 prompt 和模型输出。

5. 常见问题与排查技巧实录：那些没人告诉你的“已知未知”

5.1 “openclaw 无法安全验证” 的终极解决方案

这个错误信息，99% 的情况都源于一个被忽略的细节：OpenClaw 的cors.allowed_origins配置，必须与发起请求的 Origin 完全一致，包括末尾的斜杠。例如，你的 React 应用在http://localhost:5173/运行，那么allowed_origins里就必须写http://localhost:5173/，而不是http://localhost:5173。少一个/，就会触发 CORS 验证失败。

排查步骤：

  1. 打开浏览器开发者工具（F12），切换到 Network 标签页。
  2. 点击“生成摘要”按钮。
  3. 找到api/generate这个请求，点击它，查看 Headers 标签页下的Request Headers区域。
  4. 找到Origin这一行，记下它的完整值（比如http://localhost:5173/）。
  5. 打开~/.openclaw/config/config.yaml，将allowed_origins数组中的对应项，严格按 Origin 的值填写，保存并重启 OpenClaw。

这是一个典型的“配置即代码”问题。OpenClaw 不会帮你做字符串标准化，它只做精确匹配。

5.2 WSL2 下 OpenClaw 启动失败：“failed to load model: invalid path format”

这个问题的根源，是 OpenClaw 在解析config.yaml中的models[].endpoint时，对 Windows 路径分隔符的处理有 Bug。当你在 WSL2 中，endpoint写成http://localhost:11434是绝对正确的。但如果你不小心写成了http://127.0.0.1:11434，或者更糟，写成了http://localhost\11434（混用了\），OpenClaw 就会抛出这个错误。

实操心得：永远用localhost，永远用:，永远不要用\。在 WSL2 中，localhost和127.0.0.1在绝大多数情况下是等价的，但 OpenClaw 的内部 DNS 解析器对localhost的处理更稳定。

5.3 Node.js 服务返回 500，但控制台无错误日志

这通常意味着错误发生在fetch调用 OpenClaw 的异步环节，而你没有在try/catch中捕获到。Node.js 的fetchAPI 是 Promise-based 的，如果await fetch(...)抛出异常（比如网络超时、DNS 失败），它会被catch块捕获。但如果fetch成功了（返回了Response对象），但response.json()失败了（比如返回了 HTML 错误页），这个错误会在.then()或await response.json()时才抛出，而你的代码里并没有对它进行try/catch。

修正方案：在index.js的app.post回调中，对response.json()也进行错误处理：

// 在 fetch 之后，添加 if (!response.ok) { const errorText = await response.text(); // 获取原始错误文本 throw new Error(`OpenClaw returned ${response.status}: ${errorText}`); }

这样，当 OpenClaw 返回500 Internal Server Error的 HTML 页面时，你就能在 Node.js 控制台看到完整的错误信息，而不是一个模糊的500。

5.4 React 前端收不到 SSE 流，但 Network 面板显示请求状态为 200

这是一个经典的“流式响应未正确设置”问题。SSE 要求服务器必须设置特定的响应头：

  • Content-Type: text/event-stream
  • Cache-Control: no-cache
  • Connection: keep-alive

如果其中任何一个缺失，浏览器的EventSource就会认为连接已结束，从而触发onerror事件。在index.js中，res.writeHead(200, {...})这一行必须完整、准确。我曾经因为少写了Connection: keep-alive，导致在 Chrome 中一切正常，但在 Safari 中，流在 30 秒后自动断开，因为 Safari 对连接保活的要求更严格。

5.5 性能瓶颈：为什么第一次请求总是特别慢？

Paperclip 的首次响应延迟，主要来自三个“冷启动”环节：

  1. Ollama 模型加载：Qwen2.5-3B 第一次被调用时，Ollama 需要将模型权重从磁盘加载到内存，这个过程可能需要 10-20 秒。
  2. OpenClaw 的 JIT 编译：OpenClaw 的 Rust 二进制文件在首次处理请求时，会