feat: add npm-upgrade.sh for npm-based plugin installation

Supports installing from npm registry (latest/tag/version) or local tgz. Handles config backup, old plugin cleanup, install, config restore and gateway restart automatically.
2026-04-30 13:50:24 +08:00 · 2026-03-10 14:42:12 +08:00
parent 2aae43a16f
commit 9da6027965
7 changed files with 317 additions and 7 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -5,4 +5,6 @@ package-lock.json
 .idea/
 .codebuddy/
 .codebuddy.zip
-openclaw.json
+openclaw.json
+*.tgz
+*.log
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).

 ## [1.5.5] - 2026-03-09

+### Added
+
+- Add `npm-upgrade.sh` script for npm-based plugin installation and upgrade.
+  - Supports `--tag` and `--version` options, defaults to `@alpha`.
+  - Handles channel config backup/restore, old plugin cleanup (including legacy variants like `qqbot`, `@sliverp/qqbot`, `openclaw-qq`), and gateway restart.
+  - Temporarily removes `channels.qqbot` before install to avoid `unknown channel id` validation error.
+
 ### Fixed

 - Fix plugin id not matching package name, causing plugin load failure.
--- a/CHANGELOG.zh.md
+++ b/CHANGELOG.zh.md
@@ -6,6 +6,13 @@

 ## [1.5.5] - 2026-03-09

+### 新增
+
+- 新增 `npm-upgrade.sh` 脚本，支持通过 npm 包安装和升级插件。
+  - 支持 `--tag` 和 `--version` 选项，默认安装 `@alpha`。
+  - 自动处理通道配置备份/恢复、旧插件清理（包括 `qqbot`、`@sliverp/qqbot`、`openclaw-qq` 等历史版本）、网关重启。
+  - 安装前临时移除 `channels.qqbot` 配置，避免 `unknown channel id` 校验错误。
+
 ### 修复

 - 修复插件 ID 与包名不一致导致插件加载失败的问题。
--- a/README.md
+++ b/README.md
@@ -142,7 +142,7 @@ AI sends videos via `<qqvideo>path</qqvideo>`. Supports local files and URLs. La
 2. After scanning, tap **Agree** on your phone — you'll land on the bot configuration page.
 3. Click **Create Bot** to create a new QQ bot.

-<img width="1982" height="1316" alt="Clipboard_Screenshot_1772980440" src="https://github.com/user-attachments/assets/3ccb494d-6e4d-462c-9218-b4dfd43a254f" />
+<img width="720" alt="Create Bot" src="docs/images/create_robot.png" />

 4. Find **AppID** and **AppSecret** on the bot's page, click **Copy** for each, and save them somewhere safe (e.g., a notepad). **AppSecret is not stored in plaintext — if you leave the page without saving it, you'll have to regenerate a new one.**

@@ -154,7 +154,13 @@ AI sends videos via `<qqvideo>path</qqvideo>`. Supports local files and URLs. La

 ### Step 2 — Install the Plugin

-**Option A: One-Click Install & Run (Recommended)**
+**Option A: Install via npm (Recommended)**
+
+```bash
+openclaw plugins install @tencent-connect/openclaw-qqbot
+```
+
+**Option B: One-Click Install & Run**

 ```bash
 git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
@@ -163,7 +169,7 @@ bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET

 The script handles everything: cleanup old plugins → install deps → register plugin → configure channel → start service. Once done, skip to [Step 4](#step-4--start--test).

-**Option B: Manual Step-by-Step**
+**Option C: Manual Step-by-Step**

 ```bash
 git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
@@ -350,6 +356,24 @@ STT supports two-level configuration with priority fallback:

 ## 🔄 Upgrade

