企业官网建设流程全解析

1. 项目概述：Paperclip 不是回形针，而是一个被严重低估的 AI Agent 协作基座

你搜“paperclip”，第一反应是不是办公桌抽屉里那个银色小金属件？别急——在 2024 年底到 2025 年初的开发者圈子里，“Paperclip”正悄悄取代“LangChain”“LlamaIndex”这类老面孔，成为高频出现的新锐关键词。它不是 UI 框架，不是模型训练工具，更不是又一个 CLI 脚手架；它是一个面向真实业务场景的 AI Agent 协作运行时（Agent Runtime），核心定位是：让多个专业角色型 Agent（比如“合同审核员”“数据校验员”“合规检查员”）能在同一个上下文里稳定协同、可追溯、可调试、可审计地完成端到端任务。这和当前主流的单 Agent 流水线（single-agent pipeline）有本质区别——Paperclip 的设计哲学是“人机协作结构化”，不是“模型能力堆叠”。

为什么这个项目突然火了？直接看热词线索：Node.js、React、OpenClaw、AI agents四个关键词高频共现。这不是巧合。Paperclip 的底层运行时用 TypeScript + Node.js 18+ 构建，提供标准 HTTP 接口与 WebSocket 支持；它的默认控制台（Dashboard）是 React 应用，支持实时观察 Agent 状态、消息流、决策链路；而它最关键的落地场景，恰恰是与 OpenClaw 深度集成——OpenClaw 是一个开源的、轻量级的本地 AI 工具链调度器（尤其擅长调用本地 Ollama 模型、RAG 索引、Python 工具函数），Paperclip 则负责把 OpenClaw 启动的各个工具型 Agent 组织成有角色、有记忆、有分工的协作体。换句话说：OpenClaw 解决“能不能跑起来”，Paperclip 解决“怎么跑得稳、跑得明白、跑得可控”。

我去年在给一家金融风控团队做内部 AI 工具平台时，就踩过纯 LangChain 流水线的坑：一个“贷款材料完整性检查”任务，需要依次调用 OCR 提取、PDF 结构化解析、关键字段比对、逻辑一致性校验四个子 Agent。LangChain 写出来是线性链条，但实际业务中，OCR 失败要重试并通知人工介入，字段比对异常要触发二次验证流程，逻辑校验失败需回溯前序步骤——这些分支、状态跃迁、人工干预点，在 Paperclip 的AgentGraph模型里，是原生支持的。它用类似有限状态机（FSM）的图谱定义协作协议，每个节点是一个 Agent 实例，边是带条件的事件触发规则（比如on: "ocr_failed" → goto: "manual_review"）。这种设计，让开发者的注意力从“怎么拼接 API”转向“怎么定义协作契约”。

适合谁参考这篇？如果你正在用 Node.js 做后端服务，想接入 LLM 能力但苦于状态管理混乱；如果你是前端工程师，用 React 做 AI 控制台却总被后端返回的“黑盒 JSON”搞晕；如果你已经部署了 OpenClaw，但发现它启动的 Agent 像散兵游勇，缺乏统一指挥——那你就是 Paperclip 的目标用户。它不替代你的模型或工具，而是给你一套“AI 团队的作战手册”。

2. 核心架构拆解：为什么是 Node.js + React + OpenClaw 这个铁三角？

2.1 Paperclip 的三层运行时模型：Runtime / Orchestrator / Dashboard

Paperclip 的代码仓库结构非常干净，只有三个核心包：@paperclip/runtime、@paperclip/orchestrator、@paperclip/dashboard。这不是工程炫技，而是刻意为之的职责分离。

• @paperclip/runtime是最底层，用纯 Node.js（ESM 模块）实现，不依赖任何框架。它只做三件事：管理 Agent 实例生命周期（创建、挂起、销毁）、维护共享内存（Memory Store，支持 Redis 或 LevelDB）、转发事件（Event Bus，基于 EventEmitter3 封装）。它的设计原则是“最小侵入”——你现有的 Express/Koa/Fastify 服务，只需引入几行代码就能接入。比如在 Express 中：

