Merge pull request #15 from tencent-connect/docs/upgrade-guide-clarify

Docs/upgrade guide clarify
2026-05-01 06:10:58 +08:00 · 2026-03-11 16:34:15 +08:00
parent aaa9f2d102 8efb9c07d9
commit 1400ed05dd
16 changed files with 560 additions and 762 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,7 +24,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).

 - 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.
+  - Handles channel config backup/restore, old plugin cleanup (including legacy variants like `qqbot`, `@sliverp/qqbot`), and gateway restart.
  - Temporarily removes `channels.qqbot` before install to avoid `unknown channel id` validation error.

 ### Fixed
--- a/CHANGELOG.zh.md
+++ b/CHANGELOG.zh.md
@@ -24,7 +24,7 @@

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

 ### 修复
--- a/README.md
+++ b/README.md
@@ -176,7 +176,10 @@ openclaw plugins install @tencent-connect/openclaw-qqbot

 ```bash
 git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
-bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
+# First-time install/config (appid and secret are required)
+bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET
+# Subsequent upgrades (existing config)
+bash ./scripts/upgrade-via-source.sh
 ```

 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).
@@ -368,113 +371,94 @@ STT supports two-level configuration with priority fallback:

 ## 🔄 Upgrade

-### Option 1: Upgrade via npm (Recommended)
+If you previously installed qqbot but are not familiar with `openclaw plugins` commands or npm operations, use the built-in scripts first.

-Current latest npm version: `1.5.6`
+### Option 1: Recommended (Script-based upgrade)
+
+#### 1) Upgrade via npm package (easiest)

 ```bash
-bash ./scripts/npm-upgrade.sh
+# Upgrade to latest
+bash ./scripts/upgrade-via-npm.sh
+
+# Upgrade to a specific version
+bash ./scripts/upgrade-via-npm.sh --version <version>
 ```

-The script automatically backs up channel config → uninstalls old plugins → installs new version → restores config → restarts gateway.
+> 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 .`).

 ```bash
-# Specify exact version
-bash ./scripts/npm-upgrade.sh --version 1.5.6
+# Run directly if you already have config
+bash ./scripts/upgrade-via-source.sh
+
+# First install / first-time config (appid and secret are required)
+bash ./scripts/upgrade-via-source.sh --appid your_appid --secret your_secret
 ```

-### Option 2: Upgrade via Source
+> Note: For first-time installation, you must provide `appid` and `secret` (or set `QQBOT_APPID` / `QQBOT_SECRET`); for subsequent upgrades with existing config, run `bash ./scripts/upgrade-via-source.sh` directly.

-Run the one-click script to upgrade and restart:
+### Option 2: Manual upgrade (for users familiar with openclaw / npm)
+
+#### A. Install latest from npm directly

 ```bash
-bash ./scripts/upgrade-and-run.sh
-```
-
-When no `--appid` / `--secret` is provided, the script reads existing config from `~/.openclaw/openclaw.json` automatically.
-
-```bash
-# First-time or override credentials
-bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
-```
-
-<details>
-<summary>Full Options</summary>
-
-| Option | Description |
-|--------|-------------|
-| `--appid <id>` | QQ Bot AppID |
-| `--secret <secret>` | QQ Bot AppSecret |
-| `--markdown <yes\|no>` | Enable Markdown format (default: no) |
-| `-h, --help` | Show help |
-
-Environment variables `QQBOT_APPID`, `QQBOT_SECRET`, `QQBOT_TOKEN` (AppID:Secret) are also supported.
-
-</details>
-
---
-
-## 🔀 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)
+# Optional: uninstall old plugins first (based on your actual installation)
+# Run `openclaw plugins list` to check installed plugin IDs
+# Common legacy plugin IDs: qqbot / openclaw-qqbot
+# Corresponding npm packages: @sliverp/qqbot / @tencent-connect/openclaw-qqbot
 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 you installed other qqbot-related plugins, uninstall them as well
+# openclaw plugins uninstall <other-plugin-id>
+
+# Install latest
+openclaw plugins install @tencent-connect/openclaw-qqbot@latest
+
+# Or install a specific version
+openclaw plugins install @tencent-connect/openclaw-qqbot@<version>
 ```

-If `plugins uninstall` doesn't fully clean up, manually remove residual directories:
+#### B. Install from source directory

 ```bash
-rm -rf ~/.openclaw/extensions/qqbot
-rm -rf ~/.openclaw/extensions/openclaw-qqbot
-rm -rf ~/.openclaw/extensions/openclaw-qq
+cd /path/to/openclaw-qqbot
+npm install --omit=dev
+openclaw plugins install .
 ```

-**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**
+#### C. Configure channel (required for first install)

 ```bash
-openclaw plugins install @tencent-connect/openclaw-qqbot
+openclaw channels add --channel qqbot --token "appid:appsecret"
 ```

-**5. Restore channel config**
-
-Write back the previously saved `channels.qqbot` config to `~/.openclaw/openclaw.json`.
-
-**6. Restart the gateway**
+#### D. Restart gateway

 ```bash
 openclaw gateway restart
 ```

+#### E. Verify
+
+```bash
+openclaw plugins list
+openclaw channels list
+openclaw logs --follow
+```
+
 ---

 ## 📚 Documentation & Links
