@tencent-connect/openclaw-qqbot 1.6.5-alpha.6 → 1.6.5

package/dist/src/gateway.js

@@ -87,6 +87,22 @@ export async function startGateway(ctx) {
             log?.info(`[qqbot:${account.accountId}] ${w}`);
         }
     }
+    // 预检 openclaw runtime 模块是否可正常解析（兼容性诊断）
+    // openclaw 3.23+ 存在 plugin-sdk/root-alias.cjs 回归 bug，
+    // 内置插件（qwen-portal-auth 等）全部加载失败，导致 AI agent 调用返回
+    // "Unable to resolve plugin runtime module"。提前检测并告警。
+    try {
+        const pluginRuntime = getQQBotRuntime();
+        if (pluginRuntime?.channel?.reply?.dispatchReplyWithBufferedBlockDispatcher) {
+            log?.info(`[qqbot:${account.accountId}] Runtime module preflight: OK`);
+        }
+        else {
+            log?.error(`[qqbot:${account.accountId}] ⚠️ Runtime preflight: dispatchReply API 不可用，AI 消息处理可能失败。请检查 openclaw 版本兼容性`);
+        }
+    }
+    catch (preflightErr) {
+        log?.error(`[qqbot:${account.accountId}] ⚠️ Runtime preflight failed: ${preflightErr}. AI 消息处理可能失败`);
+    }
     // 后台版本检查（供 /bot-version、/bot-upgrade 指令被动查询）
     triggerUpdateCheck(log);
     // 初始化 API 配置（markdown 支持）
@@ -883,8 +899,13 @@ export async function startGateway(ctx) {
                                         clearTimeout(timeoutId);
                                         timeoutId = null;
                                     }
-                                    // 发送错误提示给用户，显示完整错误信息
                                     const errMsg = String(err);
+                                    // 兼容 openclaw 3.23+ 的 plugin-sdk/root-alias.cjs 模块解析失败
+                                    if (errMsg.includes("Unable to resolve plugin runtime module") || errMsg.includes("root-alias.cjs")) {
+                                        log?.error(`[qqbot:${account.accountId}] ⚠️ openclaw 框架 runtime 模块解析失败，可能是 openclaw 版本与 plugin-sdk 不兼容。请尝试: npm install -g openclaw@latest && openclaw gateway restart`);
+                                        await sendErrorMessage("⚠️ AI 服务暂时不可用：openclaw 框架运行时模块加载失败。\n\n请管理员执行：\nnpm install -g openclaw@latest\nopenclaw gateway restart\n\n斜杠命令（如 /bot-ping）不受影响。");
+                                        return;
+                                    }
                                     if (errMsg.includes("401") || errMsg.includes("key") || errMsg.includes("auth")) {
                                         log?.error(`[qqbot:${account.accountId}] AI auth error: ${errMsg}`);
                                     }