+### Option 1: Upgrade via npm (Recommended)
+
+```bash
+bash ./scripts/npm-upgrade.sh
+```
+
+The script automatically backs up channel config → uninstalls old plugins → installs new version → restores config → restarts gateway.
+
+```bash
+# Specify tag
+bash ./scripts/npm-upgrade.sh --tag alpha
+
+# Specify exact version
+bash ./scripts/npm-upgrade.sh --version 1.0.0-alpha.0
+```
+
+### Option 2: Upgrade via Source
+
 Run the one-click script to upgrade and restart:

 ```bash
@@ -379,6 +403,69 @@ Environment variables `QQBOT_APPID`, `QQBOT_SECRET`, `QQBOT_TOKEN` (AppID:Secret

 ---

+## 🔀 Migrating from Legacy Plugins
+
+If you previously installed `qqbot`, `@sliverp/qqbot`, `@tencent-connect/qqbot`, or other related legacy plugins, you need to uninstall the old plugin before installing the new version.
+
+### Recommended: Use npm-upgrade Script (Automatic)
+
+```bash
+bash ./scripts/npm-upgrade.sh
+```
+
+The script automatically uninstalls all legacy plugin variants (`qqbot`, `@sliverp/qqbot`, `openclaw-qq`, etc.), cleans up residual directories, and backs up/restores channel config.
+
+### Manual Migration
+
+**1. Back up your channel config**
+
+Save the `channels.qqbot` section from `~/.openclaw/openclaw.json` (including `appId`, `clientSecret`, `allowFrom`, etc.) — you'll need to restore it later.
+
+**2. Uninstall old plugins**
+
+Run the appropriate uninstall command(s) based on what you had installed:
+
+```bash
+# Uninstall legacy plugin variants (pick the ones that apply)
+openclaw plugins uninstall qqbot
+openclaw plugins uninstall @sliverp/qqbot
+openclaw plugins uninstall @tencent-connect/qqbot
+openclaw plugins uninstall openclaw-qqbot
+openclaw plugins uninstall openclaw-qq
+```
+
+If `plugins uninstall` doesn't fully clean up, manually remove residual directories:
+
+```bash
+rm -rf ~/.openclaw/extensions/qqbot
+rm -rf ~/.openclaw/extensions/openclaw-qqbot
+rm -rf ~/.openclaw/extensions/openclaw-qq
+```
+
+**3. Temporarily remove channel config**
+
+> ⚠️ Important: `openclaw plugins install` validates the config file. If `channels.qqbot` exists but no plugin provides that channel, it will fail with `unknown channel id: qqbot`.
+
+Before installing, temporarily remove the `channels.qqbot` section from `~/.openclaw/openclaw.json`.
+
+**4. Install the new version**
+
+```bash
+openclaw plugins install @tencent-connect/openclaw-qqbot
+```
+
+**5. Restore channel config**
+
+Write back the previously saved `channels.qqbot` config to `~/.openclaw/openclaw.json`.
+
+**6. Restart the gateway**
+
+```bash
+openclaw gateway restart
+```
+
+---
+
 ## 📚 Documentation & Links

 - [Command Reference](docs/commands.md) — OpenClaw CLI commands
--- a/README.zh.md
+++ b/README.zh.md
@@ -139,7 +139,7 @@ AI 通过 `<qqvideo>路径</qqvideo>` 发送视频，支持本地文件和公网
 2. 手机 QQ 扫码后选择**同意**，即完成注册，进入 QQ 机器人配置页。
 3. 点击**创建机器人**，即可直接新建一个 QQ 机器人。

-<img width="1982" height="1316" alt="Clipboard_Screenshot_1772980440" src="https://github.com/user-attachments/assets/3ccb494d-6e4d-462c-9218-b4dfd43a254f" />
+<img width="720" alt="创建机器人" src="docs/images/create_robot.png" />

 4. 在机器人页面中找到 **AppID** 和 **AppSecret**，分别点击右侧**复制**按钮，保存到记事本或备忘录中。**AppSecret 不支持明文保存，离开页面后再查看会强制重置，请务必妥善保存。**

@@ -151,7 +151,13 @@ AI 通过 `<qqvideo>路径</qqvideo>` 发送视频，支持本地文件和公网

 ### 第二步 — 安装插件

-**方式一：一键安装并启动（推荐）**
+**方式一：通过 npm 安装（推荐）**
+
+```bash
+openclaw plugins install @tencent-connect/openclaw-qqbot
+```
+
+**方式二：一键安装并启动**

 ```bash
 git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