--- a/README.zh.md
+++ b/README.zh.md
@@ -173,7 +173,10 @@ openclaw plugins install @tencent-connect/openclaw-qqbot

 ```bash
 git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
-bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
+# 首次安装/首次配置（需要提供 appid 和 secret）
+bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET
+# 后续升级（已有配置）
+bash ./scripts/upgrade-via-source.sh
 ```

 脚本会自动完成：清理旧插件 → 安装依赖 → 注册插件 → 配置通道 → 启动服务。完成后可直接跳到[第四步](#第四步--启动并测试)。
@@ -365,113 +368,94 @@ STT 支持两级配置，按优先级查找：

 ## 🔄 升级

-### 方式一：通过 npm 升级（推荐）
+如果你之前安装过 qqbot 插件，但不熟悉 `openclaw plugins` 升级命令或 `npm` 操作，建议优先使用项目内置脚本。

-当前最新 npm 版本：`1.5.6`
+### 方式一：推荐（脚本升级）
+
+#### 1) 通过 npm 包升级（最省事）

 ```bash
-bash ./scripts/npm-upgrade.sh
+# 升级到 latest
+bash ./scripts/upgrade-via-npm.sh
+
+# 指定版本
+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 .` 安装本地源码）。

 ```bash
-# 指定版本号
-bash ./scripts/npm-upgrade.sh --version 1.5.6
+# 已有配置时可直接执行
+bash ./scripts/upgrade-via-source.sh
+
+# 首次安装/首次配置（必须提供 appid 和 secret）
+bash ./scripts/upgrade-via-source.sh --appid your_appid --secret your_secret
 ```

-### 方式二：通过源码升级
+> 注意：首次安装必须设置 `appid` 和 `secret`（或设置环境变量 `QQBOT_APPID` / `QQBOT_SECRET`）；后续升级如已有配置可直接执行 `bash ./scripts/upgrade-via-source.sh`。

-运行一键脚本即可升级并重启：
+### 方式二：手动升级（适合熟悉 openclaw / npm 的用户）
+
+#### A. 直接从 npm 安装最新版本

 ```bash
-bash ./scripts/upgrade-and-run.sh
-```
-
-不传 `--appid` / `--secret` 参数时，脚本会自动读取 `~/.openclaw/openclaw.json` 中已有的配置。
-
-```bash
-# 首次配置或需要覆盖时
-bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
-```
-
-<details>
-<summary>完整选项</summary>
-
-| 选项 | 说明 |
-|------|------|
-| `--appid <id>` | QQ 机器人 AppID |
-| `--secret <secret>` | QQ 机器人 AppSecret |
-| `--markdown <yes\|no>` | 是否启用 Markdown 消息格式（默认: no） |
-| `-h, --help` | 显示帮助 |
-
-也支持环境变量：`QQBOT_APPID`、`QQBOT_SECRET`、`QQBOT_TOKEN`（AppID:Secret）。
-
-</details>
-
---
-
-## 🔀 从旧版插件迁移
-
-如果你之前安装的是 `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 list` 查看已安装插件 ID
+# 常见历史插件 ID：qqbot / openclaw-qqbot
+# 对应 npm 包：@sliverp/qqbot / @tencent-connect/openclaw-qqbot
 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
+
+# 如果你还安装过其它 qqbot 相关插件，也请一并 uninstall
+# openclaw plugins uninstall <其它插件ID>
+
+# 安装最新版本
+openclaw plugins install @tencent-connect/openclaw-qqbot@latest
+
+# 或安装指定版本
+openclaw plugins install @tencent-connect/openclaw-qqbot@<version>
 ```

-如果 `plugins uninstall` 未能完全清理，手动删除残留目录：
+#### B. 从源码目录安装

 ```bash
-rm -rf ~/.openclaw/extensions/qqbot
-rm -rf ~/.openclaw/extensions/openclaw-qqbot
-rm -rf ~/.openclaw/extensions/openclaw-qq
+cd /path/to/openclaw-qqbot
+npm install --omit=dev
+openclaw plugins install .
 ```

-**3. 临时移除通道配置**
-
-> ⚠️ 重要：`openclaw plugins install` 会校验配置文件。如果配置中存在 `channels.qqbot` 但对应插件尚未安装，会报 `unknown channel id: qqbot` 错误并拒绝安装。
-
-安装前需要临时从 `~/.openclaw/openclaw.json` 中移除 `channels.qqbot` 配置段。
-
-**4. 安装新版本**
+#### C. 配置通道（首次安装必做）

 ```bash
-openclaw plugins install @tencent-connect/openclaw-qqbot
+openclaw channels add --channel qqbot --token "appid:appsecret"
 ```

-**5. 恢复通道配置**
-
-将之前备份的 `channels.qqbot` 配置写回 `~/.openclaw/openclaw.json`。
-
-**6. 重启网关**
+#### D. 重启网关

 ```bash
 openclaw gateway restart
 ```

+#### E. 验证
+
+```bash
+openclaw plugins list
+openclaw channels list
+openclaw logs --follow
+```
+
 ---

 ## 📚 文档与链接
--- a/bin/qqbot-cli.js
+++ b/bin/qqbot-cli.js
@@ -1,7 +1,7 @@
 #!/usr/bin/env node

 /**
- * QQBot CLI - 用于升级和管理 QQBot 插件
+ * qqbot CLI - 用于升级和管理 qqbot 插件
 * 
 * 用法:
 *   npx openclaw-qqbot upgrade    # 升级插件
@@ -131,7 +131,7 @@ function runCommand(cmd, args = []) {

 // 升级命令
 function upgrade() {
-  console.log('=== QQBot 插件升级脚本 ===');
+  console.log('=== qqbot 插件升级脚本 ===');

  let foundInstallation = null;
  let savedConfig = null;
@@ -175,7 +175,7 @@ function upgrade() {
    }
  } else {
    console.log('未找到已保存的 qqbot 配置，请手动配置:');
-    console.log(`  ${foundInstallation} channels add --channel qqbot --token "AppID:AppSecret"`);
+    console.log(`  ${foundInstallation} channels add --channel qqbot --token "appid:appsecret"`);
    return;
  }

@@ -186,7 +186,7 @@ function upgrade() {

 // 安装命令
 function install() {
-  console.log('=== QQBot 插件安装 ===');
+  console.log('=== qqbot 插件安装 ===');

  const cmd = detectInstallation();
  if (!cmd) {
@@ -200,13 +200,13 @@ function install() {

  console.log('\n=== 安装完成 ===');
  console.log('\n请配置机器人通道:');
-  console.log(`  ${cmd} channels add --channel qqbot --token "AppID:AppSecret"`);
+  console.log(`  ${cmd} channels add --channel qqbot --token "appid:appsecret"`);
 }

 // 显示帮助
 function showHelp() {
  console.log(`
-QQBot CLI - QQ机器人插件管理工具
+qqbot CLI - QQ机器人插件管理工具

 用法:
  npx openclaw-qqbot <命令>
--- a/docs/UPGRADE_GUIDE.md
+++ b/docs/UPGRADE_GUIDE.md
@@ -0,0 +1,91 @@
+# qqbot Plugin Upgrade Guide
+
+If you previously installed qqbot but are not familiar with `openclaw plugins` commands or npm operations, use the built-in scripts first.
+
+## Option 1: Recommended (Script-based upgrade)
+
+### 1) Upgrade via npm package (easiest)
+
+```bash
+# Upgrade to latest
+bash ./scripts/upgrade-via-npm.sh
+
+# Upgrade to a specific version
+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 .`).
+
+```bash
+# Run directly if you already have config
+bash ./scripts/upgrade-via-source.sh
+
+# First install / first-time config (appid and secret are required)
+bash ./scripts/upgrade-via-source.sh --appid your_appid --secret your_secret
+```
+
+> Note: For first-time installation, you must provide `appid` and `secret` (or set `QQBOT_APPID` / `QQBOT_SECRET`); for subsequent upgrades with existing config, run `bash ./scripts/upgrade-via-source.sh` directly.
+
+---
+
+## Option 2: Manual upgrade (for users familiar with openclaw / npm)
+
+### A. Install latest from npm directly
+
+```bash
+# Optional: uninstall old plugins first (based on your actual installation)
+# Run `openclaw plugins list` to check installed plugin IDs
+# Common legacy plugin IDs: qqbot / openclaw-qqbot
+# Corresponding npm packages: @sliverp/qqbot / @tencent-connect/openclaw-qqbot
+openclaw plugins uninstall qqbot
+openclaw plugins uninstall openclaw-qqbot
+
+# If you installed other qqbot-related plugins, uninstall them as well
+# openclaw plugins uninstall <other-plugin-id>
+
+# Install latest
+openclaw plugins install @tencent-connect/openclaw-qqbot@latest
+
+# Or install a specific version
+openclaw plugins install @tencent-connect/openclaw-qqbot@<version>
+```
+
+### B. Install from source directory
+
+```bash
+cd /path/to/openclaw-qqbot
+npm install --omit=dev
+openclaw plugins install .
+```
+
+### C. Configure channel (required for first install)
+
+```bash
+openclaw channels add --channel qqbot --token "appid:appsecret"
+```
+
+### D. Restart gateway
+
+```bash
+openclaw gateway restart
+```
+
+### E. Verify
+
+```bash
+openclaw plugins list
+openclaw channels list
+openclaw logs --follow
+```
--- a/docs/UPGRADE_GUIDE.zh.md
+++ b/docs/UPGRADE_GUIDE.zh.md
@@ -0,0 +1,91 @@
+# qqbot 插件升级指南
+
+如果你之前安装过 qqbot 插件，但不熟悉 `openclaw plugins` 升级命令或 `npm` 操作，建议优先使用项目内置脚本。
+
+## 方式一：推荐（脚本升级）
+
+### 1) 通过 npm 包升级（最省事）
+
+```bash
+# 升级到 latest
+bash ./scripts/upgrade-via-npm.sh
+
+# 指定版本
+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 .` 安装本地源码）。
+
+```bash
+# 已有配置时可直接执行
+bash ./scripts/upgrade-via-source.sh
+
+# 首次安装/首次配置（必须提供 appid 和 secret）
+bash ./scripts/upgrade-via-source.sh --appid your_appid --secret your_secret
+```
+
+> 注意：首次安装必须设置 `appid` 和 `secret`（或设置环境变量 `QQBOT_APPID` / `QQBOT_SECRET`）；后续升级如已有配置可直接执行 `bash ./scripts/upgrade-via-source.sh`。
+
+---
+
+## 方式二：手动升级（适合熟悉 openclaw / npm 的用户）
+
+### A. 直接从 npm 安装最新版本
+
+```bash
+# 可选：先卸载旧插件（按实际安装情况执行）
+# 可先执行 `openclaw plugins list` 查看已安装插件 ID
+# 常见历史插件 ID：qqbot / openclaw-qqbot
+# 对应 npm 包：@sliverp/qqbot / @tencent-connect/openclaw-qqbot
+openclaw plugins uninstall qqbot
+openclaw plugins uninstall openclaw-qqbot
+
+# 如果你还安装过其它 qqbot 相关插件，也请一并 uninstall
+# openclaw plugins uninstall <其它插件ID>
+
+# 安装最新版本
+openclaw plugins install @tencent-connect/openclaw-qqbot@latest
+
+# 或安装指定版本
+openclaw plugins install @tencent-connect/openclaw-qqbot@<version>
+```
+
+### B. 从源码目录安装
+
+```bash
+cd /path/to/openclaw-qqbot
+npm install --omit=dev
+openclaw plugins install .
+```
+
+### C. 配置通道（首次安装必做）
+
+```bash
+openclaw channels add --channel qqbot --token "appid:appsecret"
+```
+
+### D. 重启网关
+
+```bash
+openclaw gateway restart
+```
+
+### E. 验证
+
+```bash
+openclaw plugins list
+openclaw channels list
+openclaw logs --follow
+```
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -1,4 +1,4 @@
-# OpenClaw 常用指令手册
+# openclaw 常用指令手册

 本文档整理了 `openclaw` 的常用命令，方便日常使用和维护。

@@ -33,16 +33,16 @@ openclaw plugins list

 ## 📺 通道管理

-### 配置 QQBot 通道
+### 配置 qqbot 通道
 ```bash
-# QQBot 是自定义插件，通过 config set 配置（不是 channels add）
-openclaw config set channels.qqbot.appId "你的AppID"
-openclaw config set channels.qqbot.clientSecret "你的AppSecret"
+# qqbot 是自定义插件，通过 config set 配置（不是 channels add）
+openclaw config set channels.qqbot.appId "你的appid"
+openclaw config set channels.qqbot.clientSecret "你的appsecret"
 openclaw config set channels.qqbot.enabled true
 ```

 > **注意**：`openclaw channels add --channel` 仅支持内置通道（telegram、discord 等）。
-> QQBot 作为自定义插件，需通过 `config set` 或直接编辑 `~/.openclaw/openclaw.json` 配置。
+> qqbot 作为自定义插件，需通过 `config set` 或直接编辑 `~/.openclaw/openclaw.json` 配置。

 ### 禁用通道
 ```bash
@@ -111,10 +111,10 @@ openclaw logs --plain

 ### 设置配置项
 ```bash