@@ -929,7 +950,15 @@ export async function startGateway(ctx) {
                         }
                     }
                     catch (err) {
+                        const errStr = String(err);
                         log?.error(`[qqbot:${account.accountId}] Message processing failed: ${err}`);
+                        // 兼容 openclaw 3.23+ runtime 模块解析失败：给用户发可操作的提示
+                        if (errStr.includes("Unable to resolve plugin runtime module") || errStr.includes("root-alias.cjs")) {
+                            try {
+                                await sendErrorMessage("⚠️ AI 服务暂时不可用：openclaw 框架运行时模块加载失败。\n\n请管理员执行：\nnpm install -g openclaw@latest\nopenclaw gateway restart\n\n斜杠命令（如 /bot-ping）不受影响。");
+                            }
+                            catch { /* best-effort */ }
+                        }
                     }
                     finally {
                         // 无论成功/失败/超时，都停止输入状态续期

package/dist/src/slash-commands.js

@@ -726,7 +726,11 @@ function fireHotUpgrade(targetVersion) {
 /**
  * /bot-upgrade — 统一升级入口
  *
- * 产品流程：
+ * upgradeMode 开关：
+ *   - "doc"（默认）：只展示升级指引文档，不执行热更新
+ *   - "hot-reload"：执行 npm 升级脚本进行热更新
+ *
+ * 热更新模式下的产品流程：
  *   /bot-upgrade              — 展示版本信息+确认按钮（不直接升级）
  *   /bot-upgrade --latest     — 确认升级到最新版本
  *   /bot-upgrade --version X  — 升级到指定版本
@@ -735,21 +739,49 @@ function fireHotUpgrade(targetVersion) {
 let _upgrading = false; // 升级锁
 registerCommand({
     name: "bot-upgrade",
-    description: "检查更新并自动热更",
+    description: "检查更新并查看升级指引",
     usage: [
-        `/bot-upgrade              检查是否有新版本（展示信息+确认按钮）`,
-        `/bot-upgrade --latest     确认升级到最新版本`,
-        `/bot-upgrade --version X  升级到指定版本（如 1.6.5）`,
-        `/bot-upgrade --force      强制重新安装当前版本`,
-        ``,
-        `⚠️ 仅在私聊中可用。升级过程约 30~60 秒，期间服务短暂不可用。`,
-        ``,
-        `环境要求：`,
-        `  - 操作系统：macOS / Linux / Windows`,
-        `  - OpenClaw 框架版本 ≥ ${UPGRADE_REQUIREMENTS.minFrameworkVersion}`,
-        `  - Node.js ≥ v${UPGRADE_REQUIREMENTS.minNodeVersion}`,
+        `/bot-upgrade              检查是否有新版本`,
+        `/bot-upgrade --latest     确认升级到最新版本（需 upgradeMode=hot-reload）`,
+        `/bot-upgrade --version X  升级到指定版本（需 upgradeMode=hot-reload）`,
+        `/bot-upgrade --force      强制重新安装当前版本（需 upgradeMode=hot-reload）`,
     ].join("\n"),
     handler: async (ctx) => {
+        const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
+        const upgradeMode = ctx.accountConfig?.upgradeMode || "doc";
+        const args = ctx.args.trim();
+        const info = await getUpdateInfo();
+        const GITHUB_URL = "https://github.com/tencent-connect/openclaw-qqbot/";
+        // ── doc 模式（默认）：只展示升级指引，不执行热更新 ──
+        if (upgradeMode !== "hot-reload") {
+            if (info.checkedAt === 0) {
+                return `⏳ 版本检查中，请稍后再试`;
+            }
+            if (info.error) {
+                return [
+                    `❌ 主机网络访问异常，无法检查更新`,
+                    ``,
+                    `查看升级指引：[点击查看](${url})`,
+                ].join("\n");
+            }
+            if (!info.hasUpdate) {
+                return [
+                    `✅ 当前已是最新版本 v${PLUGIN_VERSION}`,
+                    ``,
+                    `项目地址：[GitHub](${GITHUB_URL})`,
+                ].join("\n");
+            }
+            return [
+                `🆕 发现新版本`,
+                ``,
+                `当前版本：**v${PLUGIN_VERSION}**`,
+                `最新版本：**v${info.latest}**`,
+                ``,
+                `📖 升级指引：[点击查看](${url})`,
+                `🌟 官方 GitHub 仓库：[点击前往](${GITHUB_URL})`,
+            ].join("\n");
+        }
+        // ── hot-reload 模式：执行热更新 ──
         // 升级相关指令仅在私聊中可用
         if (ctx.type !== "c2c") {
             return `💡 请在私聊中使用此指令`;
@@ -758,9 +790,6 @@ registerCommand({
         if (_upgrading) {
             return `⏳ 正在升级中，请稍候...`;
         }
-        const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
-        const args = ctx.args.trim();
-        const info = await getUpdateInfo();
         let isForce = false;
         let isLatest = false;
         let versionArg;
@@ -797,7 +826,6 @@ registerCommand({
                 continue;
             }
         }
-        const GITHUB_URL = "https://github.com/tencent-connect/openclaw-qqbot/";
         // ── 无参数（也没有 --latest / --version / --force）：只展示信息+确认按钮 ──
         if (!versionArg && !isLatest && !isForce) {
             if (info.checkedAt === 0) {
@@ -818,7 +846,7 @@ registerCommand({
                 ];
                 return lines.join("\n");
             }
-            // 有新版本：展示信息 + 确认按钮（同通道：alpha 只展示 alpha，正式版只展示正式版）
+            // 有新版本：展示信息 + 确认按钮
             return [
                 `🆕 发现新版本`,
                 ``,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-connect/openclaw-qqbot",
-  "version": "1.6.5-alpha.6",
+  "version": "1.6.5",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/upgrade-via-npm.sh

@@ -117,8 +117,12 @@ done
 
 EXTENSIONS_DIR="$HOME/.$CMD/extensions"
 
+# 检测 openclaw 版本
+OPENCLAW_VERSION="$($CMD --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1 || true)"
+
 echo "==========================================="
 echo "  qqbot 升级: $INSTALL_SRC"
+echo "  openclaw 版本: ${OPENCLAW_VERSION:-unknown}"
 echo "==========================================="
 echo ""
 

package/scripts/upgrade-via-source.sh

@@ -483,40 +483,33 @@ else
     ' 2>/dev/null || echo "unknown")
 fi
 
-# ── 恢复 channels.qqbot 配置 ──
-# 安装完成（无论成功或失败），把之前暂存的 channels.qqbot 写回 openclaw.json
-if [ -n "$_QQBOT_CHANNEL_STASH" ] && [ -n "$_STASH_CFG" ] && [ -f "$_STASH_CFG" ]; then
-    node -e "
-        const fs = require('fs');
-        const cfg = JSON.parse(fs.readFileSync('$_STASH_CFG', 'utf8'));
-        if (!cfg.channels) cfg.channels = {};
-        cfg.channels.qqbot = $_QQBOT_CHANNEL_STASH;
-        fs.writeFileSync('$_STASH_CFG', JSON.stringify(cfg, null, 4) + '\n');
-    " 2>/dev/null && echo "  已恢复 channels.qqbot 配置" || echo "  ⚠️  恢复 channels.qqbot 配置失败"
-fi
+# ── 暂不恢复 channels.qqbot 配置 ──
+# openclaw 3.23+ 启动时在插件加载前就校验 channels，
+# 如果此时恢复 channels.qqbot，gateway 会因 "unknown channel id: qqbot" 拒绝启动。
+# 延迟到 gateway 启动、插件加载完成后再恢复（见 Step 6）。
+echo "  [兼容] channels.qqbot 将在 gateway 启动后恢复（避免启动校验失败）"
+
+# ── Step 4/5：不在此时写入 channels.qqbot 配置 ──
+# openclaw 3.23+ 在插件加载前校验 channels，此时写入 channels.qqbot 会导致
+# "unknown channel id: qqbot" 错误。所有 channels.qqbot 相关配置延迟到
+# gateway 启动、插件加载完成后统一写入（见 Step 6 末尾）。
+#
+# 这里只计算出 DESIRED_QQBOT_TOKEN 和 MARKDOWN_VALUE，不实际写入。
 
-# 4. 配置机器人通道（仅在需要变更时写入配置，避免无意义覆盖）
+# 4. 确定机器人通道配置
 echo ""
-echo "[4/6] 配置机器人通道..."
+echo "[4/6] 准备机器人通道配置..."
 
-# 读取当前 qqbot token（兼容多 key）
+# 读取当前 qqbot token（从暂存或配置文件）
+# 注意：channels.qqbot 已被暂存移除，所以从 _QQBOT_CHANNEL_STASH 读取
 CURRENT_QQBOT_TOKEN=""
-for _app in openclaw clawdbot moltbot; do
-    _cfg="$HOME/.$_app/$_app.json"
-    if [ -f "$_cfg" ]; then
-        CURRENT_QQBOT_TOKEN=$(node -e "
-            const cfg = JSON.parse(require('fs').readFileSync('$_cfg', 'utf8'));
-            const keys = ['qqbot', 'openclaw-qqbot', 'openclaw-qq'];
-            for (const key of keys) {
-              const ch = cfg.channels && cfg.channels[key];
-              if (!ch) continue;
-              if (ch.token) { process.stdout.write(ch.token); process.exit(0); }
-              if (ch.appId && ch.clientSecret) { process.stdout.write(ch.appId + ':' + ch.clientSecret); process.exit(0); }
-            }
-        " 2>/dev/null || true)
-        [ -n "$CURRENT_QQBOT_TOKEN" ] && break
-    fi
-done
+if [ -n "$_QQBOT_CHANNEL_STASH" ]; then
+    CURRENT_QQBOT_TOKEN=$(node -e "
+        const ch = $_QQBOT_CHANNEL_STASH;
+        if (ch.token) { process.stdout.write(ch.token); }
+        else if (ch.appId && ch.clientSecret) { process.stdout.write(ch.appId + ':' + ch.clientSecret); }
+    " 2>/dev/null || true)
+fi
 
 DESIRED_QQBOT_TOKEN=""
 if [ -n "$APPID" ] && [ -n "$SECRET" ]; then
@@ -531,104 +524,40 @@ elif [ -n "$SAVED_QQBOT_TOKEN" ]; then
 fi
 
 if [ -n "$DESIRED_QQBOT_TOKEN" ]; then
-    echo "配置机器人通道: qqbot"
-    echo "目标Token: ${DESIRED_QQBOT_TOKEN:0:10}..."
-    if [ "$CURRENT_QQBOT_TOKEN" = "$DESIRED_QQBOT_TOKEN" ]; then
-        echo "✅ 当前配置已是目标值，跳过写入（避免配置覆盖提示）"
-        _config_changed=0
-    elif ! openclaw channels add --channel qqbot --token "$DESIRED_QQBOT_TOKEN" 2>&1; then
-        echo "⚠️  警告: 机器人通道配置失败，继续使用已有配置"
-        _config_changed=0
-    else
-        echo "✅ 机器人通道配置成功"
-        _config_changed=1
-        # channels 配置变更在 reload plan 中匹配为 hot reload（非 restart），
-        # 由 channel 插件热重载处理，通常 <1 秒完成，无需长时间等待。
-        sleep 1
-    fi
+    echo "目标 Token: ${DESIRED_QQBOT_TOKEN:0:10}..."
+    echo "  [兼容] 将在 gateway 启动后写入 channels.qqbot"
+elif [ -z "$CURRENT_QQBOT_TOKEN" ] && [ -z "$_QQBOT_CHANNEL_STASH" ]; then
+    echo ""
+    echo "❌ 未检测到 qqbot 通道配置！"
+    echo ""
+    echo "首次运行请提供 appid 和 appsecret："
+    echo ""
+    echo "  bash $0 --appid <你的appid> --secret <你的appsecret>"
+    echo ""
+    echo "也可以通过环境变量："
+    echo ""
+    echo "  QQBOT_APPID=<appid> QQBOT_SECRET=<appsecret> bash $0"
+    echo ""
+    echo "appid 和 appsecret 可在 QQ 开放平台 (https://q.qq.com) 获取。"
+    exit 1
 else
-    # 未提供任何可用 token 时，检查是否已有可用配置
-    _has_channel=0
-    if [ -n "$CURRENT_QQBOT_TOKEN" ]; then
-        _has_channel=1
-    fi
-
-    if [ "$_has_channel" -eq 0 ]; then
-        echo ""
-        echo "❌ 未检测到 qqbot 通道配置！"
-        echo ""
-        echo "首次运行请提供 appid 和 appsecret："
-        echo ""
-        echo "  bash $0 --appid <你的appid> --secret <你的appsecret>"
-        echo ""
-        echo "也可以通过环境变量："
-        echo ""
-        echo "  QQBOT_APPID=<appid> QQBOT_SECRET=<appsecret> bash $0"
-        echo ""
-        echo "appid 和 appsecret 可在 QQ 开放平台 (https://q.qq.com) 获取。"
-        exit 1
-    else
-        echo "使用已有配置"
-    fi
+    echo "使用已有配置（暂存中）"
 fi
 
-# 5. 配置 markdown 选项（仅在明确指定时才配置）
+# 5. 确定 markdown 选项
 echo ""
-echo "[5/6] 配置 markdown 选项..."
+echo "[5/6] 准备 markdown 配置..."
 
+MARKDOWN_VALUE=""
 if [ -n "$MARKDOWN" ]; then
-    # 设置 markdown 配置
     if [ "$MARKDOWN" = "yes" ] || [ "$MARKDOWN" = "y" ] || [ "$MARKDOWN" = "true" ]; then
         MARKDOWN_VALUE="true"
-        echo "启用 markdown 消息格式..."
+        echo "将启用 markdown 消息格式"
     else
         MARKDOWN_VALUE="false"
-        echo "禁用 markdown 消息格式（使用纯文本）..."
-    fi
-
-    CURRENT_MARKDOWN_VALUE=$(node -e "
-      const fs = require('fs');
-      const path = require('path');
-      const home = process.env.HOME;
-      for (const app of ['openclaw', 'clawdbot', 'moltbot']) {
-        const f = path.join(home, '.' + app, app + '.json');
-        if (!fs.existsSync(f)) continue;
-        try {
-          const cfg = JSON.parse(fs.readFileSync(f, 'utf8'));
-          const keys = ['qqbot', 'openclaw-qqbot', 'openclaw-qq'];
-          for (const key of keys) {
-            const ch = cfg.channels && cfg.channels[key];
-            if (!ch) continue;
-            if (typeof ch.markdownSupport === 'boolean') { process.stdout.write(String(ch.markdownSupport)); process.exit(0); }
-          }
-        } catch {}
-      }
-    " 2>/dev/null || true)
-
-    if [ "$CURRENT_MARKDOWN_VALUE" = "$MARKDOWN_VALUE" ]; then
-        echo "✅ markdown 配置已是目标值，跳过写入（避免配置覆盖提示）"
-    elif openclaw config set channels.qqbot.markdownSupport "$MARKDOWN_VALUE" 2>&1; then
-        echo "✅ markdown配置成功"
-        _config_changed=1
-    else
-        echo "⚠️  openclaw config set 失败，尝试直接编辑配置文件..."
-        OPENCLAW_CONFIG="$HOME/.openclaw/openclaw.json"
-        if [ -f "$OPENCLAW_CONFIG" ] && node -e "
-          const fs = require('fs');
-          const cfg = JSON.parse(fs.readFileSync('$OPENCLAW_CONFIG', 'utf-8'));
-          if (!cfg.channels) cfg.channels = {};
-          if (!cfg.channels.qqbot) cfg.channels.qqbot = {};
-          const target = $MARKDOWN_VALUE;
-          if (cfg.channels.qqbot.markdownSupport === target) process.exit(0);
-          cfg.channels.qqbot.markdownSupport = target;
-          fs.writeFileSync('$OPENCLAW_CONFIG', JSON.stringify(cfg, null, 4) + '\n');
-        " 2>&1; then
-            echo "✅ markdown配置成功（直接编辑配置文件）"
-            _config_changed=1
-        else
-            echo "⚠️  markdown配置设置失败，不影响后续运行"
-        fi
+        echo "将禁用 markdown 消息格式（使用纯文本）"
     fi
+    echo "  [兼容] 将在 gateway 启动后写入配置"
 else
     echo "未指定 markdown 选项，使用已有配置"
 fi
@@ -727,10 +656,70 @@ case "$start_choice" in
             fi
         fi
 
-        # 端口就绪后：检查 qqbot 连接 + 跟踪日志
+        # 端口就绪后：恢复 channels.qqbot 配置 + 检查连接 + 跟踪日志
         if [ "$_port_ready" -eq 1 ]; then
-            echo "✅ Gateway 端口已就绪"
+            echo "✅ Gateway 端口已就绪（插件已加载）"
             echo ""
+
+            # ── 恢复 channels.qqbot 配置 ──
+            # gateway 已启动、插件已注册 qqbot channel，现在可以安全写回配置
+            _need_reload=0
+            _target_cfg=""
+            for _app in openclaw clawdbot moltbot; do
+                _cfg="$HOME/.$_app/$_app.json"
+                if [ -f "$_cfg" ]; then
+                    _target_cfg="$_cfg"
+                    break
+                fi
+            done
+
+            if [ -n "$_target_cfg" ]; then
+                # 构建完整的 channels.qqbot 对象（合并暂存配置 + 新 token + markdown）
+                node -e "
+                    const fs = require('fs');
+                    const cfg = JSON.parse(fs.readFileSync('$_target_cfg', 'utf8'));
+                    if (!cfg.channels) cfg.channels = {};
+
+                    // 从暂存恢复基础配置
+                    const stash = '$_QQBOT_CHANNEL_STASH';
+                    if (stash) {
+                        try { cfg.channels.qqbot = JSON.parse(stash); } catch {}
+                    }
+                    if (!cfg.channels.qqbot) cfg.channels.qqbot = {};
+
+                    // 覆盖 token（如果有新值）
+                    const desired = '$DESIRED_QQBOT_TOKEN';
+                    if (desired && desired.includes(':')) {
+                        const [appId, ...rest] = desired.split(':');
+                        cfg.channels.qqbot.appId = appId;
+                        cfg.channels.qqbot.clientSecret = rest.join(':');
+                        delete cfg.channels.qqbot.token;
+                    }
+
+                    // 覆盖 markdown（如果有指定）
+                    const md = '$MARKDOWN_VALUE';
+                    if (md === 'true') cfg.channels.qqbot.markdownSupport = true;
+                    else if (md === 'false') cfg.channels.qqbot.markdownSupport = false;
+
+                    fs.writeFileSync('$_target_cfg', JSON.stringify(cfg, null, 4) + '\n');
+                " 2>/dev/null || true
+                echo "  ✅ 已恢复 channels.qqbot 配置（含 token/markdown）"
+                _need_reload=1
+            fi
+
+            # 配置写回后 reload gateway 使其生效
+            if [ "$_need_reload" -eq 1 ]; then
+                echo "  重载配置..."
+                sleep 1
+                openclaw gateway restart 2>/dev/null || true
+                # 等待重启后端口重新就绪
+                for _k in $(seq 1 15); do
+                    if lsof -i :18789 -sTCP:LISTEN >/dev/null 2>&1; then
+                        break
+                    fi
+                    sleep 2
+                done
+            fi
             # 检查 qqbot WS 是否连接成功（最多等 20 秒）
             echo "检查 qqbot 插件连接状态..."
             _LOG_FILE="/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log"
@@ -775,10 +764,27 @@ case "$start_choice" in
     n|no)
         echo ""
         echo "✅ 插件更新完毕，未启动服务"
+        # 不启动时也需要恢复 channels.qqbot，否则配置丢失
+        # 注意：下次 gateway 启动可能因 "unknown channel id" 失败，
+        # 需要用户手动 stop → 移除 channels.qqbot → start → 恢复
+        if [ -n "$_QQBOT_CHANNEL_STASH" ] && [ -n "$_STASH_CFG" ] && [ -f "$_STASH_CFG" ]; then
+            node -e "
+                const fs = require('fs');
+                const cfg = JSON.parse(fs.readFileSync('$_STASH_CFG', 'utf8'));
+                if (!cfg.channels) cfg.channels = {};
+                cfg.channels.qqbot = $_QQBOT_CHANNEL_STASH;
+                fs.writeFileSync('$_STASH_CFG', JSON.stringify(cfg, null, 4) + '\n');
+            " 2>/dev/null || true
+            echo "  已恢复 channels.qqbot 配置"
+        fi
         echo ""
-        echo "后续可手动启动:"
-        echo "  openclaw gateway restart    # 重启后台服务"
-        echo "  openclaw logs --follow      # 跟踪日志"
+        echo "后续启动方法（兼容 openclaw 3.23+）："
+        echo "  1. 先临时移除 channels.qqbot 再启动："
+        echo "     openclaw gateway restart"
+        echo "  2. 或使用本脚本自动处理："
+        echo "     bash $0"
+        echo "  3. 跟踪日志："
+        echo "     openclaw logs --follow"
         ;;
     *)
         echo "无效选择，按默认值 y 执行后台重启"

package/src/gateway.ts

@@ -112,6 +112,21 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
     }
   }
 
+  // 预检 openclaw runtime 模块是否可正常解析（兼容性诊断）
+  // openclaw 3.23+ 存在 plugin-sdk/root-alias.cjs 回归 bug，
+  // 内置插件（qwen-portal-auth 等）全部加载失败，导致 AI agent 调用返回
+  // "Unable to resolve plugin runtime module"。提前检测并告警。
+  try {
+    const pluginRuntime = getQQBotRuntime();
+    if (pluginRuntime?.channel?.reply?.dispatchReplyWithBufferedBlockDispatcher) {
+      log?.info(`[qqbot:${account.accountId}] Runtime module preflight: OK`);
+    } else {
+      log?.error(`[qqbot:${account.accountId}] ⚠️ Runtime preflight: dispatchReply API 不可用，AI 消息处理可能失败。请检查 openclaw 版本兼容性`);
+    }
+  } catch (preflightErr) {
+    log?.error(`[qqbot:${account.accountId}] ⚠️ Runtime preflight failed: ${preflightErr}. AI 消息处理可能失败`);
+  }
+
   // 后台版本检查（供 /bot-version、/bot-upgrade 指令被动查询）
   triggerUpdateCheck(log);
 
@@ -1019,8 +1034,15 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                   timeoutId = null;
                 }
                 
-                // 发送错误提示给用户，显示完整错误信息
                 const errMsg = String(err);
+
+                // 兼容 openclaw 3.23+ 的 plugin-sdk/root-alias.cjs 模块解析失败
+                if (errMsg.includes("Unable to resolve plugin runtime module") || errMsg.includes("root-alias.cjs")) {
+                  log?.error(`[qqbot:${account.accountId}] ⚠️ openclaw 框架 runtime 模块解析失败，可能是 openclaw 版本与 plugin-sdk 不兼容。请尝试: npm install -g openclaw@latest && openclaw gateway restart`);
+                  await sendErrorMessage("⚠️ AI 服务暂时不可用：openclaw 框架运行时模块加载失败。\n\n请管理员执行：\nnpm install -g openclaw@latest\nopenclaw gateway restart\n\n斜杠命令（如 /bot-ping）不受影响。");
+                  return;
+                }
+
                 if (errMsg.includes("401") || errMsg.includes("key") || errMsg.includes("auth")) {
                   log?.error(`[qqbot:${account.accountId}] AI auth error: ${errMsg}`);
                 } else {
@@ -1062,7 +1084,14 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
             }
           }
         } catch (err) {
+          const errStr = String(err);
           log?.error(`[qqbot:${account.accountId}] Message processing failed: ${err}`);
+          // 兼容 openclaw 3.23+ runtime 模块解析失败：给用户发可操作的提示
+          if (errStr.includes("Unable to resolve plugin runtime module") || errStr.includes("root-alias.cjs")) {
+            try {
+              await sendErrorMessage("⚠️ AI 服务暂时不可用：openclaw 框架运行时模块加载失败。\n\n请管理员执行：\nnpm install -g openclaw@latest\nopenclaw gateway restart\n\n斜杠命令（如 /bot-ping）不受影响。");
+            } catch { /* best-effort */ }
+          }
         } finally {
           // 无论成功/失败/超时，都停止输入状态续期
           typing.keepAlive?.stop();

package/src/slash-commands.ts

@@ -830,7 +830,11 @@ function fireHotUpgrade(targetVersion?: string): HotUpgradeStartResult {
 /**
  * /bot-upgrade — 统一升级入口
  *
- * 产品流程：
+ * upgradeMode 开关：
+ *   - "doc"（默认）：只展示升级指引文档，不执行热更新
+ *   - "hot-reload"：执行 npm 升级脚本进行热更新
+ *
+ * 热更新模式下的产品流程：
  *   /bot-upgrade              — 展示版本信息+确认按钮（不直接升级）
  *   /bot-upgrade --latest     — 确认升级到最新版本
  *   /bot-upgrade --version X  — 升级到指定版本
@@ -840,21 +844,54 @@ let _upgrading = false; // 升级锁
 
 registerCommand({
   name: "bot-upgrade",
-  description: "检查更新并自动热更",
+  description: "检查更新并查看升级指引",
   usage: [
-    `/bot-upgrade              检查是否有新版本（展示信息+确认按钮）`,
-    `/bot-upgrade --latest     确认升级到最新版本`,
-    `/bot-upgrade --version X  升级到指定版本（如 1.6.5）`,
-    `/bot-upgrade --force      强制重新安装当前版本`,
-    ``,
-    `⚠️ 仅在私聊中可用。升级过程约 30~60 秒，期间服务短暂不可用。`,
-    ``,
-    `环境要求：`,
-    `  - 操作系统：macOS / Linux / Windows`,
-    `  - OpenClaw 框架版本 ≥ ${UPGRADE_REQUIREMENTS.minFrameworkVersion}`,
-    `  - Node.js ≥ v${UPGRADE_REQUIREMENTS.minNodeVersion}`,
+    `/bot-upgrade              检查是否有新版本`,
+    `/bot-upgrade --latest     确认升级到最新版本（需 upgradeMode=hot-reload）`,
+    `/bot-upgrade --version X  升级到指定版本（需 upgradeMode=hot-reload）`,
+    `/bot-upgrade --force      强制重新安装当前版本（需 upgradeMode=hot-reload）`,
   ].join("\n"),
   handler: async (ctx) => {
+    const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
+    const upgradeMode = ctx.accountConfig?.upgradeMode || "doc";
+    const args = ctx.args.trim();
+    const info = await getUpdateInfo();
+
+    const GITHUB_URL = "https://github.com/tencent-connect/openclaw-qqbot/";
+
+    // ── doc 模式（默认）：只展示升级指引，不执行热更新 ──
+    if (upgradeMode !== "hot-reload") {
+      if (info.checkedAt === 0) {
+        return `⏳ 版本检查中，请稍后再试`;
+      }
+      if (info.error) {
+        return [
+          `❌ 主机网络访问异常，无法检查更新`,
+          ``,
+          `查看升级指引：[点击查看](${url})`,
+        ].join("\n");
+      }
+      if (!info.hasUpdate) {
+        return [
+          `✅ 当前已是最新版本 v${PLUGIN_VERSION}`,
+          ``,
+          `项目地址：[GitHub](${GITHUB_URL})`,
+        ].join("\n");
+      }
+
+      return [
+        `🆕 发现新版本`,
+        ``,
+        `当前版本：**v${PLUGIN_VERSION}**`,
+        `最新版本：**v${info.latest}**`,
+        ``,
+        `📖 升级指引：[点击查看](${url})`,
+        `🌟 官方 GitHub 仓库：[点击前往](${GITHUB_URL})`,
+      ].join("\n");
+    }
+
+    // ── hot-reload 模式：执行热更新 ──
+
     // 升级相关指令仅在私聊中可用
     if (ctx.type !== "c2c") {
       return `💡 请在私聊中使用此指令`;
@@ -865,10 +902,6 @@ registerCommand({
       return `⏳ 正在升级中，请稍候...`;
     }
 
-    const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
-    const args = ctx.args.trim();
-    const info = await getUpdateInfo();
-
     let isForce = false;
     let isLatest = false;
     let versionArg: string | undefined;
@@ -906,8 +939,6 @@ registerCommand({
       }
     }
 
-    const GITHUB_URL = "https://github.com/tencent-connect/openclaw-qqbot/";
-
     // ── 无参数（也没有 --latest / --version / --force）：只展示信息+确认按钮 ──
     if (!versionArg && !isLatest && !isForce) {
       if (info.checkedAt === 0) {
@@ -929,7 +960,7 @@ registerCommand({
         return lines.join("\n");
       }
 
-      // 有新版本：展示信息 + 确认按钮（同通道：alpha 只展示 alpha，正式版只展示正式版）
+      // 有新版本：展示信息 + 确认按钮
       return [
         `🆕 发现新版本`,
         ``,