@tencent-connect/openclaw-qqbot 1.5.7 → 1.6.0-alpha.2

package/README.md

@@ -6,14 +6,19 @@
 
 # QQ Bot Channel Plugin for OpenClaw
 
+
+
 **Connect your AI assistant to QQ — private chat, group chat, and rich media, all in one plugin.**
 
+### 🚀 Current Version: `v1.5.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/)
 [![Platform](https://img.shields.io/badge/platform-OpenClaw-orange)](https://github.com/tencent-connect/openclaw-qqbot)
 [![Node.js](https://img.shields.io/badge/Node.js->=18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
+
 <br/>
 
 **[简体中文](README.zh.md) | English**
@@ -56,6 +61,8 @@ QQ quote events carry index keys (e.g. `REFIDX_xxx`) instead of full original me
 - Store path: `~/.openclaw/qqbot/data/ref-index.jsonl` (survives gateway restart).
 - Quote body may include text + media summary (image/voice/video/file).
 
+<img width="360" src="docs/images/ref_msg.png" alt="Quoted Message Context Demo" />
+
 ### 🎙️ Voice Messages (STT)
 
 With STT configured, the plugin automatically transcribes voice messages to text before passing them to AI. The whole process is transparent to the user — sending voice feels as natural as sending text.
@@ -86,7 +93,7 @@ If your main model supports vision (e.g. Tencent Hunyuan `hunyuan-vision`), AI c
 
 <img width="360" src="docs/images/59d421891f813b0d3c0cbe12574b6a72_720.jpg" alt="Image Understanding Demo" />
 
-### 🎨 Image Generation
+### 🎨 Image Sending
 
 > **You**: Draw me a cat
 >
@@ -96,7 +103,7 @@ AI sends images via `<qqimg>path</qqimg>`. Supports local paths and URLs. Format
 
 <img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="Image Generation Demo" />
 
-### 🔊 Voice Reply (TTS)
+### 🔊 Voice Sending
 
 > **You**: Tell me a joke in voice
 >

package/README.zh.md

@@ -6,8 +6,11 @@
 
 # QQ Bot — OpenClaw 渠道插件
 
+
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
+### 🚀 当前版本： `v1.5.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/)
 [![Platform](https://img.shields.io/badge/platform-OpenClaw-orange)](https://github.com/tencent-connect/openclaw-qqbot)
@@ -53,6 +56,8 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 - 存储位置：`~/.openclaw/qqbot/data/ref-index.jsonl`（网关重启后仍可恢复）。
 - 引用内容支持文本 + 媒体摘要（图片/语音/视频/文件）。
 
+<img width="360" src="docs/images/ref_msg.png" alt="引用消息上下文演示" />
+
 ### 🎙️ 语音消息（STT）
 
 配置 STT 后，插件会自动将语音转录为文字再交给 AI 处理。整个过程对用户完全透明——发语音就像发文字一样自然，AI 听得懂你在说什么。
@@ -83,7 +88,7 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 
 <img width="360" src="docs/images/59d421891f813b0d3c0cbe12574b6a72_720.jpg" alt="图片理解演示" />
 
-### 🎨 AI 画图
+### 🎨 图片发送
 
 > **你**：画一只猫咪
 >
@@ -93,7 +98,7 @@ AI 通过 `<qqimg>路径</qqimg>` 发送图片，支持本地文件路径和网
 
 <img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="发图片演示" />
 
-### 🔊 语音回复（TTS）
+### 🔊 语音发送
 
 > **你**：给我讲一个笑话
 >

package/package.json

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

package/scripts/upgrade-via-npm.sh

@@ -1,6 +1,10 @@
 #!/bin/bash
 
-# qqbot 通过 npm 包升级
+# qqbot 通过 npm 包升级（纯文件操作版本）
+#
+# 重要：此脚本不修改 openclaw.json 配置文件！
+# 配置更新由调用方（TS handler）在脚本完成后统一处理，
+# 避免 gateway config watcher 在安装过程中触发 SIGUSR1 重启导致竞态。
 #
 # 用法:
 #   upgrade-via-npm.sh                                    # 升级到 latest（默认）
@@ -11,8 +15,6 @@ set -eo pipefail
 
 PKG_NAME="@tencent-connect/openclaw-qqbot"
 INSTALL_SRC=""
-APPID=""
-SECRET=""
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
@@ -30,16 +32,11 @@ print_usage() {
     echo "用法:"
     echo "  upgrade-via-npm.sh                              # 升级到 latest（默认）"
     echo "  upgrade-via-npm.sh --version <版本号>            # 升级到指定版本"
-    echo "  upgrade-via-npm.sh --appid <appid> --secret <secret>  # 配置通道并启动"
     if [ -n "$LOCAL_VERSION" ]; then
         echo "  upgrade-via-npm.sh --self-version               # 升级到当前仓库版本（$LOCAL_VERSION）"
     else
         echo "  upgrade-via-npm.sh --self-version               # 升级到当前仓库版本"
     fi
-    echo ""
-    echo "也可以通过环境变量设置:"
-    echo "  QQBOT_APPID           QQ机器人 appid"
-    echo "  QQBOT_SECRET          QQ机器人 secret"
 }
 
 while [[ $# -gt 0 ]]; do
@@ -59,16 +56,6 @@ while [[ $# -gt 0 ]]; do
             INSTALL_SRC="${PKG_NAME}@${LOCAL_VERSION}"
             shift 1
             ;;
-        --appid)
-            [ -z "$2" ] && echo "❌ --appid 需要参数" && exit 1
-            APPID="$2"
-            shift 2
-            ;;
-        --secret)
-            [ -z "$2" ] && echo "❌ --secret 需要参数" && exit 1
-            SECRET="$2"
-            shift 2
-            ;;
         -h|--help)
             print_usage
             exit 0
@@ -78,18 +65,13 @@ while [[ $# -gt 0 ]]; do
 done
 INSTALL_SRC="${INSTALL_SRC:-${PKG_NAME}@latest}"
 
-# 使用命令行参数或环境变量
-APPID="${APPID:-$QQBOT_APPID}"
-SECRET="${SECRET:-$QQBOT_SECRET}"
-
-# 检测 CLI
+# 检测 CLI（仅用于确定 extensions 目录路径）
 CMD=""
 for name in openclaw clawdbot moltbot; do
     command -v "$name" &>/dev/null && CMD="$name" && break
 done
 [ -z "$CMD" ] && echo "❌ 未找到 openclaw / clawdbot / moltbot" && exit 1
 
-APP_CONFIG="$HOME/.$CMD/$CMD.json"
 EXTENSIONS_DIR="$HOME/.$CMD/extensions"
 
 echo "==========================================="
@@ -97,108 +79,96 @@ echo "  qqbot npm 升级: $INSTALL_SRC"
 echo "==========================================="
 echo ""
 
-# [1/4] 备份并临时移除通道配置（避免 plugins install 因 unknown channel 拒绝执行）
-echo "[1/4] 备份通道配置..."
-if [ -f "$APP_CONFIG" ]; then
-    node -e "
-        const fs = require('fs');
-        const cfg = JSON.parse(fs.readFileSync('$APP_CONFIG', 'utf8'));
-        const keys = ['qqbot', 'openclaw-qqbot', 'openclaw-qq'];
-        let saved = null;
-        for (const key of keys) {
-            const ch = cfg.channels && cfg.channels[key];
-            if (ch) { saved = ch; delete cfg.channels[key]; break; }
-        }
-        // 清理 plugins.entries 中的旧记录（避免 stale config entry 告警）
-        if (cfg.plugins && cfg.plugins.entries) {
-            delete cfg.plugins.entries['openclaw-qqbot'];
-        }
-        if (saved) {
-            fs.writeFileSync('$APP_CONFIG.qqbot-backup.json', JSON.stringify(saved, null, 2));
-            fs.writeFileSync('$APP_CONFIG', JSON.stringify(cfg, null, 4) + '\n');
-            console.log('  ✅ 已备份并临时移除 channels.qqbot');
-        } else {
-            console.log('  ℹ️  无已有通道配置');
-        }
-    " 2>/dev/null || echo "  ⚠️  备份失败"
+# [1/3] 下载并安装新版本到临时目录
+echo "[1/3] 下载新版本..."
+TMPDIR_PACK=$(mktemp -d)
+EXTRACT_DIR=$(mktemp -d)
+trap "rm -rf '$TMPDIR_PACK' '$EXTRACT_DIR'" EXIT
+
+cd "$TMPDIR_PACK"
+npm pack "$INSTALL_SRC" --quiet 2>&1 || { echo "❌ npm pack 失败"; exit 1; }
+TGZ_FILE=$(ls -1 *.tgz 2>/dev/null | head -1)
+[ -z "$TGZ_FILE" ] && echo "❌ 未找到下载的 tgz 文件" && exit 1
+echo "  已下载: $TGZ_FILE"
+
+tar xzf "$TGZ_FILE" -C "$EXTRACT_DIR"
+PACKAGE_DIR="$EXTRACT_DIR/package"
+[ ! -d "$PACKAGE_DIR" ] && echo "❌ 解压失败，未找到 package 目录" && exit 1
+
+# 准备 staging 目录：放在 ~/.openclaw/ 下（extensions 的父目录），
+# 同一文件系统保证 mv 原子操作，同时避免 OpenClaw 扫描 extensions/ 时发现它。
+STAGING_DIR="$(dirname "$EXTENSIONS_DIR")/.qqbot-upgrade-staging"
+rm -rf "$STAGING_DIR"
+mkdir -p "$STAGING_DIR"
+cp -R "$PACKAGE_DIR/"* "$STAGING_DIR/"
+
+# 依赖处理：所有 production dependencies 都声明为 bundledDependencies，
+# npm pack 时已打包进 tgz，解压后 node_modules/ 已包含全部依赖，无需 npm install。
+# 注意：不能执行 npm install，否则会安装 peerDependencies（openclaw 平台及其 400+ 传递依赖），
+# 导致插件目录膨胀到 900MB+，而这些依赖在运行时由宿主 openclaw 提供。
+if [ -d "$STAGING_DIR/node_modules" ]; then
+    BUNDLED_COUNT=$(ls -d "$STAGING_DIR/node_modules"/*/ "$STAGING_DIR/node_modules"/@*/*/ 2>/dev/null | wc -l | tr -d ' ')
+    echo "  bundled 依赖已就绪（${BUNDLED_COUNT} 个包）"
 else
-    echo "  ℹ️  无配置文件"
+    echo "  ⚠️  未找到 bundled node_modules，尝试安装依赖..."
+    NPM_TMP_CACHE=$(mktemp -d)
+    (cd "$STAGING_DIR" && npm install --omit=dev --omit=peer --ignore-scripts --cache="$NPM_TMP_CACHE" --quiet 2>&1) || echo "  ⚠️  依赖安装失败"
+    rm -rf "$NPM_TMP_CACHE"
 fi
 
-# [2/4] 清理旧插件目录
-echo ""
-echo "[2/4] 清理旧插件..."
-for old_plugin in openclaw-qqbot qqbot openclaw-qq @sliverp/qqbot @tencent-connect/qqbot @tencent-connect/openclaw-qq @tencent-connect/openclaw-qqbot; do
-    $CMD plugins uninstall "$old_plugin" 2>/dev/null && echo "  已卸载: $old_plugin" || true
-done
-for dir_name in openclaw-qqbot qqbot openclaw-qq; do
-    if [ -d "$EXTENSIONS_DIR/$dir_name" ]; then
-        rm -rf "$EXTENSIONS_DIR/$dir_name"
-        echo "  已清理残留目录: $dir_name"
-    fi
-done
+# 清理下载临时文件
+rm -rf "$TMPDIR_PACK" "$EXTRACT_DIR"
+cd "$HOME"
 
-# [3/4] 安装新版本
+# [2/3] 原子替换：先移走旧目录，再把 staging 目录 rename 过去
+# 这样 extensions/openclaw-qqbot 只有极短的不存在时间窗口
 echo ""
-echo "[3/4] 安装新版本..."
-$CMD plugins install "$INSTALL_SRC" 2>&1
-
-# 恢复通道配置
-BACKUP_FILE="$APP_CONFIG.qqbot-backup.json"
-if [ -f "$BACKUP_FILE" ] && [ -f "$APP_CONFIG" ]; then
-    node -e "
-        const fs = require('fs');
-        const cfg = JSON.parse(fs.readFileSync('$APP_CONFIG', 'utf8'));
-        const saved = JSON.parse(fs.readFileSync('$BACKUP_FILE', 'utf8'));
-        cfg.channels = cfg.channels || {};
-        cfg.channels.qqbot = saved;
-        fs.writeFileSync('$APP_CONFIG', JSON.stringify(cfg, null, 4) + '\n');
-        fs.unlinkSync('$BACKUP_FILE');
-        console.log('  ✅ 通道配置已恢复');
-    " 2>/dev/null || echo "  ⚠️  通道配置恢复失败，请手动检查: $APP_CONFIG"
+echo "[2/3] 原子替换插件目录..."
+TARGET_DIR="$EXTENSIONS_DIR/openclaw-qqbot"
+OLD_DIR="$(dirname "$EXTENSIONS_DIR")/.qqbot-upgrade-old"
+
+rm -rf "$OLD_DIR"
+if [ -d "$TARGET_DIR" ]; then
+    mv "$TARGET_DIR" "$OLD_DIR"
 fi
+mv "$STAGING_DIR" "$TARGET_DIR"
+rm -rf "$OLD_DIR"
 
-# 配置通道（如果提供了 appid 和 secret）
-if [ -n "$APPID" ] && [ -n "$SECRET" ]; then
-    echo ""
-    echo "配置机器人通道..."
-    DESIRED_TOKEN="${APPID}:${SECRET}"
-
-    # 读取当前配置中的 token
-    CURRENT_TOKEN=""
-    if [ -f "$APP_CONFIG" ]; then
-        CURRENT_TOKEN=$(node -e "
-            const cfg = JSON.parse(require('fs').readFileSync('$APP_CONFIG', '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)
-    fi
+# 清理可能残留的旧版 staging 目录（extensions 内外都清理）
+rm -rf "$EXTENSIONS_DIR/openclaw-qqbot.staging"
+rm -rf "$EXTENSIONS_DIR/.qqbot-upgrade-staging"
+rm -rf "$EXTENSIONS_DIR/.qqbot-upgrade-old"
 
-    if [ "$CURRENT_TOKEN" = "$DESIRED_TOKEN" ]; then
-        echo "  ✅ 当前配置已是目标值，跳过写入"
-    elif $CMD channels add --channel qqbot --token "$DESIRED_TOKEN" 2>&1; then
-        echo "  ✅ 机器人通道配置成功"
-    else
-        echo "  ⚠️  通道配置失败，请手动执行: $CMD channels add --channel qqbot --token \"$DESIRED_TOKEN\""
-    fi
-fi
+# 同时清理历史遗留的其他目录名
+for dir_name in qqbot openclaw-qq; do
+    [ -d "$EXTENSIONS_DIR/$dir_name" ] && rm -rf "$EXTENSIONS_DIR/$dir_name"
+done
+echo "  已安装到: $TARGET_DIR"
 
-# [4/4] 重启网关
+# [3/3] 输出新版本号和升级报告（供调用方解析）
 echo ""
-echo "[4/4] 重启网关..."
-$CMD gateway restart 2>&1 || true
+echo "[3/3] 验证安装..."
+NEW_VERSION="$(node -e "
+  try {
+    const fs = require('fs');
+    const path = require('path');
+    const p = path.join('$EXTENSIONS_DIR', 'openclaw-qqbot', 'package.json');
+    if (fs.existsSync(p)) {
+      const v = JSON.parse(fs.readFileSync(p, 'utf8')).version;
+      if (v) { process.stdout.write(v); process.exit(0); }
+    }
+  } catch {}
+" 2>/dev/null || true)"
+echo "QQBOT_NEW_VERSION=${NEW_VERSION:-unknown}"
+
+# 输出结构化升级报告（QQBOT_REPORT=...），供 TS handler 解析后直接回复用户
+if [ -n "$NEW_VERSION" ] && [ "$NEW_VERSION" != "unknown" ]; then
+    echo "QQBOT_REPORT=✅ QQBot 升级完成: v${NEW_VERSION}"
+else
+    echo "QQBOT_REPORT=⚠️ QQBot 升级异常，无法确认新版本"
+fi
 
 echo ""
 echo "==========================================="
-echo "  ✅ 升级完成"
+echo "  ✅ 文件安装完成"
 echo "==========================================="
-echo ""
-echo "常用命令:"
-echo "  $CMD logs --follow        # 跟踪日志"
-echo "  $CMD gateway restart      # 重启服务"
-echo "  $CMD plugins list         # 查看插件列表"

package/scripts/upgrade-via-source.sh

@@ -186,6 +186,19 @@ INSTALL_LOG="/tmp/openclaw-install-$(date +%s).log"
 echo "安装日志文件: $INSTALL_LOG"
 echo "详细信息将记录到日志文件中..."
 
+# 安装前先 stop gateway，防止 chokidar 在 plugins install 写入配置的中间状态
+# 触发 restart，导致 "unknown channel id: qqbot" 等错误
+_gw_was_running=0
+if lsof -i :18789 -sTCP:LISTEN >/dev/null 2>&1; then
+    _gw_was_running=1
+    echo "  暂停 gateway 服务（避免安装过程中中间状态 restart）..."
+    openclaw gateway stop 2>/dev/null || true
+    sleep 1
+fi
+
+# 清理之前可能残留的 staging 目录
+find "$HOME/.openclaw/extensions/" -maxdepth 1 -name ".openclaw-install-stage-*" -exec rm -rf {} + 2>/dev/null || true
+
 # 尝试安装并捕获详细输出
 if ! openclaw plugins install . 2>&1 | tee "$INSTALL_LOG"; then
     echo ""
@@ -243,15 +256,136 @@ if ! openclaw plugins install . 2>&1 | tee "$INSTALL_LOG"; then
     esac
 else
     echo ""
-    echo "✅ 插件安装成功！"
+    echo "✅ 插件安装命令执行完成"
     echo "安装日志已保存到: $INSTALL_LOG"
 
-    # plugins install 会修改 openclaw.json（plugins.allow/entries/installs），
-    # gateway 检测到 config change 后会自动 SIGUSR1 重启（可能触发 1~2 次）。
-    # 必须等这波自动重启完全结束，否则后续的 gateway restart 会叠加导致竞态。
-    echo ""
-    echo "等待 gateway 自动重启链完成（约 20 秒）..."
-    sleep 20
+    # 验证插件目录是否真正创建（防止 "安装成功" 但目录缺失的情况）
+    _plugin_dir_ok=0
+    for _candidate_name in openclaw-qqbot qqbot openclaw-qq; do
+        if [ -d "$HOME/.openclaw/extensions/$_candidate_name" ] && \
+           [ -f "$HOME/.openclaw/extensions/$_candidate_name/package.json" ]; then
+            _plugin_dir_ok=1
+            echo "  ✅ 插件目录验证通过: ~/.openclaw/extensions/$_candidate_name/"
+            break
+        fi
+    done
+    if [ "$_plugin_dir_ok" -eq 0 ]; then
+        echo ""
+        echo "⚠️  警告: 插件目录不存在！安装命令返回成功但目录未创建"
+        echo "  可能原因: staging 目录未正确 rename（参考 openclaw/issues）"
+        echo "  检查 staging 残留:"
+        ls -la "$HOME/.openclaw/extensions/" 2>/dev/null
+        echo ""
+        echo "  尝试自动修复: 清理残留并重试安装..."
+        find "$HOME/.openclaw/extensions/" -maxdepth 1 -name ".openclaw-install-stage-*" -exec rm -rf {} + 2>/dev/null || true
+        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
+                    _plugin_dir_ok=1
+                    echo "  ✅ 重试安装成功: ~/.openclaw/extensions/$_candidate_name/"
+                    break
+                fi
+            done
+        fi
+        if [ "$_plugin_dir_ok" -eq 0 ]; then
+            echo "  ❌ 重试安装仍失败，插件目录不存在"
+            echo "  请手动排查: ls -la ~/.openclaw/extensions/"
+            # 清理无效的配置条目，防止 gateway 启动时报错
+            echo "  清理无效的配置条目..."
+            node -e "
+              const fs = require('fs');
+              const path = require('path');
+              for (const app of ['openclaw', 'clawdbot', 'moltbot']) {
+                const f = path.join(process.env.HOME, '.' + app, app + '.json');
+                if (!fs.existsSync(f)) continue;
+                const cfg = JSON.parse(fs.readFileSync(f, 'utf8'));
+                let changed = false;
+                // 移除 channels.qqbot（插件未加载时此配置会导致 unknown channel id 错误）
+                if (cfg.channels && cfg.channels.qqbot) { delete cfg.channels.qqbot; changed = true; }
+                // 清理 plugins.allow 中的 openclaw-qqbot
+                if (cfg.plugins && Array.isArray(cfg.plugins.allow)) {
+                  cfg.plugins.allow = cfg.plugins.allow.filter(x => x !== 'openclaw-qqbot');
+                  changed = true;
+                }
+                if (changed) fs.writeFileSync(f, JSON.stringify(cfg, null, 4) + '\n');
+                break;
+              }
+            " 2>/dev/null || true
+            echo "  已清理无效配置，gateway 可正常启动（无 qqbot 插件状态）"
+            read -t 10 -p "是否继续? (y/N): " _cont || _cont="N"
+            case "$_cont" in
+                [Yy]* ) echo "继续..." ;;
+                * ) exit 1 ;;
+            esac
+        fi
+    fi
+
+    # 清理多余的 peerDependencies 传递依赖（兼容旧版 openclaw）：
+    # openclaw v2026.3.4 之前的 plugins install 缺少 --omit=peer，会把 peerDeps
+    # （openclaw 平台及其 400+ 传递依赖）也安装到插件 node_modules 中。
+    # 新版已修复，此处通过阈值判断：包数量 > 50 才触发清理，避免对新版做无用操作。
+    PLUGIN_NM=""
+    for _candidate in openclaw-qqbot qqbot openclaw-qq; do
+        _nm="$HOME/.openclaw/extensions/$_candidate/node_modules"
+        [ -d "$_nm" ] && PLUGIN_NM="$_nm" && break
+    done
+    if [ -n "$PLUGIN_NM" ]; then
+        _before=$(ls -d "$PLUGIN_NM"/*/ "$PLUGIN_NM"/@*/*/ 2>/dev/null | wc -l | tr -d ' ')
+        if [ "$_before" -gt 50 ]; then
+            # 读取 bundledDependencies 列表，只保留这些包及其子依赖
+            _bundled_deps=$(node -e "
+              const fs = require('fs');
+              const path = require('path');
+              const pkgPath = path.join('$PLUGIN_NM', '..', '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('$PLUGIN_NM', 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);
+              const installed = fs.readdirSync('$PLUGIN_NM').filter(n => !n.startsWith('.'));
+              const toRemove = [];
+              for (const item of installed) {
+                if (item.startsWith('@')) {
+                  const scopeDir = path.join('$PLUGIN_NM', item);
+                  const subs = fs.readdirSync(scopeDir);
+                  const keepSubs = subs.filter(s => keep.has(item + '/' + s));
+                  if (keepSubs.length === 0) toRemove.push(item);
+                  else {
+                    for (const s of subs) {
+                      if (!keep.has(item + '/' + s)) toRemove.push(item + '/' + s);
+                    }
+                  }
+                } else {
+                  if (!keep.has(item)) toRemove.push(item);
+                }
+              }
+              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
+                find "$PLUGIN_NM" -maxdepth 1 -type d -name '@*' -empty -delete 2>/dev/null || true
+                _after=$(ls -d "$PLUGIN_NM"/*/ "$PLUGIN_NM"/@*/*/ 2>/dev/null | wc -l | tr -d ' ')
+                echo "  已清理: ${_before} → ${_after} 个包"
+            fi
+        else
+            echo "  node_modules 包数量正常（${_before} 个），无需清理"
+        fi
+    fi
+
+    # gateway 已在安装前 stop，此时不会有自动 restart 的问题
+    # 所有配置写入完成后，在 Step 6 统一启动
 
     # 记录更新后的 qqbot 插件版本
     NEW_QQBOT_VERSION=$(node -e '
@@ -318,10 +452,9 @@ if [ -n "$DESIRED_QQBOT_TOKEN" ]; then
     else
         echo "✅ 机器人通道配置成功"
         _config_changed=1
-        # 重要：配置写入后 gateway 会自动检测变化并热重载（SIGUSR1）
-        # 必须等待热重载完成，否则后续的 gateway restart 会导致连续两次重启
-        echo "等待 gateway 热重载完成..."
-        sleep 5
+        # channels 配置变更在 reload plan 中匹配为 hot reload（非 restart），
+        # 由 channel 插件热重载处理，通常 <1 秒完成，无需长时间等待。
+        sleep 1
     fi
 else
     # 未提供任何可用 token 时，检查是否已有可用配置
@@ -446,19 +579,37 @@ start_choice=$(printf '%s' "$start_choice" | tr '[:upper:]' '[:lower:]')
 case "$start_choice" in
     y|yes)
         echo ""
-        # 不论配置是否变更，都显式 restart 一次，确保插件正确加载
-        # （plugins install 触发的自动重启链已在第 3 步等待完成）
+        # gateway 在 Step 3 安装前已 stop，此处统一 restart
         echo "正在后台重启 openclaw 网关服务..."
-        if ! openclaw gateway restart 2>&1; then
+        _restart_output=$(openclaw gateway restart 2>&1) || true
+        echo "$_restart_output"
+
+        if echo "$_restart_output" | grep -qi "not loaded\|not found\|not running\|not installed"; then
             echo ""
-            echo "⚠️  后台重启失败，可能服务未安装"
-            echo "尝试: openclaw gateway install && openclaw gateway start"
+            echo "⚠️  gateway 服务未加载，尝试自动恢复..."
+            echo ""
+            echo "  [1/2] 注册 gateway 服务..."
+            _install_out=$(openclaw gateway install 2>&1) || true
+            echo "  $_install_out"
+            echo ""
+            echo "  [2/2] 启动 gateway 服务..."
+            _start_out=$(openclaw gateway start 2>&1) || true
+            echo "  $_start_out"
+            if echo "$_start_out" | grep -qi "restart\|started\|bootstrap"; then
+                echo ""
+                echo "✅ gateway 服务恢复成功"
+            else
+                echo ""
+                echo "⚠️  自动恢复可能失败，请手动执行："
+                echo "  openclaw gateway install && openclaw gateway start"
+            fi
+        else
+            echo ""
+            echo "✅ openclaw 网关已在后台重启"
         fi
         echo ""
-        echo "✅ openclaw 网关已在后台重启"
-        echo ""
-        # 等待 gateway 端口就绪（插件安装+自动重启可能需要 30-60 秒）
-        echo "等待 gateway 就绪（插件安装中，可能需要 30-60 秒）..."
+        # 等待 gateway 端口就绪
+        echo "等待 gateway 就绪..."
         echo "========================================="
         _port_ready=0
         for i in $(seq 1 30); do
@@ -472,32 +623,49 @@ case "$start_choice" in
         echo ""
 
         if [ "$_port_ready" -eq 0 ]; then
-            echo "⚠️  等待超时，gateway 可能仍在启动中"
-            echo "请手动检查: openclaw doctor"
-            echo "或查看日志: tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log"
-        else
+            echo "⚠️  等待超时，尝试 openclaw doctor --fix 自动修复..."
+            _doctor_output=$(openclaw doctor --fix 2>&1) || true
+            echo "$_doctor_output"
+            # doctor --fix 后再尝试 restart 一次
+            echo ""
+            echo "doctor 修复后重试 gateway restart..."
+            openclaw gateway restart 2>&1 || true
+            sleep 5
+            if lsof -i :18789 -sTCP:LISTEN >/dev/null 2>&1; then
+                echo "✅ doctor --fix 后 gateway 启动成功"
+                _port_ready=1
+            else
+                echo "❌ 仍然无法启动，请手动排查:"
+                echo "  openclaw doctor"
+                echo "  tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log"
+            fi
+        fi
+
+        # 端口就绪后：检查 qqbot 连接 + 跟踪日志
+        if [ "$_port_ready" -eq 1 ]; then
             echo "✅ Gateway 端口已就绪"
             echo ""
-            # 检查 qqbot WS 是否连接成功（最多等 30 秒）
+            # 检查 qqbot WS 是否连接成功（最多等 20 秒）
             echo "检查 qqbot 插件连接状态..."
             _LOG_FILE="/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log"
+            _restart_ts=$(date +%s)
             _qqbot_ready=0
-            for _j in $(seq 1 15); do
-                if grep -q "Gateway ready" "$_LOG_FILE" 2>/dev/null && \
-                   _last_ready_time=$(grep "Gateway ready" "$_LOG_FILE" | tail -1 | grep -o '"date":"[^"]*"' | tail -1) && \
-                   [ -n "$_last_ready_time" ]; then
-                    _qqbot_ready=1
-                    break
+            for _j in $(seq 1 10); do
+                if [ -f "$_LOG_FILE" ]; then
+                    _last_line=$(grep "Gateway ready" "$_LOG_FILE" 2>/dev/null | tail -1 || true)
+                    if [ -n "$_last_line" ]; then
+                        _qqbot_ready=1
+                        break
+                    fi
                 fi
-                printf "\r  等待 qqbot WS 连接... (%d/15)" "$_j"
+                printf "\r  等待 qqbot WS 连接... (%d/10)" "$_j"
                 sleep 2
             done
             echo ""
 
             if [ "$_qqbot_ready" -eq 0 ]; then
-                echo "⚠️  qqbot 插件可能未正确加载，尝试再次重启..."
-                openclaw gateway restart 2>&1 || true
-                sleep 10
+                echo "⚠️  qqbot 插件可能未正确加载"
+                echo "请检查: openclaw doctor"
             else
                 echo "✅ qqbot 插件已连接"
             fi