1. 项目概述OpenClaw Node.js 客户端如果你正在 Node.js 生态里折腾 AI 应用想让你的程序能跟一个“有记忆、会思考、能调用工具”的 AI 智能体对话而不是每次交互都像一次性的问答那么openclaw-node这个库很可能就是你正在找的“连接器”。简单来说它就是一个官方出品的 Node.js SDK让你能用几行代码通过 WebSocket 连接到本地的 OpenClaw Gateway从而与运行在 Gateway 上的 AI 智能体进行交互。这相当于给你的 Node.js 应用装上了一根直接通向 AI 大脑的“神经导管”。这个库的核心价值在于它把 OpenClaw 那套复杂的、基于 WebSocket 的私有协议包括握手、认证、心跳、消息分片等全部封装了起来对外暴露出一套简洁、直观的 Promise 和 AsyncIterator API。你不用关心底层协议帧怎么组也不用处理断线重连的脏活只需要关注业务逻辑发送消息接收回复。无论是想构建一个支持流式输出的 CLI 聊天工具还是想为你的 Express 后端增加一个 AI 助手接口甚至是开发一个监控智能体状态的管理面板openclaw-node都能提供稳定、类型安全的基础设施支持。2. 核心概念与架构解析在开始写代码之前理解 OpenClaw 的几个核心概念至关重要。这能帮你更好地设计应用结构而不是仅仅停留在“调通接口”的层面。2.1 核心组件关系图整个 OpenClaw 的运作可以看作一个三层架构你的应用 (Your App)使用openclaw-node客户端。OpenClaw Gateway一个本地运行的服务作为智能体的“运行沙盒”和“调度中心”。AI 智能体 (Agents)运行在 Gateway 内的、具备特定能力和记忆的 AI 实例。openclaw-node的作用就是打通第一层和第二层。它通过 WebSocket 与 Gateway 建立长连接所有与智能体的对话、配置管理、状态查询都通过这个连接进行。2.2 关键实体详解Gateway网关这是整个系统的基石。它是一个本地服务器进程你可以通过npm install -g openclaw安装并用openclaw gateway start启动。它默认监听ws://localhost:18789。Gateway 负责管理所有智能体的生命周期、维护会话状态、处理工具调用并对外提供统一的 WebSocket 接口。你可以把它想象成一个 AI 智能体的“操作系统”。Agent智能体这是具体的“AI 员工”。每个智能体在 Gateway 中都有一个唯一的agentId。你可以为不同的智能体配置不同的“人格”系统提示词、赋予不同的工具如网络搜索、代码执行、数据库查询等以及设定不同的记忆策略。你的应用可以通过指定agentId来与特定的智能体对话。Session会话这是对话的上下文线程。每个会话有一个唯一的sessionKey。它的妙处在于持久化。即使你的客户端断开连接再重连只要使用相同的sessionKey就能继续之前的对话智能体还记得之前聊过的所有内容。这对于构建需要长期记忆的助手型应用比如个人学习伴侣、项目进度跟踪机器人是核心功能。Token令牌一个可选的认证字符串用于保护你的 Gateway。如果你在启动 Gateway 时设置了环境变量OPENCLAW_GATEWAY_TOKEN那么任何客户端包括openclaw-node在连接时都必须提供相同的令牌否则连接会被拒绝。这对于将 Gateway 暴露在内部网络非本地主机时非常重要。3. 环境准备与快速上手理论说再多不如跑通一行代码。我们从一个最简单的例子开始确保你的环境一切就绪。3.1 前置条件检查与 Gateway 启动首先你需要一个正在运行的 OpenClaw Gateway。如果你的机器上还没有按照以下步骤操作# 1. 全局安装 OpenClaw CLI 工具 npm install -g openclaw # 2. 启动 Gateway 服务 openclaw gateway start执行成功后你应该能在终端看到类似Gateway started on ws://localhost:18789的日志。这意味着 Gateway 已经在后台运行并等待连接。注意Gateway 启动时会加载其配置文件通常位于~/.openclaw/config.json。如果你需要配置特定的模型如 OpenAI GPT-4、Claude 等或工具需要先编辑这个配置文件并重启 Gateway。openclaw-node客户端本身不负责模型配置它只负责通信。3.2 客户端安装与基础连接接下来在你的 Node.js 项目目录中安装openclaw-node客户端库。npm install openclaw-node关于 WebSocket 依赖的特别说明该库在 Node.js 22 或更高版本上可以开箱即用因为它使用了 Node.js 内置的 WebSocket 客户端。如果你的项目运行在 Node.js 20 或 21 版本你需要额外安装ws库npm install openclaw-node ws库的内部逻辑会自动检测并使用已安装的ws。现在创建一个最简单的脚本文件例如demo.js写入以下代码import { OpenClawClient } from openclaw-node; async function main() { // 1. 创建客户端实例指向本地默认 Gateway 地址 const client new OpenClawClient({ url: ws://localhost:18789, // 如果启动 Gateway 时设置了 OPENCLAW_GATEWAY_TOKEN这里需要填入相同的值 // token: process.env.OPENCLAW_GATEWAY_TOKEN, }); // 2. 建立连接 console.log(正在连接 Gateway...); await client.connect(); console.log(连接成功); // 3. 发送一条消息并流式接收回复 console.log(提问今天天气怎么样); const stream client.chat(今天天气怎么样); for await (const chunk of stream) { if (chunk.type text) { // 流式输出每个文本块 process.stdout.write(chunk.text); } else if (chunk.type done) { console.log(\n--- 回答完毕 ---); } } // 4. 断开连接 await client.disconnect(); console.log(连接已断开。); } main().catch(console.error);用node demo.js运行它。如果一切正常你将看到客户端成功连接并向默认的智能体发送了消息。智能体的回复会以流式逐词或逐句的方式打印在终端上。这个简单的流程涵盖了最核心的“连接-对话-断开”生命周期。4. 客户端 API 深度使用指南掌握了基础连接后我们来深入探索openclaw-node提供的丰富 API这些 API 是你构建复杂应用的基石。4.1 客户端配置与连接管理创建OpenClawClient实例时除了必填的url还有几个关键配置项const client new OpenClawClient({ url: ws://localhost:18789, // 必须。Gateway 的 WebSocket 地址。 token: your-secret-token-here, // 可选。与 Gateway 设置的认证令牌一致。 autoReconnect: true, // 可选默认 true。是否在连接断开时自动重连。 maxReconnectAttempts: 10, // 可选默认 10。自动重连的最大尝试次数。达到后触发 disconnected 事件。 });连接事件监听在实际应用中监听连接状态变化是必不可少的这能让你在 UI 上显示连接状态或在断线时进行降级处理。client.on(connected, (info) { console.log(已连接到 Gateway (协议版本: ${info.protocolVersion})); }); client.on(disconnected, ({ reason }) { console.warn(连接断开原因: ${reason}); // 可以在这里触发用户提示或尝试手动重连 }); client.on(error, (err) { console.error(客户端发生错误:, err); // 网络错误、协议错误等会在这里触发 });手动重连策略虽然autoReconnect在大多数网络波动情况下很好用但在某些场景如令牌过期、Gateway 重启后地址变更你可能需要更精细的控制。我通常的做法是结合事件监听和手动connect调用。let reconnectTimer: NodeJS.Timeout; client.on(disconnected, ({ reason }) { if (reason auth_failed) { console.error(认证失败请检查令牌。将在10秒后尝试重连...); reconnectTimer setTimeout(() client.connect(), 10000); } else if (reason manual) { console.log(手动断开连接。); } else { // 网络等原因依赖 autoReconnect console.log(连接断开 (${reason})自动重连已启用。); } }); // 在适当的时候清除定时器比如应用退出时 process.on(SIGINT, () { clearTimeout(reconnectTimer); client.disconnect(); });4.2 对话模式流式与非流式openclaw-node提供了两种对话方式适应不同场景。流式对话 (client.chat())这是与 AI 交互最自然的方式尤其适合需要实时显示、长时间生成的场景。它返回一个异步迭代器 (AsyncIterator)。const stream client.chat(请用中文写一首关于秋天的五言绝句。, { // 可选指定会话实现连续对话 sessionKey: my-poetry-session, // 可选指定与哪个智能体对话 agentId: creative-writer, }); for await (const chunk of stream) { switch (chunk.type) { case text: // 最常见的类型AI 生成的文本片段 process.stdout.write(chunk.text); break; case tool_use: // AI 决定使用一个工具。chunk.text 通常是工具名和参数。 console.log(\n[智能体正在使用工具: ${chunk.text}]); break; case tool_result: // 工具执行完成并返回了结果。 console.log(\n[工具执行结果: ${chunk.text}]); break; case done: // 整个回复流结束。 console.log(\n--- 生成结束 ---); // 此时可以做一些清理工作或者更新 UI 状态。 break; default: // 处理其他未知的 chunk 类型未来协议扩展 console.log(收到未知块类型:, chunk); } }非流式对话 (client.chatSync())当你不需要中间过程只关心最终结果时例如在后端 API 中处理一个简单的问答这个方法更简洁。它直接返回一个 Promise解析为完整的回复字符串。try { const fullResponse await client.chatSync(计算一下 15 的平方根是多少); console.log(AI 回复:, fullResponse); // 直接得到完整字符串 } catch (error) { console.error(对话失败:, error); }实操心得选择哪种模式用chat()流式CLI 工具、聊天界面、需要显示“正在思考”状态的应用、生成长文如报告、代码时给用户即时反馈。用chatSync()非流式后端 API 接口、定时任务、单元测试、对响应时间要求不高且回复较短的场景。它的代码更简洁错误处理也更直接一个try-catch包住即可。4.3 会话管理实战会话管理是构建有状态 AI 应用的关键。openclaw-node通过client.sessions对象提供了完整的会话 CRUD 操作。创建与延续会话最简单的方式是在chat或chatSync时传入一个sessionKey。如果该sessionKey不存在Gateway 会自动创建如果存在则在该会话的历史基础上继续对话。// 假设这是一个用户支持机器人每个用户一个独立会话 const userId user_12345; const sessionKey support_${userId}; // 第一次交互创建会话 let reply await client.chatSync(我的订单 #1001 发货了吗, { sessionKey }); console.log(首次回复:, reply); // 几分钟后用户再次提问上下文是连贯的 reply await client.chatSync(那预计什么时候能到, { sessionKey }); console.log(后续回复:, reply); // AI 知道“那”指的是上一个订单的物流查询与管理会话你可以列出所有会话或查看特定会话的历史记录这对于实现“历史对话”功能或清理旧会话非常有用。// 列出最近的10个会话 const sessionList await client.sessions.list({ limit: 10 }); console.log(最近会话:, sessionList.sessions.map(s s.key)); // 获取某个会话的详细历史消息 const history await client.sessions.history(sessionKey, { limit: 50 }); console.log(会话 ${sessionKey} 的历史消息数:, history.messages.length); // history.messages 是一个数组包含用户和 AI 的交替消息。会话的生命周期默认情况下会话会持久化在 Gateway 的存储中通常是本地文件。除非手动删除或配置了过期策略否则它们会一直存在。对于内存敏感的生产环境建议定期清理不活跃的会话。// 注意当前版本的 openclaw-node 可能未直接提供删除会话的 API。 // 但你可以通过低级的 client.request 方法或管理 Gateway 的存储文件来实现。 // 这是一个需要根据 Gateway 版本确认的高级操作。5. 高级功能与系统集成除了核心的对话功能openclaw-node还暴露了 Gateway 的管理接口让你能动态调整系统行为。5.1 动态配置管理你可以在运行时读取和修改 Gateway 的配置而无需重启 Gateway 服务。这通过client.config对象实现它采用了乐观锁机制来避免并发修改冲突。// 1. 获取当前配置和它的版本哈希 const current await client.config.get(); console.log(当前配置版本哈希:, current.hash); // current.config 是一个大的 JSON 对象包含了所有 Gateway 设置。 // 2. 使用 JSON Merge Patch 更新部分配置 // 例如动态启用 Telegram 频道 const patch { channels: { telegram: { enabled: true, token: process.env.TELEGRAM_BOT_TOKEN, // 从环境变量读取 token }, }, }; try { await client.config.patch( JSON.stringify(patch), // 要合并的配置片段 current.hash, // 基于哪个版本修改乐观锁 { note: 通过 API 动态启用 Telegram 机器人, restartDelayMs: 2000, // 让 Gateway 在 2 秒后重启相关服务以应用更改 } ); console.log(配置更新成功相关服务将在2秒后重启。); } catch (error: any) { if (error.message.includes(hash mismatch)) { console.error(配置已被其他人修改请重试。); // 最佳实践重新获取最新配置合并你的修改再次尝试 } else { throw error; } } // 3. 完全替换配置 (谨慎使用) // const newFullConfig { ... }; // await client.config.apply(JSON.stringify(newFullConfig), latestHash);注意事项配置更新的副作用修改channels如 Telegram, Slack或agents的配置通常会触发 Gateway 重启对应的服务。restartDelayMs参数给了你一个缓冲期。在生产环境中最好在低峰期进行此类操作并通过client.channels.status()监控服务状态。5.2 频道状态监控与配对管理如果你的 Gateway 配置了像 Telegram、Slack 这样的消息频道你可以通过 API 检查它们的连接状态。const channelStatus await client.channels.status(); console.log(频道状态:, channelStatus); // 输出可能类似: { telegram: { connected: true, botUsername: MyBot }, slack: { connected: false } } if (!channelStatus.telegram?.connected) { console.warn(Telegram 机器人未连接请检查配置和网络。); }对于需要用户授权的频道如 Telegram 私聊机器人首次使用会有“配对”流程。你可以管理这些待处理的配对请求。// 列出 Telegram 频道所有待处理的配对请求 const pendingRequests await client.pairing.list(telegram); console.log(待处理配对:, pendingRequests); if (pendingRequests.length 0) { const firstRequest pendingRequests[0]; // 在真实应用中这里可能是你的管理后台审核逻辑 console.log(用户 ${firstRequest.userId} 请求配对。); // 批准配对 await client.pairing.approve(telegram, firstRequest.requestId); console.log(配对已批准。); }5.3 处理网关事件Gateway 除了对话还会产生各种系统事件例如工具执行需要批准如果配置了审核、智能体上线/下线等。你可以监听这些事件来构建更交互式的应用。client.on(event, (event) { console.log([网关事件] 类型: ${event.event}); switch (event.event) { case exec_approval_required: // 当 AI 尝试执行一个需要人工批准的工具如“发送邮件”时触发 const { approvalId, sessionKey, toolCall } event.payload; console.log(会话 ${sessionKey} 请求执行工具:, toolCall.name); console.log(参数:, toolCall.arguments); // 模拟一个管理界面询问管理员是否批准 // 在实际应用中这里可以触发一个通知或更新数据库状态。 setTimeout(async () { try { // 假设我们自动批准 await client.request(exec_approval, { approvalId, approved: true }); console.log(已批准执行请求 ${approvalId}); } catch (e) { console.error(批准失败:, e); } }, 2000); break; case agent_presence: // 智能体状态变化如启动、停止 console.log(智能体 ${event.payload.agentId} 状态变为: ${event.payload.status}); break; // 可以处理其他事件类型... default: console.log(收到事件详情:, event.payload); } });6. 实战项目案例构建一个 Express AI 问答 API让我们把这些知识点串联起来构建一个实用的后端服务。这个服务提供一个 RESTful API允许前端通过发送问题获取 AI 助手的回答并支持基于用户 ID 的会话隔离。项目结构openclaw-api/ ├── src/ │ ├── app.js # Express 应用主文件 │ ├── openclaw-client.js # OpenClaw 客户端封装 │ └── routes/ │ └── chat.js # 聊天 API 路由 ├── .env # 环境变量 ├── package.json └── README.md第一步封装 OpenClaw 客户端 (src/openclaw-client.js)为了避免在每次请求时都创建新连接我们创建一个单例客户端并加入简单的连接池和错误恢复逻辑。import { OpenClawClient } from openclaw-node; class OpenClawService { constructor() { this.client null; this.isConnecting false; this.connectionPromise null; } async getClient() { // 如果已有连接直接返回 if (this.client?.isConnected) { return this.client; } // 如果正在连接中等待同一个 Promise if (this.isConnecting) { return this.connectionPromise.then(() this.client); } // 发起新连接 this.isConnecting true; this.connectionPromise this.connect(); try { await this.connectionPromise; return this.client; } finally { this.isConnecting false; } } async connect() { this.client new OpenClawClient({ url: process.env.OPENCLAW_GATEWAY_URL || ws://localhost:18789, token: process.env.OPENCLAW_GATEWAY_TOKEN, autoReconnect: true, maxReconnectAttempts: 5, }); // 设置事件监听器 this.client.on(connected, () { console.log([OpenClawService] 已连接到 Gateway); }); this.client.on(disconnected, ({ reason }) { console.warn([OpenClawService] 连接断开: ${reason}); }); this.client.on(error, (err) { console.error([OpenClawService] 客户端错误:, err); }); await this.client.connect(); console.log([OpenClawService] 连接初始化完成); } // 提供一个干净的关闭方法 async disconnect() { if (this.client) { await this.client.disconnect(); this.client null; } } } // 导出单例实例 export const openClawService new OpenClawService();第二步创建聊天 API 路由 (src/routes/chat.js)这个路由处理/ask和/ask/stream两个端点分别对应同步回答和流式回答。import express from express; import { openClawService } from ../openclaw-client.js; const router express.Router(); // 同步问答接口 router.post(/ask, express.json(), async (req, res) { const { question, userId, agentId } req.body; if (!question) { return res.status(400).json({ error: 缺少问题内容 (question) }); } try { const client await openClawService.getClient(); // 为每个用户生成独立的会话 Key实现上下文隔离 const sessionKey userId ? api_user_${userId} : api_anon_${Date.now()}; const answer await client.chatSync(question, { sessionKey, agentId: agentId || undefined, // 可指定智能体否则用默认 }); res.json({ success: true, data: { answer, sessionKey, // 返回 sessionKey前端可用于后续连续对话 }, }); } catch (error) { console.error(同步问答失败:, error); res.status(500).json({ success: false, error: AI 服务暂时不可用, details: process.env.NODE_ENV development ? error.message : undefined, }); } }); // 流式问答接口 (Server-Sent Events) router.get(/ask/stream, async (req, res) { const { question, userId, agentId } req.query; if (!question) { return res.status(400).json({ error: 缺少问题内容 (question) }); } // 设置 SSE 相关的响应头 res.setHeader(Content-Type, text/event-stream); res.setHeader(Cache-Control, no-cache); res.setHeader(Connection, keep-alive); res.flushHeaders(); // 立即发送头部建立连接 try { const client await openClawService.getClient(); const sessionKey userId ? api_user_${userId} : api_anon_${Date.now()}; const stream client.chat(question, { sessionKey, agentId }); for await (const chunk of stream) { if (chunk.type text) { // 以 SSE 格式发送文本块 res.write(data: ${JSON.stringify({ type: text, data: chunk.text })}\n\n); } else if (chunk.type done) { res.write(data: ${JSON.stringify({ type: done })}\n\n); break; } // 可以根据需要发送 tool_use, tool_result 等事件 } res.end(); // 流结束 } catch (error) { console.error(流式问答失败:, error); // 发送错误事件 res.write(data: ${JSON.stringify({ type: error, data: Stream failed })}\n\n); res.end(); } }); export default router;第三步组装 Express 应用 (src/app.js)这是应用的主入口集成路由并处理全局错误。import express from express; import chatRouter from ./routes/chat.js; import { openClawService } from ./openclaw-client.js; const app express(); const PORT process.env.PORT || 3000; // 基础中间件 app.use(express.json()); app.use(express.urlencoded({ extended: true })); // 健康检查端点 app.get(/health, (req, res) { res.json({ status: ok, gatewayConnected: openClawService.client?.isConnected || false }); }); // 挂载聊天路由 app.use(/api/chat, chatRouter); // 全局 404 处理 app.use((req, res) { res.status(404).json({ error: 接口不存在 }); }); // 全局错误处理 app.use((err, req, res, next) { console.error(服务器错误:, err); res.status(500).json({ error: 内部服务器错误 }); }); // 启动服务器前先连接 OpenClaw Gateway async function startServer() { try { await openClawService.connect(); app.listen(PORT, () { console.log(AI 问答 API 服务已启动监听端口 ${PORT}); console.log(健康检查: http://localhost:${PORT}/health); console.log(同步问答接口: POST http://localhost:${PORT}/api/chat/ask); console.log(流式问答接口: GET http://localhost:${PORT}/api/chat/ask/stream?question你的问题); }); } catch (error) { console.error(无法连接到 OpenClaw Gateway服务启动失败:, error); process.exit(1); } } // 优雅关闭 process.on(SIGTERM, async () { console.log(收到终止信号正在关闭服务...); await openClawService.disconnect(); process.exit(0); }); startServer();运行与测试确保 OpenClaw Gateway 正在运行。在项目根目录创建.env文件配置必要的环境变量如OPENCLAW_GATEWAY_TOKEN。运行npm start。使用curl或 Postman 测试接口# 测试同步接口 curl -X POST http://localhost:3000/api/chat/ask \ -H Content-Type: application/json \ -d {question: 你好请介绍一下你自己, userId: test_user_1} # 测试流式接口 (使用浏览器或支持 SSE 的工具查看效果更佳) curl -N http://localhost:3000/api/chat/ask/stream?question讲一个简短的笑话userIdtest_user_1这个案例展示了如何将openclaw-node集成到一个生产级的 Node.js 后端服务中涵盖了客户端封装、错误处理、会话管理、以及提供 RESTful 和流式两种 API 模式。你可以在此基础上扩展比如增加请求限流、对话记录存储、多智能体路由等功能。7. 常见问题排查与调试技巧在实际开发和运维中你肯定会遇到各种问题。下面是我在多次集成中总结的一些常见坑点和解决方法。7.1 连接与认证问题问题连接被拒绝或立即断开症状client.connect()抛出错误或连接后立刻触发disconnected事件。排查步骤检查 Gateway 是否运行在终端执行openclaw gateway status。确保状态是running。检查地址和端口确认OpenClawClient构造函数的url与 Gateway 日志中显示的地址一致。默认是ws://localhost:18789。检查防火墙/网络如果 Gateway 运行在另一台机器Docker 容器、远程服务器确保防火墙放行了18789端口并且客户端能访问该地址。检查认证令牌如果 Gateway 配置了OPENCLAW_GATEWAY_TOKEN客户端必须提供完全相同的令牌。一个常见的错误是环境变量值有空格或换行符。建议在代码中打印一下process.env.OPENCLAW_GATEWAY_TOKEN的长度和内容部分打码进行确认。问题连接成功但无法发送消息症状client.isConnected为true但调用chat()或chatSync()时无响应或报错。排查步骤检查协议版本兼容性对照openclaw-node的 README 中的兼容性表格确保你的openclaw-node版本与 OpenClaw Gateway 版本匹配。不匹配的协议版本可能导致通信失败。监听error事件在客户端上添加client.on(error, console.error)看是否有底层 WebSocket 或协议错误被抛出。查看 Gateway 日志运行 Gateway 的终端会输出详细日志。查看是否有关于消息解析错误、智能体加载失败等信息。日志是排查这类问题的第一手资料。7.2 智能体与会话问题问题AI 回复不符合预期或没有使用工具症状能收到回复但内容很奇怪或者明明配置了工具AI 却说自己无法执行。排查步骤确认智能体配置通过client.config.get()查看 Gateway 的配置确认你指定的agentId是否存在并且其systemPrompt和tools配置正确。检查模型配置AI 的行为很大程度上取决于其背后的语言模型。确保 Gateway 配置中指定的模型 API如 OpenAI, Anthropic密钥有效且有足够的额度。启用调试输出在启动 Gateway 时可以尝试增加日志级别例如openclaw gateway start --log-level debug观察 AI 请求和响应的原始内容注意可能包含敏感信息。测试工具调用在chat()的流式输出中监听tool_use和tool_result事件。如果没有触发tool_use可能是提示词未引导 AI 使用工具或者工具的参数定义不清晰。问题会话上下文丢失症状使用相同的sessionKey但 AI 似乎不记得之前的对话。排查步骤确认会话持久化默认 Gateway 将会话存储在本地文件。检查 Gateway 的数据目录如~/.openclaw/data是否有对应的会话文件。如果文件不存在可能是存储路径配置有误或权限问题。检查sessionKey一致性确保在多次请求中传递的sessionKey字符串完全一致包括大小写。一个常见的错误是前后端生成的sessionKey格式不同例如一个用userId另一个用user_id。查看会话历史使用await client.sessions.history(sessionKey)来验证该会话下是否确实存在历史消息。如果返回空数组说明上下文确实丢失了。7.3 性能与稳定性优化连接保活与断线重连虽然库有autoReconnect但在生产环境我建议实现一个更健壮的“心跳检测”机制。let heartbeatInterval: NodeJS.Timeout; client.on(connected, () { console.log(连接建立启动心跳检测); clearInterval(heartbeatInterval); // 清理旧的定时器 heartbeatInterval setInterval(async () { try { // 发送一个无害的低成本请求如获取状态 await client.request(status, {}); } catch (err) { console.warn(心跳检测失败连接可能已失效, err); clearInterval(heartbeatInterval); // 可以在这里触发主动重连逻辑而不是等待 autoReconnect if (!client.isConnected) { client.connect().catch(e console.error(主动重连失败:, e)); } } }, 30000); // 每30秒一次 }); client.on(disconnected, () { clearInterval(heartbeatInterval); });错误处理与降级在关键业务路径上一定要对chat()和chatSync()进行try-catch包装。对于非核心的 AI 功能准备一个友好的降级方案。async function getAIAnswer(question: string, sessionKey: string): Promisestring { try { const client await getOpenClawClient(); // 你的客户端获取函数 return await client.chatSync(question, { sessionKey }); } catch (error) { console.error(AI 服务调用失败使用备用回复, error); // 降级策略返回缓存答案、调用一个更简单的模型、或者返回提示信息 return 抱歉AI助手暂时无法回答。您的问题已记录。原问题${question.substring(0, 50)}...; } }资源清理在应用关闭时务必调用client.disconnect()来优雅地关闭 WebSocket 连接避免资源泄漏和 Gateway 端的僵尸连接。// 例如在 Express 应用关闭时 process.on(SIGINT, async () { console.log(正在关闭 OpenClaw 客户端...); await openClawService.disconnect(); process.exit(0); });通过系统地理解这些概念、API 和实战模式你应该能够 confidently 将openclaw-node集成到你的下一个 Node.js 项目中为它注入强大的、可对话的 AI 能力。记住关键是从小处着手先让基础对话跑起来再逐步引入会话、工具、事件等高级特性。