@ywfe/openclaw-plugin-caryscloud-im 0.0.1

package/INTEGRATION.md

@@ -0,0 +1,544 @@
+# OpenClaw WebSocket 频道插件接入指南
+
+本文档详细说明如何将 WebSocket 频道插件接入到 OpenClaw 系统中。
+
+## 目录
+
+1. [前置要求](#前置要求)
+2. [安装插件](#安装插件)
+3. [配置 OpenClaw](#配置-openclaw)
+4. [启动和验证](#启动和验证)
+5. [WebSocket 服务器要求](#websocket-服务器要求)
+6. [常见问题](#常见问题)
+
+---
+
+## 前置要求
+
+### 系统要求
+
+- Node.js >= 18.0.0
+- pnpm >= 8.0.0 (或 npm/yarn)
+- OpenClaw 已安装并正常运行
+
+### WebSocket 服务器要求
+
+- 支持 WebSocket 协议 (wss:// 或 ws://)
+- 支持 JSON 格式消息
+
+---
+
+## 安装插件
+
+### 方式一：从源码构建
+
+```bash
+# 1. 进入插件目录
+cd /caryscloud-plugin
+
+# 2. 安装依赖
+pnpm install
+
+# 3. 构建插件
+pnpm build
+
+# 4. 链接到 OpenClaw（如果需要）
+# 方式 A: 使用 pnpm link
+pnpm link --global
+cd /path/to/openclaw
+pnpm link --global @ywfe/openclaw-plugin-caryscloud-im
+
+# 方式 B: 直接在 OpenClaw 的 package.json 中引用本地路径
+# 在 OpenClaw 的 package.json 中添加：
+# "dependencies": {
+#   "@ywfe/openclaw-plugin-caryscloud-im": "file:/openclaw/caryscloud-plugin"
+# }
+```
+
+### 方式二：通过 npm/pnpm 安装（如果已发布）
+
+```bash
+cd /path/to/openclaw
+pnpm add @ywfe/openclaw-plugin-caryscloud-im
+```
+
+---
+
+## 配置 OpenClaw
+
+### 1. 找到 OpenClaw 配置文件
+
+OpenClaw 的配置文件通常位于：
+- `~/.openclaw/config.json`
+- 或项目根目录的 `openclaw.config.json`
+
+### 2. 添加 WebSocket 频道配置
+
+在配置文件中添加 `channels.websocket` 配置：
+
+```json
+{
+  "channels": {
+    "caryscloud-im": {
+      "accounts": {
+        "default": {
+          "targetUserId": "your-target-user-id",
+          "wsUrl": "wss://your-websocket-server.com/ws",
+          "uuid": "openclaw-instance-001",
+          "name": "我的 OpenClaw 助手",
+          "avatarUrl": "https://example.com/avatar.png",
+          "authToken": "your-auth-token-here",
+          "enabled": true
+        }
+      }
+    }
+  }
+}
+```
+
+### 3. 配置参数说明
+
+#### 必填参数
+
+| 参数 | 类型 | 说明 | 示例 |
+|------|------|------|------|
+| `targetUserId` | string | 消息接收方的用户 ID | `"user123"` |
+| `wsUrl` | string | WebSocket 服务器地址 | `"wss://api.example.com/ws"` |
+
+#### 可选参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `uuid` | string | 自动生成 | 当前 OpenClaw 实例的唯一标识，留空则从 deviceId 自动生成 |
+| `name` | string | `openclaw_${uuid}` | 显示名称 |
+| `avatarUrl` | string | 默认头像 | 头像 URL |
+| `authToken` | string | - | WebSocket 连接的认证令牌 |
+| `enabled` | boolean | `true` | 是否启用此账号 |
+
+### 4. 多账号配置示例
+
+```json
+{
+  "channels": {
+    "caryscloud-im": {
+      "accounts": {
+        "production": {
+          "targetUserId": "prod-user-001",
+          "wsUrl": "wss://prod.example.com/ws",
+          "authToken": "prod-token-xxx",
+          "enabled": true
+        },
+        "staging": {
+          "targetUserId": "staging-user-001",
+          "wsUrl": "wss://staging.example.com/ws",
+          "authToken": "staging-token-yyy",
+          "enabled": false
+        },
+        "development": {
+          "targetUserId": "dev-user-001",
+          "wsUrl": "ws://localhost:8080/ws",
+          "enabled": true
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## 启动和验证
+
+### 1. 启动 OpenClaw
+
+```bash
+# 启动 OpenClaw
+openclaw start
+
+# 或者如果是开发模式
+openclaw dev
+```
+
+### 2. 验证插件加载
+
+查看 OpenClaw 日志，应该看到类似输出：
+
+```
+[WebSocket] Plugin register() called
+[WebSocket] ✅ Channel registered with OpenClaw
+[WebSocket] Plugin registration complete. Accounts will be initialized by OpenClaw lifecycle.
+[WebSocket] onAccountStart called for account: default
+[WebSocket] Config: uuid=openclaw-instance-001, wsUrl=wss://your-server.com/ws
+[WebSocket] Initializing WebSocket client...
+[WebSocket] Connecting to wss://your-server.com/ws...
+[WebSocket] WebSocket connected
+[WebSocket] Auth message sent
+[WebSocket] Authentication successful
+[WebSocket] Client stored for account default
+[WebSocket] ✅ Account default started successfully
+[WebSocket] Message handlers registered for account default
+```
+
+### 3. 测试消息发送
+
+通过 OpenClaw CLI 或 API 发送测试消息：
+
+```bash
+# 使用 OpenClaw CLI 发送消息
+openclaw send --channel websocket --account default --to user123 --text "Hello, WebSocket!"
+```
+
+### 4. 验证连接状态
+
+```bash
+# 查看频道状态
+openclaw status --channel websocket
+
+# 应该显示：
+# Channel: websocket
+# Account: default
+# Status: ✅ Connected
+# UUID: openclaw-instance-001
+# Target: user123
+```
+
+---
+
+## WebSocket 服务器要求
+
+### 消息协议
+
+WebSocket 服务器必须支持以下 JSON 格式的消息协议：
+
+#### 1. 客户端 → 服务器消息
+
+**认证消息（如果配置了 authToken）：**
+```json
+{
+  "type": "auth",
+  "payload": {
+    "token": "your-auth-token",
+    "uuid": "openclaw-instance-001"
+  }
+}
+```
+
+**文本消息：**
+```json
+{
+  "type": "text",
+  "from": "openclaw-instance-001",
+  "to": "user123",
+  "text": "你好，世界！",
+  "messageId": "msg_1234567890_abc123",
+  "timestamp": 1234567890000
+}
+```
+
+**图片消息：**
+```json
+{
+  "type": "image",
+  "from": "openclaw-instance-001",
+  "to": "user123",
+  "payload": {
+    "base64": "data:image/png;base64,iVBORw0KGgoAAAANS...",
+    "filename": "screenshot.png",
+    "size": 12345
+  },
+  "messageId": "msg_1234567890_abc124",
+  "timestamp": 1234567890000
+}
+```
+
+**文件消息：**
+```json
+{
+  "type": "file",
+  "from": "openclaw-instance-001",
+  "to": "user123",
+  "payload": {
+    "base64": "data:application/pdf;base64,JVBERi0xLjQK...",
+    "filename": "document.pdf",
+    "size": 54321
+  },
+  "messageId": "msg_1234567890_abc125",
+  "timestamp": 1234567890000
+}
+```
+
+#### 2. 服务器 → 客户端消息
+
+**认证响应：**
+```json
+{
+  "type": "auth_response",
+  "success": true
+}
+```
+
+**文本消息：**
+```json
+{
+  "type": "text",
+  "from": "user123",
+  "to": "openclaw-instance-001",
+  "text": "收到你的消息！",
+  "messageId": "msg_server_001",
+  "timestamp": 1234567890000
+}
+```
+
+**图片/文件消息：**
+```json
+{
+  "type": "image",
+  "from": "user123",
+  "to": "openclaw-instance-001",
+  "mediaUrl": "https://example.com/images/photo.jpg",
+  "messageId": "msg_server_002",
+  "timestamp": 1234567890000
+}
+```
+
+**冲突通知（UUID 重复）：**
+```json
+{
+  "type": "conflict",
+  "reason": "UUID openclaw-instance-001 已在其他设备上使用"
+}
+```
+
+**Pong 响应（心跳）：**
+```json
+{
+  "type": "pong",
+  "timestamp": 1234567890000
+}
+```
+
+### 服务器实现要点
+
+1. **WebSocket 连接处理**
+   - 接受 wss:// 或 ws:// 连接
+   - 支持 WebSocket ping/pong 帧（用于心跳检测）
+
+2. **认证处理**
+   - 如果客户端发送 `auth` 消息，验证 token
+   - 返回 `auth_response` 消息表示认证结果
+
+3. **消息路由**
+   - 根据 `to` 字段将消息路由到目标用户
+   - 保存 `messageId` 用于消息去重和追踪
+
+4. **UUID 冲突检测**
+   - 检测同一 UUID 的多个连接
+   - 向新连接发送 `conflict` 消息
+   - 可选：断开旧连接或拒绝新连接
+
+5. **心跳处理**
+   - 响应 WebSocket ping 帧
+   - 或响应 JSON 格式的 ping 消息
+
+### 服务器示例（Node.js + ws）
+
+```javascript
+const WebSocket = require('ws');
+const wss = new WebSocket.Server({ port: 8080 });
+
+const clients = new Map(); // uuid -> WebSocket
+
+wss.on('connection', (ws) => {
+  let clientUuid = null;
+
+  ws.on('message', (data) => {
+    try {
+      const message = JSON.parse(data);
+
+      switch (message.type) {
+        case 'auth':
+          // 验证 token
+          if (validateToken(message.payload.token)) {
+            clientUuid = message.payload.uuid;
+            
+            // 检查 UUID 冲突
+            if (clients.has(clientUuid)) {
+              ws.send(JSON.stringify({
+                type: 'conflict',
+                reason: `UUID ${clientUuid} 已在其他设备上使用`
+              }));
+              ws.close();
+              return;
+            }
+            
+            clients.set(clientUuid, ws);
+            ws.send(JSON.stringify({
+              type: 'auth_response',
+              success: true
+            }));
+          } else {
+            ws.send(JSON.stringify({
+              type: 'auth_response',
+              success: false
+            }));
+            ws.close();
+          }
+          break;
+
+        case 'text':
+        case 'image':
+        case 'file':
+          // 路由消息到目标用户
+          const targetWs = clients.get(message.to);
+          if (targetWs && targetWs.readyState === WebSocket.OPEN) {
+            targetWs.send(JSON.stringify(message));
+          }
+          break;
+
+        case 'ping':
+          ws.send(JSON.stringify({
+            type: 'pong',
+            timestamp: Date.now()
+          }));
+          break;
+      }
+    } catch (error) {
+      console.error('消息处理错误:', error);
+    }
+  });
+
+  ws.on('close', () => {
+    if (clientUuid) {
+      clients.delete(clientUuid);
+    }
+  });
+
+  // 响应 WebSocket ping 帧
+  ws.on('ping', () => {
+    ws.pong();
+  });
+});
+
+function validateToken(token) {
+  // 实现你的 token 验证逻辑
+  return token === 'valid-token';
+}
+```
+
+---
+
+## 常见问题
+
+### 1. 连接失败
+
+**问题：** 插件无法连接到 WebSocket 服务器
+
+**解决方案：**
+- 检查 `wsUrl` 是否正确
+- 确认服务器正在运行并监听正确的端口
+- 检查防火墙设置
+- 验证 SSL 证书（如果使用 wss://）
+- 查看 OpenClaw 日志中的详细错误信息
+
+### 2. 认证失败
+
+**问题：** 收到 "Authentication failed" 错误
+
+**解决方案：**
+- 验证 `authToken` 是否正确
+- 检查服务器端的 token 验证逻辑
+- 确认 token 未过期
+- 查看服务器日志中的认证错误
+
+### 3. UUID 冲突
+
+**问题：** 收到 "UUID conflict" 错误
+
+**解决方案：**
+- 确保每个 OpenClaw 实例使用唯一的 `uuid`
+- 停止使用相同 UUID 的其他实例
+- 或在配置中为每个实例设置不同的 `uuid`
+
+### 4. 消息未送达
+
+**问题：** 发送的消息对方未收到
+
+**解决方案：**
+- 检查 WebSocket 连接状态（`openclaw status`）
+- 验证 `targetUserId` 是否正确
+- 确认目标用户已连接到服务器
+- 检查服务器的消息路由逻辑
+- 查看服务器日志中的消息处理记录
+
+### 5. 频繁断线重连
+
+**问题：** WebSocket 连接频繁断开并重连
+
+**解决方案：**
+- 检查网络稳定性
+- 增加心跳间隔（修改 `DEFAULT_HEARTBEAT_INTERVAL`）
+- 检查服务器是否主动关闭连接
+- 查看服务器负载情况
+- 检查是否有防火墙或代理干扰
+
+### 6. 消息队列溢出
+
+**问题：** 日志显示 "Message queue full, dropping oldest message"
+
+**解决方案：**
+- 检查 WebSocket 连接状态
+- 减少消息发送频率
+- 增加消息队列大小（修改 `DEFAULT_MESSAGE_QUEUE_MAX_SIZE`）
+- 优化网络连接稳定性
+
+---
+
+## 高级配置
+
+### 自定义超时和重连参数
+
+如果需要自定义超时和重连参数，可以修改 `src/shared/constants.ts`：
+
+```typescript
+export const DEFAULT_HEARTBEAT_INTERVAL = 30000;        // 心跳间隔（毫秒）
+export const DEFAULT_CONNECTION_TIMEOUT = 10000;        // 连接超时（毫秒）
+export const DEFAULT_RECONNECT_MAX_ATTEMPTS = 5;        // 最大重连次数
+export const DEFAULT_RECONNECT_BASE_DELAY = 1000;       // 重连基础延迟（毫秒）
+export const DEFAULT_RECONNECT_MAX_DELAY = 30000;       // 重连最大延迟（毫秒）
+export const DEFAULT_MESSAGE_QUEUE_MAX_SIZE = 100;      // 消息队列最大大小
+export const DEFAULT_PONG_TIMEOUT = 15000;              // Pong 超时（毫秒）
+```
+
+修改后需要重新构建：
+
+```bash
+pnpm build
+```
+
+### 日志级别调整
+
+在 OpenClaw 配置中调整日志级别：
+
+```json
+{
+  "logging": {
+    "level": "debug"  // 可选: error, warn, info, debug
+  }
+}
+```
+
+---
+
+## 技术支持
+
+如有问题，请：
+1. 查看 [README.md](./README.md) 了解基本使用
+2. 检查 OpenClaw 日志文件
+3. 查看 WebSocket 服务器日志
+4. 提交 Issue 到项目仓库
+
+---
+
+## 许可证
+
+MIT