@tencent-connect/openclaw-qqbot 1.6.7-beta.3 → 1.6.7

package/README.md

@@ -10,7 +10,7 @@
 
 **Connect your AI assistant to QQ — private chat, group chat, and rich media, all in one plugin.**
 
-### 🚀 Current Version: `v1.6.6`
+### 🚀 Current Version: `v1.6.7`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)

package/README.zh.md

@@ -9,7 +9,7 @@
 
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
-### 🚀 当前版本： `v1.6.6`
+### 🚀 当前版本： `v1.6.7`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)

package/dist/src/slash-commands.js

@@ -21,11 +21,8 @@ import { fileURLToPath } from "node:url";
 import { getPackageVersion } from "./utils/pkg-version.js";
 const require = createRequire(import.meta.url);
 let PLUGIN_VERSION = getPackageVersion(import.meta.url);
-// 获取 openclaw 框架版本（缓存结果，只执行一次）
-let _frameworkVersion = null;
+// 获取 openclaw 框架版本（不缓存，每次实时获取）
 export function getFrameworkVersion() {
-    if (_frameworkVersion !== null)
-        return _frameworkVersion;
     try {
         // 先尝试 PATH 中的 CLI
         // Windows 上 npm 安装的 CLI 通常是 .cmd wrapper，execFileSync 需要 shell:true 才能执行
@@ -37,8 +34,7 @@ export function getFrameworkVersion() {
                 }).trim();
                 // 输出格式: "OpenClaw 2026.3.13 (61d171a)"
                 if (out) {
-                    _frameworkVersion = out;
-                    return _frameworkVersion;
+                    return out;
                 }
             }
             catch {
@@ -50,16 +46,14 @@ export function getFrameworkVersion() {
         if (cliPath) {
             const out = execCliSync(cliPath, ["--version"]);
             if (out) {
-                _frameworkVersion = out;
-                return _frameworkVersion;
+                return out;
             }
         }
     }
     catch {
         // fallback
     }
-    _frameworkVersion = "unknown";
-    return _frameworkVersion;
+    return "unknown";
 }
 // ============ 热更新兼容性检查 ============
 /**
@@ -152,7 +146,7 @@ function checkUpgradeCompatibility() {
     // 3. 检查 Node.js 版本
     const nodeVer = process.version.replace(/^v/, "");
     if (compareSemver(nodeVer, req.minNodeVersion) < 0) {
-        errors.push(`❌ NoVBNde.js 版本过低：当前 **v${nodeVer}**，热更新要求最低 **v${req.minNodeVersion}**`);
+        errors.push(`❌ Node.js 版本过低：当前 **v${nodeVer}**，热更新要求最低 **v${req.minNodeVersion}**`);
     }
     // 4. 检查系统架构（arm 等特殊架构提示）
     const arch = process.arch;
@@ -690,10 +684,118 @@ function fireHotUpgrade(targetVersion, pkg, useLocal) {
         shellArgs = [scriptPath, "--no-restart", ...(targetVersion ? ["--version", targetVersion] : []), ...(pkg ? ["--pkg", pkg] : [])];
     }
     console.log(`[qqbot] fireHotUpgrade: shell=${shell}, script=${scriptPath}, cli=${cli}, target=${targetVersion || "latest"}, pkg=${pkg || "default"}`);
+    // ── 兼容 openclaw 3.23+ 配置严格校验 ──
+    // openclaw plugins install/update 启动时会校验整个配置文件，
+    // 如果 channels.qqbot 已存在但 qqbot 插件尚未加载，校验会报 "unknown channel id: qqbot"。
+    //
+    // ⚠️ 关键：绝不能直接修改真实的 openclaw.json！
+    //    gateway 的 config file watcher 会检测到变更并触发 SIGUSR1 重启，
+    //    导致当前进程被杀、execFile 回调（restoreConfigAndCleanup）永远不会执行，
+    //    channels.qqbot 配置就此丢失。
+    //
+    // 策略：创建临时配置副本（不含 channels.qqbot），通过 OPENCLAW_CONFIG_PATH
+    //       环境变量传递给子进程，真实配置文件不受影响。
+    //       shell 脚本（upgrade-via-npm.sh）内部也有同样的临时配置机制作为双保险。
+    const homeDir = getHomeDir();
+    const realConfigPath = path.join(homeDir, ".openclaw", "openclaw.json");
+    let tempConfigPath = null;
+    const childEnv = { ...process.env };
+    try {
+        if (fs.existsSync(realConfigPath)) {
+            const cfg = JSON.parse(fs.readFileSync(realConfigPath, "utf8"));
+            const needsTempConfig = !!(cfg.channels?.qqbot) ||
+                !!(cfg.plugins?.entries?.["openclaw-qqbot"]);
+            if (needsTempConfig) {
+                // 创建临时配置副本（移除 channels.qqbot 和 plugins.entries.openclaw-qqbot）
+                const cleanCfg = JSON.parse(JSON.stringify(cfg)); // deep clone
+                if (cleanCfg.channels?.qqbot) {
+                    delete cleanCfg.channels.qqbot;
+                    if (Object.keys(cleanCfg.channels).length === 0)
+                        delete cleanCfg.channels;
+                }
+                if (cleanCfg.plugins?.entries?.["openclaw-qqbot"]) {
+                    delete cleanCfg.plugins.entries["openclaw-qqbot"];
+                    if (cleanCfg.plugins.entries && Object.keys(cleanCfg.plugins.entries).length === 0)
+                        delete cleanCfg.plugins.entries;
+                }
+                const tmpDir = path.join(homeDir, ".openclaw", ".qqbot-upgrade-tmp");
+                fs.mkdirSync(tmpDir, { recursive: true });
+                tempConfigPath = path.join(tmpDir, "openclaw-tmp.json");
+                fs.writeFileSync(tempConfigPath, JSON.stringify(cleanCfg, null, 4) + "\n");
+                childEnv.OPENCLAW_CONFIG_PATH = tempConfigPath;
+                console.log(`[qqbot] fireHotUpgrade: created temp config without channels.qqbot (OPENCLAW_CONFIG_PATH=${tempConfigPath}), real config untouched`);
+            }
+        }
+    }
+    catch (e) {
+        console.warn(`[qqbot] fireHotUpgrade: failed to create temp config: ${e.message}, proceeding with original`);
+        tempConfigPath = null;
+    }
+    /**
+     * 将 openclaw plugins install 写入临时配置的 installs/entries 记录同步回真实配置，
+     * 然后清理临时文件。
+     *
+     * 注意：真实配置中的 channels.qqbot 从未被移除，无需恢复。
+     */
+    function syncTempConfigAndCleanup() {
+        try {
+            if (tempConfigPath && fs.existsSync(tempConfigPath) && fs.existsSync(realConfigPath)) {
+                const tmp = JSON.parse(fs.readFileSync(tempConfigPath, "utf8"));
+                const real = JSON.parse(fs.readFileSync(realConfigPath, "utf8"));
+                let changed = false;
+                // 同步 plugins.installs（openclaw plugins install 会写入安装记录）
+                if (tmp.plugins?.installs) {
+                    if (!real.plugins)
+                        real.plugins = {};
+                    real.plugins.installs = { ...(real.plugins.installs || {}), ...tmp.plugins.installs };
+                    changed = true;
+                }
+                // 同步 plugins.entries（openclaw plugins install 会写入 entries）
+                // 注意：不同步 openclaw-qqbot 自身的 entry，因为插件通过 auto-discover 加载，
+                // 显式写入 entries 会导致 "duplicate plugin id" 警告刷屏。
+                if (tmp.plugins?.entries) {
+                    if (!real.plugins)
+                        real.plugins = {};
+                    if (!real.plugins.entries)
+                        real.plugins.entries = {};
+                    for (const [k, v] of Object.entries(tmp.plugins.entries)) {
+                        if (k === "openclaw-qqbot")
+                            continue; // 跳过自身，避免 duplicate
+                        if (!real.plugins.entries[k]) {
+                            real.plugins.entries[k] = v;
+                            changed = true;
+                        }
+                    }
+                }
+                if (changed) {
+                    fs.writeFileSync(realConfigPath, JSON.stringify(real, null, 4) + "\n");
+                    console.log("[qqbot] fireHotUpgrade: synced install/entries records from temp config to real config");
+                }
+            }
+        }
+        catch (e) {
+            console.warn(`[qqbot] fireHotUpgrade: failed to sync temp config: ${e.message}`);
+        }
+        // 清理临时文件
+        try {
+            if (tempConfigPath)
+                fs.unlinkSync(tempConfigPath);
+        }
+        catch { /* ignore */ }
+    }
     // 异步执行升级脚本