-# 启用 Markdown 消息格式
+# 启用 markdown 消息格式
 openclaw config set channels.qqbot.markdownSupport true

-# 禁用 Markdown 消息格式
+# 禁用 markdown 消息格式
 openclaw config set channels.qqbot.markdownSupport false
 ```

@@ -138,16 +138,16 @@ openclaw config
 ### 一键升级并启动
 ```bash
 # 基本用法
-./scripts/upgrade-and-run.sh
+./scripts/upgrade-via-source.sh

-# 指定 AppID 和 Secret
-./scripts/upgrade-and-run.sh --appid 123456789 --secret your_secret
+# 指定 appid 和 secret
+./scripts/upgrade-via-source.sh --appid 123456789 --secret your_secret

-# 同时启用 Markdown
-./scripts/upgrade-and-run.sh --appid 123456789 --secret your_secret --markdown yes
+# 同时启用 markdown
+./scripts/upgrade-via-source.sh --appid 123456789 --secret your_secret --markdown yes

 # 查看帮助
-./scripts/upgrade-and-run.sh --help
+./scripts/upgrade-via-source.sh --help
 ```

 **环境变量方式：**
@@ -155,15 +155,15 @@ openclaw config
 export QQBOT_APPID="123456789"
 export QQBOT_SECRET="your_secret"
 export QQBOT_MARKDOWN="no"
-./scripts/upgrade-and-run.sh
+./scripts/upgrade-via-source.sh
 ```

-### Markdown 设置脚本
+### markdown 设置脚本
 ```bash
-# 启用 Markdown
+# 启用 markdown
 ./scripts/set-markdown.sh enable

-# 禁用 Markdown
+# 禁用 markdown
 ./scripts/set-markdown.sh disable

 # 查看当前状态
@@ -176,7 +176,7 @@ export QQBOT_MARKDOWN="no"
 ### 升级脚本（清理旧版本）
 ```bash
 # 清理旧版本插件和配置
-bash ./scripts/upgrade.sh
+bash ./scripts/cleanup-legacy-plugins.sh
 ```

 ---
@@ -185,10 +185,10 @@ bash ./scripts/upgrade.sh

 | 路径 | 说明 |
 |------|------|
-| `~/.openclaw/` | OpenClaw 主目录 |
+| `~/.openclaw/` | openclaw 主目录 |
 | `~/.openclaw/openclaw.json` | 全局配置文件 |
 | `~/.openclaw/extensions/` | 插件安装目录 |
-| `~/.openclaw/extensions/qqbot/` | QQBot 插件目录 |
+| `~/.openclaw/extensions/qqbot/` | qqbot 插件目录 |

 ---

@@ -212,14 +212,14 @@ openclaw channels list
 ### 重新安装插件
 ```bash
 # 1. 清理旧版本
-bash ./scripts/upgrade.sh
+bash ./scripts/cleanup-legacy-plugins.sh

 # 2. 重新安装
 openclaw plugins install .

 # 3. 重新配置通道
