`、`＜qqimg＞` 等 30 多种变体写法）、上传缓存（短时间内相同文件自动复用）、有序队列发送（混合消息按顺序投递，单项失败不影响其他）、音频格式多层降级。
-
----
-
-## ⭐ Star History
-
-
-
-[](https://www.star-history.com/#tencent-connect/openclaw-qqbot&type=date&legend=top-left)
-
-
+> **底层细节：** 30+ 种标签变体自动纠正、上传去重缓存、有序队列发送、音频格式多层降级。
---
@@ -266,11 +206,13 @@ openclaw gateway
---
-## 🤖 多账户配置（Multi-Bot）
+## ⚙️ 进阶配置
+
+### 多账户配置（Multi-Bot）
支持在同一个 OpenClaw 实例下同时运行多个 QQ 机器人。
-### 配置方式
+#### 配置方式
编辑 `~/.openclaw/openclaw.json`，在 `channels.qqbot` 下增加 `accounts` 字段：
@@ -312,7 +254,7 @@ openclaw gateway
openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"
```
-### 向指定账户的用户发送消息
+#### 向指定账户的用户发送消息
使用 `openclaw message send` 发消息时，需要通过 `--account` 参数指定使用哪个机器人发送：
@@ -339,7 +281,7 @@ openclaw message send --channel "qqbot" \
> ⚠️ **注意**：每个机器人的用户 OpenID 是不同的。机器人 A 收到的用户 OpenID 不能用机器人 B 去发消息，否则会返回 500 错误。必须用对应机器人的 accountId 去给该机器人的用户发消息。
-### 工作原理
+#### 工作原理
- 启动 `openclaw gateway` 后，所有 `enabled: true` 的账户会同时启动 WebSocket 连接
- 每个账户独立维护 Token 缓存（基于 `appId` 隔离），互不干扰
@@ -347,9 +289,9 @@ openclaw message send --channel "qqbot" \
---
-## 🎙️ 语音能力配置（可选）
+### 语音能力配置（STT / TTS）
-### STT（语音转文字）— 自动转录用户发来的语音消息
+#### STT（语音转文字）— 自动转录用户发来的语音消息
STT 支持两级配置，按优先级查找：
@@ -375,7 +317,7 @@ STT 支持两级配置，按优先级查找：
- 设置 `enabled: false` 可禁用
- 配置后，用户发来的语音消息会自动转换（SILK→WAV）并转录为文字
-### TTS（文字转语音）— 机器人发送语音消息
+#### TTS（文字转语音）— 机器人发送语音消息
| 优先级 | 配置路径 | 作用域 |
|--------|----------|--------|
@@ -405,16 +347,7 @@ STT 支持两级配置，按优先级查找：
## 🔄 升级
-### 通过 OpenClaw / npm 升级
-
-> npm 包即将发布，届时可通过以下方式安装和升级：
->
-> ```bash
-> openclaw plugins install openclaw-qqbot@latest
-> openclaw plugins upgrade openclaw-qqbot@latest
-> ```
-
-### 通过 upgrade-and-run.sh 一键升级
+运行一键脚本即可升级并重启：
```bash
bash ./scripts/upgrade-and-run.sh
@@ -441,40 +374,17 @@ bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
-### 通过 pull-latest.sh（Git 源码更新）
-
-```bash
-bash ./scripts/pull-latest.sh
-```
-
-
-选项
-
-```bash
-bash ./scripts/pull-latest.sh --branch main # 指定分支（默认 main）
-bash ./scripts/pull-latest.sh --force # 跳过交互，强制更新
-bash ./scripts/pull-latest.sh --repo # 使用其他仓库地址
-```
-
-
-
-### 从源码升级
-
-```bash
-git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
-npm install --omit=dev
-bash ./scripts/upgrade.sh
-openclaw plugins install .
-openclaw channels add --channel qqbot --token "AppID:AppSecret"
-openclaw gateway restart
-```
-
---
-## 📚 文档
+## 📚 文档与链接
-- [富媒体指南](docs/qqbot-media-guide.md) — 详细的 STT/TTS 配置示例和标签用法
- [命令参考](docs/commands.md) — OpenClaw CLI 常用命令
-- [更新日志](docs/changelog/) — 各版本变更记录（[最新: 1.5.4](docs/changelog/1.5.4.md)）
+- [更新日志](CHANGELOG.md) — 各版本变更记录
+## ⭐ Star History
+
+
+[](https://www.star-history.com/#tencent-connect/openclaw-qqbot&type=date&legend=top-left)
+
+
diff --git a/docs/changelog/1.5.4.md b/docs/changelog/1.5.4.md
deleted file mode 100644
index 0eed74b..0000000
--- a/docs/changelog/1.5.4.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# 1.5.4
-
-## 中文
-
-### 🐛 修复
-
-- **修复多账户并发时 Token 串号问题**：将 `api.ts` 中的全局 Token 缓存（单变量）重构为按 `appId` 隔离的 `Map`，解决多个机器人同时运行时 Token 互相覆盖导致 `11255 invalid request` 报错的问题。
-- **Token 后台刷新支持多实例**：`clearTokenCache()` 和 `stopBackgroundTokenRefresh()` 改为接受 `appId` 参数，各账户独立管理。
-- **修复 `openclaw message send` 向非默认账户发消息失败**：未指定 `--account` 时 `accountId` 始终 fallback 为 `"default"`，导致用非默认机器人的 OpenID 发消息时 Token 与目标不匹配返回 500 错误。现已在文档中说明需通过 `--account` 参数指定目标机器人。
-
-### ✨ 新增
-
-- **多账户配置文档**：README 新增「多账户配置」章节，说明如何配置和使用多个 QQ 机器人。
-- **调试日志增强**：`channel.ts` 新增 `[qqbot:channel]` 前缀的详细日志，覆盖 account 解析、消息发送、网关启动全链路。
-- **API 日志前缀**：所有 API 请求日志加上 `[qqbot-api:${appId}]` 前缀，方便多实例排查。
-
----
-
-## English
-
-### 🐛 Fixes
-
-- **Fix Token collision in multi-account concurrent mode**: Refactored the global Token cache in `api.ts` from a single variable to a per-`appId` `Map`, resolving `11255 invalid request` errors caused by Token overwrite when multiple bots run simultaneously.
-- **Per-instance background Token refresh**: `clearTokenCache()` and `stopBackgroundTokenRefresh()` now accept an `appId` parameter for independent per-account management.
-- **Fix `openclaw message send` failing for non-default accounts**: Without `--account`, `accountId` always fell back to `"default"`, causing a 500 error when sending to an OpenID belonging to a different bot (Token/target mismatch). Documentation now clarifies that `--account` must be specified for non-default bots.
-
-### ✨ New
-
-- **Multi-account documentation**: Added "Multi-Account Setup" section to README, explaining how to configure and use multiple QQ bots.
-- **Enhanced debug logging**: Added detailed `[qqbot:channel]` prefixed logs in `channel.ts`, covering account resolution, message sending, and gateway startup.
-- **API log prefix**: All API request logs now include `[qqbot-api:${appId}]` prefix for easier multi-instance debugging.
diff --git a/docs/qqbot-media-guide.md b/docs/qqbot-media-guide.md
deleted file mode 100644
index d58b60b..0000000
--- a/docs/qqbot-media-guide.md
+++ /dev/null
@@ -1,174 +0,0 @@
-# OpenClaw QQ Bot 富媒体能力全解
-
-纯文字的 AI 聊天就像只能发消息的朋友——能聊天，但少了点温度。
-
-想象一下：你发一段语音它就能听懂，你丢一份文件它就能读完，它还能画图、发语音、传文件、甚至发视频给你——这才叫全能搭档。
-
-OpenClaw QQ Bot 插件为此提供了富媒体收发支持，覆盖图片、语音、视频、文件的双向交互。下面来看看实际效果 👇
-
-
----
-
-## AI 能接收什么
-
-用户发给 AI 的不只是文字——语音、文件、图片都能被理解。
-
-### 语音消息（STT）
-
-用户发的语音消息也能被 AI "听懂"。配置 STT 后，插件会自动将语音转录为文字再交给 AI 处理。
-
-STT 支持两级配置，按优先级查找：`channels.qqbot.stt`（插件专属） → `tools.media.audio.models[0]`（框架级回退）。以框架级配置为例：
-
-```json
-{
- "tools": {
- "media": {
- "audio": {
- "models": [
- { "provider": "openai", "model": "FunAudioLLM/SenseVoiceSmall" }
- ]
- }
- }
- }
-}
-```
-
-`provider` 引用 `models.providers` 中的 key，自动继承 `baseUrl` 和 `apiKey`，支持任何 OpenAI 兼容的 STT 接口。也可在条目中直接写 `baseUrl` / `apiKey` 覆盖。
-
-> **你**：（发送一段语音）"明天深圳天气怎么样"
->
-> **QQBot**：明天（3月7日 周六）深圳的天气预报 🌤️ ...
-
-整个过程对用户完全透明——发语音就像发文字一样自然，AI 听得懂你在说什么。
-
-
-
-
-### 文件
-
-用户发文件给 AI，AI 同样能接住。不管是一本小说还是一份报告，AI 会自动识别文件内容并给出智能回复：
-
-> **你**：（发送《战争与和平》TXT 文件）
->
-> **QQBot**：收到！你上传了列夫·托尔斯泰的《战争与和平》中文版文本。从内容来看，这是第一章的开头……你想让我做什么？
-
-
-
-### 图片
-
-如果主模型支持视觉（如腾讯混元 `hunyuan-vision`），用户发图片 AI 也能看懂。这是多模态模型的通用能力，非插件专属功能，主模型配置方式见 [README](../README.zh.md#步骤3-配置openclaw)。
-
-> **你**：（发送一张图片）
->
-> **QQBot**：哈哈，好可爱！这是QQ企鹅穿上小龙虾套装吗？🦞🐧 ...
-
-
-
----
-
-## AI 能发送什么
-
-AI 的回复不只是文字——图片、语音、文件、视频都能直接发出来。
-
-### 图片
-
-AI 在回复中写 `` 标签，系统自动上传发送。用户说"画个猫咪"，AI 就能调用绘图工具生成图片，直接发到对话里：
-
-> **你**：画一只猫咪
->
-> **QQBot**：`~/.openclaw/qqbot/images/cute-cat.png`
-
-本地文件路径和网络 URL 都行，支持 jpg/png/gif/webp/bmp。
-
-
-
-### 语音（TTS）
-
-配置 TTS 后，AI 可以把文字变成语音消息发出来。比如让它讲个笑话，回复直接就是一条语音。
-
-TTS 同样支持两级配置：`channels.qqbot.tts`（插件专属） → `messages.tts`（框架级回退）。以插件专属配置为例：
-
-```json
-{
- "channels": {
- "qqbot": {
- "tts": { "provider": "openai", "model": "FunAudioLLM/CosyVoice2-0.5B", "voice": "FunAudioLLM/CosyVoice2-0.5B:claire" }
- }
- }
-}
-```
-
-`provider` 引用 `models.providers` 中的 key，自动继承 `baseUrl` 和 `apiKey`。可通过 `voice` 选择音色，设置 `enabled: false` 可禁用。详细的多级配置说明见 [README](../README.zh.md#语音能力配置可选)。
-
-> **你**：用语音讲个笑话
->
-> **QQBot**：`~/.openclaw/qqbot/tts/joke.silk`
-
-支持 mp3/wav/silk/ogg 等常见音频格式，未安装 ffmpeg 也可正常使用。
-
-
-
-### 文件
-
-> **你**：战争与和平的第一章截取一下发文件给我
->
-> **QQBot**：`~/.openclaw/qqbot/downloads/战争与和平_第一章.txt`
-
-PDF、Excel、ZIP、TXT，什么格式都能发，最大 20MB。
-
-
-
-### 视频
-
-> **你**：发一个演示视频给我
->
-> **QQBot**：`~/.openclaw/qqbot/downloads/demo.mp4`
-
-支持本地文件路径和公网 URL，大文件（>5MB）会自动提示"正在上传..."。
-
-
-
----
-
-## 体验演示场景
-
-以下是几个可以直接复现的玩法：
-
-| 方向 | 你说 | AI 做 |
-|------|------|-------|
-| 接收语音 | 发送一段语音提问天气 | STT 自动转录，AI 理解后文字回复 |
-| 接收文件 | 发送一个文件给机器人 | AI 识别文件内容，智能分析回复 |
-| 发送图片 | "帮我画一只猫咪" | 调用绘图工具，生成图片发回 |
-| 发送语音 | "用语音讲个笑话" | TTS 生成语音，直接发送语音消息 |
-| 发送文件 | "帮我生成一个文件" | 生成文件并通过 `` 发送 |
-| 发送视频 | "发个视频给我" | 通过 `` 直接发送视频 |
-
----
-
-## 为什么体验这么丝滑？
-
-不是因为功能多，而是因为**细节做对了**：
-
-- **标签容错**：``、``、甚至中文尖括号 `＜qqimg＞` 等 30 多种变体写法均可自动纠正为标准标签
-- **上传缓存**：相同文件短时间内发给同一目标，自动复用上次的上传结果，避免重复传输
-- **有序发送**：一条消息里混着文字、图片、语音，系统自动拆解成队列按顺序发，某一项失败不影响其他
-- **分层降级**：音频格式转换会自动尝试多种方式，确保语音正常送达
-
-这些细节不会出现在功能列表里，但它们决定了实际使用时顺不顺手。
-
----
-
-## 快速回顾
-
-```
-接收 语音 → STT 自动转录，用户发语音 AI 就能懂
- 文件 → 自动下载识别内容
- 图片 → 需主模型支持视觉（非插件功能）
-
-发送 图片 → 标签，本地文件/URL 均可
- 语音 → 标签，TTS 合成或已有音频
- 文件 → 标签，任意格式最大 20MB
- 视频 → 标签，本地文件/URL
-```
-
-配置 STT/TTS 后语音双向打通，其余能力开箱即用。
-
-
-
-
-
-
-