diff --git a/.gitignore b/.gitignore
index 77ab1cc..ec4c548 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,4 +5,6 @@ package-lock.json
.idea/
.codebuddy/
.codebuddy.zip
-openclaw.json
\ No newline at end of file
+openclaw.json
+*.tgz
+*.log
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8e9490b..bcfcd3e 100644
--- 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.
diff --git a/CHANGELOG.zh.md b/CHANGELOG.zh.md
index 0c14081..a5576b6 100644
--- 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 与包名不一致导致插件加载失败的问题。
diff --git a/README.md b/README.md
index 300c194..269ab84 100644
--- a/README.md
+++ b/README.md
@@ -142,7 +142,7 @@ AI sends videos via `path`. 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.
-
+
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 `path`. 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
diff --git a/README.zh.md b/README.zh.md
index c1d1161..1389808 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -139,7 +139,7 @@ AI 通过 `路径` 发送视频，支持本地文件和公网
2. 手机 QQ 扫码后选择**同意**，即完成注册，进入 QQ 机器人配置页。
3. 点击**创建机器人**，即可直接新建一个 QQ 机器人。
-
+
4. 在机器人页面中找到 **AppID** 和 **AppSecret**，分别点击右侧**复制**按钮，保存到记事本或备忘录中。**AppSecret 不支持明文保存，离开页面后再查看会强制重置，请务必妥善保存。**
@@ -151,7 +151,13 @@ AI 通过 `路径` 发送视频，支持本地文件和公网
### 第二步 — 安装插件
-**方式一：一键安装并启动（推荐）**
+**方式一：通过 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 常用命令
diff --git a/docs/images/create_robot.png b/docs/images/create_robot.png
new file mode 100644
index 0000000..f9c0e51
Binary files /dev/null and b/docs/images/create_robot.png differ
diff --git a/scripts/npm-upgrade.sh b/scripts/npm-upgrade.sh
new file mode 100755
index 0000000..2b3f2e9
--- /dev/null
+++ 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 # 查看插件列表"