-openclaw config set channels.qqbot.appId "你的AppID"
-openclaw config set channels.qqbot.clientSecret "你的AppSecret"
+openclaw config set channels.qqbot.appId "你的appid"
+openclaw config set channels.qqbot.clientSecret "你的appsecret"
 openclaw config set channels.qqbot.enabled true
 ```

@@ -228,7 +228,7 @@ openclaw config set channels.qqbot.enabled true
 ## ⚠️ 注意事项

 1. **不要使用 sudo 运行脚本**：会导致配置文件权限问题
-2. **Markdown 功能需要权限**：启用前需在 QQ 开放平台申请 Markdown 消息权限
+2. **markdown 功能需要权限**：启用前需在 QQ 开放平台申请 markdown 消息权限

 ---

--- a/package-lock.json
+++ b/package-lock.json
@@ -1,18 +1,19 @@
 {
  "name": "@tencent-connect/openclaw-qqbot",
-  "version": "1.5.5",
+  "version": "1.5.6",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "@tencent-connect/openclaw-qqbot",
-      "version": "1.5.5",
+      "version": "1.5.6",
      "bundleDependencies": [
        "mpg123-decoder",
        "silk-wasm",
        "ws"
      ],
      "dependencies": {
+        "@tencent-connect/openclaw-qqbot": "^1.5.6",
        "mpg123-decoder": "^1.0.3",
        "silk-wasm": "^3.7.1",
        "ws": "^8.18.0"
@@ -4243,6 +4244,93 @@
        "node": ">=18.0.0"
      }
    },
+    "node_modules/@tencent-connect/openclaw-qqbot": {
+      "version": "1.5.6",
+      "resolved": "https://mirrors.tencent.com/npm/@tencent-connect/openclaw-qqbot/-/openclaw-qqbot-1.5.6.tgz",
+      "integrity": "sha512-DNznnKZVIr0YPi3GpCggLr9MrKbRPGLG5SHWQJeY6J1K+Fo7yuq+tgh3HamTpbrTK7iBfEWb2MjT/CQbAm5sbA==",
+      "bundleDependencies": [
+        "mpg123-decoder",
+        "silk-wasm",
+        "ws"
+      ],
+      "dependencies": {
+        "mpg123-decoder": "^1.0.3",
+        "silk-wasm": "^3.7.1",
+        "ws": "^8.18.0"
+      },
+      "bin": {
+        "openclaw-qqbot": "bin/qqbot-cli.js",
+        "qqbot": "bin/qqbot-cli.js"
+      },
+      "peerDependencies": {
+        "clawdbot": "*",
+        "moltbot": "*",
+        "openclaw": "*"
+      }
+    },
+    "node_modules/@tencent-connect/openclaw-qqbot/node_modules/@eshaz/web-worker": {
+      "version": "1.2.2",
+      "inBundle": true,
+      "license": "Apache-2.0"
+    },
+    "node_modules/@tencent-connect/openclaw-qqbot/node_modules/@wasm-audio-decoders/common": {
+      "version": "9.0.7",
+      "inBundle": true,
+      "license": "MIT",
+      "dependencies": {
+        "@eshaz/web-worker": "1.2.2",
+        "simple-yenc": "^1.0.4"
+      }
+    },
+    "node_modules/@tencent-connect/openclaw-qqbot/node_modules/mpg123-decoder": {
+      "version": "1.0.3",
+      "inBundle": true,
+      "license": "MIT",
+      "dependencies": {
+        "@wasm-audio-decoders/common": "9.0.7"
+      },
+      "funding": {
+        "type": "individual",
+        "url": "https://github.com/sponsors/eshaz"
+      }
+    },
+    "node_modules/@tencent-connect/openclaw-qqbot/node_modules/silk-wasm": {
+      "version": "3.7.1",
+      "inBundle": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=16.11.0"
+      }
+    },
+    "node_modules/@tencent-connect/openclaw-qqbot/node_modules/simple-yenc": {
+      "version": "1.0.4",
+      "inBundle": true,
+      "license": "MIT",
+      "funding": {
+        "type": "individual",
+        "url": "https://github.com/sponsors/eshaz"
+      }
+    },
+    "node_modules/@tencent-connect/openclaw-qqbot/node_modules/ws": {
+      "version": "8.19.0",
+      "inBundle": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
    "node_modules/@tinyhttp/content-disposition": {
      "version": "2.2.3",
      "resolved": "https://registry.npmjs.org/@tinyhttp/content-disposition/-/content-disposition-2.2.3.tgz",
--- a/package.json
+++ b/package.json
@@ -44,6 +44,7 @@
    "prepack": "npm install --omit=dev"
  },
  "dependencies": {
+    "@tencent-connect/openclaw-qqbot": "^1.5.6",
    "mpg123-decoder": "^1.0.3",
    "silk-wasm": "^3.7.1",
    "ws": "^8.18.0"
--- a/scripts/cleanup-legacy-plugins.sh
+++ b/scripts/cleanup-legacy-plugins.sh
@@ -1,11 +1,11 @@
 #!/bin/bash
-# QQBot 插件升级脚本
+# qqbot 插件升级脚本
 # 用于清理旧版本插件并重新安装
 # 兼容 clawdbot 和 openclaw 两种安装

 set -e

-echo "=== QQBot 插件升级脚本 ==="
+echo "=== qqbot 插件升级脚本 ==="

 # 检测使用的是 clawdbot 还是 openclaw
 detect_installation() {
@@ -123,5 +123,5 @@ echo ""
 echo "接下来请执行以下命令重新安装插件:"
 echo "  cd /path/to/openclaw-qqbot"
 echo "  $CMD plugins install ."
-echo "  $CMD channels add --channel qqbot --token \"AppID:AppSecret\""
+echo "  $CMD channels add --channel qqbot --token \"appid:appsecret\""
 echo "  $CMD gateway restart"
--- a/scripts/draw_arch.py
+++ b/scripts/draw_arch.py
@@ -1,174 +0,0 @@
-#!/usr/bin/env python3
-"""Generate QQBot + OpenClaw architecture diagram for product managers."""
-
-import matplotlib
-matplotlib.use('Agg')
-import matplotlib.pyplot as plt
-import matplotlib.patches as mpatches
-from matplotlib.patches import FancyBboxPatch, FancyArrowPatch
-import numpy as np
-
-# ── 中文字体 ──
-plt.rcParams['font.sans-serif'] = ['PingFang SC', 'Heiti SC', 'STHeiti', 'SimHei', 'Arial Unicode MS']
-plt.rcParams['axes.unicode_minus'] = False
-
-fig, ax = plt.subplots(1, 1, figsize=(20, 14))
-ax.set_xlim(0, 20)
-ax.set_ylim(0, 14)
-ax.axis('off')
-fig.patch.set_facecolor('#FAFBFC')
-
-# ── 颜色 ──
-C = {
-    'user':    '#4A90D9',
-    'qq':      '#12B7F5',
-    'plugin':  '#FF6B35',
-    'openclaw':'#6C5CE7',
-    'ai':      '#00B894',
-    'skill':   '#FDCB6E',
-    'white':   '#FFFFFF',
-    'text':    '#2D3436',
-    'light':   '#F0F0F5',
-    'border':  '#DFE6E9',
-}
-
-def rounded_box(x, y, w, h, color, label, sublabel=None, fontsize=13, icon=None, alpha=0.95):
-    box = FancyBboxPatch((x, y), w, h, boxstyle="round,pad=0.15",
-                         facecolor=color, edgecolor='white', linewidth=2, alpha=alpha, zorder=2)
-    ax.add_patch(box)
-    cy = y + h/2
-    if sublabel:
-        cy += 0.15
-    txt = f"{icon} {label}" if icon else label
-    ax.text(x + w/2, cy, txt, ha='center', va='center', fontsize=fontsize,
-            fontweight='bold', color='white' if color not in [C['white'], C['light'], C['skill']] else C['text'], zorder=3)
-    if sublabel:
-        ax.text(x + w/2, cy - 0.35, sublabel, ha='center', va='center', fontsize=9,
-                color='#ffffffbb' if color not in [C['white'], C['light'], C['skill']] else '#636e72', zorder=3)
-
-def section_box(x, y, w, h, color, label, fontsize=11):
-    box = FancyBboxPatch((x, y), w, h, boxstyle="round,pad=0.1",
-                         facecolor=color + '15', edgecolor=color, linewidth=1.5, linestyle='--', zorder=1)
-    ax.add_patch(box)
-    ax.text(x + 0.15, y + h - 0.25, label, ha='left', va='center', fontsize=fontsize,
-            fontweight='bold', color=color, zorder=3)
-
-def arrow(x1, y1, x2, y2, color='#636e72', style='->', label=None, lw=2):
-    ax.annotate('', xy=(x2, y2), xytext=(x1, y1),
-                arrowprops=dict(arrowstyle=style, color=color, lw=lw, connectionstyle="arc3,rad=0"),
-                zorder=4)
-    if label:
-        mx, my = (x1+x2)/2, (y1+y2)/2
-        ax.text(mx, my + 0.2, label, ha='center', va='center', fontsize=8, color=color,
-                bbox=dict(boxstyle='round,pad=0.2', facecolor='white', edgecolor='none', alpha=0.9), zorder=5)
-
-def double_arrow(x1, y1, x2, y2, color='#636e72', label=None, lw=2):
-    arrow(x1, y1, x2, y2, color=color, style='<->', label=label, lw=lw)
-
-# ══════════════════════════════════════════════
-# 标题
-# ══════════════════════════════════════════════
-ax.text(10, 13.5, 'OpenClaw QQBot 插件 · 系统架构', ha='center', va='center',
-        fontsize=22, fontweight='bold', color=C['text'])
-ax.text(10, 13.1, '让 AI 助手通过 QQ 与用户对话', ha='center', va='center',
-        fontsize=12, color='#636e72')
-
-# ══════════════════════════════════════════════
-# 第一层：用户侧
-# ══════════════════════════════════════════════
-rounded_box(1, 11.2, 2.5, 1.2, C['user'], '👤 QQ 用户', '私聊 / 群聊 / 频道', fontsize=14)
-rounded_box(5, 11.2, 2.5, 1.2, C['user'], '👥 QQ 群', '@ 机器人触发', fontsize=14)
-rounded_box(9, 11.2, 2.5, 1.2, C['user'], '📢 QQ 频道', '公域/私域频道', fontsize=14)
-
-# ══════════════════════════════════════════════
-# 第二层：QQ 平台
-# ══════════════════════════════════════════════
-section_box(0.5, 9, 12, 1.8, C['qq'], '')
-rounded_box(3, 9.3, 6, 1.2, C['qq'], '🐧 QQ 机器人平台', 'WebSocket 长连接 + HTTP API', fontsize=15)
-
-# 用户 → QQ 平台
-arrow(2.25, 11.2, 4.5, 10.5, C['qq'], label='发消息')
-arrow(6.25, 11.2, 6, 10.5, C['qq'])
-arrow(10.25, 11.2, 7.5, 10.5, C['qq'])
-
-# ══════════════════════════════════════════════
-# 第三层：QQBot 插件（核心）
-# ══════════════════════════════════════════════
-section_box(0.5, 5.2, 18.5, 3.5, C['plugin'], 'QQBot 渠道插件 (@tencent-connect/openclaw-qqbot)')
-
-# 左侧：网关
-rounded_box(1, 6.8, 3, 1.2, C['plugin'], '🔌 WebSocket 网关', '连接/心跳/重连/Resume', fontsize=11)
-# 中间：消息处理
-rounded_box(4.5, 6.8, 3.5, 1.2, C['plugin'], '📨 消息处理引擎', '收发/分块/限流/队列', fontsize=11)
-# 右侧：富媒体
-rounded_box(8.5, 6.8, 3, 1.2, C['plugin'], '🎨 富媒体处理', '图片/语音/视频/文件', fontsize=11)
-
-# 下排
-rounded_box(1, 5.5, 2.5, 1, '#E17055', '🔑 多账户管理', '独立Token/连接', fontsize=9)
-rounded_box(3.8, 5.5, 2.5, 1, '#E17055', '📢 主动消息', '推送/广播/定时', fontsize=9)
-rounded_box(6.6, 5.5, 2.5, 1, '#E17055', '🎙️ 语音处理', 'STT转文字/TTS合成', fontsize=9)
-rounded_box(9.4, 5.5, 2.5, 1, '#E17055', '🖼️ 本地图床', '自动上传/去重缓存', fontsize=9)
-
-# 右侧能力标签
-rounded_box(12.2, 7.5, 6.3, 1, C['skill'], '⭐ 核心能力', fontsize=12)
-capabilities = [
-    '✅ 私聊 / 群聊 / 频道 三场景',
-    '✅ 图片·语音·视频·文件 收发',
-    '✅ 语音转文字 (STT) + 文字转语音 (TTS)',
-    '✅ 多机器人同时在线',
-    '✅ 定时提醒 & 主动推送',
-    '✅ 断线自动重连 & Session 恢复',
-    '✅ 30+ 标签变体自动纠错',
-    '✅ 跨平台 Mac/Linux/Windows',
-]
-for i, cap in enumerate(capabilities):
-    ax.text(12.4, 7.2 - i * 0.28, cap, ha='left', va='center', fontsize=8.5,
-            color=C['text'], zorder=3)
-
-# QQ平台 → 插件
-double_arrow(6, 9.3, 6, 8.0, C['qq'], label='WebSocket', lw=2.5)
-
-# ══════════════════════════════════════════════
-# 第四层：OpenClaw 框架
-# ══════════════════════════════════════════════
-section_box(0.5, 1.5, 12, 3.4, C['openclaw'], 'OpenClaw AI 助手框架')
-
-rounded_box(1, 3.2, 2.8, 1.2, C['openclaw'], '🧠 对话管理', '上下文/多轮/记忆', fontsize=11)
-rounded_box(4.2, 3.2, 2.8, 1.2, C['openclaw'], '🔧 工具系统', 'Function Calling', fontsize=11)
-rounded_box(7.4, 3.2, 2.8, 1.2, C['openclaw'], '⏰ 定时任务', 'Cron 调度器', fontsize=11)
-
-rounded_box(1, 1.8, 3.5, 1.1, C['openclaw'], '📚 Skills 技能', 'qqbot-media / qqbot-cron', fontsize=10)
-rounded_box(5, 1.8, 3, 1.1, C['openclaw'], '🔌 插件系统', '渠道/工具插件', fontsize=10)
-rounded_box(8.5, 1.8, 3.5, 1.1, C['openclaw'], '⚙️ 配置管理', 'openclaw.json', fontsize=10)
-
-# 插件 → OpenClaw
-double_arrow(4, 5.5, 4, 4.4, C['openclaw'], label='消息桥接', lw=2.5)
-
-# ══════════════════════════════════════════════
-# 右侧：AI 模型层
-# ══════════════════════════════════════════════
-section_box(13, 1.5, 6, 3.4, C['ai'], 'AI 模型层（可替换）')
-
-rounded_box(13.5, 3.5, 5, 0.85, C['ai'], '🤖 Claude / GPT / DeepSeek / 混元 ...', fontsize=10)
-rounded_box(13.5, 2.5, 2.3, 0.8, '#00A884', '💬 对话', fontsize=10)
-rounded_box(16.2, 2.5, 2.3, 0.8, '#00A884', '🎨 画图', fontsize=10)
-rounded_box(13.5, 1.7, 2.3, 0.65, '#00A884', '🔍 搜索', fontsize=9)
-rounded_box(16.2, 1.7, 2.3, 0.65, '#00A884', '📝 写作', fontsize=9)
-
-# OpenClaw → AI
-double_arrow(10.3, 3.2, 13.5, 3.2, C['ai'], label='API 调用', lw=2.5)
-
-# ══════════════════════════════════════════════
-# 流程标注
-# ══════════════════════════════════════════════
-ax.text(10, 0.7, '💡 用户在 QQ 发消息 → QQBot 插件接收 → 交给 OpenClaw → AI 模型回复 → 通过 QQ 返回给用户',
-        ha='center', va='center', fontsize=11, color='#636e72', style='italic',
-        bbox=dict(boxstyle='round,pad=0.5', facecolor='#f8f9fa', edgecolor=C['border'], linewidth=1))
-
-ax.text(10, 0.2, 'v1.5.5 · @tencent-connect/openclaw-qqbot · MIT License',
-        ha='center', va='center', fontsize=9, color='#b2bec3')
-
-plt.tight_layout(pad=0.5)
-plt.savefig('/Users/lishoushuai/tmp/qqbot/docs/images/architecture.png', dpi=200, bbox_inches='tight',
-            facecolor='#FAFBFC', edgecolor='none')
-print("Architecture diagram saved to docs/images/architecture.png")
--- a/scripts/pull-latest.sh
+++ b/scripts/pull-latest.sh
@@ -1,316 +0,0 @@
-#!/bin/bash
-
-# QQBot 拉取最新源码并更新
-# 从 GitHub 拉取最新代码，安装依赖并重启网关
-# 兼容 clawdbot / openclaw / moltbot，macOS 开箱即用
-#
-# 用法:
-#   pull-latest.sh                          # 拉取最新代码并更新
-#   pull-latest.sh --branch main            # 指定分支（默认 main）
-#   pull-latest.sh --force                  # 跳过交互，强制更新
-#   pull-latest.sh --repo <git-url>         # 指定仓库地址
-
-set -euo pipefail
-
-##############################################################################
-# 常量 & 参数
-##############################################################################
-readonly DEFAULT_REPO="https://github.com/tencent-connect/openclaw-qqbot.git"
-readonly GATEWAY_PORT=18789
-readonly SUPPORTED_CLIS=(openclaw clawdbot moltbot)
-
-FORCE=false
-BRANCH="main"
-REPO_URL=""
-
-while [[ $# -gt 0 ]]; do
-    case "$1" in
-        -f|--force) FORCE=true; shift ;;
-        -b|--branch) BRANCH="$2"; shift 2 ;;
-        --repo) REPO_URL="$2"; shift 2 ;;
-        -h|--help)
-            echo "QQBot 拉取最新源码并更新"
-            echo ""
-            echo "用法:"
-            echo "  pull-latest.sh                          # 拉取最新代码并更新"
-            echo "  pull-latest.sh --branch main            # 指定分支（默认 main）"
-            echo "  pull-latest.sh --force                  # 跳过交互，强制更新"
-            echo "  pull-latest.sh --repo <git-url>         # 指定仓库地址"
-            exit 0
-            ;;
-        *)
-            echo "未知选项: $1 (使用 --help 查看帮助)"
-            exit 1
-            ;;
-    esac
-done
-REPO_URL="${REPO_URL:-$DEFAULT_REPO}"
-
-##############################################################################
-# 工具函数
-##############################################################################
-json_get() {
-    local file="$1" expr="$2"
-    node -e "process.stdout.write(String((function(){$expr})(JSON.parse(require('fs').readFileSync('$file','utf8')))||''))" 2>/dev/null || true
-}
-
-##############################################################################
-# 环境检查
-##############################################################################
-printf "%b\n" "\033[32m=========================================\033[0m"
-printf "%b\n" "\033[32m  QQBot 拉取最新源码并更新\033[0m"
-printf "%b\n" "\033[32m=========================================\033[0m"
-echo ""
-
-# 检查必要命令
-for dep in node npm git; do
-    if ! command -v "$dep" &>/dev/null; then
-        printf "%b\n" "\033[31m❌ 未检测到 $dep，请先安装\033[0m"
-        exit 1
-    fi
-done
-
-printf "%b\n" "\033[34m系统信息:\033[0m"
-echo "  macOS  $(sw_vers -productVersion 2>/dev/null || echo '未知')"
-echo "  Node   $(node -v)"
-echo "  npm    $(npm -v)"
-echo "  Git    $(git --version 2>/dev/null | awk '{print $3}')"
-echo "  仓库   $REPO_URL"
-echo "  分支   $BRANCH"
-
-# 检测 CLI
-CMD=""
-for name in "${SUPPORTED_CLIS[@]}"; do
-    if command -v "$name" &>/dev/null; then
-        CMD="$name"
-        break
-    fi
-done
-if [ -z "$CMD" ]; then
-    printf "%b\n" "\033[31m❌ 未找到 openclaw / clawdbot / moltbot 命令，请先安装其中之一\033[0m"
-    exit 1
-fi
-echo "  CLI    $CMD ($($CMD --version 2>/dev/null || echo '未知版本'))"
-
-APP_HOME="$HOME/.$CMD"
-APP_CONFIG="$APP_HOME/$CMD.json"
-
-##############################################################################
-# 定位插件目录
-##############################################################################
-PROJ_DIR=""
-FRESH_INSTALL=false
-
-for app in "${SUPPORTED_CLIS[@]}"; do
-    for plugin_dir in openclaw-qqbot qqbot openclaw-qq; do
-        ext_dir="$HOME/.$app/extensions/$plugin_dir"
-        if [ -d "$ext_dir" ] && [ -f "$ext_dir/package.json" ]; then
-            PROJ_DIR="$ext_dir"
-            break 2
-        fi
-    done
-done
-
-if [ -z "$PROJ_DIR" ]; then
-    PROJ_DIR="$APP_HOME/extensions/openclaw-qqbot"
-    FRESH_INSTALL=true
-    echo "  插件   未安装（首次安装）"
-else
-    echo "  插件   $PROJ_DIR"
-fi
-
-##############################################################################
-# 第一步：获取当前版本
-##############################################################################
-echo ""
-printf "%b\n" "\033[34m1. 获取当前版本...\033[0m"
-
-LOCAL_VER=""
-LOCAL_COMMIT=""
-if [ "$FRESH_INSTALL" = true ]; then
-    echo "  首次安装，无本地版本"
-else
-    [ -f "$PROJ_DIR/package.json" ] && LOCAL_VER=$(json_get "$PROJ_DIR/package.json" "c => c.version")
-    [ -d "$PROJ_DIR/.git" ] && LOCAL_COMMIT=$(cd "$PROJ_DIR" && git rev-parse --short HEAD 2>/dev/null || echo "")
-    echo "  当前版本: ${LOCAL_VER:-未知}${LOCAL_COMMIT:+ (${LOCAL_COMMIT})}"
-fi
-
-##############################################################################
-# 第二步：备份通道配置
-##############################################################################
-echo ""
-printf "%b\n" "\033[34m2. 备份通道配置...\033[0m"
-
-SAVED_CHANNELS_JSON=""
-for app in "${SUPPORTED_CLIS[@]}"; do
-    cfg="$HOME/.$app/$app.json"
-    [ -f "$cfg" ] || continue
-    SAVED_CHANNELS_JSON=$(node -e "
-        const cfg = JSON.parse(require('fs').readFileSync('$cfg', 'utf8'));
-        // 尝试所有可能的 channel key（原仓库 + 本仓库）
-        const keys = ['qqbot', 'openclaw-qqbot', 'openclaw-qq'];
-        for (const key of keys) {
-            const ch = cfg.channels && cfg.channels[key];
-            if (ch) { process.stdout.write(JSON.stringify(ch)); process.exit(0); }
-        }
-    " 2>/dev/null || true)
-    [ -n "$SAVED_CHANNELS_JSON" ] && break
-done
-
-if [ -n "$SAVED_CHANNELS_JSON" ]; then
-    echo "  ✅ 已备份 qqbot 通道配置"
-else
-    echo "  ℹ️  未找到已有通道配置"
-fi
-
-##############################################################################
-# 第三步：拉取最新代码
-##############################################################################
-echo ""
-printf "%b\n" "\033[34m3. 拉取最新代码...\033[0m"
-
-TMP_DIR="${TMPDIR:-/tmp}/qqbot-update-$$"
-cleanup() { rm -rf "$TMP_DIR" 2>/dev/null; }
-trap cleanup EXIT INT TERM
-
-if [ -d "$PROJ_DIR/.git" ] && [ "$FRESH_INSTALL" = false ]; then
-    cd "$PROJ_DIR"
-
-    # 有本地修改直接重置，插件目录不需要保留用户改动
-    if ! git diff --quiet 2>/dev/null || ! git diff --cached --quiet 2>/dev/null; then
-        echo "  检测到本地修改，自动重置..."
-        git checkout -- . 2>/dev/null
-        git clean -fd 2>/dev/null
-    fi
-
-    echo "  切换到分支 $BRANCH..."
-    git fetch --all --prune 2>&1 | tail -3
-    git checkout "$BRANCH" 2>/dev/null || git checkout -b "$BRANCH" "origin/$BRANCH" 2>/dev/null || true
-    git reset --hard "origin/$BRANCH" 2>/dev/null
-
-    REMOTE_COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo "")
-    NEW_VER=$(json_get "$PROJ_DIR/package.json" "c => c.version")
-
-    if [ -n "$LOCAL_COMMIT" ] && [ "$LOCAL_COMMIT" = "$REMOTE_COMMIT" ]; then
-        echo "  ✅ 已是最新 ($LOCAL_VER, commit: $LOCAL_COMMIT)，继续检查依赖..."
-    else
-        echo "  更新: ${LOCAL_COMMIT:-???} → ${REMOTE_COMMIT}"
-        git --no-pager log --oneline "${LOCAL_COMMIT}..HEAD" 2>/dev/null | head -10 || true
-    fi
-else
-    rm -rf "$TMP_DIR"
-    echo "  克隆仓库..."
-    if ! git clone --branch "$BRANCH" --depth 1 "$REPO_URL" "$TMP_DIR" 2>&1 | tail -3; then
-        printf "%b\n" "\033[31m❌ Git clone 失败\033[0m"
-        echo ""
-        echo "请排查:"
-        echo "  1. 检查网络: curl -I https://github.com"
-        echo "  2. 检查仓库地址: $REPO_URL"
-        echo "  3. 如果是私有仓库，确认已配置 SSH key 或 token"
-        exit 1
-    fi
-
-    mkdir -p "$PROJ_DIR"
-    rsync -a --delete --exclude 'node_modules' "$TMP_DIR/" "$PROJ_DIR/"
-
-    cd "$PROJ_DIR"
-    REMOTE_COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo "")
-    NEW_VER=$(json_get "$PROJ_DIR/package.json" "c => c.version")
-    echo "  已克隆到版本: ${NEW_VER:-未知} (${REMOTE_COMMIT})"
-    cleanup
-fi
-
-NEW_VER="${NEW_VER:-未知}"
-printf "%b\n" "\033[32m  ✅ 代码已更新到 $NEW_VER\033[0m"
-
-##############################################################################
-# 第四步：安装依赖
-##############################################################################
-echo ""
-printf "%b\n" "\033[34m4. 安装依赖...\033[0m"
-
-cd "$PROJ_DIR"
-if ! npm install --omit=dev 2>&1 | tail -5; then
-    printf "%b\n" "\033[31m❌ npm 依赖安装失败\033[0m"
-    echo ""
-    echo "请排查:"
-    echo "  1. 手动重试: cd $PROJ_DIR && npm install --omit=dev"
-    echo "  2. 清理后重试: rm -rf $PROJ_DIR/node_modules && npm install --omit=dev"
-    echo "  3. 切换镜像: npm config set registry https://registry.npmmirror.com/"
-    exit 1
-fi
-echo "  ✅ 依赖安装完成"
-
-##############################################################################
-# 第五步：恢复配置 → 重启网关
-##############################################################################
-echo ""
-printf "%b\n" "\033[34m5. 恢复配置并重启网关...\033[0m"
-
-# 恢复通道配置
-if [ -n "$SAVED_CHANNELS_JSON" ]; then
-    if node -e "
-        const fs = require('fs');
-        const cfg = JSON.parse(fs.readFileSync('$APP_CONFIG', 'utf8'));
-        cfg.channels = cfg.channels || {};
-        cfg.channels.qqbot = $SAVED_CHANNELS_JSON;
-        fs.writeFileSync('$APP_CONFIG', JSON.stringify(cfg, null, 4) + '\n');
-    " 2>/dev/null; then
-        echo "  ✅ 通道配置已恢复"
-    else
-        printf "%b\n" "\033[33m  ⚠️  通道配置写入失败，请手动检查: $APP_CONFIG\033[0m"
-    fi
-elif [ "$FRESH_INSTALL" = true ]; then
-    echo ""
-    printf "%b\n" "\033[33m  ⚠️  首次安装，请配置 QQ Bot 凭据:\033[0m"
-    echo "     $CMD channels add --channel qqbot --token 'YOUR_APPID:YOUR_SECRET'"
-    echo ""
-fi
-
-# 停止旧 gateway
-echo "  停止旧网关..."
-$CMD gateway stop 2>/dev/null || true
-sleep 1
-
-# 强制杀占用端口的进程
-PORT_PID=$(lsof -ti:"$GATEWAY_PORT" 2>/dev/null || true)
-if [ -n "$PORT_PID" ]; then
-    printf "%b\n" "\033[33m  ⚠️  端口 $GATEWAY_PORT 仍被占用 (PID: $PORT_PID)，强制终止...\033[0m"
-    kill -9 $PORT_PID 2>/dev/null || true
-    sleep 1
-fi
-
-# 卸载 launchd 服务（防止自动拉起旧进程）
-for svc in ai.openclaw.gateway ai.clawdbot.gateway ai.moltbot.gateway; do
-    launchctl bootout "gui/$(id -u)/$svc" 2>/dev/null || true
-done
-
-# 启动网关
-echo "  启动网关..."
-if $CMD gateway 2>&1; then
-    printf "%b\n" "\033[32m  ✅ 网关已启动\033[0m"
-else
-    echo ""
-    printf "%b\n" "\033[33m  ⚠️  网关启动失败（不影响已安装的插件）\033[0m"
-    echo ""
-    echo "  请手动启动:"
-    echo "    1. 安装服务: $CMD gateway install"
-    echo "    2. 启动网关: $CMD gateway"
-    echo "    3. 查看日志: $CMD logs --follow"
-fi
-
-##############################################################################
-# 完成
-##############################################################################
-echo ""
-printf "%b\n" "\033[32m=========================================\033[0m"
-printf "%b\n" "\033[32m  ✅ QQBot 已更新到 ${NEW_VER}${REMOTE_COMMIT:+ (${REMOTE_COMMIT})}\033[0m"
-[ -n "$LOCAL_VER" ] && printf "%b\n" "\033[32m     (从 ${LOCAL_VER}${LOCAL_COMMIT:+ (${LOCAL_COMMIT})} 升级)\033[0m"
-printf "%b\n" "\033[32m=========================================\033[0m"
-echo ""
-echo "常用命令:"
-echo "  $CMD logs --follow        # 跟踪日志"
-echo "  $CMD gateway restart      # 重启服务"
-echo "  $CMD plugins list         # 查看插件列表"
-echo "  cd $PROJ_DIR && git log   # 查看更新历史"
-echo "========================================="
--- a/scripts/set-markdown.sh
+++ b/scripts/set-markdown.sh
@@ -1,7 +1,7 @@
 #!/bin/bash

-# QQBot Markdown 配置脚本
-# 用于单独设置是否启用 Markdown 消息格式
+# qqbot markdown 配置脚本
+# 用于单独设置是否启用 markdown 消息格式
 # 直接编辑 JSON 配置文件，避免框架验证拒绝未注册的 channel

 set -e
@@ -29,18 +29,18 @@ show_help() {
    echo "用法: $0 [选项]"
    echo ""
    echo "选项:"
-    echo "  enable, on, yes      启用 Markdown 消息格式"
-    echo "  disable, off, no     禁用 Markdown 消息格式（使用纯文本）"
-    echo "  status               显示当前 Markdown 配置状态"
+    echo "  enable, on, yes      启用 markdown 消息格式"
+    echo "  disable, off, no     禁用 markdown 消息格式（使用纯文本）"
+    echo "  status               显示当前 markdown 配置状态"
    echo "  -h, --help           显示帮助信息"
    echo ""
    echo "示例:"
-    echo "  $0 enable            启用 Markdown"
-    echo "  $0 disable           禁用 Markdown"
+    echo "  $0 enable            启用 markdown"
+    echo "  $0 disable           禁用 markdown"
    echo "  $0 status            查看当前状态"
    echo "  $0                   交互式选择"
    echo ""
-    echo "⚠️  注意: 启用 Markdown 需要在 QQ 开放平台申请 Markdown 消息权限"
+    echo "⚠️  注意: 启用 markdown 需要在 QQ 开放平台申请 markdown 消息权限"
    echo "         如果没有权限，消息将无法正常发送！"
 }

@@ -57,22 +57,22 @@ set_markdown_value() {
 }

 enable_markdown() {
-    echo "✅ 启用 Markdown 消息格式..."
+    echo "✅ 启用 markdown 消息格式..."
    set_markdown_value true
    echo ""
-    echo "Markdown 已启用。"
-    echo "⚠️  请确保您已在 QQ 开放平台申请了 Markdown 消息权限。"
+    echo "markdown 已启用。"
+    echo "⚠️  请确保您已在 QQ 开放平台申请了 markdown 消息权限。"
 }

 disable_markdown() {
-    echo "❌ 禁用 Markdown 消息格式（使用纯文本）..."
+    echo "❌ 禁用 markdown 消息格式（使用纯文本）..."
    set_markdown_value false
    echo ""
-    echo "Markdown 已禁用，将使用纯文本格式发送消息。"
+    echo "markdown 已禁用，将使用纯文本格式发送消息。"
 }

 show_status() {
-    echo "当前 Markdown 配置状态:"
+    echo "当前 markdown 配置状态:"
    echo "  配置文件: $OPENCLAW_CONFIG"
    echo ""
    current=$(node -e "
@@ -82,7 +82,7 @@ show_status() {
    if [ "$current" = "true" ]; then
        echo "  状态: ✅ 已启用"
        echo ""
-        echo "  ⚠️  请确保您已在 QQ 开放平台申请了 Markdown 消息权限。"
+        echo "  ⚠️  请确保您已在 QQ 开放平台申请了 markdown 消息权限。"
    elif [ "$current" = "false" ]; then
        echo "  状态: ❌ 已禁用（纯文本模式）"
    else
@@ -92,20 +92,20 @@ show_status() {

 interactive_select() {
    echo "========================================="
-    echo "  QQBot Markdown 配置"
+    echo "  qqbot markdown 配置"
    echo "========================================="
    echo ""
    show_status
    echo ""
    echo "-----------------------------------------"
    echo ""
-    echo "是否启用 Markdown 消息格式？"
+    echo "是否启用 markdown 消息格式？"
    echo ""
-    echo "⚠️  注意: 启用 Markdown 需要在 QQ 开放平台申请 Markdown 消息权限"
+    echo "⚠️  注意: 启用 markdown 需要在 QQ 开放平台申请 markdown 消息权限"
    echo "         如果没有权限，消息将无法正常发送！"
    echo ""
-    echo "  1) 启用 Markdown"
-    echo "  2) 禁用 Markdown（纯文本）"
+    echo "  1) 启用 markdown"
+    echo "  2) 禁用 markdown（纯文本）"
    echo "  3) 取消"
    echo ""
    read -t 10 -p "请选择 [1-3] (默认: 2): " choice || choice="2"
--- a/scripts/upgrade-via-npm.sh
+++ b/scripts/upgrade-via-npm.sh
@@ -1,29 +1,62 @@
 #!/bin/bash

-# QQBot 通过 npm 包升级
+# qqbot 通过 npm 包升级
 #
 # 用法:
-#   npm-upgrade.sh                                    # 升级到 latest（默认）
-#   npm-upgrade.sh --tag alpha                        # 升级到 alpha
-#   npm-upgrade.sh --version 1.0.0-alpha.0            # 升级到指定版本
+#   upgrade-via-npm.sh                                    # 升级到 latest（默认）
+#   upgrade-via-npm.sh --version <version>                # 升级到指定版本
+#   upgrade-via-npm.sh --self-version                     # 升级到当前仓库 package.json 版本

 set -eo pipefail

 PKG_NAME="@tencent-connect/openclaw-qqbot"
 INSTALL_SRC=""
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+LOCAL_VERSION="$(node -e "
+  try {
+    const fs = require('fs');
+    const path = require('path');
+    const p = path.join('$PROJECT_DIR', 'package.json');
+    const v = JSON.parse(fs.readFileSync(p, 'utf8')).version;
+    if (v) process.stdout.write(String(v));
+  } catch {}
+" 2>/dev/null || true)"
+
+print_usage() {
+    echo "用法:"
+    echo "  upgrade-via-npm.sh                              # 升级到 latest（默认）"
+    echo "  upgrade-via-npm.sh --version <版本号>            # 升级到指定版本"
+    if [ -n "$LOCAL_VERSION" ]; then
+        echo "  upgrade-via-npm.sh --self-version               # 升级到当前仓库版本（$LOCAL_VERSION）"
+    else
+        echo "  upgrade-via-npm.sh --self-version               # 升级到当前仓库版本"
+    fi
+}

 while [[ $# -gt 0 ]]; do
    case "$1" in
-        --tag)     INSTALL_SRC="${PKG_NAME}@$2"; shift 2 ;;
-        --version) INSTALL_SRC="${PKG_NAME}@$2"; shift 2 ;;
+        --tag)
+            [ -z "$2" ] && echo "❌ --tag 需要参数" && exit 1
+            INSTALL_SRC="${PKG_NAME}@$2"
+            shift 2
+            ;;
+        --version)
+            [ -z "$2" ] && echo "❌ --version 需要参数" && exit 1
+            INSTALL_SRC="${PKG_NAME}@$2"
+            shift 2
+            ;;
+        --self-version)
+            [ -z "$LOCAL_VERSION" ] && echo "❌ 无法从 package.json 读取版本" && exit 1
+            INSTALL_SRC="${PKG_NAME}@${LOCAL_VERSION}"
+            shift 1
+            ;;
        -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       # 升级到指定版本"
+            print_usage
            exit 0
            ;;
-        *) echo "未知选项: $1"; exit 1 ;;
+        *) echo "未知选项: $1"; print_usage; exit 1 ;;
    esac
 done
 INSTALL_SRC="${INSTALL_SRC:-${PKG_NAME}@latest}"
@@ -39,7 +72,7 @@ APP_CONFIG="$HOME/.$CMD/$CMD.json"
 EXTENSIONS_DIR="$HOME/.$CMD/extensions"

 echo "==========================================="
-echo "  QQBot npm 升级: $INSTALL_SRC"
+echo "  qqbot npm 升级: $INSTALL_SRC"
 echo "==========================================="
 echo ""

--- a/scripts/upgrade-via-source.sh
+++ b/scripts/upgrade-via-source.sh
@@ -1,6 +1,6 @@
 #!/bin/bash

-# QQBot 一键更新并启动脚本
+# qqbot 一键更新并启动脚本
 # 版本: 2.0 (增强错误处理版)
 #
 # 主要改进:
@@ -44,20 +44,20 @@ while [[ $# -gt 0 ]]; do
            echo "用法: $0 [选项]"
            echo ""
            echo "选项:"
-            echo "  --appid <appid>       QQ机器人 AppID"
-            echo "  --secret <secret>     QQ机器人 Secret"
-            echo "  --markdown <yes|no>   是否启用 Markdown 消息格式（默认: no）"
+            echo "  --appid <appid>       QQ机器人 appid"
+            echo "  --secret <secret>     QQ机器人 secret"
+            echo "  --markdown <yes|no>   是否启用 markdown 消息格式（默认: no）"
            echo "  -h, --help            显示帮助信息"
            echo ""
            echo "也可以通过环境变量设置:"
-            echo "  QQBOT_APPID           QQ机器人 AppID"
-            echo "  QQBOT_SECRET          QQ机器人 Secret"
-            echo "  QQBOT_TOKEN           QQ机器人 Token (AppID:Secret)"
-            echo "  QQBOT_MARKDOWN        是否启用 Markdown（yes/no）"
+            echo "  QQBOT_APPID           QQ机器人 appid"
+            echo "  QQBOT_SECRET          QQ机器人 secret"
+            echo "  QQBOT_TOKEN           QQ机器人 token (appid:secret)"
+            echo "  QQBOT_MARKDOWN        是否启用 markdown（yes/no）"
            echo ""
            echo "不带参数时，将使用已有配置直接启动。"
            echo ""
-            echo "⚠️  注意: 启用 Markdown 需要在 QQ 开放平台申请 Markdown 消息权限"
+            echo "⚠️  注意: 启用 markdown 需要在 QQ 开放平台申请 markdown 消息权限"
            exit 0
            ;;
        *)
@@ -74,7 +74,7 @@ SECRET="${SECRET:-$QQBOT_SECRET}"
 MARKDOWN="${MARKDOWN:-$QQBOT_MARKDOWN}"

 echo "========================================="
-echo "  QQBot 一键更新启动脚本"
+echo "  qqbot 一键更新启动脚本"
 echo "========================================="

 # 1. 备份已有 qqbot 通道配置，防止升级过程丢失
@@ -134,19 +134,34 @@ fi
 # 2. 移除老版本
 echo ""
 echo "[2/6] 移除老版本..."
-if [ -f "$PROJ_DIR/scripts/upgrade.sh" ]; then
-    bash "$PROJ_DIR/scripts/upgrade.sh"
+if [ -f "$PROJ_DIR/scripts/cleanup-legacy-plugins.sh" ]; then
+    bash "$PROJ_DIR/scripts/cleanup-legacy-plugins.sh"
 else
-    echo "警告: upgrade.sh 不存在，跳过移除步骤"
+    echo "警告: cleanup-legacy-plugins.sh 不存在，跳过移除步骤"
 fi

 # 3. 安装当前版本
 echo ""
-echo "[3/6] 安装当前版本..."
+echo "[3/6] 安装当前版本（源码安装）..."

 echo "检查当前目录: $(pwd)"
 echo "检查openclaw版本: $(openclaw --version 2>/dev/null || echo 'openclaw not found')"

+LOCAL_PACKAGE_VERSION=$(node -e "
+  try {
+    const fs = require('fs');
+    const path = require('path');
+    const p = path.join('$PROJ_DIR', 'package.json');
+    const v = JSON.parse(fs.readFileSync(p, 'utf8')).version;
+    if (v) process.stdout.write(String(v));
+  } catch {}
+" 2>/dev/null || true)
+if [ -n "$LOCAL_PACKAGE_VERSION" ]; then
+    echo "即将安装本地源码版本: $LOCAL_PACKAGE_VERSION"
+else
+    echo "即将安装本地源码版本: unknown（未读取到 package.json version）"
+fi
+
 # 记录更新前的 qqbot 插件版本
 OLD_QQBOT_VERSION=$(node -e '
    try {
@@ -165,6 +180,7 @@ OLD_QQBOT_VERSION=$(node -e '
 ' 2>/dev/null || echo "not_installed")

 echo "开始安装插件..."
+echo "安装来源: 当前仓库源码（openclaw plugins install .）"
 INSTALL_LOG="/tmp/openclaw-install-$(date +%s).log"

 echo "安装日志文件: $INSTALL_LOG"
@@ -281,13 +297,13 @@ done
 DESIRED_QQBOT_TOKEN=""
 if [ -n "$APPID" ] && [ -n "$SECRET" ]; then
    DESIRED_QQBOT_TOKEN="${APPID}:${SECRET}"
-    echo "使用提供的 AppID 和 Secret 配置..."
+    echo "使用提供的 appid 和 secret 配置..."
 elif [ -n "$QQBOT_TOKEN" ]; then
    DESIRED_QQBOT_TOKEN="$QQBOT_TOKEN"
    echo "使用环境变量 QQBOT_TOKEN 配置..."
 elif [ -n "$SAVED_QQBOT_TOKEN" ]; then
    DESIRED_QQBOT_TOKEN="$SAVED_QQBOT_TOKEN"
-    echo "未提供 AppID/Secret，使用备份 token 恢复配置..."
+    echo "未提供 appid/secret，使用备份 token 恢复配置..."
 fi

 if [ -n "$DESIRED_QQBOT_TOKEN" ]; then
@@ -318,33 +334,33 @@ else
        echo ""
        echo "❌ 未检测到 qqbot 通道配置！"
        echo ""
-        echo "首次运行请提供 AppID 和 AppSecret："
+        echo "首次运行请提供 appid 和 appsecret："
        echo ""
-        echo "  bash $0 --appid <你的AppID> --secret <你的AppSecret>"
+        echo "  bash $0 --appid <你的appid> --secret <你的appsecret>"
        echo ""
        echo "也可以通过环境变量："
        echo ""
-        echo "  QQBOT_APPID=<AppID> QQBOT_SECRET=<AppSecret> bash $0"
+        echo "  QQBOT_APPID=<appid> QQBOT_SECRET=<appsecret> bash $0"
        echo ""
-        echo "AppID 和 AppSecret 可在 QQ 开放平台 (https://q.qq.com) 获取。"
+        echo "appid 和 appsecret 可在 QQ 开放平台 (https://q.qq.com) 获取。"
        exit 1
    else
        echo "使用已有配置"
    fi
 fi

-# 5. 配置 Markdown 选项（仅在明确指定时才配置）
+# 5. 配置 markdown 选项（仅在明确指定时才配置）
 echo ""
-echo "[5/6] 配置 Markdown 选项..."
+echo "[5/6] 配置 markdown 选项..."

 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 消息格式（使用纯文本）..."
+        echo "禁用 markdown 消息格式（使用纯文本）..."
    fi

    CURRENT_MARKDOWN_VALUE=$(node -e "
@@ -367,9 +383,9 @@ if [ -n "$MARKDOWN" ]; then
    " 2>/dev/null || true)

    if [ "$CURRENT_MARKDOWN_VALUE" = "$MARKDOWN_VALUE" ]; then
-        echo "✅ Markdown 配置已是目标值，跳过写入（避免配置覆盖提示）"
+        echo "✅ markdown 配置已是目标值，跳过写入（避免配置覆盖提示）"
    elif openclaw config set channels.qqbot.markdownSupport "$MARKDOWN_VALUE" 2>&1; then
-        echo "✅ Markdown配置成功"
+        echo "✅ markdown配置成功"
        _config_changed=1
    else
        echo "⚠️  openclaw config set 失败，尝试直接编辑配置文件..."
@@ -384,14 +400,14 @@ if [ -n "$MARKDOWN" ]; then
          cfg.channels.qqbot.markdownSupport = target;
          fs.writeFileSync('$OPENCLAW_CONFIG', JSON.stringify(cfg, null, 4) + '\n');
        " 2>&1; then
-            echo "✅ Markdown配置成功（直接编辑配置文件）"
+            echo "✅ markdown配置成功（直接编辑配置文件）"
            _config_changed=1
        else
-            echo "⚠️  Markdown配置设置失败，不影响后续运行"
+            echo "⚠️  markdown配置设置失败，不影响后续运行"
        fi
    fi
 else
-    echo "未指定 Markdown 选项，使用已有配置"
+    echo "未指定 markdown 选项，使用已有配置"
 fi

 # 6. 启动 openclaw
@@ -404,26 +420,26 @@ if ! command -v openclaw &> /dev/null; then
    echo "❌ 错误: openclaw 命令未找到！"
    echo ""
    echo "可能的原因:"
-    echo "1. OpenClaw未安装或安装失败"
+    echo "1. openclaw未安装或安装失败"
    echo "2. PATH环境变量未包含openclaw路径"
    echo "3. 需要重新登录或重启终端"
    echo ""
    exit 1
 fi

-echo "OpenClaw版本: $(openclaw --version 2>/dev/null || echo '未知')"
+echo "openclaw版本: $(openclaw --version 2>/dev/null || echo '未知')"

 # 显示 qqbot 插件更新信息
 NEW_QQBOT_VERSION="${NEW_QQBOT_VERSION:-unknown}"
 if [ "$OLD_QQBOT_VERSION" = "$NEW_QQBOT_VERSION" ]; then
-    echo "QQBot 插件版本: $NEW_QQBOT_VERSION (未变化)"
+    echo "qqbot 插件版本: $NEW_QQBOT_VERSION (未变化)"
 elif [ "$OLD_QQBOT_VERSION" = "not_installed" ]; then
-    echo "QQBot 插件版本: $NEW_QQBOT_VERSION (新安装)"
+    echo "qqbot 插件版本: $NEW_QQBOT_VERSION (新安装)"
 else
-    echo "QQBot 插件版本: $OLD_QQBOT_VERSION -> $NEW_QQBOT_VERSION"
+    echo "qqbot 插件版本: $OLD_QQBOT_VERSION -> $NEW_QQBOT_VERSION"
 fi
 echo ""
-read -t 120 -p "是否后台重启 OpenClaw 网关服务？[Y/n] " start_choice || start_choice="y"
+read -t 120 -p "是否后台重启 openclaw 网关服务？[Y/n] " start_choice || start_choice="y"
 start_choice="${start_choice:-y}"
 start_choice=$(printf '%s' "$start_choice" | tr '[:upper:]' '[:lower:]')

@@ -432,14 +448,14 @@ case "$start_choice" in
        echo ""
        # 不论配置是否变更，都显式 restart 一次，确保插件正确加载
        # （plugins install 触发的自动重启链已在第 3 步等待完成）
-        echo "正在后台重启 OpenClaw 网关服务..."
+        echo "正在后台重启 openclaw 网关服务..."
        if ! openclaw gateway restart 2>&1; then
            echo ""
            echo "⚠️  后台重启失败，可能服务未安装"
            echo "尝试: openclaw gateway install && openclaw gateway start"
        fi
        echo ""
-        echo "✅ OpenClaw 网关已在后台重启"
+        echo "✅ openclaw 网关已在后台重启"
        echo ""
        # 等待 gateway 端口就绪（插件安装+自动重启可能需要 30-60 秒）
        echo "等待 gateway 就绪（插件安装中，可能需要 30-60 秒）..."
@@ -462,8 +478,8 @@ case "$start_choice" in
        else
            echo "✅ Gateway 端口已就绪"
            echo ""
-            # 检查 QQBot WS 是否连接成功（最多等 30 秒）
-            echo "检查 QQBot 插件连接状态..."
+            # 检查 qqbot WS 是否连接成功（最多等 30 秒）
+            echo "检查 qqbot 插件连接状态..."
            _LOG_FILE="/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log"
            _qqbot_ready=0
            for _j in $(seq 1 15); do
@@ -473,17 +489,17 @@ case "$start_choice" in
                    _qqbot_ready=1
                    break
                fi
-                printf "\r  等待 QQBot WS 连接... (%d/15)" "$_j"
+                printf "\r  等待 qqbot WS 连接... (%d/15)" "$_j"
                sleep 2
            done
            echo ""

            if [ "$_qqbot_ready" -eq 0 ]; then
-                echo "⚠️  QQBot 插件可能未正确加载，尝试再次重启..."
+                echo "⚠️  qqbot 插件可能未正确加载，尝试再次重启..."
                openclaw gateway restart 2>&1 || true
                sleep 10
            else
-                echo "✅ QQBot 插件已连接"
+                echo "✅ qqbot 插件已连接"
            fi
            echo ""
            echo "正在跟踪日志输出（按 Ctrl+C 停止查看，不影响后台服务）..."
@@ -513,12 +529,12 @@ case "$start_choice" in
    *)
        echo "无效选择，按默认值 y 执行后台重启"
        echo ""
-        echo "正在后台重启 OpenClaw 网关服务..."
+        echo "正在后台重启 openclaw 网关服务..."
        if ! openclaw gateway restart 2>&1; then
            echo "⚠️  后台重启失败，可能服务未安装"
            echo "尝试: openclaw gateway install && openclaw gateway start"
        fi
-        echo "✅ OpenClaw 网关已在后台重启"
+        echo "✅ openclaw 网关已在后台重启"
        ;;
 esac