import { PaperclipRuntime } from '@paperclip/runtime'; const runtime = new PaperclipRuntime({ memory: { type: 'redis', url: 'redis://localhost:6379' }, eventBus: { type: 'in-memory' } // 生产环境建议换为 Redis Stream }); // 挂载到 Express 路由 app.use('/paperclip', runtime.expressMiddleware());

这段代码执行后，你的服务就具备了 Agent 注册、状态查询、事件推送等基础能力。注意：runtime本身不处理任何业务逻辑，它只是“舞台”和“灯光师”。

• @paperclip/orchestrator是中间层，也是 Paperclip 的灵魂所在。它用 TypeScript 编写，核心是一个AgentGraph类，用于定义和编排 Agent 协作流程。一个典型的graph.ts配置长这样：

import { defineGraph } from '@paperclip/orchestrator'; export const loanReviewGraph = defineGraph({ id: 'loan-review-v2', initialState: 'ocr_start', states: { ocr_start: { agent: 'ocr-agent', on: { 'ocr_success': 'pdf_parse', 'ocr_failed': 'manual_review' } }, pdf_parse: { agent: 'pdf-parser', on: { 'parse_success': 'field_check', 'parse_error': 'retry_ocr' } }, field_check: { agent: 'field-validator', on: { 'all_valid': 'compliance_check', 'missing_fields': 'manual_review' } } } });

这个配置文件不是 JSON，而是可执行的 TypeScript 模块。defineGraph函数会在运行时生成一个状态机实例，并自动注册到runtime的事件总线上。orchestrator的价值在于：它把“协作逻辑”从代码里抽离成声明式配置，让非开发人员（如业务分析师）也能参与流程设计。我实测过，一个熟悉 YAML 的风控专员，经过 2 小时培训就能修改on规则，调整异常分支走向。

• @paperclip/dashboard是最上层，一个标准的 Vite + React 18 应用。它通过 WebSocket 连接到runtime的/ws端点，实时订阅所有 Agent 的state_change、message_sent、error_thrown事件。Dashboard 不渲染任何业务 UI，只提供三类视图：① Graph View（可视化展示当前运行的 AgentGraph 状态流）；② Trace View（按时间轴展开每条消息的完整链路，包括输入、输出、耗时、Token 数）；③ Memory View（查看某个会话 ID 下的所有共享内存快照）。这个设计很克制——它不试图做“低代码平台”，而是做“可观测性基础设施”。我在客户现场部署后，运维同事第一次看到 Trace View 里清晰标出“OCR 耗时 3.2s，其中 2.8s 在等待 GPU 显存释放”，立刻定位到显卡驱动问题，比以前靠日志 grep 快了 10 倍。

提示：Paperclip 的 Dashboard 默认不包含身份认证，生产环境必须前置 Nginx 或 Cloudflare Access 做鉴权。官方文档明确警告：“Dashboard 是调试工具，不是用户界面”。

2.2 为什么选 Node.js 而不是 Python 或 Rust？

热词里node.js出现频次远超python或rust，这不是偶然。Paperclip 选择 Node.js 有三个硬性理由：

第一，事件驱动天然匹配 Agent 协作模型。Agent 之间的通信本质是异步事件（event）：一个 Agent 发送field_check_request，另一个监听该事件并响应field_check_result。Node.js 的 Event Loop 和 Promise 链，比 Python 的 asyncio 更轻量、更易调试。我对比过同等规模的 AgentGraph 在 Node.js 和 Python（FastAPI + Celery）下的表现：Node.js 平均事件延迟 12ms，Python 为 47ms（Celery broker 开销大）；且 Node.js 的堆栈追踪能精准定位到on: 'ocr_failed'这一行，Python 的 traceback 常卡在 Celery worker 进程里。

第二，生态无缝对接 OpenClaw。OpenClaw 的核心是openclaw-cli，一个用 Node.js 编写的命令行工具，用于一键启动本地模型服务（Ollama）、向量数据库（Chroma）、工具函数（Python 脚本封装为 HTTP 接口）。Paperclip 的orchestrator直接调用openclaw-cli的子进程 API，启动一个ocr-agent时，实际执行的是：

openclaw-cli start --tool ocr --model llava:7b --port 8081

如果 Paperclip 用 Python 写，就得用subprocess.Popen去调用 Node.js CLI，多一层序列化/反序列化开销。而同为 Node.js，Paperclip 可以直接require('openclaw-cli')，共享同一套配置文件（openclaw.config.js），连端口冲突检测都复用 OpenClaw 的port-checker模块。

第三，前端同构降低学习成本。Paperclip 的 Dashboard 是 React，而很多团队的内部工具前端也是 React。当后端工程师需要调试一个 Agent 异常时，他可以直接打开浏览器 DevTools，输入window.paperclip.runtime.getState('session-abc123')查看内存状态——因为 Dashboard 和 Runtime 共享同一套 TypeScript 类型定义（@paperclip/types包）。这种“前后端类型一致”的体验，在 Python/Java 后端 + React 前端的组合里是奢望。

注意：Paperclip 官方明确不支持 Node.js < 18.17。原因是其runtime使用了stream/web标准 API（ReadableStream.from），而该 API 在 Node.js 18.17 才稳定。我试过强行降级到 18.13，memory.store的批量写入会随机丢数据——这是底层 Stream 实现的 bug，不是 Paperclip 的问题。

2.3 React Dashboard 如何与 OpenClaw 的本地服务打通？

热词中openclaw ubuntu安装教程、openclaw本地一键部署高频出现，说明用户痛点是“本地部署难”。Paperclip 的 Dashboard 正是为解决这个痛点而生。

OpenClaw 默认启动的服务是http://localhost:3000（Web UI）和http://localhost:8000（API），但它的 Agent 实例（如ocr-agent）是动态分配端口的（比如http://localhost:8081）。传统方案是让用户手动在 Dashboard 里填一堆 IP 和端口，极其反人类。Paperclip 的解法是：让 OpenClaw 主动向 Paperclip 注册。

具体流程如下：

1. 用户执行openclaw-cli start --tool ocr，OpenClaw 启动一个 Python FastAPI 服务（端口 8081）；
2. 该服务在启动完成后，自动向 Paperclip Runtime 的/register端点发送 POST 请求，携带自身元数据（{ "id": "ocr-agent", "type": "tool", "endpoint": "http://localhost:8081", "capabilities": ["image_to_text"] }）；
3. Paperclip Runtime 将该元数据存入 Redis 的agent:registryHash 表；
4. Dashboard 的AgentSelector组件通过 WebSocket 订阅agent:registered事件，实时更新下拉菜单。

这个机制的关键在于：注册是单向的、无状态的。OpenClaw 不需要知道 Paperclip 的内部结构，Paperclip 也不需要主动扫描端口。我部署过 12 个 OpenClaw Agent（OCR、PDF 解析、Excel 提取、SQL 查询、邮件发送……），Dashboard 的 Agent 列表始终准确，从未出现“僵尸 Agent”（即服务已死但列表还显示在线）。

实操中有个细节：OpenClaw 的注册请求默认超时 5 秒。如果 Paperclip Runtime 还没启动，OpenClaw 会重试 3 次（间隔 2 秒），然后静默退出。这个策略很务实——它避免了“启动顺序依赖”这个经典运维难题。你可以先npm run dev启动 Paperclip，再一个个openclaw-cli start，完全不用记先后。

3. 实操部署全链路：从零开始搭建一个可调试的 Loan Review Agent 系统

3.1 环境准备：Node.js 18.20.4 LTS + Ubuntu 22.04（非 CentOS 7.9）

热词里centos 7.9 node.js安装部署出现多次，但必须明确告知：Paperclip 不支持 CentOS 7.9。原因很现实：CentOS 7.9 默认的 OpenSSL 版本是 1.0.2k，而 Node.js 18.20.4 要求 OpenSSL ≥ 1.1.1。强行编译会报SSL_CTX_set_ciphersuites未定义错误。我试过升级 OpenSSL，结果导致系统yum崩溃——这是 CentOS 7 的经典兼容性陷阱。

推荐环境：Ubuntu 22.04（LTS）或 macOS Monterey+。以下是 Ubuntu 22.04 的标准安装步骤（非apt install nodejs，那是旧版）：

# 1. 清理可能存在的旧 Node.js sudo apt remove nodejs npm sudo apt autoremove # 2. 添加 NodeSource 官方源（Node.js 18.x） curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - # 3. 安装（自动解决 OpenSSL 依赖） sudo apt update sudo apt install -y nodejs # 4. 验证版本（必须是 18.20.4） node --version # v18.20.4 npm --version # 9.8.1（随 Node.js 18.20.4 自带） # 5. 设置 npm 全局路径（避免权限问题） mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc

注意：node.js 22.12+热词虽高，但 Paperclip 当前（v0.8.3）尚未适配 Node.js 22。其runtime依赖的undiciHTTP 客户端在 Node.js 22 下有连接池泄漏 Bug。官方 GitHub Issue #422 明确标注 “target: v0.9.0 for Node.js 22 support”。所以，严格锁定 18.20.4 是稳妥之选。

3.2 安装 Paperclip Runtime 与 Orchestrator

Paperclip 不提供全局 CLI，所有操作基于npx或本地npm install。这是刻意设计——避免全局污染，方便多项目隔离。

# 创建项目目录 mkdir loan-review-system && cd loan-review-system # 初始化 npm（使用 --yes 跳过交互） npm init --yes # 安装核心包（注意：orchestrator 是可选的，但强烈建议装） npm install @paperclip/runtime @paperclip/orchestrator # 创建入口文件 server.js cat > server.js << 'EOF' import { PaperclipRuntime } from '@paperclip/runtime'; import { loadGraph } from '@paperclip/orchestrator'; import express from 'express'; // 1. 初始化 Runtime const runtime = new PaperclipRuntime({ memory: { type: 'redis', url: 'redis://localhost:6379' }, eventBus: { type: 'redis', url: 'redis://localhost:6379' } }); // 2. 加载 AgentGraph（稍后创建） const graph = await loadGraph('./graphs/loan-review-graph.ts'); // 3. 创建 Express 服务 const app = express(); app.use(express.json()); app.use('/paperclip', runtime.expressMiddleware()); // 4. 启动 const PORT = 3001; app.listen(PORT, () => { console.log(`Paperclip Runtime running on http://localhost:${PORT}`); }); EOF # 创建 graphs 目录和配置文件 mkdir graphs cat > graphs/loan-review-graph.ts << 'EOF' import { defineGraph } from '@paperclip/orchestrator'; export const loanReviewGraph = defineGraph({ id: 'loan-review-v2', initialState: 'ocr_start', states: { ocr_start: { agent: 'ocr-agent', on: { 'ocr_success': 'pdf_parse', 'ocr_failed': 'manual_review' } }, pdf_parse: { agent: 'pdf-parser', on: { 'parse_success': 'field_check', 'parse_error': 'retry_ocr' } }, field_check: { agent: 'field-validator', on: { 'all_valid': 'compliance_check', 'missing_fields': 'manual_review' } } } }); EOF

此时，server.js还不能运行，因为缺少 Redis 和 OpenClaw。但结构已清晰：runtime管理状态，orchestrator加载图谱，express暴露接口。

3.3 部署 OpenClaw 并注册 Agent

OpenClaw 的安装比 Paperclip 更简单，因为它本质是个 CLI 工具。热词openclaw ubuntu安装教程的核心就是这一行：

# 安装 OpenClaw（需要先安装 Ollama） curl -fsSL https://ollama.com/install.sh | sh npm install -g openclaw-cli # 验证 openclaw-cli --version # 0.5.2+

接下来，为 Paperclip 注册三个核心 Agent：

# 1. 启动 OCR Agent（基于 LLaVA 模型） openclaw-cli start --tool ocr --model llava:7b --port 8081 # 2. 启动 PDF 解析 Agent（基于 PyMuPDF） openclaw-cli start --tool pdf-parse --port 8082 # 3. 启动字段校验 Agent（自定义 Python 脚本） # 先创建脚本 cat > validate_fields.py << 'EOF' from fastapi import FastAPI import uvicorn import json app = FastAPI() @app.post("/validate") def validate(data: dict): # 简单示例：检查是否含 "id_card" 和 "income_proof" required = ["id_card", "income_proof"] missing = [f for f in required if f not in data] if missing: return {"status": "failed", "missing": missing} return {"status": "success", "validated": True} if __name__ == "__main__": uvicorn.run(app, host="0.0.0.0:8083", port=8083) EOF # 用 OpenClaw 封装为 Agent openclaw-cli start --tool custom --script validate_fields.py --port 8083

执行完这三行openclaw-cli start，你会看到终端输出类似：

[INFO] Agent registered: ocr-agent -> http://localhost:8081 [INFO] Agent registered: pdf-parser -> http://localhost:8082 [INFO] Agent registered: field-validator -> http://localhost:8083

这就是 Paperclip Runtime 的agent:registry数据来源。你可以用redis-cli验证：

redis-cli hgetall "agent:registry" # 输出应包含三个 key-value 对

3.4 启动 Paperclip Dashboard 并接入

Paperclip Dashboard 是独立的 React 应用，需单独克隆和启动：

# 克隆官方 Dashboard（不要用 npm create，官方未发布模板） git clone https://github.com/paperclip-ai/dashboard.git cd dashboard # 安装依赖（Vite + React 18） npm install # 修改配置：指向你的 Paperclip Runtime # 编辑 src/config.ts # const API_BASE_URL = 'http://localhost:3001/paperclip'; # const WS_URL = 'ws://localhost:3001/paperclip/ws'; npm run dev

启动后，访问http://localhost:5173，你会看到 Dashboard 界面。左上角显示Connected to http://localhost:3001，下方 Agent 列表应显示ocr-agent、pdf-parser、field-validator三个在线状态。

现在，发起一个测试请求，触发整个协作流：

# 向 Paperclip Runtime 发送初始事件 curl -X POST http://localhost:3001/paperclip/events \ -H "Content-Type: application/json" \ -d '{ "type": "start_review", "payload": { "session_id": "test-001", "document_url": "https://example.com/loan-app.pdf" } }'

Dashboard 的 Graph View 会立即动画显示：ocr_start节点高亮 →ocr-agent发送ocr_success事件 →pdf_parse节点高亮 → 依此类推。Trace View 会列出每一步的耗时和返回值。这才是真正的“所见即所得”调试。

实操心得：第一次调试时，我遇到pdf-parser返回parse_error，但 Dashboard 的 Trace View 显示该事件未被loan-review-graph的on: 'parse_error'捕获。排查发现，pdf-parser发送的事件类型是parsing_error（多了一个 'g'），而图谱里写的是parse_error。Paperclip 的设计是“事件类型严格匹配”，不会做模糊匹配。这个细节在文档里没强调，但却是高频踩坑点——建议所有 Agent 发送事件前，先用curl http://localhost:8082/debug/events查看其支持的事件清单。

4. 核心技术点详解：AgentGraph 状态机、内存共享、事件总线的实现原理

4.1 AgentGraph 状态机：如何用 TypeScript 实现可扩展的协作协议？

Paperclip 的defineGraph看似简单，其背后是精心设计的状态机引擎。我们来拆解loan-review-graph.ts的编译过程：

当你执行loadGraph('./graphs/loan-review-graph.ts')，@paperclip/orchestrator实际做了三件事：

1. AST 解析：用@swc/core（比 Babel 更快）解析 TypeScript 文件，提取defineGraph调用的参数对象；
2. 状态图验证：检查initialState是否在states中存在；检查每个on键是否指向一个合法的state；检查是否有循环引用（如A → B → A）；
3. 运行时编译：生成一个GraphInstance类，其核心方法是transition(stateId, event)：

class GraphInstance { private currentState: string; private stateMap: Map<string, StateConfig>; transition(stateId: string, event: string): void { const state = this.stateMap.get(stateId); if (!state) throw new Error(`State ${stateId} not found`); const next = state.on[event]; if (!next) { // 未定义的事件，触发兜底行为（如记录告警） this.emit('unhandled_event', { stateId, event }); return; } // 执行 Agent 调用（这里是关键） this.callAgent(state.agent, { session_id: this.sessionId, event: event, payload: this.memory.get(this.sessionId) }); this.currentState = next; } }

这个transition方法的精妙之处在于：它不阻塞主线程。callAgent是一个异步函数，内部用fetch调用 Agent 的 HTTP 接口，并设置 30 秒超时。如果 Agent 响应慢，transition会立即返回，等待 Agent 主动推送event回来。这实现了“事件驱动”的真正含义——Paperclip 从不轮询 Agent 状态，而是被动接收事件。

更关键的是，GraphInstance支持动态重载。你修改loan-review-graph.ts后，无需重启 Node.js 服务，只需向/paperclip/graphs/reload发送 POST 请求，orchestrator会重新解析文件并替换运行时实例。我在客户现场做过测试：一个正在处理 200 份贷款材料的会话，重载图谱后，新会话走新逻辑，老会话继续按旧逻辑完成——零中断。

4.2 共享内存（Memory Store）：LevelDB vs Redis 的选型实战

Paperclip 的memory配置支持level（LevelDB）和redis两种后端。热词里没提 LevelDB，但它是 Paperclip 的默认选项，值得深挖。

LevelDB 是一个嵌入式键值存储，优势是零依赖、启动快、读写极快（微秒级）。Paperclip 用它存储会话内存（Session Memory），结构是：

Key: memory:session:test-001 Value: { "ocr_result": "...", "pdf_parsed": { "name": "张三", "amount": 50000 }, "field_validation": { "status": "success" } }

我用wrk压测过 LevelDB 和 Redis 在 100 并发下的表现：

• LevelDB：平均写入延迟 0.8ms，99% < 2ms；
• Redis（本地 loopback）：平均写入延迟 3.2ms，99% < 8ms。

差距明显。但 LevelDB 的致命缺陷是不支持多进程共享。如果你用pm2启动 4 个 Paperclip 进程，每个进程都有自己的 LevelDB 实例，会话内存就分裂了。

Redis 则天然支持多进程。Paperclip 的 Redis 实现用了redis包的pipeline批量操作，确保memory.set(sessionId, data)是原子的。其get方法还做了缓存穿透防护：如果 Key 不存在，会先查一次 Redis，再 fallback 到一个内存 LRU Cache（大小 1000 条），避免雪崩。

我的选型建议：

• 开发/测试环境：用 LevelDB，启动快、调试直观（直接ls ./data/memory就能看到文件）；
• 生产环境：必须用 Redis，且建议用 Redis Cluster 模式，避免单点故障。

注意：Paperclip 的memory不是通用 KV 存储，它只存会话相关数据。业务数据（如用户信息、合同原文）必须存在你自己的数据库里。Paperclip 文档反复强调：“Memory is ephemeral, not authoritative”。

4.3 事件总线（Event Bus）：为什么放弃 Kafka/RabbitMQ 选择 Redis Stream？

Paperclip 的eventBus配置支持in-memory、redis（Stream）、kafka。但官方文档和所有热词教程都只提 Redis Stream，原因很实在。

Kafka 和 RabbitMQ 是企业级消息队列，功能强大但重。Paperclip 的事件场景有三个特点：① 事件量不大（单日百万级，非十亿级）；② 消费者固定（主要是 Dashboard 和日志服务）；③ 需要严格有序（ocr_success必须在pdf_parse之前）。

Redis Stream 完美匹配：

• 天然有序：Stream 的每个消息有唯一 ID（毫秒时间戳+序列号），XRANGE命令保证严格 FIFO；
• 多消费者组：Dashboard 用一个消费者组（dashboard-group），日志服务用另一个（logger-group），互不干扰；
• 断线重连：Dashboard 断开 WebSocket 后重连，可指定从上次 ID 继续消费，不丢事件。

Paperclip 的 Redis Stream 实现代码仅 87 行（runtime/src/eventbus/redis.ts），核心是：

// 发布事件 async publish(event: PaperclipEvent) { await this.client.xadd('paperclip:events', '*', 'type', event.type, 'payload', JSON.stringify(event.payload), 'timestamp', Date.now().toString() ); } // 订阅（Dashboard 使用） async subscribe(groupId: string, consumerName: string) { // 创建消费者组（如果不存在） try { await this.client.xgroupCreate('paperclip:events', groupId, '$', 'MKSTREAM'); } catch (e) { // 组已存在，忽略 } // 从最新消息开始读取 const messages = await this.client.xreadgroup( groupId, consumerName, { key: 'paperclip:events', id: '>' } ); }

这个实现没有用 Kafka 的分区（partition）概念，因为 Paperclip 的事件不需要水平扩展——所有事件都属于同一个逻辑流。用 Redis Stream，部署成本从“3 台 Kafka 服务器”降到“1 台 Redis”，运维复杂度直线下降。

5. 常见问题与避坑指南：来自 12 个真实部署现场的血泪总结

5.1 “Agent 显示在线，但事件不触发” —— 网络策略与 CORS 的隐形杀手

这是部署成功率最低的问题，占我处理工单的 43%。现象：Dashboard 显示ocr-agent状态为绿色（online），但发送start_review事件后，ocr_start节点毫无反应。

根本原因有两个，且常同时发生：

第一，防火墙拦截了 Agent 的回调端口。Paperclip Runtime 启动在localhost:3001，但它需要主动调用ocr-agent的http://localhost:8081/process。如果ocr-agent运行在另一台机器（比如 Docker 容器），localhost就指错了。解决方案：在openclaw-cli start时指定--host 0.0.0.0，并确保容器端口映射正确：

# 错误：docker run -p 8081:8081 ...（只映射了 8081） # 正确：docker run -p 8081:8081 -p 3001:3001 ...（Runtime 也要暴露）

第二，CORS 阻止了 Dashboard 的 WebSocket 连接。Paperclip Dashboard 的ws://localhost:3001/paperclip/ws请求，如果 Runtime 服务没配置 CORS，Chrome 会静默失败。解决方案：在 Express 中添加 CORS 中间件：

import cors from 'cors'; // 在 app.use() 之前 app.use(cors({ origin: ['http://localhost:5173'], // Dashboard 地址 credentials: true }));

实操心得：我写了个一键检测脚本check-network.sh，它会自动测试：① Runtime 是否能 curl 通所有 Agent；② Agent 是否能 curl 通 Runtime；③ Dashboard 的 WebSocket 是否能建立。每次部署新环境，先跑这个脚本，5 分钟定位 90% 的网络问题。

5.2 “Trace View 里看不到完整链路” —— Agent 事件命名不规范的代价

热词react + sse/websocket 轮询文件变化暗示了前端对实时性的渴求，但 Paperclip 的 Trace View 依赖 Agent 主动上报事件。如果 Agent 发送的事件类型不规范，链路就断了。

常见不规范命名：

• ocr_successvsocr-success（Paperclip 要求下划线，不接受短横线）；
• pdf_parsing_donevsparse_success（图谱里写parse_success，Agent 却发pdf_parsing_done）；
• error（太泛，Paperclip 推荐ocr_timeout、ocr_invalid_format等具体类型）。

Paperclip 的处理策略是“静默丢弃”——不报错，也不记录。这很反直觉，但设计如此：避免因一个 Agent 的错误事件拖垮整个系统。

解决方案：强制所有 Agent 在启动时，向 Runtime 的/debug/schema端点注册其支持的事件清单。Paperclip 会校验该清单与AgentGraph的on字段是否匹配，不匹配则拒绝注册。我在validate_fields.py里加了这行：

# 在 FastAPI 启动后 @app.on_event("startup") async def register_events(): async with httpx.AsyncClient() as client: await client.post("http://localhost:3001/paperclip/debug/schema", json={ "agent_id": "field-validator", "events": ["all_valid", "missing_fields", "validation_error"] })

这样，Dashboard 的 Agent 列表会显示每个 Agent 的“支持事件”，调试时一目了然。

5.3 “内存占用飙升，Node.js 进程 OOM” —— 会话内存泄漏的根因分析

Paperclip 的memory默认永不过期，这是为调试友好。但在生产环境，大量会话积累会导致内存爆炸。热词react native 启动白屏虽是前端问题，但背后逻辑相通：资源不释放，必然崩溃。

Paperclip 提供了两种清理机制：

第一，自动 TTL（Time-To-Live）。在PaperclipRuntime构造函数中设置：

const runtime = new PaperclipRuntime({ memory: { type: 'redis', url: 'redis://localhost:6379', ttl: 3600 // 1 小时后自动过期 } });

第二，手动清理 API。向/paperclip/memory/clear?session_id=test-001发送 DELETE 请求，立即清除指定会话。

但更深层的问题是：Agent 自身的内存泄漏。比如ocr-agent用 Python 的PIL.Image加载图片