-    execFile(shell, shellArgs, {
-        timeout: 120_000,
-        env: { ...process.env },
+    // 必须显式设置 cwd 为一个确定存在的目录（如 homeDir），
+    // 否则子进程继承 gateway 的 cwd，如果该目录在升级过程中被删除/移动，
+    // openclaw CLI 启动时 process.cwd() 会报 ENOENT: uv_cwd 错误。
+    // 超时设为 5 分钟：openclaw plugins install 需要下载 npm 包，
+    // 网络慢时（如国内访问 npm registry）可能需要 2-3 分钟。
+    // 120 秒超时会导致脚本被杀但 openclaw CLI 子进程继续运行，
+    // 同时 bash 的 cleanup_on_exit 回滚了备份目录，造成 "plugin already exists" 错误。
+    const child = execFile(shell, shellArgs, {
+        timeout: 300_000,
+        cwd: homeDir,
+        env: childEnv,
+        killSignal: "SIGTERM",
         ...(isWindows() ? { windowsHide: true } : {}),
     }, (error, stdout, _stderr) => {
         if (error) {
@@ -702,6 +804,25 @@ function fireHotUpgrade(targetVersion, pkg, useLocal) {
                 console.error(`[qqbot] fireHotUpgrade: stdout: ${stdout.slice(0, 2000)}`);
             if (_stderr)
                 console.error(`[qqbot] fireHotUpgrade: stderr: ${_stderr.slice(0, 2000)}`);
+            // 超时时确保子进程树被清理，防止 openclaw plugins install 继续运行
+            // 与 cleanup_on_exit 的回滚逻辑冲突（回滚恢复了旧目录，install 又尝试写入）
+            if (error.killed || error.message.includes("TIMEOUT")) {
+                try {
+                    // 尝试杀掉子进程树（SIGKILL 确保立即终止）
+                    child.kill("SIGKILL");
+                    // 额外尝试通过 pkill 杀掉可能残留的 openclaw plugins install 子进程
+                    if (!isWindows()) {
+                        try {
+                            execFileSync("pkill", ["-9", "-f", "openclaw.*plugins.*install"], { timeout: 3000, stdio: "pipe" });
+                        }
+                        catch { /* ignore */ }
+                    }
+                }
+                catch {
+                    // 进程可能已退出
+                }
+            }
+            syncTempConfigAndCleanup();
             cleanupTempScript();
             _upgrading = false;
             return;
@@ -712,12 +833,14 @@ function fireHotUpgrade(targetVersion, pkg, useLocal) {
         const newVersion = versionMatch?.[1];
         if (newVersion === "unknown") {
             console.error(`[qqbot] fireHotUpgrade: script output QQBOT_NEW_VERSION=unknown, aborting restart`);
+            syncTempConfigAndCleanup();
             cleanupTempScript();
             _upgrading = false;
             return;
         }
         console.log(`[qqbot] fireHotUpgrade: new version=${newVersion || "(not detected)"}, triggering restart...`);
-        // 脚本执行成功，清理临时脚本副本
+        // 脚本执行成功，同步临时配置中的 install 记录并清理
+        syncTempConfigAndCleanup();
         cleanupTempScript();
         // 文件替换成功，在 restart 之前把 source 从 path 切换为 npm，
         // 确保新进程启动时读到的是 npm source，不会被本地源码覆盖。
@@ -760,17 +883,175 @@ function fireHotUpgrade(targetVersion, pkg, useLocal) {
             }
         }
         else {
-            // Mac/Linux: 直接 restart（框架通常以 daemon 模式运行）
-            execCliAsync(cli, ["gateway", "restart"], { timeout: 30_000 }, (restartErr) => {
-                if (restartErr) {
-                    console.error(`[qqbot] fireHotUpgrade: restart failed: ${restartErr.message}, trying stop+start fallback`);
-                    execCliAsync(cli, ["gateway", "stop"], { timeout: 10_000 }, () => {
-                        setTimeout(() => {
-                            execCliAsync(cli, ["gateway", "start"], { timeout: 30_000 }, () => { });
-                        }, 1000);
-                    });
+            // Mac/Linux: 使用 detached shell 脚本执行 stop+start
+            //
+            // 兼容 openclaw 2026.3.24+ 配置严格校验：
+            //   gateway restart 时 openclaw 先校验配置（loadConfig）再加载插件。
+            //   如果 channels.qqbot 存在但 qqbot channel type 尚未注册，校验会失败。
+            //   解决：stop 后临时移除 channels.qqbot → start（插件加载、qqbot type 注册）→ 恢复。
+            const cliInvoke = cli.endsWith(".mjs")
+                ? `"${process.execPath}" "${cli}"`
+                : `"${cli}"`;
+            const homeDir = getHomeDir();
+            const configPath = path.join(homeDir, ".openclaw", "openclaw.json");
+            const qqbotChannelBackup = path.join(homeDir, ".openclaw", ".qqbot-channel-backup.json");
+            const restartScript = path.join(homeDir, ".openclaw", ".qqbot-restart.sh");
+            // 先保存 channels.qqbot 到临时文件（在当前进程中，JSON 处理更安全）
+            let hasChannel = false;
+            try {
+                const cfgRaw = fs.readFileSync(configPath, "utf8");
+                const cfg = JSON.parse(cfgRaw);
+                const qqbot = cfg?.channels?.qqbot;
+                if (qqbot) {
+                    fs.writeFileSync(qqbotChannelBackup, JSON.stringify(qqbot, null, 2), "utf8");
+                    hasChannel = true;
                 }
-            });
+            }
+            catch {
+                // 配置文件不存在或 JSON 解析失败，不做处理
+            }
+            const shContent = `#!/bin/bash
+# 注意：不使用 set -e，因为 gateway start 失败时仍需恢复 channels.qqbot
+CLI="${cliInvoke}"
+CONFIG="${configPath}"
+BACKUP="${qqbotChannelBackup}"
+
+# ── 兼容 openclaw 3.23+ 配置严格校验 ──
+# 所有 openclaw CLI 命令（包括 gateway stop/start）启动时都会 loadConfig 校验配置，
+# 如果 channels.qqbot 存在但 qqbot 插件尚未加载，校验会报 "unknown channel id: qqbot"。
+#
+# 策略：
+#   1. gateway stop：使用 OPENCLAW_CONFIG_PATH 临时配置（不含 channels.qqbot）
+#   2. gateway start：先尝试直接启动（真实配置），如果 CLI 校验失败，
+#      则临时修改真实配置（此时 gateway 已停止，无 config watcher），启动后恢复。
+#      这样 gateway 进程读取的是完整配置（含 channels.qqbot）。
+
+# 为 gateway stop 创建临时配置
+TEMP_RESTART_CONFIG=""
+if [ -f "$BACKUP" ]; then
+  TEMP_RESTART_CONFIG="\$(mktemp)"
+  node -e "
+    const fs = require('fs');
+    const cfg = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+    if (cfg.channels && cfg.channels.qqbot) {
+      delete cfg.channels.qqbot;
+      if (Object.keys(cfg.channels).length === 0) delete cfg.channels;
+    }
+    if (cfg.plugins && cfg.plugins.entries && cfg.plugins.entries['openclaw-qqbot']) {
+      delete cfg.plugins.entries['openclaw-qqbot'];
+      if (Object.keys(cfg.plugins.entries).length === 0) delete cfg.plugins.entries;
+    }
+    fs.writeFileSync(process.argv[2], JSON.stringify(cfg, null, 4) + '\\n');
+  " "$CONFIG" "$TEMP_RESTART_CONFIG" 2>/dev/null
+  if [ \$? -ne 0 ] || [ ! -s "$TEMP_RESTART_CONFIG" ]; then
+    echo "[qqbot-upgrade] WARNING: failed to create temp config"
+    TEMP_RESTART_CONFIG=""
+  fi
+fi
+
+echo "[qqbot-upgrade] Stopping gateway..."
+if [ -n "$TEMP_RESTART_CONFIG" ]; then
+  OPENCLAW_CONFIG_PATH="$TEMP_RESTART_CONFIG" $CLI gateway stop 2>/dev/null || true
+else
+  $CLI gateway stop 2>/dev/null || true
+fi
+sleep 2
+
+# 清理临时配置（不再需要）
+if [ -n "$TEMP_RESTART_CONFIG" ] && [ -f "$TEMP_RESTART_CONFIG" ]; then
+  rm -f "$TEMP_RESTART_CONFIG"
+fi
+
+echo "[qqbot-upgrade] Starting gateway..."
+START_OK=false
+
+# 先尝试直接启动（使用真实配置，含 channels.qqbot）
+# 如果 openclaw 版本不做严格校验，或者插件已注册，这会直接成功
+if $CLI gateway start 2>/dev/null; then
+  START_OK=true
+  echo "[qqbot-upgrade] Gateway started successfully (direct start)"
+elif [ -f "$BACKUP" ]; then
+  # 直接启动失败（可能是 channels.qqbot 校验失败），
+  # 临时修改真实配置（此时 gateway 已停止，无 config watcher，安全）
+  echo "[qqbot-upgrade] Direct start failed, temporarily removing channels.qqbot from real config..."
+  node -e "
+    const fs = require('fs');
+    const cfg = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+    let changed = false;
+    if (cfg.channels && cfg.channels.qqbot) {
+      delete cfg.channels.qqbot;
+      if (Object.keys(cfg.channels).length === 0) delete cfg.channels;
+      changed = true;
+    }
+    if (cfg.plugins && cfg.plugins.entries && cfg.plugins.entries['openclaw-qqbot']) {
+      delete cfg.plugins.entries['openclaw-qqbot'];
+      if (Object.keys(cfg.plugins.entries).length === 0) delete cfg.plugins.entries;
+      changed = true;
+    }
+    if (changed) {
+      fs.writeFileSync(process.argv[1], JSON.stringify(cfg, null, 4) + '\\n');
+    }
+  " "$CONFIG" 2>/dev/null
+
+  if $CLI gateway start 2>/dev/null; then
+    START_OK=true
+    echo "[qqbot-upgrade] Gateway started successfully (after config fix)"
+  else
+    echo "[qqbot-upgrade] WARNING: gateway start still failed after config fix"
+  fi
+
+  # 等待 gateway 进程启动并加载插件（插件注册 qqbot channel type）
+  echo "[qqbot-upgrade] Waiting for plugin to load (8s)..."
+  sleep 8
+
+  # 恢复 channels.qqbot 到真实配置
+  # gateway 的 config file watcher 会检测到变更并热加载
+  echo "[qqbot-upgrade] Restoring channels.qqbot to real config..."
+  node -e "
+    const fs = require('fs');
+    const cfg = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+    const qqbot = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+    if (!cfg.channels) cfg.channels = {};
+    cfg.channels.qqbot = qqbot;
+    // 注意：不写入 plugins.entries.openclaw-qqbot，
+    // 插件通过 auto-discover 加载，显式 entry 会导致 duplicate plugin id 警告。
+    fs.writeFileSync(process.argv[1], JSON.stringify(cfg, null, 4) + '\\n');
+  " "$CONFIG" "$BACKUP" 2>/dev/null
+  rm -f "$BACKUP"
+  echo "[qqbot-upgrade] channels.qqbot restored"
+else
+  echo "[qqbot-upgrade] WARNING: gateway start failed, no backup to restore"
+fi
+
+# 直接启动成功的情况下，清理备份文件
+if [ "$START_OK" = "true" ] && [ -f "$BACKUP" ]; then
+  rm -f "$BACKUP"
+fi
+
+# 如果 start 失败，尝试再次启动
+if [ "$START_OK" != "true" ]; then
+  echo "[qqbot-upgrade] Retrying gateway start..."
+  sleep 2
+  $CLI gateway start 2>/dev/null || echo "[qqbot-upgrade] WARNING: retry also failed"
+fi
+
+# 清理自身
+rm -f "$0"
+echo "[qqbot-upgrade] Done."
+`;
+            try {
+                fs.writeFileSync(restartScript, shContent, { mode: 0o755 });
+                const child = spawn("bash", [restartScript], {
+                    detached: true,
+                    stdio: "ignore",
+                });
+                child.unref();
+                console.log(`[qqbot] fireHotUpgrade: launched detached restart script (pid=${child.pid}), hasChannel=${hasChannel}`);
+            }
+            catch (shErr) {
+                console.error(`[qqbot] fireHotUpgrade: failed to launch restart script: ${shErr.message}, falling back to direct restart`);
+                execCliAsync(cli, ["gateway", "restart"], { timeout: 30_000 }, () => { });
+            }
         }
     });
     return { ok: true };

package/dist/src/utils/pkg-version.js

@@ -6,10 +6,22 @@ import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import path from "node:path";
 import fs from "node:fs";
-let _cached = null;
+/** 已定位到的 package.json 路径，避免重复遍历目录树 */
+let _resolvedPkgPath = null;
 export function getPackageVersion(metaUrl) {
-    if (_cached !== null)
-        return _cached;
+    // 如果之前已定位到 package.json 路径，直接重新读取（快速路径）
+    if (_resolvedPkgPath) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(_resolvedPkgPath, "utf8"));
+            if (pkg.name === "@tencent-connect/openclaw-qqbot" && pkg.version) {
+                return pkg.version;
+            }
+        }
+        catch {
+            // 文件可能已被删除（升级过程中），清除路径缓存，走完整查找
+            _resolvedPkgPath = null;
+        }
+    }
     // Strategy 1: 从调用者的 import.meta.url（或本模块）向上遍历找 package.json
     const startFile = metaUrl ? fileURLToPath(metaUrl) : fileURLToPath(import.meta.url);
     let dir = path.dirname(startFile);
@@ -21,8 +33,8 @@ export function getPackageVersion(metaUrl) {
                 const pkg = JSON.parse(fs.readFileSync(candidate, "utf8"));
                 // 确认是我们自己的包（避免找到其他 package.json）
                 if (pkg.name === "@tencent-connect/openclaw-qqbot" && pkg.version) {
-                    _cached = pkg.version;
-                    return _cached;
+                    _resolvedPkgPath = candidate;
+                    return pkg.version;
                 }
             }
         }
@@ -38,14 +50,12 @@ export function getPackageVersion(metaUrl) {
             try {
                 const pkg = require(rel);
                 if (pkg?.version) {
-                    _cached = pkg.version;
-                    return _cached;
+                    return pkg.version;
                 }
             }
             catch { /* next */ }
         }
     }
     catch { /* fallback */ }
-    _cached = "unknown";
-    return _cached;
+    return "unknown";
 }

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@tencent-connect/openclaw-qqbot",
-  "version": "1.6.7-beta.3",
+  "version": "1.6.7",
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/upgrade-via-npm.sh

