diff --git a/README.md b/README.md
index 1ce21e5..2ba7861 100644
--- a/README.md
+++ b/README.md
@@ -375,7 +375,17 @@ If you previously installed qqbot but are not familiar with `openclaw plugins` c
 
 ### Option 1: Recommended (Script-based upgrade)
 
-#### 1) Upgrade via npm package (easiest)
+#### 1) Upgrade via npm package (easiest, choose either way)
+
+**Way A — direct download and run (no clone required):**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/npm-upgrade.sh -o /tmp/upgrade-via-npm.sh
+bash /tmp/upgrade-via-npm.sh
+# or: bash /tmp/upgrade-via-npm.sh --version <version>
+```
+
+**Way B — run from local repository:**
 
 ```bash
 # Upgrade to latest
@@ -387,14 +397,6 @@ bash ./scripts/upgrade-via-npm.sh --version <version>
 
 > If `--version` is omitted, `latest` is used by default.
 
-> You can also download and run this script directly:
->
-> ```bash
-> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/npm-upgrade.sh -o /tmp/upgrade-via-npm.sh
-> bash /tmp/upgrade-via-npm.sh
-> # or: bash /tmp/upgrade-via-npm.sh --version <version>
-> ```
-
 #### 2) One-click upgrade from local source and restart
 
 > Note: this script must be run inside this repository (it installs via `openclaw plugins install .`).
@@ -463,6 +465,7 @@ openclaw logs --follow
 
 ## 📚 Documentation & Links
 
+- [Upgrade Guide](docs/UPGRADE_GUIDE.md) — full upgrade paths and migration notes
 - [Command Reference](docs/commands.md) — OpenClaw CLI commands
 - [Changelog](CHANGELOG.md) — release notes
 
diff --git a/README.zh.md b/README.zh.md
index 5a5639a..5aa6770 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -372,7 +372,17 @@ STT 支持两级配置，按优先级查找：
 
 ### 方式一：推荐（脚本升级）
 
-#### 1) 通过 npm 包升级（最省事）
+#### 1) 通过 npm 包升级（最省事，二选一）
+
+**方式 A：直连下载后执行（无需 clone 仓库）**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/npm-upgrade.sh -o /tmp/upgrade-via-npm.sh
+bash /tmp/upgrade-via-npm.sh
+# 或：bash /tmp/upgrade-via-npm.sh --version <version>
+```
+
+**方式 B：在本地仓库内执行脚本**
 
 ```bash
 # 升级到 latest
@@ -384,14 +394,6 @@ bash ./scripts/upgrade-via-npm.sh --version <version>
 
 > 不传 `--version` 时，默认使用 `latest`。
 
-> 也可以直接下载并执行该脚本：
->
-> ```bash
-> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/npm-upgrade.sh -o /tmp/upgrade-via-npm.sh
-> bash /tmp/upgrade-via-npm.sh
-> # 或：bash /tmp/upgrade-via-npm.sh --version <version>
-> ```
-
 #### 2) 通过源码一键升级并重启
 
 > 注意：该脚本必须在当前仓库内执行（通过 `openclaw plugins install .` 安装本地源码）。
@@ -460,6 +462,7 @@ openclaw logs --follow
 
 ## 📚 文档与链接
 
+- [升级指南](docs/UPGRADE_GUIDE.zh.md) — 完整升级路径与迁移说明
 - [命令参考](docs/commands.md) — OpenClaw CLI 常用命令
 - [更新日志](CHANGELOG.md) — 各版本变更记录
 
diff --git a/docs/UPGRADE_GUIDE.md b/docs/UPGRADE_GUIDE.md
index c6ac688..c2ea329 100644
--- a/docs/UPGRADE_GUIDE.md
+++ b/docs/UPGRADE_GUIDE.md
@@ -4,7 +4,17 @@ If you previously installed qqbot but are not familiar with `openclaw plugins` c
 
 ## Option 1: Recommended (Script-based upgrade)
 
-### 1) Upgrade via npm package (easiest)
+### 1) Upgrade via npm package (easiest, choose either way)
+
+**Way A — direct download and run (no clone required):**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/npm-upgrade.sh -o /tmp/upgrade-via-npm.sh
+bash /tmp/upgrade-via-npm.sh
+# or: bash /tmp/upgrade-via-npm.sh --version <version>
+```
+
+**Way B — run from local repository:**
 
 ```bash
 # Upgrade to latest
@@ -16,14 +26,6 @@ bash ./scripts/upgrade-via-npm.sh --version <version>
 
 > If `--version` is omitted, `latest` is used by default.
 
-> You can also download and run this script directly:
->
-> ```bash
-> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/npm-upgrade.sh -o /tmp/upgrade-via-npm.sh
-> bash /tmp/upgrade-via-npm.sh
-> # or: bash /tmp/upgrade-via-npm.sh --version <version>
-> ```
-
 ### 2) One-click upgrade from local source and restart
 
 > Note: this script must be run inside this repository (it installs via `openclaw plugins install .`).
diff --git a/docs/UPGRADE_GUIDE.zh.md b/docs/UPGRADE_GUIDE.zh.md
index 2ed3a22..514b68c 100644
--- a/docs/UPGRADE_GUIDE.zh.md
+++ b/docs/UPGRADE_GUIDE.zh.md
@@ -4,7 +4,17 @@
 
 ## 方式一：推荐（脚本升级）
 
-### 1) 通过 npm 包升级（最省事）
+### 1) 通过 npm 包升级（最省事，二选一）
+
+**方式 A：直连下载后执行（无需 clone 仓库）**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/npm-upgrade.sh -o /tmp/upgrade-via-npm.sh
+bash /tmp/upgrade-via-npm.sh
+# 或：bash /tmp/upgrade-via-npm.sh --version <version>
+```
+
+**方式 B：在本地仓库内执行脚本**
 
 ```bash
 # 升级到 latest
@@ -16,14 +26,6 @@ bash ./scripts/upgrade-via-npm.sh --version <version>
 
 > 不传 `--version` 时，默认使用 `latest`。
 
-> 也可以直接下载并执行该脚本：
->
-> ```bash
-> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/npm-upgrade.sh -o /tmp/upgrade-via-npm.sh
-> bash /tmp/upgrade-via-npm.sh
-> # 或：bash /tmp/upgrade-via-npm.sh --version <version>
-> ```
-
 ### 2) 通过源码一键升级并重启
 
 > 注意：该脚本必须在当前仓库内执行（通过 `openclaw plugins install .` 安装本地源码）。