@voko/lite 0.3.1

package/src/server/openclaw-websocket-handler.js

@@ -0,0 +1,1290 @@
+const WebSocket = require('ws');
+const { getPublicKeyAsync, signAsync, utils } = require('@noble/ed25519');
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const bus = require('../core/lite-bus');
+
+/**
+ * OpenClaw WebSocket 处理器
+ * 使用 WebSocket + Ed25519 设备认证与 OpenClaw Gateway 通信
+ * 
+ * 特性：
+ * - 自动检测配置文件变化，动态更新 token
+ * - 连接断开后自动重连
+ * - 消息队列，离线时缓存消息
+ * - 连接状态监控
+ */
+class OpenClawWebSocketHandler {
+  constructor(database, mainWindow) {
+    this.db = database;
+    this.mainWindow = mainWindow;
+    
+    // Gateway 配置
+    this.gatewayUrl = 'ws://127.0.0.1:18789';
+    this.authToken = null;
+    this.gatewayPort = 18789;
+    
+    // 状态控制
+    this.enabled = false;
+    this.processingChannels = new Set();
+    
+    // WebSocket 连接
+    this.ws = null;
+    this.sessionId = null;
+    this._protocolVer = 4; // 优先 v4，失败后降级到 v3
+    this.device = null;
+    this.connected = false;
+    this.connecting = false;
+    
+    // 消息队列（离线时缓存）
+    this.messageQueue = [];
+    this.maxQueueSize = 100;
+    
+    // Gateway 启动互斥锁（防止重复启动）
+    this._gatewayStarting = false;
+
+    // 重连配置
+    this.reconnectAttempts = 0;
+    this.maxReconnectAttempts = 10;
+    this.reconnectDelay = 2000; // 初始重连延迟 2 秒
+    this.maxReconnectDelay = 30000; // 最大重连延迟 30 秒
+    this.reconnectTimer = null;
+
+    // 日志缓冲区
+    this.logs = [];
+    this.maxLogSize = 200;
+    
+    // 配置文件监控
+    this.configPath = path.join(
+      os.homedir(),
+      '.openclaw',
+      'openclaw.json'
+    );
+    this.configWatcher = null;
+    this.lastConfigMtime = 0;
+    
+    // 当前回复处理（按 visitorId 隔离）
+    this.pendingReplies = new Map();  // {visitorId: {currentReply, replyResolve, timeout}}
+
+    // 事件监听器
+    this.eventListeners = new Map();  // {eventName: [handler]}
+
+    // 订阅状态追踪
+    this.subscribedSessions = new Set();  // 已成功订阅的 session key
+    this.pendingSubscriptions = new Map();  // 待确认的订阅请求 {sessionKey: {timestamp, id}}
+    this._caseMap = new Map();  // gateway 转小写后的 key → 原始大小写 key
+    this._processedMsgs = new Map();  // 已处理 final 消息去重 key → timestamp
+
+    // 初始化
+    this.loadConfig();
+    this.startConfigWatcher();
+  }
+
+  /**
+   * 加载 OpenClaw 配置文件
+   */
+  loadConfig() {
+    try {
+      if (fs.existsSync(this.configPath)) {
+        const stats = fs.statSync(this.configPath);
+        this.lastConfigMtime = stats.mtimeMs;
+        
+        const config = JSON.parse(fs.readFileSync(this.configPath, 'utf8'));
+        
+        const newPort = config.gateway?.port || 18789;
+        const newToken = config.gateway?.auth?.token || null;
+        const newUrl = `ws://127.0.0.1:${newPort}`;
+        
+        // 检测配置变化
+        const portChanged = this.gatewayPort !== newPort;
+        const tokenChanged = this.authToken !== newToken;
+        const urlChanged = this.gatewayUrl !== newUrl;
+        
+        if (portChanged || tokenChanged || urlChanged) {
+          console.log('[OpenClaw WS] 配置更新:');
+          if (portChanged) console.log(`  - Port: ${this.gatewayPort} → ${newPort}`);
+          if (tokenChanged) console.log(`  - Token: ${this.authToken ? '已设置' : '未设置'} → ${newToken ? '已设置' : '未设置'}`);
+          if (urlChanged) console.log(`  - URL: ${this.gatewayUrl} → ${newUrl}`);
+          
+          this.gatewayPort = newPort;
+          this.authToken = newToken;
+          this.gatewayUrl = newUrl;
+          
+          // 如果已连接，需要重新连接以应用新配置
+          if (this.connected || this.connecting) {
+            console.log('[OpenClaw WS] 配置变化，触发重新连接...');
+            this.scheduleReconnect(100); // 100ms 后重连
+          }
+        } else {
+          console.log('[OpenClaw WS] 配置检查完成，无变化');
+        }
+        
+        return true;
+      } else {
+        console.warn('[OpenClaw WS] 配置文件不存在:', this.configPath);
+        return false;
+      }
+    } catch (err) {
+      console.error('[OpenClaw WS] 加载配置失败:', err.message);
+      return false;
+    }
+  }
+
+  /**
+   * 启动配置文件监控（使用轮询方式，更可靠）
+   */
+  startConfigWatcher() {
+    // 每 5 秒检查一次配置文件变化
+    this.configWatcher = setInterval(() => {
+      try {
+        if (fs.existsSync(this.configPath)) {
+          const stats = fs.statSync(this.configPath);
+          if (stats.mtimeMs > this.lastConfigMtime) {
+            console.log('[OpenClaw WS] 检测到配置文件变化，重新加载...');
+            this.loadConfig();
+          }
+        }
+      } catch (err) {
+        console.error('[OpenClaw WS] 检查配置失败:', err.message);
+      }
+    }, 5000);
+    
+    console.log('[OpenClaw WS] 配置文件监控已启动');
+  }
+
+  /**
+   * 停止配置文件监控
+   */
+  stopConfigWatcher() {
+    if (this.configWatcher) {
+      clearInterval(this.configWatcher);
+      this.configWatcher = null;
+      console.log('[OpenClaw WS] 配置文件监控已停止');
+    }
+  }
+
+  /**
+   * 设置启用/禁用状态
+   */
+  setEnabled(enabled) {
+    this.enabled = enabled;
+    console.log('[OpenClaw WS] 自动回复:', enabled ? '已启用' : '已禁用');
+    
+    if (enabled) {
+      if (!this.connected && !this.connecting) {
+        this.connect();
+      }
+    } else {
+      this.disconnect();
+    }
+  }
+
+  /**
+   * 获取连接状态
+   */
+  getStatus() {
+    return {
+      connected: this.connected,
+      connecting: this.connecting,
+      enabled: this.enabled,
+      queueSize: this.messageQueue.length,
+      gatewayUrl: this.gatewayUrl,
+      authToken: this.authToken,
+      reconnectAttempts: this.reconnectAttempts,
+      deviceId: this.device?.deviceId || null,
+      devicePublicKey: this.device?.publicKey || null,
+      gatewayPort: this.gatewayPort,
+      sessionId: this.sessionId,
+      subscribedSessions: Array.from(this.subscribedSessions || []),
+      pendingSubscriptions: Array.from(this.pendingSubscriptions?.keys() || []),
+      maxReconnectAttempts: this.maxReconnectAttempts,
+      reconnectDelay: this.reconnectDelay,
+      maxReconnectDelay: this.maxReconnectDelay,
+      logs: this.logs.slice(),
+      hasToken: !!this.authToken
+    };
+  }
+
+  /**
+   * 根据平台解析 openclaw 命令，返回 { cmd, args, shell }
+   * Windows: 直接找 node.exe + openclaw.mjs 入口文件，绕过 .cmd 避免弹窗
+   * macOS/Linux: which 查找 openclaw 可执行文件
+   */
+  _resolveOpenclawCmd() {
+    if (process.platform === 'win32') {
+      // Windows: 直接用 node + openclaw.mjs 入口运行，绕过 .cmd 文件的 title %COMSPEC% 弹窗
+      const npmDir = path.join(process.env.APPDATA || '', 'npm');
+      const entryPoint = path.join(npmDir, 'node_modules', 'openclaw', 'openclaw.mjs');
+      if (require('fs').existsSync(entryPoint)) {
+        const nodePath = path.join(npmDir, 'node.exe');
+        if (require('fs').existsSync(nodePath)) {
+          return { cmd: nodePath, args: [entryPoint, 'gateway', 'run', '--force'], shell: false };
+        }
+        // npm 目录下没有 node.exe，用系统 PATH 中的 node
+        return { cmd: 'node', args: [entryPoint, 'gateway', 'run', '--force'], shell: false };
+      }
+      // 兜底：走 .cmd 文件
+      const cmdPath = path.join(npmDir, 'openclaw.cmd');
+      if (require('fs').existsSync(cmdPath)) return { cmd: cmdPath, args: ['gateway', 'run', '--force'], shell: true };
+      try {
+        const result = require('child_process').execSync('where openclaw', { encoding: 'utf8', timeout: 5000, shell: true, windowsHide: true });
+        const firstLine = result.trim().split('\n')[0].trim();
+        if (firstLine) return { cmd: firstLine, args: ['gateway', 'run', '--force'], shell: firstLine.endsWith('.cmd') || firstLine.endsWith('.bat') };
+      } catch {}
+    } else {
+      // macOS/Linux
+      try {
+        const result = require('child_process').execSync('which openclaw', { encoding: 'utf8', timeout: 5000 });
+        if (result.trim()) return { cmd: result.trim(), args: ['gateway', 'run', '--force'], shell: false };
+      } catch {}
+    }
+    // 终极兜底
+    const isWin = process.platform === 'win32';
+    return { cmd: isWin ? 'openclaw.cmd' : 'openclaw', args: ['gateway', 'run', '--force'], shell: isWin };
+  }
+
+  /**
+   * 检测并确保 OpenClaw Gateway 正在运行
+   * 如果 gateway 未运行，自动尝试启动
+   * @returns {Promise<boolean>} gateway 是否已就绪
+   */
+  async _ensureGatewayRunning() {
+    const { spawn } = require('child_process');
+
+    // 已连上就不需要操作
+    if (this.connected) return true;
+    // 已经在启动中，防止重复启动
+    if (this._gatewayStarting) return false;
+    this._gatewayStarting = true;
+
+    try {
+      // 先检查 gateway 是否已在运行
+      try {
+        const http = require('http');
+        await new Promise((resolve, reject) => {
+          const req = http.get(`http://127.0.0.1:${this.gatewayPort}/health`, (res) => {
+            resolve(res.statusCode === 200);
+          });
+          req.on('error', reject);
+          req.setTimeout(3000, () => { req.destroy(); reject(new Error('timeout')); });
+        });
+        console.log(`[OpenClaw WS] Gateway 已在运行 (port=${this.gatewayPort})`);
+        return true;
+      } catch {
+        console.log(`[OpenClaw WS] Gateway 未运行，尝试启动 (port=${this.gatewayPort})...`);
+      }
+
+      // 启动 gateway 进程
+      const started = await new Promise((resolve) => {
+        const { cmd, args, shell } = this._resolveOpenclawCmd();
+        let child;
+        try {
+          child = spawn(cmd, args, {
+            stdio: 'ignore',
+            detached: true,
+            windowsHide: true,
+            shell,
+            // Windows: 直接 spawn node 时不创建控制台窗口
+            ...(process.platform === 'win32' && !shell ? { creationFlags: 0x08000000 } : {}),
+          });
+          child.unref();
+          child.on('error', (err) => {
+            console.error('[OpenClaw WS] 无法启动 openclaw 进程:', err.message);
+            resolve(false);
+          });
+        } catch (err) {
+          console.error('[OpenClaw WS] 无法启动 openclaw 进程:', err.message);
+          resolve(false);
+          return;
+        }
+
+        // 等待最多 15 秒，每秒检测 gateway 是否就绪
+        let waited = 0;
+        const interval = setInterval(async () => {
+          waited++;
+          try {
+            const http = require('http');
+            await new Promise((resolve, reject) => {
+              const req = http.get(`http://127.0.0.1:${this.gatewayPort}/health`, (res) => {
+                resolve(res.statusCode === 200);
+              });
+              req.on('error', reject);
+              req.setTimeout(2000, () => { req.destroy(); reject(new Error('timeout')); });
+            });
+            clearInterval(interval);
+            clearTimeout(timeout);
+            console.log(`[OpenClaw WS] Gateway 启动成功 (${waited}s)`);
+            resolve(true);
+          } catch {
+            if (waited >= 15) {
+              clearInterval(interval);
+              clearTimeout(timeout);
+              console.error(`[OpenClaw WS] Gateway 启动超时 (15s)`);
+              resolve(false);
+            }
+          }
+        }, 1000);
+
+        const timeout = setTimeout(() => {
+          clearInterval(interval);
+          resolve(false);
+        }, 16000);
+      });
+
+      return started;
+    } finally {
+      this._gatewayStarting = false;
+    }
+  }
+
+  addLog(msg) {
+    const entry = `[${new Date().toLocaleTimeString()}] ${msg}`;
+    this.logs.push(entry);
+    if (this.logs.length > this.maxLogSize) {
+      this.logs.shift();
+    }
+    console.log(`[OpenClaw WS] ${msg}`);
+  }
+
+  on(event, handler) {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, []);
+    }
+    this.eventListeners.get(event).push(handler);
+  }
+
+  off(event, handler) {
+    if (!this.eventListeners.has(event)) return;
+    const handlers = this.eventListeners.get(event);
+    const idx = handlers.indexOf(handler);
+    if (idx >= 0) handlers.splice(idx, 1);
+  }
+
+  emit(event, msg) {
+    if (!this.eventListeners.has(event)) return;
+    this.eventListeners.get(event).forEach(h => h(msg));
+  }
+
+  // ============ 设备身份 ============
+
+  /**
+   * 生成设备身份
+   */
+  async createDeviceIdentity() {
+    // 生成 32 字节私钥种子 (@noble/ed25519 格式)
+    const privateKey = utils.randomSecretKey();
+    const publicKey = await getPublicKeyAsync(privateKey);
+    
+    // deviceId = SHA256(publicKey) in hex
+    const hash = crypto.createHash('sha256').update(Buffer.from(publicKey)).digest();
+    const deviceId = Array.from(new Uint8Array(hash)).map(b => b.toString(16).padStart(2, '0')).join('');
+    
+    return {
+      deviceId,
+      publicKey: this.base64UrlEncode(publicKey),
+      privateKey: this.base64UrlEncode(privateKey)  // base64 encode 存储
+    };
+  }
+
+  base64UrlEncode(bytes) {
+    return Buffer.from(bytes).toString('base64')
+      .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+  }
+
+  base64UrlDecode(input) {
+    const normalized = input.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4);
+    return new Uint8Array(Buffer.from(padded, 'base64'));
+  }
+
+  generateId() {
+    return `req-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  // ============ 认证 ============
+
+  /**
+   * 构建认证 payload
+   */
+  buildAuthPayload(params) {
+    return [
+      'v2',
+      params.deviceId,
+      params.clientId,
+      params.clientMode,
+      params.role,
+      params.scopes.join(','),
+      String(params.signedAtMs),
+      params.token ?? '',
+      params.nonce,
+    ].join('|');
+  }
+
+  /**
+   * 签名 payload
+   */
+  async signPayload(privateKeyBase64Url, payload) {
+    const key = this.base64UrlDecode(privateKeyBase64Url);
+    const data = new TextEncoder().encode(payload);
+    const sig = await signAsync(data, key);
+    return this.base64UrlEncode(sig);
+  }
+
+  // ============ WebSocket 连接管理 ============
+
+  /**
+   * 连接 WebSocket
+   */
+  async connect() {
+    if (this.connecting || this.connected) {
+      console.log('[OpenClaw WS] 已经在连接中或已连接');
+      return;
+    }
+
+    if (!this.authToken) {
+      console.error('[OpenClaw WS] 无法连接: 没有有效的 auth token，请先配置 OpenClaw Gateway');
+      return;
+    }
+
+    this.connecting = true;
+    console.log('[OpenClaw WS] 正在连接:', this.gatewayUrl);
+
+    return new Promise((resolve, reject) => {
+      // 连接超时处理
+      const connectionTimeout = setTimeout(() => {
+        if (!this.connected) {
+          this.addLog('❌ 连接超时');
+          this.connecting = false;
+          this.ws?.close();
+          this.scheduleReconnect();
+          reject(new Error('连接超时'));
+        }
+      }, 30000);
+
+      try {
+        this.ws = new WebSocket(this.gatewayUrl);
+      } catch (err) {
+        console.error('[OpenClaw WS] 创建 WebSocket 失败:', err.message);
+        this.connecting = false;
+        clearTimeout(connectionTimeout);
+        this.scheduleReconnect();
+        reject(err);
+        return;
+      }
+      
+      this.ws.on('open', () => {
+        console.log('[OpenClaw WS] ✅ WebSocket 已连接，等待认证...');
+        this.addLog('🔌 WebSocket 已连接，等待认证...');
+      });
+
+      this.ws.on('message', async (data) => {
+        try {
+          const msg = JSON.parse(data.toString());
+          // 噪音事件只打印到控制台，不写入日志缓冲区
+          const hideEvents = ['event health', 'event tick', 'event agent', 'event chat', 'res'];
+          const eventStr = msg.type + ' ' + (msg.event || msg.method || '');
+          const isNoise = hideEvents.some(e => eventStr.includes(e));
+          if (!isNoise) {
+            console.log('[OpenClaw WS] 📩 收到:', msg.type, msg.event || msg.method || msg.payload?.type);
+            this.addLog(`📩 收到: ${msg.type} ${msg.event || msg.method || msg.payload?.type || ''}`);
+          }
+
+          await this.handleMessage(msg, resolve, connectionTimeout);
+        } catch (e) {
+          console.error('[OpenClaw WS] 解析消息失败:', e.message, data.toString().substring(0, 200));
+        }
+      });
+
+      this.ws.on('error', (err) => {
+        console.error('[OpenClaw WS] ❌ 连接错误:', err.message);
+        this.connecting = false;
+        clearTimeout(connectionTimeout);
+        this.scheduleReconnect();
+        reject(err);
+      });
+
+      this.ws.on('close', (code, reason) => {
+        console.log(`[OpenClaw WS] 🔌 连接关闭 (code: ${code}, reason: ${reason || '无'})`);
+      this.addLog(`🔌 连接关闭 (code: ${code}, reason: ${reason || '无'})`);
+        this.connected = false;
+        this.connecting = false;
+        this.ws = null;
+        
+        // 如果启用了自动回复，尝试重连
+        if (this.enabled) {
+          this.scheduleReconnect();
+        }
+      });
+    }).catch(err => {
+      // Promise 被拒绝时的处理已在上面完成
+      console.log('[OpenClaw WS] 连接 Promise 被拒绝:', err.message);
+    });
+  }
+
+  /**
+   * 处理收到的消息
+   */
+  async handleMessage(msg, resolve, connectionTimeout) {
+    // 处理连接挑战
+    if (msg.type === 'event' && msg.event === 'connect.challenge') {
+      console.log('[OpenClaw WS] 🔐 收到认证挑战');
+      
+      try {
+        this.device = await this.createDeviceIdentity();
+        
+        const signedAtMs = Date.now();
+        const payload = this.buildAuthPayload({
+          deviceId: this.device.deviceId,
+          clientId: 'cli',
+          clientMode: 'cli',
+          role: 'operator',
+          scopes: ['operator.read', 'operator.write', 'operator.admin'],
+          signedAtMs,
+          token: this.authToken,
+          nonce: msg.payload.nonce
+        });
+        
+        const signature = await this.signPayload(this.device.privateKey, payload);
+
+        this.send({
+          type: 'req',
+          id: this.generateId(),
+          method: 'connect',
+          params: {
+            minProtocol: this._protocolVer,
+            maxProtocol: this._protocolVer,
+            client: { 
+              id: 'cli', 
+              version: '1.0.0', 
+              platform: 'windows', 
+              mode: 'cli' 
+            },
+            role: 'operator',
+            scopes: ['operator.read', 'operator.write', 'operator.admin'],
+            auth: { token: this.authToken },
+            device: {
+              id: this.device.deviceId,
+              publicKey: this.device.publicKey,
+              signature: signature,
+              signedAt: signedAtMs,
+              nonce: msg.payload.nonce
+            },
+            locale: 'zh-CN',
+            userAgent: 'voko-im-websocket/1.0'
+          }
+        });
+      } catch (err) {
+        console.error('[OpenClaw WS] 认证挑战处理失败:', err.message);
+        this.ws?.close();
+      }
+    }
+
+    // 处理认证响应
+    if (msg.type === 'res' && msg.ok) {
+      const wasConnected = this.connected; // 记录重连前状态
+      const hadSubscribed = this.subscribedSessions.size;
+      const wasReconnecting = this.reconnectAttempts > 0; // 是否在重连中
+      console.log('[OpenClaw WS] ✅ 认证成功 wasConnected=' + wasConnected + ' hadSubscribed=' + hadSubscribed + ' wasReconnecting=' + wasReconnecting);
+      this.addLog('✅ 认证成功');
+      this.connected = true;
+      this.connecting = false;
+      this.emit('connected');
+      // 使用默认 session key
+      this.sessionId = msg.payload?.sessionDefaults?.mainSessionKey || 'agent:main:main';
+      this.reconnectAttempts = 0; // 重置重连计数
+
+      console.log(`[OpenClaw WS] 认证完成 pending=${this.pendingSubscriptions.size}`);
+
+      clearTimeout(connectionTimeout);
+
+      // Gateway 重连后，清除所有订阅状态
+      // 只有在真正重连场景下（有重连计数且认证前已订阅）才需要清除
+      // 防止首次连接时错误清除订阅状态
+      if (wasReconnecting && wasConnected && hadSubscribed > 0) {
+        console.log(`[OpenClaw WS] 🔄 重连后清除 ${hadSubscribed} 个旧订阅状态`);
+        this.subscribedSessions.clear();
+      }
+
+      // 发送队列中的消息
+      this.processMessageQueue();
+
+      if (resolve) resolve();
+    }
+
+    // 处理认证失败
+    if (msg.type === 'res' && !msg.ok && msg.error) {
+      console.error('[OpenClaw WS] ❌ 认证失败:', msg.error.message);
+      this.addLog(`❌ 认证失败: ${msg.error.message}`);
+
+      // 如果是 token 无效，尝试重新加载配置
+      if (msg.error.message?.includes('token') || msg.error.code === 'UNAUTHORIZED') {
+        console.log('[OpenClaw WS] Token 可能已过期，尝试重新加载配置...');
+        this.loadConfig();
+      }
+
+      // 协议版本不匹配 → 降级到 v3 重试
+      if (msg.error.message?.includes('protocol')) {
+        if (this._protocolVer === 4) {
+          this._protocolVer = 3;
+          console.log('[OpenClaw WS] 协议版本不匹配，降级到 v3 重试...');
+          this.addLog('⬇️ 协议版本不匹配，降级到 v3');
+          this.ws?.close();
+          this.connecting = false;
+          this.scheduleReconnect(100);
+        } else {
+          console.error('[OpenClaw WS] v3 也不匹配，停止重试');
+          this.addLog('❌ 协议版本不兼容');
+        }
+      }
+    }
+
+    // 处理订阅响应
+    // 注意: msg.id 可能与发送时不一致,改用 payload.key 匹配
+    if (msg.type === 'res') {
+      const hasSubscribed = msg.payload?.subscribed !== undefined;
+      const hasKey = !!msg.payload?.key;
+      console.log(`[OpenClaw WS] 📩 收到 res id=${msg.id} subscribed=${msg.payload?.subscribed} key=${msg.payload?.key} full=${JSON.stringify(msg.payload)}`);
+
+      if (hasSubscribed && hasKey) {
+        const key = msg.payload.key;
+        const subscribed = msg.payload.subscribed;
+
+        if (this.pendingSubscriptions.has(key)) {
+          const pending = this.pendingSubscriptions.get(key);
+          const elapsed = Date.now() - pending.timestamp;
+          this.pendingSubscriptions.delete(key);
+
+          if (subscribed) {
+            this.subscribedSessions.add(key);
+            console.log(`[OpenClaw WS] ✅ 订阅成功 sessionKey=${key} 耗时=${elapsed}ms`);
+          } else {
+            console.log(`[OpenClaw WS] ❌ 订阅失败 sessionKey=${key} 耗时=${elapsed}ms`);
+          }
+        }
+      }
+    }
+
+    // 处理助手回复（流式）
+    if (msg.type === 'event' && msg.event === 'session.message') {
+      // 去重：final 消息 30 秒内跳过重复
+      const _finalMsg = msg.payload?.message;
+      if (_finalMsg && _finalMsg.stopReason === 'stop') {
+        let _fullText = '';
+        const _contentArr = _finalMsg.content || [];
+        if (Array.isArray(_contentArr)) {
+          for (const _item of _contentArr) { if (_item.type === 'text' && _item.text) _fullText += _item.text; }
+        } else if (typeof _contentArr === 'string') _fullText = _contentArr;
+        const _dedupKey = (msg.payload.sessionKey || '') + ':' + _fullText.substring(0, 100);
+        const _lastTime = this._processedMsgs.get(_dedupKey);
+        if (_lastTime && Date.now() - _lastTime < 30000) {
+          console.log('[OpenClaw WS] ⏭️ 跳过重复的 final 消息');
+          return;
+        }
+        this._processedMsgs.set(_dedupKey, Date.now());
+      }
+      // 触发 session.message 事件
+      this.emit('session.message', msg);
+      // payload 结构: {sessionKey, message: {role, content, done}, ...}
+      const innerMsg = msg.payload?.message;
+      if (!innerMsg) return;
+
+      let sessionKey = msg.payload.sessionKey || '';
+      // 解码：gateway 返回的 key 是全小写的，还原为原始大小写
+      if (sessionKey && this._caseMap.has(sessionKey)) {
+        sessionKey = this._caseMap.get(sessionKey);
+      }
+      const role = innerMsg.role;
+      const rawContent = innerMsg.content || [];
+      const isFinal = innerMsg.stopReason === 'stop';
+
+      // 从 sessionKey 提取 visitorId 和 agentId
+      // 格式: agent:{agentId}:{visitorId}
+      let visitorId = null;
+      let agentId = null;
+      const agentMatch = sessionKey.match(/^agent:([^:]+):(.+)$/);
+      if (agentMatch) {
+        agentId = agentMatch[1];
+        visitorId = agentMatch[2];
+      }
+
+      if (role === 'assistant') {
+        // 只提取 type="text" 的内容，过滤掉 thinking
+        let text = '';
+        if (Array.isArray(rawContent)) {
+          for (const item of rawContent) {
+            if (item.type === 'text' && item.text) {
+              text += item.text;
+            }
+          }
+        } else if (typeof rawContent === 'string') {
+          text = rawContent;
+        }
+
+        // 获取该 visitor 的 pending reply 状态
+        const pending = visitorId ? this.pendingReplies.get(visitorId) : null;
+
+        if (text) {
+          if (pending) {
+            pending.currentReply += text;
+          }
+        }
+
+        if (isFinal) {
+          const finalReply = pending ? pending.currentReply : text;
+          console.log(`[OpenClaw WS] ✅ 收到完整回复 sessionKey=${sessionKey} visitorId=${visitorId} 内容="${finalReply}"`);
+
+          // 不再直接发送回复到访客，只存储到 pending 状态等待后续处理
+          // 清理 pending reply 状态
+          if (pending) {
+            clearTimeout(pending.timeout);
+            if (pending.replyResolve) {
+              pending.replyResolve(finalReply);
+            }
+            this.pendingReplies.delete(visitorId);
+          }
+
+          // 触发事件让其他模块处理（存储和发送）
+          this.emit('agent.reply', {
+            agentId,
+            visitorId,
+            content: finalReply,
+            sessionKey
+          });
+        }
+      }
+    }
+
+    // 处理错误
+    if (msg.type === 'res' && !msg.ok && msg.error) {
+      console.error('[OpenClaw WS] ❌ 错误:', msg.error.code, msg.error.message);
+    }
+  }
+
+  /**
+   * 发送消息到 WebSocket
+   */
+  send(msg) {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      try {
+        const data = JSON.stringify(msg);
+        this.ws.send(data);
+        // chat.send 的详细日志在 sendChatSend 中，这里只记录其他方法
+        if (msg.method !== 'chat.send') {
+          console.log('[OpenClaw WS] 📤 发送:', msg.type, msg.method || msg.event);
+        }
+      } catch (err) {
+        console.error('[OpenClaw WS] 发送失败:', err.message);
+      }
+    } else {
+      try { console.error("[OpenClaw WS] ❌ WebSocket 未连接，无法发送消息"); } catch (_) {}
+    }
+  }
+
+  /**
+   * 断开连接
+   */
+  disconnect() {
+    // 取消重连定时器
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+
+    if (this.ws) {
+      // 正常关闭，不触发重连
+      this.ws.removeAllListeners('close');
+      this.ws.close(1000, 'Client disconnect');
+      this.ws = null;
+    }
+
+    this.connected = false;
+    this.connecting = false;
+    this.reconnectAttempts = 0;
+
+    // 清理订阅状态
+    this.subscribedSessions.clear();
+    this.pendingSubscriptions.clear();
+    this._caseMap.clear();
+
+    // 清理 pending replies
+    for (const [visitorId, pending] of this.pendingReplies) {
+      clearTimeout(pending.timeout);
+    }
+    this.pendingReplies.clear();
+
+    console.log('[OpenClaw WS] 已断开连接');
+  }
+
+  /**
+   * 计划重连
+   */
+  scheduleReconnect(delay = null) {
+    if (this.reconnectTimer) {
+      return; // 已经在计划重连
+    }
+
+    if (!this.enabled) {
+      console.log('[OpenClaw WS] 已禁用，取消重连');
+      return;
+    }
+
+    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+      console.error(`[OpenClaw WS] 重连次数超过限制 (${this.maxReconnectAttempts})，停止重连`);
+      this.addLog(`❌ 重连次数超过限制，停止重连`);
+      return;
+    }
+
+    this.reconnectAttempts++;
+    
+    // 计算重连延迟（指数退避）
+    const actualDelay = delay !== null ? delay : Math.min(
+      this.reconnectDelay * Math.pow(1.5, this.reconnectAttempts - 1),
+      this.maxReconnectDelay
+    );
+
+    console.log(`[OpenClaw WS] 计划 ${actualDelay}ms 后重连 (尝试 ${this.reconnectAttempts}/${this.maxReconnectAttempts})`);
+    this.addLog(`⏳ 计划 ${actualDelay}ms 后重连 (第${this.reconnectAttempts}次)`);
+
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      if (this.enabled && !this.connected && !this.connecting) {
+        console.log('[OpenClaw WS] 执行重连...');
+        this.addLog('🔄 执行重连...');
+        this.connect().catch(err => {
+          console.error('[OpenClaw WS] 重连失败:', err.message);
+        });
+      }
+    }, actualDelay);
+  }
+
+  // ============ 消息处理 ============
+
+  /**
+   * 发送聊天消息到 OpenClaw（按 visitorId 隔离 pending reply）
+   */
+  async sendMessage(message, visitorId = 'default', timeoutMs = 60000) {
+    if (!this.connected) {
+      console.log('[OpenClaw WS] 未连接，尝试连接...');
+      try {
+        await this.connect();
+      } catch (err) {
+        console.error('[OpenClaw WS] 连接失败，消息进入队列:', err.message);
+        this.queueMessage(message);
+        throw new Error('WebSocket 未连接，消息已缓存');
+      }
+    }
+
+    return new Promise((resolve, reject) => {
+      // 按 visitorId 存储 pending reply 状态
+      this.pendingReplies.set(visitorId, {
+        replyResolve: resolve,
+        currentReply: '',
+        timeout: setTimeout(() => {
+          const pending = this.pendingReplies.get(visitorId);
+          if (pending?.replyResolve) {
+            console.log('[OpenClaw WS] 等待回复超时 visitor=' + visitorId);
+            pending.replyResolve(pending.currentReply || '收到你的消息');
+            this.pendingReplies.delete(visitorId);
+          }
+        }, timeoutMs)
+      });
+
+      this.send({
+        type: 'req',
+        id: this.generateId(),
+        method: 'chat.send',
+        params: {
+          sessionKey: this.sessionId || 'agent:main:main',
+          message: message,
+          deliver: false,
+          idempotencyKey: this.generateId()
+        }
+      });
+    });
+  }
+
+  /**
+   * 将消息加入队列（离线缓存）
+   */
+  queueMessage(item) {
+    // 支持简单消息或带类型的对象
+    const message = typeof item === 'string' ? item : item.message;
+    const type = typeof item === 'string' ? 'simple' : (item.type || 'simple');
+
+    if (this.messageQueue.length >= this.maxQueueSize) {
+      console.warn('[OpenClaw WS] 消息队列已满，丢弃最旧的消息');
+      this.messageQueue.shift();
+    }
+    this.messageQueue.push({
+      type,
+      message,
+      sessionKey: item.sessionKey,
+      extraData: item.extraData || null,
+      timestamp: Date.now()
+    });
+    console.log('[OpenClaw WS] 消息已加入队列 type=' + type + ' 当前队列大小:', this.messageQueue.length);
+  }
+
+  /**
+   * 处理队列中的消息
+   */
+  async processMessageQueue() {
+    if (this.messageQueue.length === 0) return;
+
+    console.log('[OpenClaw WS] 处理队列中的', this.messageQueue.length, '条消息');
+
+    const queue = [...this.messageQueue];
+    this.messageQueue = [];
+
+    for (const item of queue) {
+      try {
+        // 跳过超过 5 分钟的消息
+        if (Date.now() - item.timestamp > 5 * 60 * 1000) {
+          console.log('[OpenClaw WS] 跳过过期消息');
+          continue;
+        }
+
+        if (item.type === 'sendToSession') {
+          // 处理 sendToSession 类型的消息
+          console.log(`[OpenClaw WS] 处理队列中的sendToSession sessionKey=${item.sessionKey}`);
+          this.sendToSession(item.sessionKey, item.message, item.extraData).then(() => {
+            if (item.onSent) item.onSent();
+          });
+        } else {
+          // 处理简单消息
+          const reply = await this.sendMessage(item.message);
+          console.log('[OpenClaw WS] 队列消息处理完成:', reply?.substring(0, 50));
+        }
+      } catch (err) {
+        console.error('[OpenClaw WS] 队列消息处理失败:', err.message);
+      }
+    }
+  }
+
+  // ============ 工具方法 ============
+
+  // 从 _caseMap 还原原始大小写的 visitorId
+  getOriginalVisitorId(lowercaseId, agentId) {
+    if (!lowercaseId || !agentId) return null;
+    const lowerKey = `agent:${agentId}:${lowercaseId.toLowerCase()}`;
+    const original = this._caseMap.get(lowerKey);
+    if (original) {
+      const parts = original.split(':');
+      return parts[parts.length - 1] || null;
+    }
+    return null;
+  }
+
+  // 向 _caseMap 添加大小写映射（供 main.js 在消息到达时预填充）
+  setCaseMapEntry(agentId, originalVisitorId) {
+    if (!agentId || !originalVisitorId) return;
+    const originalKey = `agent:${agentId}:${originalVisitorId}`;
+    const lowerKey = originalKey.toLowerCase();
+    if (originalKey !== lowerKey) {
+      this._caseMap.set(lowerKey, originalKey);
+    }
+  }
+
+  // 从 sessionKey 提取 visitorId
+  extractVisitorId(sessionKey) {
+    // agent:gym:http:visitor:sess_visitor123 → sess_visitor123
+    const parts = sessionKey.split(':');
+    return parts[parts.length - 1];
+  }
+
+  /**
+   * 发送消息到指定 session（不等待回复，用于转发到 gym agent）
+   * 发送前先订阅该 session，订阅成功后再发送
+   */
+  sendToSession(sessionKey, message, extraData = null) {
+    return new Promise((resolve, reject) => {
+      // Gateway 内部统一用小写处理，voko 侧对齐
+      const originalKey = sessionKey;
+      sessionKey = sessionKey.toLowerCase();
+      if (originalKey !== sessionKey) {
+        this._caseMap.set(sessionKey, originalKey);
+      }
+      const now = Date.now();
+      console.log(`[OpenClaw WS] 🚀 sendToSession sessionKey=${sessionKey} t=${now}`);
+
+      // 如果已经订阅过该 session，直接发送消息
+      if (this.subscribedSessions.has(sessionKey)) {
+        console.log(`[OpenClaw WS] 📤 已订阅，直接发送chat.send sessionKey=${sessionKey} t=${now}`);
+        this.sendChatSend(sessionKey, message, extraData, now);
+        resolve();
+        return;
+      }
+
+      // 如果正在等待订阅确认，不重复订阅，排队等待
+      if (this.pendingSubscriptions.has(sessionKey)) {
+        console.log(`[OpenClaw WS] 订阅中，排队等待 sessionKey=${sessionKey}`);
+        this.queueMessage({ type: 'sendToSession', sessionKey, message, extraData, timestamp: now, onSent: resolve });
+        return;
+      }
+
+      // 如果未连接或正在连接中，等待连接完成
+      if (!this.connected || this.connecting) {
+        console.log(`[OpenClaw WS] ⚠️ 未连接或连接中，等待... sessionKey=${sessionKey} connected=${this.connected} connecting=${this.connecting}`);
+        // 放入队列，连接成功后会自动处理
+        this.queueMessage({ type: 'sendToSession', sessionKey, message, extraData, timestamp: now, onSent: resolve });
+        return;
+      }
+
+      // 发起订阅请求
+      console.log(`[OpenClaw WS] 📤 发起订阅请求 sessionKey=${sessionKey} t=${now}`);
+      const reqId = this.generateId();
+      this.pendingSubscriptions.set(sessionKey, { timestamp: now, id: reqId, onSent: resolve, extraData });
+
+      this.send({
+        type: 'req',
+        id: reqId,
+        method: 'sessions.messages.subscribe',
+        params: { key: sessionKey }
+      });
+
+      // 等待订阅确认后发送消息
+      const waitForSubscribe = () => {
+        const pending = this.pendingSubscriptions.get(sessionKey);
+        if (!pending) {
+          // 订阅已完成（成功或失败）
+          if (this.subscribedSessions.has(sessionKey)) {
+            console.log(`[OpenClaw WS] 📤 订阅确认后发送chat.send sessionKey=${sessionKey} t=${Date.now()}`);
+            this.sendChatSend(sessionKey, message, extraData, Date.now());
+            resolve();
+          } else {
+            console.log(`[OpenClaw WS] ❌ 订阅失败，跳过消息发送 sessionKey=${sessionKey}`);
+            resolve(); // 也 resolve，避免永久等待
+          }
+        } else {
+          // 还在等待，继续检查
+          setTimeout(waitForSubscribe, 50);
+        }
+      };
+
+      // 延迟检查订阅状态（订阅响应应该很快）
+      setTimeout(waitForSubscribe, 100);
+    });
+  }
+
+  /**
+   * 发送 chat.send 消息（结构化 JSON 格式）
+   */
+  sendChatSend(sessionKey, message, extraData = null, sendTimestamp) {
+    // 格式: agent:{agentId}:{visitorId}
+    let visitorId = null;
+    const agentMatch = sessionKey.match(/^agent:([^:]+):(.+)$/);
+    if (agentMatch) {
+      visitorId = agentMatch[2];
+    }
+    // 构造结构化 JSON（去掉 untrusted 标记）
+    const structuredMsg = JSON.stringify({
+      type: 'message',
+      content: message,
+      fromUid: visitorId || '',
+      channelId: extraData?.channelId || visitorId || '',
+      channelType: extraData?.channelType ?? 1,
+      contentType: extraData?.contentType ?? 1,
+      messageId: extraData?.messageId || '',
+      timestamp: extraData?.timestamp || Math.floor((sendTimestamp || Date.now()) / 1000)
+    });
+    console.log(`[OpenClaw WS] 📤 发送chat.send sessionKey=${sessionKey} visitorId=${visitorId} t=${sendTimestamp}`);
+
+    this.send({
+      type: 'req',
+      id: this.generateId(),
+      method: 'chat.send',
+      params: {
+        sessionKey: sessionKey,
+        message: structuredMsg,
+        deliver: false,
+        idempotencyKey: this.generateId()
+      }
+    });
+  }
+
+  /**
+   * 处理 IM 新消息（入口方法）
+   */
+  async onNewMessage(channelId, messageContent, agentId) {
+    console.log(`[OpenClaw WS] onNewMessage 被调用 - Channel: ${channelId}`);
+    console.log(`[OpenClaw WS] 当前状态: enabled=${this.enabled}, connected=${this.connected}, connecting=${this.connecting}`);
+    console.log(`[OpenClaw WS] 当前处理中的频道:`, Array.from(this.processingChannels));
+
+    if (!this.enabled) {
+      console.log('[OpenClaw WS] ❌ 未启用，跳过处理');
+      return;
+    }
+
+    if (this.processingChannels.has(channelId)) {
+      console.log('[OpenClaw WS] ❌ 该频道正在处理中，跳过');
+      return;
+    }
+
+    try {
+      this.processingChannels.add(channelId);
+      console.log(`[OpenClaw WS] ✅ 开始处理 - Channel: ${channelId}`);
+      console.log(`[OpenClaw WS] 消息内容: ${messageContent?.substring(0, 100)}`);
+
+      // 构建提示词 - 简洁版本，避免双重身份定义
+      const prompt = `用户消息：${messageContent}
+
+请直接回复用户，保持友好专业的语气（100字以内）。只输出回复内容。`;
+      
+      console.log('[OpenClaw WS] 发送消息到 OpenClaw Gateway...');
+      const reply = await this.sendMessage(prompt, channelId);
+      console.log(`[OpenClaw WS] 收到回复: ${reply?.substring(0, 100)}`);
+
+      if (reply && reply.trim()) {
+        // 发送回复到 VOKO IM
+        await this.sendReply(channelId, reply, agentId);
+        console.log('[OpenClaw WS] ✅ 回复发送成功');
+      } else {
+        console.warn('[OpenClaw WS] ⚠️ 收到空回复，不发送');
+      }
+
+    } catch (err) {
+      console.error('[OpenClaw WS] ❌ 处理失败:', err.message);
+      console.error('[OpenClaw WS] 错误堆栈:', err.stack);
+    } finally {
+      this.processingChannels.delete(channelId);
+      console.log(`[OpenClaw WS] 清理完成 - Channel: ${channelId}`);
+    }
+  }
+
+  /**
+   * 发送回复到 VOKO IM HTTP API
+   */
+  sendReply(channelId, content, agentId) {
+    return new Promise((resolve, reject) => {
+      const http = require('http');
+
+      // 剥离 gym agent 消息中的 visitorId 前缀（格式: "{visitorId}\n\n{content}"）
+      const prefix = channelId + '\n\n';
+      const cleanContent = content?.startsWith(prefix) ? content.substring(prefix.length) : content;
+
+      const postData = JSON.stringify({
+        toUid: channelId,
+        content: cleanContent,
+        channelType: 1,
+        agentId: agentId
+      });
+
+      console.log(`[OpenClaw WS] 发送回复到 IM API: POST localhost:3002/api/send-message agent=${agentId}`);
+      console.log(`[OpenClaw WS] Channel: ${channelId}, Content: ${cleanContent?.substring(0, 80)}...`);
+
+      const req = http.request({
+        hostname: 'localhost',
+        port: 3002,
+        path: '/api/send-message',
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(postData)
+        }
+      }, (res) => {
+        let data = '';
+        res.on('data', chunk => data += chunk);
+        res.on('end', () => {
+          console.log(`[OpenClaw WS] IM API 响应: ${res.statusCode}, ${data}`);
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            // 发送成功后，通知渲染进程显示这条消息
+            const timestamp = Date.now() / 1000;
+            bus.emit('gym:reply-sent', {
+              channelId,
+              content: cleanContent,
+              timestamp,
+              agentId
+            });
+            resolve(data);
+          } else {
+            reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+          }
+        });
+      });
+
+      req.on('error', (err) => {
+        console.error('[OpenClaw WS] 发送回复失败:', err.message);
+        reject(err);
+      });
+      
+      req.write(postData);
+      req.end();
+    });
+  }
+
+  /**
+   * 销毁处理器（清理资源）
+   */
+  destroy() {
+    console.log('[OpenClaw WS] 销毁处理器...');
+    this.stopConfigWatcher();
+    this.disconnect();
+    this.messageQueue = [];
+  }
+
+  /**
+   * 测试到 main agent 的连接
+   */
+  testMainAgent() {
+    return new Promise((resolve) => {
+      const testSessionKey = 'agent:main:main';
+      const testMessage = '[VOKO连接测试] 这是一条来自voko-desktop的WS连接测试消息，如果正常收到，请回复：已正常接收VOKO消息';
+      this.addLog(`🧪 发送测试消息到 ${testSessionKey}...`);
+      this.addLog(`📤 发送内容: ${testMessage}`);
+
+      if (!this.connected) {
+        this.addLog('❌ 未连接，无法发送测试消息');
+        resolve({ success: false, error: '未连接' });
+        return;
+      }
+
+      let gotEcho = false;
+      const sendTime = Date.now();
+      const handler = (msg) => {
+        if (msg.type === 'event' && msg.event === 'session.message') {
+          const innerMsg = msg.payload?.message;
+          if (!innerMsg) return;
+          const rawContent = innerMsg.content || [];
+          let text = '';
+          if (Array.isArray(rawContent)) {
+            for (const item of rawContent) {
+              if (item.type === 'text' && item.text) text += item.text;
+            }
+          } else if (typeof rawContent === 'string') {
+            text = rawContent;
+          }
+          if (!text) return;
+          // 跳过第一次回显，只处理真正的回复
+          if (text.includes('[VOKO连接测试]')) {
+            gotEcho = true;
+            return;
+          }
+          const cleanText = text.replace(/\n/g, ' ').trim();
+          const elapsed = Math.round((Date.now() - sendTime) / 1000);
+          this.addLog(`🤖 Agent回复: ${cleanText}（耗时${elapsed}秒）`);
+          this.off('session.message', handler);
+          clearTimeout(timer);
+          resolve({ success: true, reply: text, elapsed });
+        }
+      };
+      this.on('session.message', handler);
+
+      const timer = setTimeout(() => {
+        this.off('session.message', handler);
+        this.addLog('⏰ 测试超时（60秒内无回复）');
+        resolve({ success: false, error: '超时' });
+      }, 60000);
+
+      this.sendToSession(testSessionKey, testMessage).catch(err => {
+        clearTimeout(timer);
+        this.off('session.message', handler);
+        this.addLog(`❌ 测试失败: ${err.message}`);
+        resolve({ success: false, error: err.message });
+      });
+    });
+  }
+}
+
+module.exports = OpenClawWebSocketHandler;