@@ -18,15 +18,62 @@
 
 set -eo pipefail
 
-# 异常退出时清理临时文件（防止泄露或残留）
+# ⚠️ 必须在 cd 之前解析脚本路径，否则相对路径的 $0 在 cd 后无法正确解析
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# 确保 cwd 是一个存在的目录。
+# 当从 gateway 进程 fork 时，继承的 cwd 可能已被删除（如旧插件目录被 mv/rm），
+# 导致 openclaw CLI 启动时 process.cwd() 报 ENOENT: uv_cwd 错误。
+cd "$HOME" 2>/dev/null || cd / 2>/dev/null || true
+
+# 异常退出时清理临时文件并回滚（防止泄露或残留）
+INSTALL_COMPLETED=false  # 标记 install 是否已完成（用于区分正常退出和异常退出）
 cleanup_on_exit() {
+    local exit_code=$?
+
+    # 异常退出时同步临时配置中的 install 记录回真实配置
     if [ -n "$TEMP_CONFIG_FILE" ] && [ -f "$TEMP_CONFIG_FILE" ]; then
+        # 尝试同步 install 记录（即使异常退出也要保留）
+        node -e "
+          try {
+            const fs = require('fs');
+            const tmp = JSON.parse(fs.readFileSync('$TEMP_CONFIG_FILE', 'utf8'));
+            const real = JSON.parse(fs.readFileSync('$CONFIG_FILE', 'utf8'));
+            if (tmp.plugins && tmp.plugins.installs) {
+              if (!real.plugins) real.plugins = {};
+              real.plugins.installs = { ...(real.plugins.installs || {}), ...tmp.plugins.installs };
+            }
+            if (tmp.plugins && tmp.plugins.entries) {
+              if (!real.plugins) real.plugins = {};
+              real.plugins.entries = { ...(real.plugins.entries || {}), ...tmp.plugins.entries };
+            }
+            fs.writeFileSync('$CONFIG_FILE', JSON.stringify(real, null, 4) + '\n');
+          } catch {}
+        " 2>/dev/null || true
         rm -f "$TEMP_CONFIG_FILE" 2>/dev/null || true
     fi
-    # 异常退出时清理本次备份目录（正常流程中备份已被删除或回滚，这里是兜底）
-    if [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ]; then
+
+    # 异常退出且 install 未完成时，回滚备份目录（而非删除）
+    if [ "$INSTALL_COMPLETED" != "true" ] && [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ]; then
+        if [ ! -d "$EXTENSIONS_DIR/$PLUGIN_ID" ] || [ ! -f "$EXTENSIONS_DIR/$PLUGIN_ID/package.json" ]; then
+            # 插件目录不存在或不完整，回滚
+            rm -rf "$EXTENSIONS_DIR/$PLUGIN_ID" 2>/dev/null || true
+            mv "$BACKUP_DIR/$PLUGIN_ID" "$EXTENSIONS_DIR/$PLUGIN_ID" 2>/dev/null || \
+            mv "$BACKUP_DIR"/* "$EXTENSIONS_DIR/$PLUGIN_ID" 2>/dev/null || true
+            echo "  ↩️  [cleanup] 异常退出，已回滚到旧版本"
+        else
+            # 插件目录完整，清理备份
+            rm -rf "$BACKUP_DIR" 2>/dev/null || true
+        fi
+    elif [ "$INSTALL_COMPLETED" = "true" ] && [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ]; then
+        # 正常完成，清理备份
         rm -rf "$BACKUP_DIR" 2>/dev/null || true
     fi
+
+    # 清理 openclaw install 可能残留的暂存目录（extensions 和 /tmp 中都可能存在）
+    find "${EXTENSIONS_DIR:-/dev/null}" -maxdepth 1 -name ".openclaw-install-stage-*" -exec rm -rf {} + 2>/dev/null || true
+    find "${TMPDIR:-/tmp}" -maxdepth 1 -name ".openclaw-install-stage-*" -exec rm -rf {} + 2>/dev/null || true
 }
 trap cleanup_on_exit EXIT
 
@@ -40,8 +87,6 @@ TARGET_VERSION=""
 APPID=""
 SECRET=""
 NO_RESTART=false
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
 LOCAL_VERSION="$(node -e "
   try {
@@ -180,30 +225,46 @@ echo "[1/4] 安装/升级插件..."
 #       环境变量让 plugins install/update 使用临时配置，真实配置文件不受影响。
 CONFIG_FILE="$HOME/.$CMD/$CMD.json"
 TEMP_CONFIG_FILE=""
-HAS_QQBOT_CHANNEL=false
+NEEDS_TEMP_CONFIG=false
 
 if [ -f "$CONFIG_FILE" ]; then
-    HAS_QQBOT_CHANNEL="$(node -e "
+    NEEDS_TEMP_CONFIG="$(node -e "
       try {
         const fs = require('fs');
         const cfg = JSON.parse(fs.readFileSync('$CONFIG_FILE', 'utf8'));
-        if (cfg.channels && cfg.channels.qqbot) process.stdout.write('true');
+        const hasChannel = !!(cfg.channels && cfg.channels.qqbot);
+        const hasAllow = Array.isArray(cfg.plugins?.allow) && cfg.plugins.allow.includes('$PLUGIN_ID');
+        const hasEntry = !!(cfg.plugins?.entries?.['$PLUGIN_ID']);
+        if (hasChannel || hasAllow || hasEntry) process.stdout.write('true');
       } catch {}
     " 2>/dev/null || true)"
 
-    if [ "$HAS_QQBOT_CHANNEL" = "true" ]; then
+    if [ "$NEEDS_TEMP_CONFIG" = "true" ]; then
         TEMP_CONFIG_FILE="$(mktemp)"
         node -e "
           try {
             const fs = require('fs');
             const cfg = JSON.parse(fs.readFileSync('$CONFIG_FILE', 'utf8'));
-            delete cfg.channels.qqbot;
-            if (Object.keys(cfg.channels).length === 0) delete cfg.channels;
+            // 移除 channels.qqbot（插件自定义通道，校验时会 unknown channel id）
+            if (cfg.channels?.qqbot) {
+              delete cfg.channels.qqbot;
+              if (Object.keys(cfg.channels).length === 0) delete cfg.channels;
+            }
+            // 移除 plugins.allow 中的 openclaw-qqbot（插件目录被备份后校验找不到）
+            if (Array.isArray(cfg.plugins?.allow)) {
+              cfg.plugins.allow = cfg.plugins.allow.filter(p => p !== '$PLUGIN_ID');
+              if (cfg.plugins.allow.length === 0) delete cfg.plugins.allow;
+            }
+            // 移除 plugins.entries 中的 openclaw-qqbot（同理）
+            if (cfg.plugins?.entries?.['$PLUGIN_ID']) {
+              delete cfg.plugins.entries['$PLUGIN_ID'];
+              if (Object.keys(cfg.plugins.entries).length === 0) delete cfg.plugins.entries;
+            }
             fs.writeFileSync('$TEMP_CONFIG_FILE', JSON.stringify(cfg, null, 4) + '\n');
           } catch(e) { process.exit(1); }
         " 2>/dev/null
         if [ $? -eq 0 ]; then
-            echo "  [兼容] 创建临时配置副本（不含 channels.qqbot）以通过配置校验"
+            echo "  [兼容] 创建临时配置副本（不含 channels.qqbot / plugins.allow / plugins.entries）以通过配置校验"
             export OPENCLAW_CONFIG_PATH="$TEMP_CONFIG_FILE"
         else
             echo "  ⚠️  创建临时配置失败，继续使用原配置"
@@ -216,22 +277,32 @@ fi
 # plugins install/update 可能把 install 记录写入了临时配置，需要同步回真实配置
 restore_qqbot_channel() {
     if [ -n "$TEMP_CONFIG_FILE" ] && [ -f "$TEMP_CONFIG_FILE" ]; then
-        # 将临时配置中 plugins.installs 的变更同步回真实配置
+        # 将临时配置中 plugins.installs 和 plugins.entries 的变更同步回真实配置
         node -e "
           try {
             const fs = require('fs');
             const tmp = JSON.parse(fs.readFileSync('$TEMP_CONFIG_FILE', 'utf8'));
             const real = JSON.parse(fs.readFileSync('$CONFIG_FILE', 'utf8'));
+            let changed = false;
             if (tmp.plugins && tmp.plugins.installs) {
               if (!real.plugins) real.plugins = {};
               real.plugins.installs = { ...(real.plugins.installs || {}), ...tmp.plugins.installs };
+              changed = true;
+            }
+            // 同步 plugins.entries（openclaw plugins install 会写入 entries）
+            if (tmp.plugins && tmp.plugins.entries) {
+              if (!real.plugins) real.plugins = {};
+              real.plugins.entries = { ...(real.plugins.entries || {}), ...tmp.plugins.entries };
+              changed = true;
+            }
+            if (changed) {
               fs.writeFileSync('$CONFIG_FILE', JSON.stringify(real, null, 4) + '\n');
             }
           } catch {}
         " 2>/dev/null || true
         rm -f "$TEMP_CONFIG_FILE"
         unset OPENCLAW_CONFIG_PATH
-        echo "  [兼容] 已同步 install 记录并清理临时配置副本"
+        echo "  [兼容] 已同步 install/entries 记录并清理临时配置副本"
     fi
 }
 
@@ -320,21 +391,57 @@ if [ "$UPGRADE_OK" != "true" ]; then
     echo "  执行 install: $INSTALL_SRC"
 
     if $CMD plugins install "$INSTALL_SRC" --pin 2>&1; then
-        UPGRADE_OK=true
-        echo "  ✅ install 成功"
-        # install 成功，清理备份
-        if [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ]; then
-            rm -rf "$BACKUP_DIR"
-            echo "  已清理旧版备份"
+        # install 返回 0，但需要验证插件目录是否真的存在且完整
+        if [ -d "$EXTENSIONS_DIR/$PLUGIN_ID" ] && [ -f "$EXTENSIONS_DIR/$PLUGIN_ID/package.json" ]; then
+            UPGRADE_OK=true
+            INSTALL_COMPLETED=true
+            echo "  ✅ install 成功"
+            # install 成功，清理备份
+            if [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ]; then
+                rm -rf "$BACKUP_DIR"
+                echo "  已清理旧版备份"
+            fi
+            # 清理 openclaw CLI install 可能留下的额外 backup 目录（extensions 内遗留 + 新路径）
+            find "$EXTENSIONS_DIR" -maxdepth 1 -name ".openclaw-qqbot-backup-*" -exec rm -rf {} + 2>/dev/null || true
+            find "${EXTENSIONS_DIR:-/dev/null}" -maxdepth 1 -name ".openclaw-install-stage-*" -exec rm -rf {} + 2>/dev/null || true
+            find "${TMPDIR:-/tmp}" -maxdepth 1 -name ".openclaw-install-stage-*" -exec rm -rf {} + 2>/dev/null || true
+            find "${TMPDIR:-/tmp}" -maxdepth 1 -name ".qqbot-upgrade-backup-*" -exec rm -rf {} + 2>/dev/null || true
+        else
+            echo "  ❌ install 命令返回成功但插件目录不完整"
+            echo "  [诊断] 目录存在: $([ -d "$EXTENSIONS_DIR/$PLUGIN_ID" ] && echo '是' || echo '否')"
+            echo "  [诊断] package.json 存在: $([ -f "$EXTENSIONS_DIR/$PLUGIN_ID/package.json" ] && echo '是' || echo '否')"
+            # 清理可能残留的暂存目录（extensions 和 /tmp 中都可能存在）
+            find "${EXTENSIONS_DIR:-/dev/null}" -maxdepth 1 -name ".openclaw-install-stage-*" -exec rm -rf {} + 2>/dev/null || true
+            find "${TMPDIR:-/tmp}" -maxdepth 1 -name ".openclaw-install-stage-*" -exec rm -rf {} + 2>/dev/null || true
+            # 回滚
+            if [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ]; then
+                rm -rf "$EXTENSIONS_DIR/$PLUGIN_ID" 2>/dev/null || true
+                # 备份目录内可能是 PLUGIN_ID 子目录或直接是内容
+                if [ -d "$BACKUP_DIR/$PLUGIN_ID" ]; then
+                    mv "$BACKUP_DIR/$PLUGIN_ID" "$EXTENSIONS_DIR/$PLUGIN_ID"
+                else
+                    mv "$BACKUP_DIR" "$EXTENSIONS_DIR/$PLUGIN_ID"
+                fi
+                echo "  ↩️  已回滚到旧版本"
+            fi
+            restore_qqbot_channel
+            echo "QQBOT_NEW_VERSION=unknown"
+            echo "QQBOT_REPORT=❌ QQBot 安装异常（目录不完整，已回滚），请重试或手动安装"
+            exit 1
         fi
-        # 清理 openclaw CLI install 可能留下的额外 backup 目录（extensions 内遗留 + 新路径）
-        find "$EXTENSIONS_DIR" -maxdepth 1 -name ".openclaw-qqbot-backup-*" -exec rm -rf {} + 2>/dev/null || true
-        find "${TMPDIR:-/tmp}" -maxdepth 1 -name ".qqbot-upgrade-backup-*" -exec rm -rf {} + 2>/dev/null || true
     else
         echo "  ❌ install 失败"
+        # 清理可能残留的暂存目录（extensions 和 /tmp 中都可能存在）
+        find "${EXTENSIONS_DIR:-/dev/null}" -maxdepth 1 -name ".openclaw-install-stage-*" -exec rm -rf {} + 2>/dev/null || true
+        find "${TMPDIR:-/tmp}" -maxdepth 1 -name ".openclaw-install-stage-*" -exec rm -rf {} + 2>/dev/null || true
         # 回滚：恢复旧目录
         if [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ]; then
-            mv "$BACKUP_DIR" "$EXTENSIONS_DIR/$PLUGIN_ID"
+            rm -rf "$EXTENSIONS_DIR/$PLUGIN_ID" 2>/dev/null || true
+            if [ -d "$BACKUP_DIR/$PLUGIN_ID" ]; then
+                mv "$BACKUP_DIR/$PLUGIN_ID" "$EXTENSIONS_DIR/$PLUGIN_ID"
+            else
+                mv "$BACKUP_DIR" "$EXTENSIONS_DIR/$PLUGIN_ID"
+            fi
             echo "  ↩️  已回滚到旧版本"
         fi
         restore_qqbot_channel

package/scripts/upgrade-via-source.sh

@@ -262,8 +262,9 @@ if lsof -i :18789 -sTCP:LISTEN >/dev/null 2>&1; then
     sleep 1
 fi
 
-# 清理之前可能残留的 staging 目录
+# 清理之前可能残留的 staging 目录（extensions 和 /tmp 中都可能存在）
 find "$HOME/.openclaw/extensions/" -maxdepth 1 -name ".openclaw-install-stage-*" -exec rm -rf {} + 2>/dev/null || true
+find "${TMPDIR:-/tmp}" -maxdepth 1 -name ".openclaw-install-stage-*" -exec rm -rf {} + 2>/dev/null || true
 
 # ── 清空并重新构建 dist/ ──
 # openclaw plugins install . 只做文件复制，不执行 npm lifecycle scripts。
@@ -290,7 +291,25 @@ fi
 # 由于 CJS/ESM 混用问题（Node 22 ERR_INTERNAL_ASSERTION），验证阶段可能失败
 # 但文件已成功拷贝。因此不依赖退出码，而是检查安装目录中关键文件是否存在。
 _INSTALL_DIR="$HOME/.openclaw/extensions/openclaw-qqbot"
+
+# ── 优化：安装前临时移走 node_modules ──
+# openclaw plugins install . 会把整个项目目录（含 node_modules/）复制到 extensions，
+# 但运行时只需要 bundledDependencies 中的 3 个包 + openclaw symlink。
+# 移走 node_modules 可避免复制数百个不必要的包，大幅加速安装。
+_NM_BACKUP=""
+if [ -d "$PROJ_DIR/node_modules" ]; then
+    echo "  临时移走 node_modules（避免整体复制到 extensions）..."
+    _NM_BACKUP="$PROJ_DIR/.node_modules_install_bak"
+    mv "$PROJ_DIR/node_modules" "$_NM_BACKUP"
+fi
+
 openclaw plugins install . 2>&1 | tee "$INSTALL_LOG" || true
+
+# ── 恢复 node_modules ──
+if [ -n "$_NM_BACKUP" ] && [ -d "$_NM_BACKUP" ]; then
+    mv "$_NM_BACKUP" "$PROJ_DIR/node_modules"
+    echo "  已恢复源码目录 node_modules"
+fi
 if [ ! -f "$_INSTALL_DIR/dist/index.js" ] || [ ! -f "$_INSTALL_DIR/preload.cjs" ]; then
     echo ""
     echo "❌ 插件安装失败！"
@@ -398,6 +417,13 @@ else
         echo ""
         echo "  尝试自动修复: 清理残留并重试安装..."
         find "$HOME/.openclaw/extensions/" -maxdepth 1 -name ".openclaw-install-stage-*" -exec rm -rf {} + 2>/dev/null || true
+        find "${TMPDIR:-/tmp}" -maxdepth 1 -name ".openclaw-install-stage-*" -exec rm -rf {} + 2>/dev/null || true
+        # 重试时同样移走 node_modules 避免整体复制
+        _NM_BACKUP=""
+        if [ -d "$PROJ_DIR/node_modules" ]; then
+            _NM_BACKUP="$PROJ_DIR/.node_modules_install_bak"
+            mv "$PROJ_DIR/node_modules" "$_NM_BACKUP"
+        fi
         if openclaw plugins install . 2>&1 | tee -a "$INSTALL_LOG"; then
             for _candidate_name in openclaw-qqbot qqbot openclaw-qq; do
                 if [ -d "$HOME/.openclaw/extensions/$_candidate_name" ]; then
@@ -407,6 +433,10 @@ else
                 fi
             done
         fi
+        # 恢复 node_modules
+        if [ -n "$_NM_BACKUP" ] && [ -d "$_NM_BACKUP" ]; then
+            mv "$_NM_BACKUP" "$PROJ_DIR/node_modules"
+        fi
         if [ "$_plugin_dir_ok" -eq 0 ]; then
             echo "  ❌ 重试安装仍失败，插件目录不存在"
             echo "  请手动排查: ls -la ~/.openclaw/extensions/"
@@ -440,18 +470,70 @@ else
         fi
     fi
 
-    # 清理多余的 peerDependencies 传递依赖（兼容旧版 openclaw）：
-    # openclaw v2026.3.4 之前的 plugins install 缺少 --omit=peer，会把 peerDeps
-    # （openclaw 平台及其 400+ 传递依赖）也安装到插件 node_modules 中。
-    # 新版已修复，此处通过阈值判断：包数量 > 50 才触发清理，避免对新版做无用操作。
+    # ── 复制 bundledDependencies 到插件 node_modules ──
+    # 由于安装前移走了源码的 node_modules，extensions 中的插件目录没有依赖。
+    # 只需复制 bundledDependencies（ws, silk-wasm, mpg123-decoder）及其传递依赖即可。
     PLUGIN_NM=""
     for _candidate in openclaw-qqbot qqbot openclaw-qq; do
         _nm="$HOME/.openclaw/extensions/$_candidate/node_modules"
-        [ -d "$_nm" ] && PLUGIN_NM="$_nm" && break
+        _ext_dir="$HOME/.openclaw/extensions/$_candidate"
+        [ -d "$_ext_dir" ] && PLUGIN_NM="$_nm" && break
     done
-    if [ -n "$PLUGIN_NM" ]; then
+    if [ -n "$PLUGIN_NM" ] && [ -d "$PROJ_DIR/node_modules" ]; then
+        # 如果 extensions 中已有大量包（旧版 openclaw 安装的 peerDeps），先清理
+        if [ -d "$PLUGIN_NM" ]; then
+            _before=$(ls -d "$PLUGIN_NM"/*/ "$PLUGIN_NM"/@*/*/ 2>/dev/null | wc -l | tr -d ' ')
+            if [ "$_before" -gt 50 ]; then
+                echo ""
+                echo "检测到 ${_before} 个包（超过阈值 50），清理多余的 peerDep 传递依赖..."
+                rm -rf "$PLUGIN_NM"
+            fi
+        fi
+
+        # 读取 bundledDependencies 及其传递依赖列表，只复制这些包
+        _deps_to_copy=$(node -e "
+          const fs = require('fs');
+          const path = require('path');
+          const pkgPath = path.join('$PROJ_DIR', 'package.json');
+          if (!fs.existsSync(pkgPath)) process.exit(0);
+          const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+          const bundled = pkg.bundledDependencies || pkg.bundleDependencies || [];
+          const keep = new Set();
+          const resolve = (name) => {
+            if (keep.has(name)) return;
+            keep.add(name);
+            const depPkg = path.join('$PROJ_DIR', 'node_modules', name, 'package.json');
+            if (!fs.existsSync(depPkg)) return;
+            const dep = JSON.parse(fs.readFileSync(depPkg, 'utf8'));
+            for (const d of Object.keys(dep.dependencies || {})) resolve(d);
+          };
+          bundled.forEach(resolve);
+          process.stdout.write([...keep].join('\\n'));
+        " 2>/dev/null || true)
+
+        if [ -n "$_deps_to_copy" ]; then
+            mkdir -p "$PLUGIN_NM"
+            _copied=0
+            echo "$_deps_to_copy" | while IFS= read -r _dep; do
+                _src="$PROJ_DIR/node_modules/$_dep"
+                _dst="$PLUGIN_NM/$_dep"
+                if [ -d "$_src" ] && [ ! -d "$_dst" ]; then
+                    # 处理 scoped 包（如 @scope/pkg）
+                    mkdir -p "$(dirname "$_dst")"
+                    cp -r "$_src" "$_dst"
+                fi
+            done
+            _after=$(ls -d "$PLUGIN_NM"/*/ "$PLUGIN_NM"/@*/*/ 2>/dev/null | wc -l | tr -d ' ')
+            echo "  ✅ 已复制 bundled 依赖到插件目录（${_after} 个包）"
+        else
+            echo "  ⚠️  未读取到 bundledDependencies，跳过依赖复制"
+        fi
+    elif [ -n "$PLUGIN_NM" ] && [ -d "$PLUGIN_NM" ]; then
+        # node_modules 已存在（可能是旧版 openclaw 安装的），检查是否需要清理
         _before=$(ls -d "$PLUGIN_NM"/*/ "$PLUGIN_NM"/@*/*/ 2>/dev/null | wc -l | tr -d ' ')
         if [ "$_before" -gt 50 ]; then
+            echo ""
+            echo "检测到 ${_before} 个包（超过阈值 50），清理多余的 peerDep 传递依赖..."
             # 读取 bundledDependencies 列表，只保留这些包及其子依赖
             _bundled_deps=$(node -e "
               const fs = require('fs');
@@ -490,8 +572,6 @@ else
               process.stdout.write(toRemove.join('\n'));
             " 2>/dev/null || true)
             if [ -n "$_bundled_deps" ]; then
-                echo ""
-                echo "检测到 ${_before} 个包（超过阈值 50），清理多余的 peerDep 传递依赖..."
                 echo "$_bundled_deps" | while IFS= read -r _pkg; do
                     rm -rf "$PLUGIN_NM/$_pkg"
                 done

package/src/slash-commands.ts

@@ -25,10 +25,8 @@ const require = createRequire(import.meta.url);
 
 let PLUGIN_VERSION = getPackageVersion(import.meta.url);
 
-// 获取 openclaw 框架版本（缓存结果，只执行一次）
-let _frameworkVersion: string | null = null;
+// 获取 openclaw 框架版本（不缓存，每次实时获取）
 export function getFrameworkVersion(): string {
-  if (_frameworkVersion !== null) return _frameworkVersion;
   try {
     // 先尝试 PATH 中的 CLI
     // Windows 上 npm 安装的 CLI 通常是 .cmd wrapper，execFileSync 需要 shell:true 才能执行
@@ -40,8 +38,7 @@ export function getFrameworkVersion(): string {
         }).trim();
         // 输出格式: "OpenClaw 2026.3.13 (61d171a)"
         if (out) {
-          _frameworkVersion = out;
-          return _frameworkVersion;
+          return out;
         }
       } catch {
         continue;
@@ -52,15 +49,13 @@ export function getFrameworkVersion(): string {
     if (cliPath) {
       const out = execCliSync(cliPath, ["--version"]);
       if (out) {
-        _frameworkVersion = out;
-        return _frameworkVersion;
+        return out;
       }
     }
   } catch {
     // fallback
   }
-  _frameworkVersion = "unknown";
-  return _frameworkVersion;
+  return "unknown";
 }
 
 // ============ 热更新兼容性检查 ============
@@ -162,7 +157,7 @@ function checkUpgradeCompatibility(): UpgradeCompatResult {
   // 3. 检查 Node.js 版本
   const nodeVer = process.version.replace(/^v/, "");
   if (compareSemver(nodeVer, req.minNodeVersion) < 0) {
-    errors.push(`❌ NoVBNde.js 版本过低：当前 **v${nodeVer}**，热更新要求最低 **v${req.minNodeVersion}**`);
+    errors.push(`❌ Node.js 版本过低：当前 **v${nodeVer}**，热更新要求最低 **v${req.minNodeVersion}**`);
   }
 
   // 4. 检查系统架构（arm 等特殊架构提示）
@@ -792,16 +787,137 @@ function fireHotUpgrade(targetVersion?: string, pkg?: string, useLocal?: boolean
 
   console.log(`[qqbot] fireHotUpgrade: shell=${shell}, script=${scriptPath}, cli=${cli}, target=${targetVersion || "latest"}, pkg=${pkg || "default"}`);
 
+  // ── 兼容 openclaw 3.23+ 配置严格校验 ──
+  // openclaw plugins install/update 启动时会校验整个配置文件，
+  // 如果 channels.qqbot 已存在但 qqbot 插件尚未加载，校验会报 "unknown channel id: qqbot"。
+  //
+  // ⚠️ 关键：绝不能直接修改真实的 openclaw.json！
+  //    gateway 的 config file watcher 会检测到变更并触发 SIGUSR1 重启，
+  //    导致当前进程被杀、execFile 回调（restoreConfigAndCleanup）永远不会执行，
+  //    channels.qqbot 配置就此丢失。
+  //
+  // 策略：创建临时配置副本（不含 channels.qqbot），通过 OPENCLAW_CONFIG_PATH
+  //       环境变量传递给子进程，真实配置文件不受影响。
+  //       shell 脚本（upgrade-via-npm.sh）内部也有同样的临时配置机制作为双保险。
+  const homeDir = getHomeDir();
+  const realConfigPath = path.join(homeDir, ".openclaw", "openclaw.json");
+  let tempConfigPath: string | null = null;
+  const childEnv: NodeJS.ProcessEnv = { ...process.env };
+
+  try {
+    if (fs.existsSync(realConfigPath)) {
+      const cfg = JSON.parse(fs.readFileSync(realConfigPath, "utf8"));
+      const needsTempConfig =
+        !!(cfg.channels?.qqbot) ||
+        !!(cfg.plugins?.entries?.["openclaw-qqbot"]);
+
+      if (needsTempConfig) {
+        // 创建临时配置副本（移除 channels.qqbot 和 plugins.entries.openclaw-qqbot）
+        const cleanCfg = JSON.parse(JSON.stringify(cfg)); // deep clone
+        if (cleanCfg.channels?.qqbot) {
+          delete cleanCfg.channels.qqbot;
+          if (Object.keys(cleanCfg.channels).length === 0) delete cleanCfg.channels;
+        }
+        if (cleanCfg.plugins?.entries?.["openclaw-qqbot"]) {
+          delete cleanCfg.plugins.entries["openclaw-qqbot"];
+          if (cleanCfg.plugins.entries && Object.keys(cleanCfg.plugins.entries).length === 0) delete cleanCfg.plugins.entries;
+        }
+
+        const tmpDir = path.join(homeDir, ".openclaw", ".qqbot-upgrade-tmp");
+        fs.mkdirSync(tmpDir, { recursive: true });
+        tempConfigPath = path.join(tmpDir, "openclaw-tmp.json");
+        fs.writeFileSync(tempConfigPath, JSON.stringify(cleanCfg, null, 4) + "\n");
+        childEnv.OPENCLAW_CONFIG_PATH = tempConfigPath;
+        console.log(`[qqbot] fireHotUpgrade: created temp config without channels.qqbot (OPENCLAW_CONFIG_PATH=${tempConfigPath}), real config untouched`);
+      }
+    }
+  } catch (e: any) {
+    console.warn(`[qqbot] fireHotUpgrade: failed to create temp config: ${e.message}, proceeding with original`);
+    tempConfigPath = null;
+  }
+
+  /**
+   * 将 openclaw plugins install 写入临时配置的 installs/entries 记录同步回真实配置，
+   * 然后清理临时文件。
+   *
+   * 注意：真实配置中的 channels.qqbot 从未被移除，无需恢复。
+   */
+  function syncTempConfigAndCleanup(): void {
+    try {
+      if (tempConfigPath && fs.existsSync(tempConfigPath) && fs.existsSync(realConfigPath)) {
+        const tmp = JSON.parse(fs.readFileSync(tempConfigPath, "utf8"));
+        const real = JSON.parse(fs.readFileSync(realConfigPath, "utf8"));
+        let changed = false;
+
+        // 同步 plugins.installs（openclaw plugins install 会写入安装记录）
+        if (tmp.plugins?.installs) {
+          if (!real.plugins) real.plugins = {};
+          real.plugins.installs = { ...(real.plugins.installs || {}), ...tmp.plugins.installs };
+          changed = true;
+        }
+        // 同步 plugins.entries（openclaw plugins install 会写入 entries）
+        // 注意：不同步 openclaw-qqbot 自身的 entry，因为插件通过 auto-discover 加载，
+        // 显式写入 entries 会导致 "duplicate plugin id" 警告刷屏。
+        if (tmp.plugins?.entries) {
+          if (!real.plugins) real.plugins = {};
+          if (!real.plugins.entries) real.plugins.entries = {};
+          for (const [k, v] of Object.entries(tmp.plugins.entries)) {
+            if (k === "openclaw-qqbot") continue; // 跳过自身，避免 duplicate
+            if (!real.plugins.entries[k]) {
+              real.plugins.entries[k] = v;
+              changed = true;
+            }
+          }
+        }
+
+        if (changed) {
+          fs.writeFileSync(realConfigPath, JSON.stringify(real, null, 4) + "\n");
+          console.log("[qqbot] fireHotUpgrade: synced install/entries records from temp config to real config");
+        }
+      }
+    } catch (e: any) {
+      console.warn(`[qqbot] fireHotUpgrade: failed to sync temp config: ${e.message}`);
+    }
+    // 清理临时文件
+    try { if (tempConfigPath) fs.unlinkSync(tempConfigPath); } catch { /* ignore */ }
+  }
+
   // 异步执行升级脚本
-  execFile(shell, shellArgs, {
-    timeout: 120_000,
-    env: { ...process.env },
+  // 必须显式设置 cwd 为一个确定存在的目录（如 homeDir），
+  // 否则子进程继承 gateway 的 cwd，如果该目录在升级过程中被删除/移动，
+  // openclaw CLI 启动时 process.cwd() 会报 ENOENT: uv_cwd 错误。
+  // 超时设为 5 分钟：openclaw plugins install 需要下载 npm 包，
+  // 网络慢时（如国内访问 npm registry）可能需要 2-3 分钟。
+  // 120 秒超时会导致脚本被杀但 openclaw CLI 子进程继续运行，
+  // 同时 bash 的 cleanup_on_exit 回滚了备份目录，造成 "plugin already exists" 错误。
+  const child = execFile(shell, shellArgs, {
+    timeout: 300_000,
+    cwd: homeDir,
+    env: childEnv,
+    killSignal: "SIGTERM",
     ...(isWindows() ? { windowsHide: true } : {}),
   }, (error, stdout, _stderr) => {
     if (error) {
       console.error(`[qqbot] fireHotUpgrade: script failed: ${error.message}`);
       if (stdout) console.error(`[qqbot] fireHotUpgrade: stdout: ${stdout.slice(0, 2000)}`);
       if (_stderr) console.error(`[qqbot] fireHotUpgrade: stderr: ${_stderr.slice(0, 2000)}`);
+
+      // 超时时确保子进程树被清理，防止 openclaw plugins install 继续运行
+      // 与 cleanup_on_exit 的回滚逻辑冲突（回滚恢复了旧目录，install 又尝试写入）
+      if ((error as any).killed || error.message.includes("TIMEOUT")) {
+        try {
+          // 尝试杀掉子进程树（SIGKILL 确保立即终止）
+          child.kill("SIGKILL");
+          // 额外尝试通过 pkill 杀掉可能残留的 openclaw plugins install 子进程
+          if (!isWindows()) {
+            try { execFileSync("pkill", ["-9", "-f", "openclaw.*plugins.*install"], { timeout: 3000, stdio: "pipe" }); } catch { /* ignore */ }
+          }
+        } catch {
+          // 进程可能已退出
+        }
+      }
+
+      syncTempConfigAndCleanup();
       cleanupTempScript();
       _upgrading = false;
       return;
@@ -814,6 +930,7 @@ function fireHotUpgrade(targetVersion?: string, pkg?: string, useLocal?: boolean
     const newVersion = versionMatch?.[1];
     if (newVersion === "unknown") {
       console.error(`[qqbot] fireHotUpgrade: script output QQBOT_NEW_VERSION=unknown, aborting restart`);
+      syncTempConfigAndCleanup();
       cleanupTempScript();
       _upgrading = false;
       return;
@@ -821,7 +938,8 @@ function fireHotUpgrade(targetVersion?: string, pkg?: string, useLocal?: boolean
 
     console.log(`[qqbot] fireHotUpgrade: new version=${newVersion || "(not detected)"}, triggering restart...`);
 
-    // 脚本执行成功，清理临时脚本副本
+    // 脚本执行成功，同步临时配置中的 install 记录并清理
+    syncTempConfigAndCleanup();
     cleanupTempScript();
 
     // 文件替换成功，在 restart 之前把 source 从 path 切换为 npm，
@@ -864,17 +982,175 @@ function fireHotUpgrade(targetVersion?: string, pkg?: string, useLocal?: boolean
         execCliAsync(cli, ["gateway", "restart"], { timeout: 30_000 }, () => {});
       }
     } else {
-      // Mac/Linux: 直接 restart（框架通常以 daemon 模式运行）
-      execCliAsync(cli, ["gateway", "restart"], { timeout: 30_000 }, (restartErr) => {
-        if (restartErr) {
-          console.error(`[qqbot] fireHotUpgrade: restart failed: ${restartErr.message}, trying stop+start fallback`);
-          execCliAsync(cli, ["gateway", "stop"], { timeout: 10_000 }, () => {
-            setTimeout(() => {
-              execCliAsync(cli, ["gateway", "start"], { timeout: 30_000 }, () => {});
-            }, 1000);
-          });
+      // Mac/Linux: 使用 detached shell 脚本执行 stop+start
+      //
+      // 兼容 openclaw 2026.3.24+ 配置严格校验：
+      //   gateway restart 时 openclaw 先校验配置（loadConfig）再加载插件。
+      //   如果 channels.qqbot 存在但 qqbot channel type 尚未注册，校验会失败。
+      //   解决：stop 后临时移除 channels.qqbot → start（插件加载、qqbot type 注册）→ 恢复。
+      const cliInvoke = cli.endsWith(".mjs")
+        ? `"${process.execPath}" "${cli}"`
+        : `"${cli}"`;
+      const homeDir = getHomeDir();
+      const configPath = path.join(homeDir, ".openclaw", "openclaw.json");
+      const qqbotChannelBackup = path.join(homeDir, ".openclaw", ".qqbot-channel-backup.json");
+      const restartScript = path.join(homeDir, ".openclaw", ".qqbot-restart.sh");
+
+      // 先保存 channels.qqbot 到临时文件（在当前进程中，JSON 处理更安全）
+      let hasChannel = false;
+      try {
+        const cfgRaw = fs.readFileSync(configPath, "utf8");
+        const cfg = JSON.parse(cfgRaw);
+        const qqbot = cfg?.channels?.qqbot;
+        if (qqbot) {
+          fs.writeFileSync(qqbotChannelBackup, JSON.stringify(qqbot, null, 2), "utf8");
+          hasChannel = true;
         }
-      });
+      } catch {
+        // 配置文件不存在或 JSON 解析失败，不做处理
+      }
+
+      const shContent = `#!/bin/bash
+# 注意：不使用 set -e，因为 gateway start 失败时仍需恢复 channels.qqbot
+CLI="${cliInvoke}"
+CONFIG="${configPath}"
+BACKUP="${qqbotChannelBackup}"
+
+# ── 兼容 openclaw 3.23+ 配置严格校验 ──
+# 所有 openclaw CLI 命令（包括 gateway stop/start）启动时都会 loadConfig 校验配置，
+# 如果 channels.qqbot 存在但 qqbot 插件尚未加载，校验会报 "unknown channel id: qqbot"。
+#
+# 策略：
+#   1. gateway stop：使用 OPENCLAW_CONFIG_PATH 临时配置（不含 channels.qqbot）
+#   2. gateway start：先尝试直接启动（真实配置），如果 CLI 校验失败，
+#      则临时修改真实配置（此时 gateway 已停止，无 config watcher），启动后恢复。
+#      这样 gateway 进程读取的是完整配置（含 channels.qqbot）。
+
+# 为 gateway stop 创建临时配置
+TEMP_RESTART_CONFIG=""
+if [ -f "$BACKUP" ]; then
+  TEMP_RESTART_CONFIG="\$(mktemp)"
+  node -e "
+    const fs = require('fs');
+    const cfg = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+    if (cfg.channels && cfg.channels.qqbot) {
+      delete cfg.channels.qqbot;
+      if (Object.keys(cfg.channels).length === 0) delete cfg.channels;
+    }
+    if (cfg.plugins && cfg.plugins.entries && cfg.plugins.entries['openclaw-qqbot']) {
+      delete cfg.plugins.entries['openclaw-qqbot'];
+      if (Object.keys(cfg.plugins.entries).length === 0) delete cfg.plugins.entries;
+    }
+    fs.writeFileSync(process.argv[2], JSON.stringify(cfg, null, 4) + '\\n');
+  " "$CONFIG" "$TEMP_RESTART_CONFIG" 2>/dev/null
+  if [ \$? -ne 0 ] || [ ! -s "$TEMP_RESTART_CONFIG" ]; then
+    echo "[qqbot-upgrade] WARNING: failed to create temp config"
+    TEMP_RESTART_CONFIG=""
+  fi
+fi
+
+echo "[qqbot-upgrade] Stopping gateway..."
+if [ -n "$TEMP_RESTART_CONFIG" ]; then
+  OPENCLAW_CONFIG_PATH="$TEMP_RESTART_CONFIG" $CLI gateway stop 2>/dev/null || true
+else
+  $CLI gateway stop 2>/dev/null || true
+fi
+sleep 2
+
+# 清理临时配置（不再需要）
+if [ -n "$TEMP_RESTART_CONFIG" ] && [ -f "$TEMP_RESTART_CONFIG" ]; then
+  rm -f "$TEMP_RESTART_CONFIG"
+fi
+
+echo "[qqbot-upgrade] Starting gateway..."
+START_OK=false
+
+# 先尝试直接启动（使用真实配置，含 channels.qqbot）
+# 如果 openclaw 版本不做严格校验，或者插件已注册，这会直接成功
+if $CLI gateway start 2>/dev/null; then
+  START_OK=true
+  echo "[qqbot-upgrade] Gateway started successfully (direct start)"
+elif [ -f "$BACKUP" ]; then
+  # 直接启动失败（可能是 channels.qqbot 校验失败），
+  # 临时修改真实配置（此时 gateway 已停止，无 config watcher，安全）
+  echo "[qqbot-upgrade] Direct start failed, temporarily removing channels.qqbot from real config..."
+  node -e "
+    const fs = require('fs');
+    const cfg = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+    let changed = false;
+    if (cfg.channels && cfg.channels.qqbot) {
+      delete cfg.channels.qqbot;
+      if (Object.keys(cfg.channels).length === 0) delete cfg.channels;
+      changed = true;
+    }
+    if (cfg.plugins && cfg.plugins.entries && cfg.plugins.entries['openclaw-qqbot']) {
+      delete cfg.plugins.entries['openclaw-qqbot'];
+      if (Object.keys(cfg.plugins.entries).length === 0) delete cfg.plugins.entries;
+      changed = true;
+    }
+    if (changed) {
+      fs.writeFileSync(process.argv[1], JSON.stringify(cfg, null, 4) + '\\n');
+    }
+  " "$CONFIG" 2>/dev/null
+
+  if $CLI gateway start 2>/dev/null; then
+    START_OK=true
+    echo "[qqbot-upgrade] Gateway started successfully (after config fix)"
+  else
+    echo "[qqbot-upgrade] WARNING: gateway start still failed after config fix"
+  fi
+
+  # 等待 gateway 进程启动并加载插件（插件注册 qqbot channel type）
+  echo "[qqbot-upgrade] Waiting for plugin to load (8s)..."
+  sleep 8
+
+  # 恢复 channels.qqbot 到真实配置
+  # gateway 的 config file watcher 会检测到变更并热加载
+  echo "[qqbot-upgrade] Restoring channels.qqbot to real config..."
+  node -e "
+    const fs = require('fs');
+    const cfg = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+    const qqbot = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+    if (!cfg.channels) cfg.channels = {};
+    cfg.channels.qqbot = qqbot;
+    // 注意：不写入 plugins.entries.openclaw-qqbot，
+    // 插件通过 auto-discover 加载，显式 entry 会导致 duplicate plugin id 警告。
+    fs.writeFileSync(process.argv[1], JSON.stringify(cfg, null, 4) + '\\n');
+  " "$CONFIG" "$BACKUP" 2>/dev/null
+  rm -f "$BACKUP"
+  echo "[qqbot-upgrade] channels.qqbot restored"
+else
+  echo "[qqbot-upgrade] WARNING: gateway start failed, no backup to restore"
+fi
+
+# 直接启动成功的情况下，清理备份文件
+if [ "$START_OK" = "true" ] && [ -f "$BACKUP" ]; then
+  rm -f "$BACKUP"
+fi
+
+# 如果 start 失败，尝试再次启动
+if [ "$START_OK" != "true" ]; then
+  echo "[qqbot-upgrade] Retrying gateway start..."
+  sleep 2
+  $CLI gateway start 2>/dev/null || echo "[qqbot-upgrade] WARNING: retry also failed"
+fi
+
+# 清理自身
+rm -f "$0"
+echo "[qqbot-upgrade] Done."
+`;
+      try {
+        fs.writeFileSync(restartScript, shContent, { mode: 0o755 });
+        const child = spawn("bash", [restartScript], {
+          detached: true,
+          stdio: "ignore",
+        });
+        child.unref();
+        console.log(`[qqbot] fireHotUpgrade: launched detached restart script (pid=${child.pid}), hasChannel=${hasChannel}`);
+      } catch (shErr: any) {
+        console.error(`[qqbot] fireHotUpgrade: failed to launch restart script: ${shErr.message}, falling back to direct restart`);
+        execCliAsync(cli, ["gateway", "restart"], { timeout: 30_000 }, () => {});
+      }
     }
   });
 

package/src/utils/pkg-version.ts

@@ -8,10 +8,22 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import fs from "node:fs";
 
-let _cached: string | null = null;
+/** 已定位到的 package.json 路径，避免重复遍历目录树 */
+let _resolvedPkgPath: string | null = null;
 
 export function getPackageVersion(metaUrl?: string): string {
-  if (_cached !== null) return _cached;
+  // 如果之前已定位到 package.json 路径，直接重新读取（快速路径）
+  if (_resolvedPkgPath) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(_resolvedPkgPath, "utf8"));
+      if (pkg.name === "@tencent-connect/openclaw-qqbot" && pkg.version) {
+        return pkg.version as string;
+      }
+    } catch {
+      // 文件可能已被删除（升级过程中），清除路径缓存，走完整查找
+      _resolvedPkgPath = null;
+    }
+  }
 
   // Strategy 1: 从调用者的 import.meta.url（或本模块）向上遍历找 package.json
   const startFile = metaUrl ? fileURLToPath(metaUrl) : fileURLToPath(import.meta.url);
@@ -25,8 +37,8 @@ export function getPackageVersion(metaUrl?: string): string {
         const pkg = JSON.parse(fs.readFileSync(candidate, "utf8"));
         // 确认是我们自己的包（避免找到其他 package.json）
         if (pkg.name === "@tencent-connect/openclaw-qqbot" && pkg.version) {
-          _cached = pkg.version as string;
-          return _cached;
+          _resolvedPkgPath = candidate;
+          return pkg.version as string;
         }
       }
     } catch {
@@ -42,13 +54,11 @@ export function getPackageVersion(metaUrl?: string): string {
       try {
         const pkg = require(rel);
         if (pkg?.version) {
-          _cached = pkg.version as string;
-          return _cached;
+          return pkg.version as string;
         }
       } catch { /* next */ }
     }
   } catch { /* fallback */ }
 
-  _cached = "unknown";
-  return _cached;
+  return "unknown";
 }