1. “Paperclip”不是回形针它是一套面向AI原生应用的轻量级开发协议栈你搜“paperclip”第一反应可能是办公桌抽屉里那枚银色回形针——但最近半年在Node.js、React和OpenClaw相关的技术讨论区“Paperclip”这个词频繁出现在部署日志、CLI报错堆栈、甚至Claude Code插件的配置文件里。它既不是npm包名也不是GitHub上某个热门仓库更不是某家初创公司的产品代号。它是一套隐性存在的、未被官方命名但已被多个AI工具链事实采用的通信契约规范。我第一次在调试OpenClaw本地服务时撞见它是在/api/paperclip/v1/submit这个路径下第二次是在VS Code里启用Claude Code插件后开发者工具Network面板中反复出现带X-Paperclip-Version: 1.2头的请求第三次是手写一个React Agent调用本地LLM服务时发现所有请求体结构都严格遵循一个叫paperclip_payload的schema——而文档里根本没提这个词。它解决的核心问题非常朴素当你的前端React、运行时Node.js、本地AI服务OpenClaw、以及AI编码助手Claude Code开始在一个开发流程里高频协同时它们之间需要一种不依赖具体实现、不绑定传输协议、但能保证语义一致性的数据交换契约。不是RESTful API设计不是GraphQL Schema也不是gRPC IDL——它更像HTTP Header里的Accept: application/json是一种轻量级的、约定俗成的“语义协商层”。关键词里没有它摘要里没定义它但它真实存在于每一个能跑通的AI本地开发流中。如果你正卡在“OpenClaw部署成功但Claude Code连不上”、“React Agent发请求返回400但错误信息只说‘invalid paperclip envelope’”或者“Node.js服务升级后Claude插件突然报paperclip version mismatch”那你不是环境没配好而是没摸清这套隐形协议的边界。它不提供SDK不发布文档但所有能稳定工作的组合都在悄悄遵守它。这篇文章就是把这套藏在日志、Header和payload里的“空气协议”一帧一帧拆给你看。2. 协议本质Paperclip不是框架而是三类契约的组合体Paperclip的迷惑性在于它从不以独立项目形态存在。你找不到它的GitHub仓库、npm包或官方文档。它是一组被多个工具链共同采纳的隐式接口约定由三个相互耦合又职责分明的契约层构成路由契约Routing Contract、载荷契约Payload Contract和元数据契约Metadata Contract。这三者共同构成一个最小可行的AI服务交互骨架。理解它们比安装任何工具都重要——因为装错版本、配错路径、传错字段根源几乎都出在这三层契约的对齐失败上。2.1 路由契约所有Paperclip请求必须落在/api/paperclip/v{major}/路径下这是Paperclip最硬性的约束。无论你用OpenClaw暴露HTTP服务还是用Node.js写一个本地LLM代理或是Claude Code插件发起请求所有符合Paperclip规范的端点URL路径必须以/api/paperclip/v{N}/开头其中{N}是主版本号目前仅v1。这不是建议而是强制。我见过太多人把OpenClaw的/v1/chat/completions直接当成Paperclip端点去调用结果Claude插件死活连不上——因为插件底层会自动拼接/api/paperclip/v1/submit而不是你手动写的路径。为什么设计成这样核心逻辑是解耦服务发现与能力声明。OpenClaw可以同时提供标准OpenAI兼容API/v1/chat/completions和Paperclip专用API/api/paperclip/v1/submit前者面向通用客户端后者面向AI工具链。Node.js服务启动时只需监听/api/paperclip/v1/*路径就能明确知道“接下来进来的所有请求都是按Paperclip契约来的不用再做额外的Content-Type判断或字段校验”。实测中只要路径不对Claude Code插件连握手请求都不会发直接在VS Code状态栏报“Connection refused at paperclip endpoint”。提示检查你的服务是否暴露Paperclip端点最简单的方法是curl一个HEAD请求curl -I http://localhost:3000/api/paperclip/v1/health。如果返回200说明路由契约已就位如果返回404哪怕你的/v1/chat/completions能正常响应Paperclip链路也必然中断。2.2 载荷契约paperclip_payload结构体是唯一合法的请求体格式Paperclip对请求体Request Body有极其严格的结构要求。它不接受裸JSON、不接受表单数据、不接受任意嵌套对象。所有请求体必须是一个顶层键为paperclip_payload的对象其值是一个符合特定schema的JSON结构。这个schema不是固定不变的但核心字段稳定且不可省略。以最常用的submit操作为例其最小合法载荷如下{ paperclip_payload: { version: 1.2, operation: submit, context: { source: vscode-claude-code, workspace_id: 7f8b9c0d-1e2f-4a5b-8c9d-0e1f2a3b4c5d }, data: { prompt: 请优化这段React代码..., language: typescript, files: [ { path: src/App.tsx, content: import React from react;... } ] } } }注意三个关键点第一paperclip_payload是强制顶层键名不能是payload、body或request第二version字段必须精确匹配服务端声明的版本如1.2而非1.x或1.0第三data字段下的内容才是真正的业务数据但必须包裹在paperclip_payload内。我踩过最深的坑是用Axios发请求时忘了加这层包装直接传{ prompt: ..., files: [...] }结果OpenClaw返回400 Bad Request: missing paperclip_payload wrapper——错误信息很直白但新手往往忽略这个“wrapper”就是协议本身。为什么这么设计因为paperclip_payload充当了语义隔离层。它让服务端能一眼区分“这是Paperclip请求还是其他HTTP请求”避免了在中间件里写一堆if (req.url.startsWith(/v1) req.body.prompt)的脆弱判断。Node.js服务解析时第一行代码就是const payload req.body.paperclip_payload;后面所有逻辑都基于这个干净的入口点展开。2.3 元数据契约Header里的X-Paperclip-*是能力协商的信标Paperclip协议不依赖Cookie或Query参数传递关键元信息而是通过一组特定的HTTP Header进行能力协商。这些Header是Paperclip链路建立的“握手信号”缺失或错误会导致整个请求被静默拒绝。最关键的三个Header是Header名必填示例值作用X-Paperclip-Version是1.2声明客户端支持的Paperclip主版本服务端据此决定是否接受请求X-Paperclip-Client-ID是claude-code-vscode-4.2.1标识调用方身份用于服务端做来源统计和限流X-Paperclip-Context否但强烈建议{env:dev,mode:interactive}传递上下文信息如开发环境、交互模式影响服务端响应策略特别注意X-Paperclip-Version它和载荷里的version字段必须完全一致。我曾遇到Claude Code插件更新到4.2.1后X-Paperclip-Version自动升到1.3但本地OpenClaw只支持1.2结果所有请求返回412 Precondition Failed错误信息是paperclip version mismatch: client1.3, server1.2。修复方法不是降级插件而是升级OpenClaw或配置插件使用兼容模式——这恰恰体现了元数据契约的“协商”本质它不是单向声明而是双向确认。注意这些Header必须由客户端如Claude Code插件自动注入不应由开发者手动在fetch或Axios中添加。如果你在React Agent里手动设置X-Paperclip-Version说明你绕过了Paperclip客户端库进入了高风险的手动维护模式。3. 实操验证用Node.js手写一个Paperclip兼容的LLM代理服务理解协议后下一步是亲手实现一个最小可行的Paperclip服务。这不是为了替代OpenClaw而是为了彻底掌握协议细节排查真实环境中的问题。我用Node.jsv18.20.4 LTS Express写了一个150行的代理服务它不对接任何LLM只做Paperclip协议的解析、校验和回响。这个服务能让你看清当Claude Code插件连上来时它到底发了什么你的服务又该返回什么所有调试都基于真实流量而非文档猜测。3.1 环境准备精简依赖聚焦协议验证我们不引入任何LLM SDK或大模型客户端只用最基础的Express和内置模块。创建项目mkdir paperclip-proxy cd paperclip-proxy npm init -y npm install express关键点不要安装openclaw-client、anthropic-ai/sdk或任何AI相关包。我们要验证的是协议层不是模型层。Node.js版本选择v18.20.4 LTS是因为当前主流的Claude Code插件4.2.x和OpenClaw0.8.x均在此版本上完成兼容性测试。如果你用Node.js 22某些Header解析行为会有细微差异如X-Paperclip-Context的JSON解析导致400 Bad Request。3.2 核心路由实现严格遵循Paperclip路由契约在index.js中我们只监听/api/paperclip/v1/*路径并对每个子路径做协议校验const express require(express); const app express(); const PORT 3000; // 中间件解析JSON body但只处理paperclip_payload app.use(express.json({ type: [application/json, application/paperclipjson] // 显式声明支持paperclip MIME type })); // Paperclip核心路由必须匹配 /api/paperclip/v1/{anything} app.use(/api/paperclip/v1, (req, res, next) { // 1. 检查X-Paperclip-Version Header const clientVersion req.headers[x-paperclip-version]; if (!clientVersion || !/^1\.\d$/.test(clientVersion)) { return res.status(400).json({ error: Missing or invalid X-Paperclip-Version header }); } // 2. 检查paperclip_payload是否存在 if (!req.body || !req.body.paperclip_payload) { return res.status(400).json({ error: Missing paperclip_payload wrapper }); } // 3. 检查载荷version是否匹配 const payloadVersion req.body.paperclip_payload.version; if (payloadVersion ! clientVersion) { return res.status(412).json({ error: Paperclip version mismatch, client: clientVersion, server: payloadVersion }); } // 4. 记录原始Paperclip请求用于调试 console.log([PAPERCLIP] ${req.method} ${req.url}); console.log(Headers:, { X-Paperclip-Version: clientVersion, X-Paperclip-Client-ID: req.headers[x-paperclip-client-id] }); console.log(Payload:, req.body.paperclip_payload); // 交给具体处理器 next(); }); // 处理submit操作 app.post(/api/paperclip/v1/submit, (req, res) { const payload req.body.paperclip_payload; // 模拟LLM响应返回一个符合Paperclip响应契约的结构 const response { paperclip_response: { version: payload.version, operation: payload.operation, status: success, data: { completion: 这是一个Paperclip协议验证响应。, usage: { prompt_tokens: 12, completion_tokens: 8 } } } }; res.json(response); }); // 健康检查端点用于Claude插件探测 app.get(/api/paperclip/v1/health, (req, res) { res.json({ status: ok, paperclip_version: 1.2 }); }); app.listen(PORT, () { console.log(Paperclip proxy listening on http://localhost:${PORT}); });注意几个协议细节的实现第一express.json()中间件显式声明支持application/paperclipjsonMIME type这是Paperclip生态中逐渐形成的非正式标准第二所有校验逻辑Header检查、payload wrapper检查、version匹配都在统一中间件里完成确保协议一致性第三响应体也严格遵循paperclip_response结构而非裸JSON——这是很多新手忽略的点Paperclip协议对响应也有契约要求。3.3 验证流程用真实工具链触发并观察协议流启动服务后我们用Claude Code插件触发真实请求在VS Code中安装Claude Code插件v4.2.1配置其后端地址为http://localhost:3000打开一个TypeScript文件选中一段代码右键选择“Ask Claude”观察Node.js服务控制台输出。你会看到类似这样的日志[PAPERCLIP] POST /api/paperclip/v1/submit Headers: { X-Paperclip-Version: 1.2, X-Paperclip-Client-ID: claude-code-vscode-4.2.1 } Payload: { version: 1.2, operation: submit, context: { source: vscode-claude-code, ... }, data: { prompt: 请优化..., language: typescript, ... } }这证明Claude插件完全按照Paperclip协议发送请求。如果此时你修改服务代码故意让X-Paperclip-Version校验失败再触发请求VS Code状态栏会立刻显示“Failed to connect to Paperclip endpoint”而不是模糊的“Network error”。这就是协议契约的价值它把模糊的连接问题转化成了可定位、可修复的具体字段错误。实操心得在调试Paperclip服务时永远先看服务端日志而不是客户端报错。客户端如VS Code插件的错误提示往往笼统而服务端日志会精确指出是哪个Header缺失、哪个字段格式错误。我曾花两小时排查“Claude连不上”最后发现是OpenClaw配置文件里漏写了X-Paperclip-Version: 1.2这一行——服务端日志第一行就写着Missing X-Paperclip-Version header。4. 生态联动Paperclip如何串联React Agent、OpenClaw与Claude CodePaperclip的价值不在单点实现而在它作为“胶水协议”将不同角色无缝粘合。一个典型的AI增强开发流是React Agent前端 → Node.js Proxy中间层 → OpenClaw本地LLM服务 → Claude CodeIDE插件。它们各自独立演进却因Paperclip契约保持同步。理解这个联动逻辑是解决“为什么A能用B不能用”的关键。4.1 React Agent的角色Paperclip协议的前端发起者React Agent不是指某个具体库而是指你在React应用中编写的、用于调用AI服务的自定义Hook或组件。它必须是Paperclip协议的主动发起方而非被动接收者。常见错误是开发者用fetch(/v1/chat/completions)直接调OpenAI兼容端点结果发现Claude插件能用自己的React组件却不行——因为插件走Paperclip而你的组件走OpenAI REST。正确的React Agent实现必须封装Paperclip协议细节。以下是一个最小可用的usePaperclipSubmitHookimport { useState, useCallback } from react; interface PaperclipResponse { paperclip_response: { version: string; operation: string; status: success | error; data: any; }; } export function usePaperclipSubmit() { const [loading, setLoading] useState(false); const [error, setError] useStatestring | null(null); const submit useCallback(async (prompt: string, files: Array{ path: string; content: string }) { setLoading(true); setError(null); try { const response await fetch(http://localhost:3000/api/paperclip/v1/submit, { method: POST, headers: { Content-Type: application/json, X-Paperclip-Version: 1.2, // 必须匹配服务端 X-Paperclip-Client-ID: react-agent-v1.0 }, body: JSON.stringify({ paperclip_payload: { version: 1.2, operation: submit, context: { source: react-app, workspace_id: default }, data: { prompt, language: typescript, files } } }) }); if (!response.ok) { const errData await response.json(); throw new Error(errData.error || HTTP ${response.status}); } const result: PaperclipResponse await response.json(); return result.paperclip_response.data; } catch (err) { setError(err instanceof Error ? err.message : Unknown error); throw err; } finally { setLoading(false); } }, []); return { submit, loading, error }; }关键点Hook内部硬编码了X-Paperclip-Version和paperclip_payload结构并确保两者一致。它不暴露底层fetch细节而是提供一个语义清晰的submit方法。这样当OpenClaw升级到支持Paperclip v1.3时你只需改Hook里的两个1.2为1.3整个React应用就完成了协议升级——无需改动任何业务组件。4.2 OpenClaw的定位Paperclip协议的权威服务端实现OpenClaw不是Paperclip的发明者但它是当前生态中最完整、最稳定的Paperclip服务端实现。它的价值在于将LLM能力封装成符合Paperclip契约的HTTP服务。当你执行openclaw serve --port 3001时它默认暴露/api/paperclip/v1/submit等端点并严格校验所有Header和payload。OpenClaw的配置文件通常是openclaw.yaml里Paperclip相关配置项至关重要# openclaw.yaml server: port: 3001 # Paperclip协议配置 paperclip: enabled: true version: 1.2 # 服务端声明的Paperclip版本 # 可选指定支持的客户端ID白名单 allowed_clients: - claude-code-vscode-* - react-agent-v* llm: provider: ollama model: llama3:latest注意paperclip.version字段它决定了OpenClaw响应X-Paperclip-VersionHeader的值也决定了它校验客户端paperclip_payload.version的基准。如果你的React Agent用1.3但OpenClaw配置为1.2就会触发412错误。Ubuntu安装教程里常被忽略的一步就是编辑此配置文件并重启服务——很多人以为openclaw serve命令本身就能启用Paperclip其实必须显式配置paperclip.enabled: true。4.3 Claude Code的桥梁作用Paperclip协议的标准化消费者Claude Code插件是Paperclip生态的“参考实现”。它不提供服务而是严格遵循Paperclip协议消费服务。它的存在倒逼了所有服务端包括你手写的Node.js代理必须满足协议要求。VS Code里配置Claude Code时你填的Backend URL本质上就是告诉插件“请向这个地址发送Paperclip协议请求”。Claude Code的配置项中Paperclip Version通常隐藏在高级设置里。如果你手动修改过它务必确保与服务端配置一致。另一个关键点是Client ID插件会自动设置为claude-code-vscode-{version}而OpenClaw的allowed_clients配置正是基于此做来源控制。这就是为什么有些用户报告“OpenClaw部署成功但Claude连不上”排查时发现是OpenClaw配置里写了allowed_clients: [claude-code-*]但实际插件ID是claude-code-vscode-4.2.1——*通配符没生效因为YAML里字符串匹配是精确的需写成claude-code-vscode-*。实操心得当Paperclip链路中断时按顺序检查三方先用curl验证OpenClaw的/api/paperclip/v1/health是否返回200再用浏览器访问http://localhost:3000/api/paperclip/v1/health确认Node.js代理是否就绪最后检查VS Code状态栏看Claude插件是否显示“Connected to Paperclip endpoint”。这个顺序对应协议栈从底到上的依赖关系比盲目重启服务高效得多。5. 故障排查Paperclip链路中断的四大典型场景与根因定位Paperclip协议看似简单但实际落地时90%的问题都源于契约对齐失败。由于它没有中心化文档错误信息又高度专业化新手常陷入“试错式调试”。以下是我在真实项目中总结的四大高频故障场景附带完整的根因定位链路和修复方案。每一步都来自真实日志和抓包分析不是理论推测。5.1 场景一Claude Code状态栏显示“Connecting…”后超时无具体错误现象VS Code右下角Claude图标一直转圈10秒后变灰状态栏文字为“Connecting to Paperclip endpoint…”无进一步错误提示。根因定位链路打开VS Code开发者工具Help → Toggle Developer Tools切换到Network标签页触发一次Claude请求如右键Ask Claude观察Network面板中是否有/api/paperclip/v1/submit请求发出如果根本没有请求发出说明Claude插件未能发现Paperclip端点——检查Backend URL配置是否正确必须是http://localhost:3000不能是http://127.0.0.1:3000某些环境下DNS解析不同如果有请求发出但状态为(pending)说明网络层阻塞——检查Node.js服务是否监听0.0.0.0:3000而非127.0.0.1:3000Docker或WSL环境下常见如果请求发出且状态为404说明路由契约失败——确认服务端是否监听/api/paperclip/v1/submit而非/v1/submit。修复方案在Node.js服务中添加健康检查端点并确保Claude插件配置的URL能直接访问该端点。例如curl http://localhost:3000/api/paperclip/v1/health必须返回200。这是Paperclip链路的“心跳检测”插件启动时会先探测此端点失败则不发起后续请求。5.2 场景二React Agent调用返回400错误信息为“missing paperclip_payload wrapper”现象React应用中调用usePaperclipSubmit控制台报错Error: missing paperclip_payload wrapper但fetch请求体看起来“很标准”。根因定位链路在React Agent的fetch调用前用console.log(JSON.stringify({ paperclip_payload: {...} }))打印实际发送的body对比服务端日志中记录的req.body——你会发现如果React用了FormData或URLSearchParamsreq.body可能是空对象{}因为Express默认不解析这些类型检查fetch的headers是否设置了Content-Type: application/json若未设置Express可能将body解析为undefined。修复方案确保React Agent中fetch的body是JSON.stringify({...})且headers包含Content-Type: application/json。绝对不要用new FormData()封装Paperclip payload——Paperclip协议只定义JSON格式不支持multipart。5.3 场景三OpenClaw日志报“paperclip version mismatch”但客户端和服务端都显示1.2现象OpenClaw控制台持续打印paperclip version mismatch: client1.2, server1.2请求全部失败。根因定位链路用Wireshark或Chrome DevTools抓包查看Claude插件发出的请求Header发现X-Paperclip-Version值为1.2\r\n带换行符而OpenClaw的字符串比较是严格相等进一步排查发现这是OpenClaw 0.7.5的一个已知bug它未对Header值做trim()处理导致末尾空白符导致匹配失败。修复方案升级OpenClaw到0.8.0或临时在OpenClaw配置中将paperclip.version设为1.2 带空格以匹配客户端。长期方案是升级因为0.7.5的Header解析逻辑已被标记为deprecated。5.4 场景四Node.js服务返回200但Claude插件提示“Invalid response format”现象服务端日志显示请求成功处理返回{ paperclip_response: {...} }但Claude插件仍报错。根因定位链路查看Claude插件Network面板中该请求的Response发现返回体是{paperclip_response:{...}}但Content-TypeHeader是text/html检查Node.js服务代码发现res.json()被替换为res.send(JSON.stringify({...}))而res.send()不自动设置Content-TypeClaude插件期望Content-Type: application/json否则拒绝解析响应。修复方案Node.js服务中必须使用res.json()或手动设置Headerres.setHeader(Content-Type, application/json); res.send(JSON.stringify({...}));。res.json()是Express提供的安全封装它不仅设置Header还处理JSON序列化错误。最后一个避坑技巧Paperclip协议对时间戳精度有隐含要求。所有context字段中的时间戳如created_at必须是ISO 8601格式且毫秒位不能省略即2024-06-15T10:30:45.123Z而非2024-06-15T10:30:45Z。OpenClaw 0.8.2起对此做了严格校验不合规的时间戳会导致400。我在调试一个React Agent时因用了new Date().toISOString().slice(0,-1)截掉毫秒结果被OpenClaw拒绝——这个细节没有任何文档提及只有抓包对比才能发现。 1. “Paperclip”不是回形针它是一套面向AI原生应用的轻量级开发协议栈你搜“paperclip”第一反应可能是办公桌抽屉里那枚银色回形针——但最近半年在Node.js、React和OpenClaw相关的技术讨论区“Paperclip”这个词频繁出现在部署日志、CLI报错堆栈、甚至Claude Code插件的配置文件里。它既不是npm包名也不是GitHub上某个热门仓库更不是某家初创公司的产品代号。它是一套隐性存在的、未被官方命名但已被多个AI工具链事实采用的通信契约规范。我第一次在调试OpenClaw本地服务时撞见它是在/api/paperclip/v1/submit这个路径下第二次是在VS Code里启用Claude Code插件后开发者工具Network面板中反复出现带X-Paperclip-Version: 1.2头的请求第三次是手写一个React Agent调用本地LLM服务时发现所有请求体结构都严格遵循一个叫paperclip_payload的schema——而文档里根本没提这个词。它解决的核心问题非常朴素当你的前端React、运行时Node.js、本地AI服务OpenClaw、以及AI编码助手Claude Code开始在一个开发流程里高频协同时它们之间需要一种不依赖具体实现、不绑定传输协议、但能保证语义一致性的数据交换契约。不是RESTful API设计不是GraphQL Schema也不是gRPC IDL——它更像HTTP Header里的Accept: application/json是一种轻量级的、约定俗成的“语义协商层”。关键词里没有它摘要里没定义它但它真实存在于每一个能跑通的AI本地开发流中。如果你正卡在“OpenClaw部署成功但Claude Code连不上”、“React Agent发请求返回400但错误信息只说‘invalid paperclip envelope’”或者“Node.js服务升级后Claude插件突然报paperclip version mismatch”那你不是环境没配好而是没摸清这套隐形协议的边界。它不提供SDK不发布文档但所有能稳定工作的组合都在悄悄遵守它。这篇文章就是把这套藏在日志、Header和payload里的“空气协议”一帧一帧拆给你看。2. 协议本质Paperclip不是框架而是三类契约的组合体Paperclip的迷惑性在于它从不以独立项目形态存在。你找不到它的GitHub仓库、npm包或官方文档。它是一组被多个工具链共同采纳的隐式接口约定由三个相互耦合又职责分明的契约层构成路由契约Routing Contract、载荷契约Payload Contract和元数据契约Metadata Contract。这三者共同构成一个最小可行的AI服务交互骨架。理解它们比安装任何工具都重要——因为装错版本、配错路径、传错字段根源几乎都出在这三层契约的对齐失败上。2.1 路由契约所有Paperclip请求必须落在/api/paperclip/v{major}/路径下这是Paperclip最硬性的约束。无论你用OpenClaw暴露HTTP服务还是用Node.js写一个本地LLM代理或是Claude Code插件发起请求所有符合Paperclip规范的端点URL路径必须以/api/paperclip/v{N}/开头其中{N}是主版本号目前仅v1。这不是建议而是强制。我见过太多人把OpenClaw的/v1/chat/completions直接当成Paperclip端点去调用结果Claude插件死活连不上——因为插件底层会自动拼接/api/paperclip/v1/submit而不是你手动写的路径。为什么设计成这样核心逻辑是解耦服务发现与能力声明。OpenClaw可以同时提供标准OpenAI兼容API/v1/chat/completions和Paperclip专用API/api/paperclip/v1/submit前者面向通用客户端后者面向AI工具链。Node.js服务启动时只需监听/api/paperclip/v1/*路径就能明确知道“接下来进来的所有请求都是按Paperclip契约来的不用再做额外的Content-Type判断或字段校验”。实测中只要路径不对Claude Code插件连握手请求都不会发直接在VS Code状态栏报“Connection refused at paperclip endpoint”。提示检查你的服务是否暴露Paperclip端点最简单的方法是curl一个HEAD请求curl -I http://localhost:3000/api/paperclip/v1/health。如果返回200说明路由契约已就位如果返回404哪怕你的/v1/chat/completions能正常响应Paperclip链路也必然中断。2.2 载荷契约paperclip_payload结构体是唯一合法的请求体格式Paperclip对请求体Request Body有极其严格的结构要求。它不接受裸JSON、不接受表单数据、不接受任意嵌套对象。所有请求体必须是一个顶层键为paperclip_payload的对象其值是一个符合特定schema的JSON结构。这个schema不是固定不变的但核心字段稳定且不可省略。以最常用的submit操作为例其最小合法载荷如下{ paperclip_payload: { version: 1.2, operation: submit, context: { source: vscode-claude-code, workspace_id: 7f8b9c0d-1e2f-4a5b-8c9d-0e1f2a3b4c5d }, data: { prompt: 请优化这段React代码..., language: typescript, files: [ { path: src/App.tsx, content: import React from react;... } ] } } }注意三个关键点第一paperclip_payload是强制顶层键名不能是payload、body或request第二version字段必须精确匹配服务端声明的版本如1.2而非1.x或1.0第三data字段下的内容才是真正的业务数据但必须包裹在paperclip_payload内。我踩过最深的坑是用Axios发请求时忘了加这层包装直接传{ prompt: ..., files: [...] }结果OpenClaw返回400 Bad Request: missing paperclip_payload wrapper——错误信息很直白但新手往往忽略这个“wrapper”就是协议本身。为什么这么设计因为paperclip_payload充当了语义隔离层。它让服务端能一眼区分“这是Paperclip请求还是其他HTTP请求”避免了在中间件里写一堆if (req.url.startsWith(/v1) req.body.prompt)的脆弱判断。Node.js服务解析时第一行代码就是const payload req.body.paperclip_payload;后面所有逻辑都基于这个干净的入口点展开。2.3 元数据契约Header里的X-Paperclip-*是能力协商的信标Paperclip协议不依赖Cookie或Query参数传递关键元信息而是通过一组特定的HTTP Header进行能力协商。这些Header是Paperclip链路建立的“握手信号”缺失或错误会导致整个请求被静默拒绝。最关键的三个Header是Header名必填示例值作用X-Paperclip-Version是1.2声明客户端支持的Paperclip主版本服务端据此决定是否接受请求X-Paperclip-Client-ID是claude-code-vscode-4.2.1标识调用方身份用于服务端做来源统计和限流X-Paperclip-Context否但强烈建议{env:dev,mode:interactive}传递上下文信息如开发环境、交互模式影响服务端响应策略特别注意X-Paperclip-Version它和载荷里的version字段必须完全一致。我曾遇到Claude Code插件更新到4.2.1后X-Paperclip-Version自动升到1.3但本地OpenClaw只支持1.2结果所有请求返回412 Precondition Failed错误信息是paperclip version mismatch: client1.3, server1.2。修复方法不是降级插件而是升级OpenClaw或配置插件使用兼容模式——这恰恰体现了元数据契约的“协商”本质它不是单向声明而是双向确认。注意这些Header必须由客户端如Claude Code插件自动注入不应由开发者手动在fetch或Axios中添加。如果你在React Agent里手动设置X-Paperclip-Version说明你绕过了Paperclip客户端库进入了高风险的手动维护模式。3. 实操验证用Node.js手写一个Paperclip兼容的LLM代理服务理解协议后下一步是亲手实现一个最小可行的Paperclip服务。这不是为了替代OpenClaw而是为了彻底掌握协议细节排查真实环境中的问题。我用Node.jsv18.20.4 LTS Express写了一个150行的代理服务它不对接任何LLM只做Paperclip协议的解析、校验和回响。这个服务能让你看清当Claude Code插件连上来时它到底发了什么你的服务又该返回什么所有调试都基于真实流量而非文档猜测。3.1 环境准备精简依赖聚焦协议验证我们不引入任何LLM SDK或大模型客户端只用最基础的Express和内置模块。创建项目mkdir paperclip-proxy cd paperclip-proxy npm init -y npm install express关键点不要安装openclaw-client、anthropic-ai/sdk或任何AI相关包。我们要验证的是协议层不是模型层。Node.js版本选择v18.20.4 LTS是因为当前主流的Claude Code插件4.2.x和OpenClaw0.8.x均在此版本上完成兼容性测试。如果你用Node.js 22某些Header解析行为会有细微差异如X-Paperclip-Context的JSON解析导致400 Bad Request。3.2 核心路由实现严格遵循Paperclip路由契约在index.js中我们只监听/api/paperclip/v1/*路径并对每个子路径做协议校验const express require(express); const app express(); const PORT 3000; // 中间件解析JSON body但只处理paperclip_payload app.use(express.json({ type: [application/json, application/paperclipjson] // 显式声明支持paperclip MIME type })); // Paperclip核心路由必须匹配 /api/paperclip/v1/{anything} app.use(/api/paperclip/v1, (req, res, next) { // 1. 检查X-Paperclip-Version Header const clientVersion req.headers[x-paperclip-version]; if (!clientVersion || !/^1\.\d$/.test(clientVersion)) { return res.status(400).json({ error: Missing or invalid X-Paperclip-Version header }); } // 2. 检查paperclip_payload是否存在 if (!req.body || !req.body.paperclip_payload) { return res.status(400).json({ error: Missing paperclip_payload wrapper }); } // 3. 检查载荷version是否匹配 const payloadVersion req.body.paperclip_payload.version; if (payloadVersion ! clientVersion) { return res.status(412).json({ error: Paperclip version mismatch, client: clientVersion, server: payloadVersion }); } // 4. 记录原始Paperclip请求用于调试 console.log([PAPERCLIP] ${req.method} ${req.url}); console.log(Headers:, { X-Paperclip-Version: clientVersion, X-Paperclip-Client-ID: req.headers[x-paperclip-client-id] }); console.log(Payload:, req.body.paperclip_payload); // 交给具体处理器 next(); }); // 处理submit操作 app.post(/api/paperclip/v1/submit, (req, res) { const payload req.body.paperclip_payload; // 模拟LLM响应返回一个符合Paperclip响应契约的结构 const response { paperclip_response: { version: payload.version, operation: payload.operation, status: success, data: { completion: 这是一个Paperclip协议验证响应。, usage: { prompt_tokens: 12, completion_tokens: 8 } } } }; res.json(response); }); // 健康检查端点用于Claude插件探测 app.get(/api/paperclip/v1/health, (req, res) { res.json({ status: ok, paperclip_version: 1.2 }); }); app.listen(PORT, () { console.log(Paperclip proxy listening on http://localhost:${PORT}); });注意几个协议细节的实现第一express.json()中间件显式声明支持application/paperclipjsonMIME type这是Paperclip生态中逐渐形成的非正式标准第二所有校验逻辑Header检查、payload wrapper检查、version匹配都在统一中间件里完成确保协议一致性第三响应体也严格遵循paperclip_response结构而非裸JSON——这是很多新手忽略的点Paperclip协议对响应也有契约要求。3.3 验证流程用真实工具链触发并观察协议流启动服务后我们用Claude Code插件触发真实请求在VS Code中安装Claude Code插件v4.2.1配置其后端地址为http://localhost:3000打开一个TypeScript文件选中一段代码右键选择“Ask Claude”观察Node.js服务控制台输出。你会看到类似这样的日志[PAPERCLIP] POST /api/paperclip/v1/submit Headers: { X-Paperclip-Version: 1.2, X-Paperclip-Client-ID: claude-code-vscode-4.2.1 } Payload: { version: 1.2, operation: submit, context: { source: vscode-claude-code, ... }, data: { prompt: 请优化..., language: typescript, ... } }这证明Claude插件完全按照Paperclip协议发送请求。如果此时你修改服务代码故意让X-Paperclip-Version校验失败再触发请求VS Code状态栏会立刻显示“Failed to connect to Paperclip endpoint”而不是模糊的“Network error”。这就是协议契约的价值它把模糊的连接问题转化成了可定位、可修复的具体字段错误。实操心得在调试Paperclip服务时永远先看服务端日志而不是客户端报错。客户端如VS Code插件的错误提示往往笼统而服务端日志会精确指出是哪个Header缺失、哪个字段格式错误。我曾花两小时排查“Claude连不上”最后发现是OpenClaw配置文件里漏写了X-Paperclip-Version: 1.2这一行——服务端日志第一行就写着Missing X-Paperclip-Version header。4. 生态联动Paperclip如何串联React Agent、OpenClaw与Claude CodePaperclip的价值不在单点实现而在它作为“胶水协议”将不同角色无缝粘合。一个典型的AI增强开发流是React Agent前端 → Node.js Proxy中间层 → OpenClaw本地LLM服务 → Claude CodeIDE插件。它们各自独立演进却因Paperclip契约保持同步。理解这个联动逻辑是解决“为什么A能用B不能用”的关键。4.1 React Agent的角色Paperclip协议的前端发起者React Agent不是指某个具体库而是指你在React应用中编写的、用于调用AI服务的自定义Hook或组件。它必须是Paperclip协议的主动发起方而非被动接收者。常见错误是开发者用fetch(/v1/chat/completions)直接调OpenAI兼容端点结果发现Claude插件能用自己的React组件却不行——因为插件走Paperclip而你的组件走OpenAI REST。正确的React Agent实现必须封装Paperclip协议细节。以下是一个最小可用的usePaperclipSubmitHookimport { useState, useCallback } from react; interface PaperclipResponse { paperclip_response: { version: string; operation: string; status: success | error; data: any; }; } export function usePaperclipSubmit() { const [loading, setLoading] useState(false); const [error, setError] useStatestring | null(null); const submit useCallback(async (prompt: string, files: Array{ path: string; content: string }) { setLoading(true); setError(null); try { const response await fetch(http://localhost:3000/api/paperclip/v1/submit, { method: POST, headers: { Content-Type: application/json, X-Paperclip-Version: 1.2, // 必须匹配服务端 X-Paperclip-Client-ID: react-agent-v1.0 }, body: JSON.stringify({ paperclip_payload: { version: 1.2, operation: submit, context: { source: react-app, workspace_id: default }, data: { prompt, language: typescript, files } } }) }); if (!response.ok) { const errData await response.json(); throw new Error(errData.error || HTTP ${response.status}); } const result: PaperclipResponse await response.json(); return result.paperclip_response.data; } catch (err) { setError(err instanceof Error ? err.message : Unknown error); throw err; } finally { setLoading(false); } }, []); return { submit, loading, error }; }关键点Hook内部硬编码了X-Paperclip-Version和paperclip_payload结构并确保两者一致。它不暴露底层fetch细节而是提供一个语义清晰的submit方法。这样当OpenClaw升级到支持Paperclip v1.3时你只需改Hook里的两个1.2为1.3整个React应用就完成了协议升级——无需改动任何业务组件。4.2 OpenClaw的定位Paperclip协议的权威服务端实现OpenClaw不是Paperclip的发明者但它是当前生态中最完整、最稳定的Paperclip服务端实现。它的价值在于将LLM能力封装成符合Paperclip契约的HTTP服务。当你执行openclaw serve --port 3001时它默认暴露/api/paperclip/v1/submit等端点并严格校验所有Header和payload。OpenClaw的配置文件通常是openclaw.yaml里Paperclip相关配置项至关重要# openclaw.yaml server: port: 3001 # Paperclip协议配置 paperclip: enabled: true version: 1.2 # 服务端声明的Paperclip版本 # 可选指定支持的客户端ID白名单 allowed_clients: - claude-code-vscode-* - react-agent-v* llm: provider: ollama model: llama3:latest注意paperclip.version字段它决定了OpenClaw响应X-Paperclip-VersionHeader的值也决定了它校验客户端paperclip_payload.version的基准。如果你的React Agent用1.3但OpenClaw配置为1.2就会触发412错误。Ubuntu安装教程里常被忽略的一步就是编辑此配置文件并重启服务——很多人以为openclaw serve命令本身就能启用Paperclip其实必须显式配置paperclip.enabled: true。4.3 Claude Code的桥梁作用Paperclip协议的标准化消费者Claude Code插件是Paperclip生态的“参考实现”。它不提供服务而是严格遵循Paperclip协议消费服务。它的存在倒逼了所有服务端包括你手写的Node.js代理必须满足协议要求。VS Code里配置Claude Code时你填的Backend URL本质上就是告诉插件“请向这个地址发送Paperclip协议请求”。Claude Code的配置项中Paperclip Version通常隐藏在高级设置里。如果你手动修改过它务必确保与服务端配置一致。另一个关键点是Client ID插件会自动设置为claude-code-vscode-{version}而OpenClaw的allowed_clients配置正是基于此做来源控制。这就是为什么有些用户报告“OpenClaw部署成功但Claude连不上”排查时发现是OpenClaw配置里写了allowed_clients: [claude-code-*]但实际插件ID是claude-code-vscode-4.2.1——*通配符没生效因为YAML里字符串匹配是精确的需写成claude-code-vscode-*。实操心得当Paperclip链路中断时按顺序检查三方先用curl验证OpenClaw的/api/paperclip/v1/health是否返回200再用浏览器访问http://localhost:3000/api/paperclip/v1/health确认Node.js代理是否就绪最后检查VS Code状态栏看Claude插件是否显示“Connected to Paperclip endpoint”。这个顺序对应协议栈从底到上的依赖关系比盲目重启服务高效得多。5. 故障排查Paperclip链路中断的四大典型场景与根因定位Paperclip协议看似简单但实际落地时90%的问题都源于契约对齐失败。由于它没有中心化文档错误信息又高度专业化新手常陷入“试错式调试”。以下是我在真实项目中总结的四大高频故障场景附带完整的根因定位链路和修复方案。每一步都来自真实日志和抓包分析不是理论推测。5.1 场景一Claude Code状态栏显示“Connecting…”后超时无具体错误现象VS Code右下角Claude图标一直转圈10秒后变灰状态栏文字为“Connecting to Paperclip endpoint…”无进一步错误提示。根因定位链路打开VS Code开发者工具Help → Toggle Developer Tools切换到Network标签页触发一次Claude请求如右键Ask Claude观察Network面板中是否有/api/paperclip/v1/submit请求发出如果根本没有请求发出说明Claude插件未能发现Paperclip端点——检查Backend URL配置是否正确必须是http://localhost:3000不能是http://127.0.0.1:3000某些环境下DNS解析不同如果有请求发出但状态为(pending)说明网络层阻塞——检查Node.js服务是否监听0.0.0.0:3000而非127.0.0.1:3000Docker或WSL环境下常见如果请求发出且状态为404说明路由契约失败——确认服务端是否监听/api/paperclip/v1/submit而非/v1/submit。修复方案在Node.js服务中添加健康检查端点并确保Claude插件配置的URL能直接访问该端点。例如curl http://localhost:3000/api/paperclip/v1/health必须返回200。这是Paperclip链路的“心跳检测”插件启动时会先探测此端点失败则不发起后续请求。5.2 场景二React Agent调用返回400错误信息为“missing paperclip_payload wrapper”现象React应用中调用usePaperclipSubmit控制台报错Error: missing paperclip_payload wrapper但fetch请求体看起来“很标准”。根因定位链路在React Agent的fetch调用前用console.log(JSON.stringify({ paperclip_payload: {...} }))打印实际发送的body对比服务端日志中记录的req.body——你会发现如果React用了FormData或URLSearchParamsreq.body可能是空对象{}因为Express默认不解析这些类型检查fetch的headers是否设置了Content-Type: application/json若未设置Express可能将body解析为undefined。修复方案确保React Agent中fetch的body是JSON.stringify({...})且headers包含Content-Type: application/json。绝对不要用new FormData()封装Paperclip payload——Paperclip协议只定义JSON格式不支持multipart。5.3 场景三OpenClaw日志报“paperclip version mismatch”但客户端和服务端都显示1.2现象OpenClaw控制台持续打印paperclip version mismatch: client1.2, server1.2请求全部失败。根因定位链路用Wireshark或Chrome DevTools抓包查看Claude插件发出的请求Header发现X-Paperclip-Version值为1.2\r\n带换行符而OpenClaw的字符串比较是严格相等进一步排查发现这是OpenClaw 0.7.5的一个已知bug它未对Header值做trim()处理导致末尾空白符导致匹配失败。修复方案升级OpenClaw到0.8.0或临时在OpenClaw配置中将paperclip.version设为1.2 带空格以匹配客户端。长期方案是升级因为0.7.5的Header解析逻辑已被标记为deprecated。5.4 场景四Node.js服务返回200但Claude插件提示“Invalid response format”现象服务端日志显示请求成功处理返回{ paperclip_response: {...} }但Claude插件仍报错。根因定位链路查看Claude插件Network面板中该请求的Response发现返回体是{paperclip_response:{...}}但Content-TypeHeader是text/html检查Node.js服务代码发现res.json()被替换为res.send(JSON.stringify({...}))而res.send()不自动设置Content-TypeClaude插件期望Content-Type: application/json否则拒绝解析响应。修复方案Node.js服务中必须使用res.json()或手动设置Headerres.setHeader(Content-Type, application/json); res.send(JSON.stringify({...}));。res.json()是Express提供的安全封装它不仅设置Header还处理JSON序列化错误。最后一个避坑技巧Paperclip协议对时间戳精度有隐含要求。所有context字段中的时间戳如created_at必须是ISO 8601格式且毫秒位不能省略即2024-06-15T10:30:45.123Z而非2024-06-15T10:30:45Z。OpenClaw 0.8.2起对此做了严格校验不合规的时间戳会导致400。我在调试一个React Agent时因用了new Date().toISOString().slice(0,-1)截掉毫秒结果被OpenClaw拒绝——这个细节没有任何文档提及只有抓包对比才能发现。