@@ -160,7 +166,7 @@ bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET

 脚本会自动完成：清理旧插件 → 安装依赖 → 注册插件 → 配置通道 → 启动服务。完成后可直接跳到[第四步](#第四步--启动并测试)。

-**方式二：手动分步安装**
+**方式三：手动分步安装**

 ```bash
 git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
@@ -347,6 +353,24 @@ STT 支持两级配置，按优先级查找：

 ## 🔄 升级

+### 方式一：通过 npm 升级（推荐）
+
+```bash
+bash ./scripts/npm-upgrade.sh
+```
+
+脚本会自动备份通道配置 → 卸载旧插件 → 安装新版本 → 恢复配置 → 重启网关。
+
+```bash
+# 指定 tag
+bash ./scripts/npm-upgrade.sh --tag alpha
+
+# 指定版本号
+bash ./scripts/npm-upgrade.sh --version 1.0.0-alpha.0
+```
+
+### 方式二：通过源码升级
+
 运行一键脚本即可升级并重启：

 ```bash
@@ -376,6 +400,69 @@ bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET

 ---

+## 🔀 从旧版插件迁移
+
+如果你之前安装的是 `qqbot`、`@sliverp/qqbot`、`@tencent-connect/qqbot` 等关联插件，需要先卸载旧插件再安装新版本。
+
+### 推荐：使用 npm-upgrade 脚本（自动处理）
+
+```bash
+bash ./scripts/npm-upgrade.sh
+```
+
+脚本会自动卸载所有历史版本的插件（`qqbot`、`@sliverp/qqbot`、`openclaw-qq` 等）、清理残留目录、备份恢复通道配置。
+
+### 手动迁移
+
+**1. 备份你的通道配置**
+
+先记录 `~/.openclaw/openclaw.json` 中 `channels.qqbot` 的内容（`appId`、`clientSecret`、`allowFrom` 等），后续需要恢复。
+
+**2. 卸载旧插件**
+
+根据你之前安装的插件名，执行对应的卸载命令：
+
+```bash
+# 卸载可能存在的旧版插件（按实际情况选择）
+openclaw plugins uninstall qqbot
+openclaw plugins uninstall @sliverp/qqbot
+openclaw plugins uninstall @tencent-connect/qqbot
+openclaw plugins uninstall openclaw-qqbot
+openclaw plugins uninstall openclaw-qq
+```
+
+如果 `plugins uninstall` 未能完全清理，手动删除残留目录：
+
+```bash
+rm -rf ~/.openclaw/extensions/qqbot
+rm -rf ~/.openclaw/extensions/openclaw-qqbot
+rm -rf ~/.openclaw/extensions/openclaw-qq
+```
+
+**3. 临时移除通道配置**
+
+> ⚠️ 重要：`openclaw plugins install` 会校验配置文件。如果配置中存在 `channels.qqbot` 但对应插件尚未安装，会报 `unknown channel id: qqbot` 错误并拒绝安装。
+
+安装前需要临时从 `~/.openclaw/openclaw.json` 中移除 `channels.qqbot` 配置段。
+
+**4. 安装新版本**
+
+```bash
+openclaw plugins install @tencent-connect/openclaw-qqbot
+```
+
+**5. 恢复通道配置**
+
+将之前备份的 `channels.qqbot` 配置写回 `~/.openclaw/openclaw.json`。
+
+**6. 重启网关**
+
+```bash
+openclaw gateway restart
+```
+
+---
+
 ## 📚 文档与链接

 - [命令参考](docs/commands.md) — OpenClaw CLI 常用命令
--- a/docs/images/create_robot.png
+++ b/docs/images/create_robot.png
--- a/scripts/npm-upgrade.sh
+++ b/scripts/npm-upgrade.sh
@@ -0,0 +1,120 @@
+#!/bin/bash
+
+# QQBot 通过 npm 包升级
+#
+# 用法:
+#   npm-upgrade.sh                                    # 升级到 latest（默认）
+#   npm-upgrade.sh --tag alpha                        # 升级到 alpha
+#   npm-upgrade.sh --version 1.0.0-alpha.0            # 升级到指定版本
+
+set -eo pipefail
+
+PKG_NAME="@tencent-connect/openclaw-qqbot"
+INSTALL_SRC=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --tag)     INSTALL_SRC="${PKG_NAME}@$2"; shift 2 ;;
+        --version) INSTALL_SRC="${PKG_NAME}@$2"; shift 2 ;;
+        -h|--help)
+            echo "用法:"
+            echo "  npm-upgrade.sh                              # 升级到 latest（默认）"
+            echo "  npm-upgrade.sh --tag alpha                   # 升级到 alpha"
+            echo "  npm-upgrade.sh --version 1.0.0-alpha.0       # 升级到指定版本"
+            exit 0
+            ;;
+        *) echo "未知选项: $1"; exit 1 ;;
+    esac
+done
+INSTALL_SRC="${INSTALL_SRC:-${PKG_NAME}@latest}"
+
+# 检测 CLI
+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 "==========================================="
+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 "  ⚠️  备份失败"
+else
+    echo "  ℹ️  无配置文件"
+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
+
+# [3/4] 安装新版本
+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"
+fi
+
+# [4/4] 重启网关
+echo ""
+echo "[4/4] 重启网关..."
+$CMD gateway restart 2>&1 || true
+
+echo ""
+echo "==========================================="
+echo "  ✅ 升级完成"
+echo "==========================================="
+echo ""
+echo "常用命令:"
+echo "  $CMD logs --follow        # 跟踪日志"
+echo "  $CMD gateway restart      # 重启服务"
+echo "  $CMD plugins list         # 查看插件列表"