github-mirrors/qqbot
1
0
Fork 0
mirror of https://mirror.skon.top/github.com/sliverp/qqbot synced 2026-04-30 13:50:24 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: optimize README structure, simplify showcase and upgrade sections

Browse Source
This commit is contained in:
rianli
2026-03-09 23:19:32 +08:00
parent 9b0d938312
commit 819fb24813
5 changed files with 124 additions and 486 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
CHANGELOG.md
View File

@@ -1,33 +1,57 @@
# Changelog
## 1.5.5 (2026-03-09)
All notable changes to this project will be documented in this file.
1. 修复插件 id 与 package name 不匹配导致插件加载失败的问题。
2. 修复 normalizeTarget 返回值类型，改为结构化 {ok, to, error} 对象。
3. 脚本全面兼容多 CLI（openclaw / clawdbot / moltbot），自动检测配置文件路径。
4. 修复 pull-latest.sh、upgrade.sh 中过时的仓库地址引用。
5. upgrade-and-run.sh 增加首次运行缺少 AppID/Secret 时的明确提示。
6. upgrade-and-run.sh 增加 qqbot 插件更新前后版本号展示。
7. 修复 proactive-api-server.ts / send-proactive.ts 中硬编码的配置文件路径。
8. 修复 set-markdown.sh 中 read 缺少超时导致非交互环境挂起的问题。
The format is based on [Keep a Changelog](https://keepachangelog.com/).
## 1.5.4 (2026-03-08)
## [1.5.5] - 2026-03-09
1. 修复多账户并发时 Token 串号问题，按 appId 隔离缓存。
2. Token 后台刷新支持多实例，各账户独立管理。
3. 修复 `openclaw message send` 向非默认账户发消息失败的问题。
4. 新增多账户配置文档及调试日志增强。
### Fixed
## 1.5.3 (2026-03-06)
- Fix plugin id not matching package name, causing plugin load failure.
- Fix `normalizeTarget` return type — now returns structured `{ok, to, error}` object.
- Fix outdated repo URL references in `pull-latest.sh` and `upgrade.sh`.
- Fix `proactive-api-server.ts` / `send-proactive.ts` hardcoded config file paths.
- Fix `set-markdown.sh` `read` missing timeout causing hang in non-interactive environments.
1. 优化富媒体标签解析功能逻辑，提升识别成功率。
2. 解决了文件乱码，特殊路径问题。导致文件无法发送的问题。
3. 解决了偶现消息seq重复导致消息丢失问题。
4. 优化升级脚本功能：升级过程中自动备份并恢复 qqbot 通道配置；
5. 升级readme.md 增加富媒体消息使用说明及插件配置、升级教程。
### Improved
## 1.5.2 (2026-03-05)
- 新增语音/文件发送能力，支持 TTS 文字转语音
- 富媒体增强：上传缓存、视频支持、失败自动重试
- Markdown 消息默认开启
- 升级脚本独立化，支持用户选择启动方式（前台/后台）
- Scripts now fully compatible with multiple CLIs (openclaw / clawdbot / moltbot) with auto-detection of config file paths.
- `upgrade-and-run.sh` now shows clear prompt when AppID/Secret is missing on first run.
- `upgrade-and-run.sh` now displays qqbot plugin version before and after upgrade.
## [1.5.4] - 2026-03-08
### Fixed
- Fix Token collision in multi-account concurrent mode — refactored global Token cache from a single variable to a per-`appId` `Map`, resolving `11255 invalid request` errors 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.
### Added
- Multi-account documentation — added "Multi-Account Setup" section to README.
- Enhanced debug logging — `[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.
## [1.5.3] - 2026-03-06
### Fixed
- Improved rich media tag parsing logic for higher recognition success rate.
- Fixed file encoding issues and special path handling that prevented file sending.
- Fixed intermittent message loss caused by duplicate message seq numbers.
### Improved
- Upgrade script now auto-backs up and restores qqbot channel config during upgrades.
- Updated README with rich media usage instructions and plugin config/upgrade tutorial.
## [1.5.2] - 2026-03-05
### Added
- Voice/file sending capability with TTS text-to-speech support.
- Rich media enhancements: upload caching, video support, automatic retry on failure.
- Markdown messages enabled by default.
- Standalone upgrade script with user choice of foreground/background startup.

167
README.md
View File

@@ -47,8 +47,7 @@ Scan to join the QQ group chat
> **Note:** This plugin serves as a **message channel** only — it relays messages between QQ and OpenClaw. Capabilities like image understanding, voice transcription, drawing, etc. depend on the **AI model** you configure and the **skills** installed in OpenClaw, not on this plugin itself.
<details>
<summary><b>🎙️ Voice Messages (STT)</b> — AI understands voice messages, auto-transcribes speech to text</summary>
### 🎙️ Voice Messages (STT)
With STT configured, the plugin automatically transcribes voice messages to text before passing them to AI. The whole process is transparent to the user — sending voice feels as natural as sending text.
@@ -58,10 +57,7 @@ With STT configured, the plugin automatically transcribes voice messages to text
<img width="360" src="docs/images/fc7b2236896cfba3a37c94be5d59ce3e_720.jpg" alt="Voice STT Demo" />
</details>
<details>
<summary><b>📄 File Understanding</b> — Send any file, AI reads and understands it</summary>
### 📄 File Understanding
Send any file to the bot — novels, reports, spreadsheets — AI automatically recognizes the content and gives an intelligent reply.
@@ -71,10 +67,7 @@ Send any file to the bot — novels, reports, spreadsheets — AI automatically
<img width="360" src="docs/images/07bff56ab68e03173d2af586eeb3bcee_720.jpg" alt="File Understanding Demo" />
</details>
<details>
<summary><b>🖼️ Image Understanding</b> — Vision-capable models can see and describe images</summary>
### 🖼️ Image Understanding
If your main model supports vision (e.g. Tencent Hunyuan `hunyuan-vision`), AI can understand images too. This is a general multimodal capability, not plugin-specific.
@@ -84,110 +77,57 @@ If your main model supports vision (e.g. Tencent Hunyuan `hunyuan-vision`), AI c
<img width="360" src="docs/images/59d421891f813b0d3c0cbe12574b6a72_720.jpg" alt="Image Understanding Demo" />
</details>
<details>
<summary><b>🎨 Image Generation</b> — Ask the bot to draw, it sends the result back</summary>
### 🎨 Image Generation
> **You**: Draw me a cat
>
> **QQBot**: Here you go! 🐱
AI uses the `<qqimg>` tag to send images. Both local file paths and URLs are supported. Formats: jpg/png/gif/webp/bmp.
```
<qqimg>~/.openclaw/qqbot/images/cute-cat.png</qqimg>
```
AI sends images via `<qqimg>path</qqimg>`. Supports local paths and URLs. Formats: jpg/png/gif/webp/bmp.
<img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="Image Generation Demo" />
</details>
<details>
<summary><b>🔊 Voice Reply (TTS)</b> — Bot replies with voice messages</summary>
### 🔊 Voice Reply (TTS)
> **You**: Tell me a joke in voice
>
> **QQBot**: *(sends a voice message)*
AI uses the `<qqvoice>` tag to send voice messages. Formats: mp3/wav/silk/ogg. Works without ffmpeg.
```
<qqvoice>~/.openclaw/qqbot/tts/joke.silk</qqvoice>
```
AI sends voice via `<qqvoice>path</qqvoice>`. Formats: mp3/wav/silk/ogg. No ffmpeg required.
<img width="360" src="docs/images/21dce8bfc553ce23d1bd1b270e9c516c.jpg" alt="TTS Voice Demo" />
</details>
<details>
<summary><b>📎 File Sending</b> — Generate and send files of any format (up to 20MB)</summary>
### 📎 File Sending
> **You**: Extract chapter 1 of War and Peace and send it as a file
>
> **QQBot**: *(sends a .txt file)*
AI uses the `<qqfile>` tag to send files. PDF, Excel, ZIP, TXT — any format, up to 20MB.
```
<qqfile>~/.openclaw/qqbot/downloads/war-and-peace-ch1.txt</qqfile>
```
AI sends files via `<qqfile>path</qqfile>`. Any format, up to 20MB.
<img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="File Sending Demo" />
</details>
<details>
<summary><b>🎬 Video Sending</b> — Send videos, large files auto-show upload progress</summary>
### 🎬 Video Sending
> **You**: Send me a demo video
>
> **QQBot**: *(sends a video)*
AI uses the `<qqvideo>` tag to send videos. Both local files and URLs are supported. Large files (>5MB) auto-show "uploading..." status.
```
<qqvideo>~/.openclaw/qqbot/downloads/demo.mp4</qqvideo>
```
AI sends videos via `<qqvideo>path</qqvideo>`. Supports local files and URLs. Large files (>5MB) auto-show upload progress.
<img width="360" src="docs/images/85d03b8a216f267ab7b2aee248a18a41_720.jpg" alt="Video Sending Demo" />
</details>
### Rich Media Tag Reference
| Tag | Direction | Usage | Notes |
|-----|-----------|-------|-------|
| `<qqimg>path</qqimg>` | Send | Image | Local path or URL, jpg/png/gif/webp/bmp |
| `<qqvoice>path</qqvoice>` | Send | Voice | mp3/wav/silk/ogg, no ffmpeg required |
| `<qqfile>path</qqfile>` | Send | File | Any format, up to 20MB |
| `<qqvideo>path</qqvideo>` | Send | Video | Local path or URL |
| Voice message | Receive | STT | Auto-transcribe with configured STT model |
| File attachment | Receive | File | Auto-download and feed content to AI |
| Image attachment | Receive | Vision | Requires vision-capable model |
| Tag | Direction | Notes |
|-----|-----------|-------|
| `<qqimg>path</qqimg>` | Send | jpg/png/gif/webp/bmp, local path or URL |
| `<qqvoice>path</qqvoice>` | Send | mp3/wav/silk/ogg, no ffmpeg required |
| `<qqfile>path</qqfile>` | Send | Any format, up to 20MB |
| `<qqvideo>path</qqvideo>` | Send | Local path or URL |
| Voice / File / Image | Receive | Auto-transcribe (STT), auto-download, or vision analysis |
### Try It Yourself
| Direction | You say | AI does |
|-----------|---------|---------|
| Receive voice | Send a voice message asking about weather | STT auto-transcribes, AI replies with text |
| Receive file | Send a file to the bot | AI reads file content, gives intelligent reply |
| Send image | "Draw me a cat" | Calls drawing tool, sends image back |
| Send voice | "Tell me a joke in voice" | TTS generates voice, sends voice message |
| Send file | "Generate a file for me" | Creates file, sends via `<qqfile>` |
| Send video | "Send me a video" | Sends video via `<qqvideo>` |
**Under the hood:** Tag variant auto-correction (30+ variants like `<qq_img>`, `<image>`, `＜qqimg＞` are all recognized), upload caching (dedup within short windows), ordered queue delivery, and multi-layer audio format fallback.
---
## ⭐ Star History
<div align="center">
[![Star History Chart](https://api.star-history.com/svg?repos=tencent-connect/openclaw-qqbot&type=date&legend=top-left)](https://www.star-history.com/#tencent-connect/openclaw-qqbot&type=date&legend=top-left)
</div>
> **Under the hood:** 30+ tag variant auto-correction, upload dedup caching, ordered queue delivery, and multi-layer audio format fallback.
---
@@ -195,7 +135,7 @@ AI uses the `<qqvideo>` tag to send videos. Both local files and URLs are suppor
### Step 1 — Create a QQ Bot on the QQ Open Platform
1. Go to the [QQ Open Platform](https://q.qq.com/) and **scan the QR code with your phone QQ** to register / log in. If you haven't registered before, scanning will automatically complete the registration and bindyour QQ account.
1. Go to the [QQ Open Platform](https://q.qq.com/) and **scan the QR code with your phone QQ** to register / log in. If you haven't registered before, scanning will automatically complete the registration and bind your QQ account.
<img width="3246" height="1886" alt="Clipboard_Screenshot_1772980354" src="https://github.com/user-attachments/assets/d8491859-57e8-47e4-9d39-b21138be54d0" />
@@ -208,7 +148,6 @@ AI uses the `<qqvideo>` tag to send videos. Both local files and URLs are suppor
<img width="1670" height="1036" alt="Clipboard_Screenshot_1772980413" src="https://github.com/user-attachments/assets/b898d171-5711-4d42-bc07-2de967b119ec" />
> For a step-by-step walkthrough with screenshots, see the [official guide](https://cloud.tencent.com/developer/article/2626045).
> ⚠️ The bot will automatically appear in your QQ message list and send a first message. However, it will reply "The bot has gone to Mars" until you complete the configuration steps below.
@@ -270,11 +209,13 @@ Open QQ, find your bot, and send a message!
---
## 🤖 Multi-Account Setup (Multi-Bot)
## ⚙️ Advanced Configuration
### Multi-Account Setup (Multi-Bot)
Run multiple QQ bots under a single OpenClaw instance.
### Configuration
#### Configuration
Edit `~/.openclaw/openclaw.json` and add an `accounts` field under `channels.qqbot`:
@@ -316,7 +257,7 @@ Add a second bot via CLI (if the framework supports the `--account` parameter):
openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"
```
### Sending Messages to a Specific Account's Users
#### Sending Messages to a Specific Account's Users
When using `openclaw message send`, specify which bot to use with the `--account` parameter:
@@ -343,7 +284,7 @@ openclaw message send --channel "qqbot" \
> ⚠️ **Important**: Each bot has its own set of user OpenIDs. An OpenID received by Bot A **cannot** be used to send messages via Bot B — this will result in a 500 error. Always use the matching bot's `accountId` to send messages to its users.
### How It Works
#### How It Works
- When `openclaw gateway` starts, all accounts with `enabled: true` launch their own WebSocket connections
- Each account maintains an independent Token cache (isolated by `appId`), preventing cross-contamination
@@ -351,9 +292,9 @@ openclaw message send --channel "qqbot" \
---
## 🎙️ Voice Configuration (Optional)
### Voice Configuration (STT / TTS)
### STT (Speech-to-Text) — Transcribe Incoming Voice Messages
#### STT (Speech-to-Text) — Transcribe Incoming Voice Messages
STT supports two-level configuration with priority fallback:
@@ -379,7 +320,7 @@ STT supports two-level configuration with priority fallback:
- Set `enabled: false` to disable
- When configured, incoming voice messages are automatically converted (SILK→WAV) and transcribed
### TTS (Text-to-Speech) — Send Voice Messages
#### TTS (Text-to-Speech) — Send Voice Messages
| Priority | Config Path | Scope |
|----------|------------|-------|
@@ -409,16 +350,7 @@ STT supports two-level configuration with priority fallback:
## 🔄 Upgrade
### Via OpenClaw / npm
> npm package coming soon. Once published, you can install and upgrade via:
>
> ```bash
> openclaw plugins install openclaw-qqbot@latest
> openclaw plugins upgrade openclaw-qqbot@latest
> ```
### Via upgrade-and-run.sh (One-Click)
Run the one-click script to upgrade and restart:
```bash
bash ./scripts/upgrade-and-run.sh
@@ -445,40 +377,17 @@ Environment variables `QQBOT_APPID`, `QQBOT_SECRET`, `QQBOT_TOKEN` (AppID:Secret
</details>
### Via pull-latest.sh (Git Source)
```bash
bash ./scripts/pull-latest.sh
```
<details>
<summary>Options</summary>
```bash
bash ./scripts/pull-latest.sh --branch main # specify branch (default: main)
bash ./scripts/pull-latest.sh --force # skip prompts, force update
bash ./scripts/pull-latest.sh --repo <git-url> # use a different repo
```
</details>
### From Source
```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
```
---
## 📚 Documentation
## 📚 Documentation & Links
- [Rich Media Guide](docs/qqbot-media-guide.md) — detailed STT/TTS config examples and tag usage
- [Command Reference](docs/commands.md) — OpenClaw CLI commands
- [Changelog](docs/changelog/) — release notes ([latest: 1.5.4](docs/changelog/1.5.4.md))
- [Changelog](CHANGELOG.md) — release notes
## ⭐ Star History
<div align="center">
[![Star History Chart](https://api.star-history.com/svg?repos=tencent-connect/openclaw-qqbot&type=date&legend=top-left)](https://www.star-history.com/#tencent-connect/openclaw-qqbot&type=date&legend=top-left)
</div>

164
README.zh.md
View File

@@ -44,8 +44,7 @@
> **说明：** 本插件仅作为**消息通道**，负责在 QQ 和 OpenClaw 之间传递消息。图片理解、语音转录、AI 画图等能力取决于你配置的 **AI 模型**以及在 OpenClaw 中安装的 **skill**，而非插件本身提供。
<details>
<summary><b>🎙️ 语音消息（STT）</b> — 配置 STT 后，自动将语音转录为文字理解</summary>
### 🎙️ 语音消息（STT）
配置 STT 后，插件会自动将语音转录为文字再交给 AI 处理。整个过程对用户完全透明——发语音就像发文字一样自然，AI 听得懂你在说什么。
@@ -55,10 +54,7 @@
<img width="360" src="docs/images/fc7b2236896cfba3a37c94be5d59ce3e_720.jpg" alt="听语音演示" />
</details>
<details>
<summary><b>📄 文件理解</b> — 发文件给 AI，自动识别内容并智能回复</summary>
### 📄 文件理解
用户发文件给 AI，AI 同样能接住。不管是一本小说还是一份报告，AI 会自动识别文件内容并给出智能回复。
@@ -68,10 +64,7 @@
<img width="360" src="docs/images/07bff56ab68e03173d2af586eeb3bcee_720.jpg" alt="AI理解用户发送的文件" />
</details>
<details>
<summary><b>🖼️ 图片理解</b> — 主模型支持视觉能力时，发图片 AI 也能看懂</summary>
### 🖼️ 图片理解
如果主模型支持视觉（如腾讯混元 `hunyuan-vision`），用户发图片 AI 也能看懂。这是多模态模型的通用能力，非插件专属功能。
@@ -81,110 +74,57 @@
<img width="360" src="docs/images/59d421891f813b0d3c0cbe12574b6a72_720.jpg" alt="图片理解演示" />
</details>
<details>
<summary><b>🎨 AI 画图</b> — 调用绘图工具生成图片，直接发到对话里</summary>
### 🎨 AI 画图
> **你**：画一只猫咪
>
> **QQBot**：给你画好了！🐱
AI 通过 `<qqimg>` 标签发送图片，支持本地文件路径和网络 URL。格式：jpg/png/gif/webp/bmp。
```
<qqimg>~/.openclaw/qqbot/images/cute-cat.png</qqimg>
```
AI 通过 `<qqimg>路径</qqimg>` 发送图片，支持本地文件路径和网络 URL。格式：jpg/png/gif/webp/bmp。
<img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="发图片演示" />
</details>
<details>
<summary><b>🔊 语音回复（TTS）</b> — AI 把文字变成语音消息发出来</summary>
### 🔊 语音回复（TTS）
> **你**：用语音讲个笑话
>
> **QQBot**：*（发送一条语音消息）*
AI 通过 `<qqvoice>` 标签发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg。
```
<qqvoice>~/.openclaw/qqbot/tts/joke.silk</qqvoice>
```
AI 通过 `<qqvoice>路径</qqvoice>` 发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg。
<img width="360" src="docs/images/21dce8bfc553ce23d1bd1b270e9c516c.jpg" alt="发语音演示" />
</details>
<details>
<summary><b>📎 文件发送</b> — 生成并发送任意格式文件，最大 20MB</summary>
### 📎 文件发送
> **你**：战争与和平的第一章截取一下发文件给我
>
> **QQBot**：*（发送 .txt 文件）*
AI 通过 `<qqfile>` 标签发送文件。PDF、Excel、ZIP、TXT，什么格式都能发，最大 20MB。
```
<qqfile>~/.openclaw/qqbot/downloads/战争与和平_第一章.txt</qqfile>
```
AI 通过 `<qqfile>路径</qqfile>` 发送文件。任意格式，最大 20MB。
<img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="发文件演示" />
</details>
<details>
<summary><b>🎬 视频发送</b> — 支持本地文件和公网 URL，大文件自动显示上传进度</summary>
### 🎬 视频发送
> **你**：发一个演示视频给我
>
> **QQBot**：*（发送视频）*
AI 通过 `<qqvideo>` 标签发送视频，支持本地文件和公网 URL。大文件（>5MB）自动提示"正在上传..."。
```
<qqvideo>~/.openclaw/qqbot/downloads/demo.mp4</qqvideo>
```
AI 通过 `<qqvideo>路径</qqvideo>` 发送视频，支持本地文件和公网 URL。大文件（>5MB）自动提示上传进度。
<img width="360" src="docs/images/85d03b8a216f267ab7b2aee248a18a41_720.jpg" alt="发视频演示" />
</details>
### 富媒体标签参考
| 标签 | 方向 | 用途 | 说明 |
|------|------|------|------|
| `<qqimg>路径</qqimg>` | 发送 | 图片 | 本地路径或 URL，jpg/png/gif/webp/bmp |
| `<qqvoice>路径</qqvoice>` | 发送 | 语音 | mp3/wav/silk/ogg，无需 ffmpeg |
| `<qqfile>路径</qqfile>` | 发送 | 文件 | 任意格式，最大 20MB |
| `<qqvideo>路径</qqvideo>` | 发送 | 视频 | 本地路径或 URL |
| 语音消息 | 接收 | STT | 自动转录，需配置 STT 模型 |
| 文件附件 | 接收 | 文件 | 自动下载并将内容交给 AI |
| 图片附件 | 接收 | 视觉 | 需主模型支持视觉能力 |
| 标签 | 方向 | 说明 |
|------|------|------|
| `<qqimg>路径</qqimg>` | 发送 | jpg/png/gif/webp/bmp，本地路径或 URL |
| `<qqvoice>路径</qqvoice>` | 发送 | mp3/wav/silk/ogg，无需 ffmpeg |
| `<qqfile>路径</qqfile>` | 发送 | 任意格式，最大 20MB |
| `<qqvideo>路径</qqvideo>` | 发送 | 本地路径或 URL |
| 语音 / 文件 / 图片 | 接收 | 自动转录(STT)、自动下载、或视觉分析 |
### 体验演示场景
| 方向 | 你说 | AI 做 |
|------|------|-------|
| 接收语音 | 发送一段语音提问天气 | STT 自动转录，AI 理解后文字回复 |
| 接收文件 | 发送一个文件给机器人 | AI 识别文件内容，智能分析回复 |
| 发送图片 | "帮我画一只猫咪" | 调用绘图工具，生成图片发回 |
| 发送语音 | "用语音讲个笑话" | TTS 生成语音，直接发送语音消息 |
| 发送文件 | "帮我生成一个文件" | 生成文件并通过 `<qqfile>` 发送 |
| 发送视频 | "发个视频给我" | 通过 `<qqvideo>` 直接发送视频 |
**底层细节：** 标签容错（自动纠正 `<qq_img>`、`<image>`、`＜qqimg＞` 等 30 多种变体写法）、上传缓存（短时间内相同文件自动复用）、有序队列发送（混合消息按顺序投递，单项失败不影响其他）、音频格式多层降级。
---
## ⭐ Star History
<div align="center">
[![Star History Chart](https://api.star-history.com/svg?repos=tencent-connect/openclaw-qqbot&type=date&legend=top-left)](https://www.star-history.com/#tencent-connect/openclaw-qqbot&type=date&legend=top-left)
</div>
> **底层细节：** 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
</details>
### 通过 pull-latest.sh（Git 源码更新）
```bash
bash ./scripts/pull-latest.sh
```
<details>
<summary>选项</summary>
```bash
bash ./scripts/pull-latest.sh --branch main # 指定分支（默认 main）
bash ./scripts/pull-latest.sh --force # 跳过交互，强制更新
bash ./scripts/pull-latest.sh --repo <git-url> # 使用其他仓库地址
```
</details>
### 从源码升级
```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
<div align="center">
[![Star History Chart](https://api.star-history.com/svg?repos=tencent-connect/openclaw-qqbot&type=date&legend=top-left)](https://www.star-history.com/#tencent-connect/openclaw-qqbot&type=date&legend=top-left)
</div>

31
docs/changelog/1.5.4.md
View File

@@ -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.

174
docs/qqbot-media-guide.md
View File

@@ -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 听得懂你在说什么。
![听语音演示](images/fc7b2236896cfba3a37c94be5d59ce3e_720.jpg)
### 文件
用户发文件给 AI，AI 同样能接住。不管是一本小说还是一份报告，AI 会自动识别文件内容并给出智能回复：
> **你**：（发送《战争与和平》TXT 文件）
>
> **QQBot**：收到！你上传了列夫·托尔斯泰的《战争与和平》中文版文本。从内容来看，这是第一章的开头……你想让我做什么？
![AI理解用户发送的文件](images/07bff56ab68e03173d2af586eeb3bcee_720.jpg)
### 图片
如果主模型支持视觉（如腾讯混元 `hunyuan-vision`），用户发图片 AI 也能看懂。这是多模态模型的通用能力，非插件专属功能，主模型配置方式见 [README](../README.zh.md#步骤3-配置openclaw)。
> **你**：（发送一张图片）
>
> **QQBot**：哈哈，好可爱！这是QQ企鹅穿上小龙虾套装吗？🦞🐧 ...
![图片理解演示](images/59d421891f813b0d3c0cbe12574b6a72_720.jpg)
---
## AI 能发送什么
AI 的回复不只是文字——图片、语音、文件、视频都能直接发出来。
### 图片
AI 在回复中写 `<qqimg>` 标签，系统自动上传发送。用户说"画个猫咪"，AI 就能调用绘图工具生成图片，直接发到对话里：
> **你**：画一只猫咪
>
> **QQBot**：`<qqimg>~/.openclaw/qqbot/images/cute-cat.png</qqimg>`
本地文件路径和网络 URL 都行，支持 jpg/png/gif/webp/bmp。
![发图片演示](images/4645f2b3a20822b7f8d6664a708529eb_720.jpg)
### 语音（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**：`<qqvoice>~/.openclaw/qqbot/tts/joke.silk</qqvoice>`
支持 mp3/wav/silk/ogg 等常见音频格式，未安装 ffmpeg 也可正常使用。
![发语音演示](images/21dce8bfc553ce23d1bd1b270e9c516c.jpg)
### 文件
> **你**：战争与和平的第一章截取一下发文件给我
>
> **QQBot**：`<qqfile>~/.openclaw/qqbot/downloads/战争与和平_第一章.txt</qqfile>`
PDF、Excel、ZIP、TXT，什么格式都能发，最大 20MB。
![发文件演示](images/17cada70df90185d45a2d6dd36e92f2f_720.jpg)
### 视频
> **你**：发一个演示视频给我
>
> **QQBot**：`<qqvideo>~/.openclaw/qqbot/downloads/demo.mp4</qqvideo>`
支持本地文件路径和公网 URL，大文件（>5MB）会自动提示"正在上传..."。
![发视频演示](images/85d03b8a216f267ab7b2aee248a18a41_720.jpg)
---
## 体验演示场景
以下是几个可以直接复现的玩法：
| 方向 | 你说 | AI 做 |
|------|------|-------|
| 接收语音 | 发送一段语音提问天气 | STT 自动转录，AI 理解后文字回复 |
| 接收文件 | 发送一个文件给机器人 | AI 识别文件内容，智能分析回复 |
| 发送图片 | "帮我画一只猫咪" | 调用绘图工具，生成图片发回 |
| 发送语音 | "用语音讲个笑话" | TTS 生成语音，直接发送语音消息 |
| 发送文件 | "帮我生成一个文件" | 生成文件并通过 `<qqfile>` 发送 |
| 发送视频 | "发个视频给我" | 通过 `<qqvideo>` 直接发送视频 |
---
## 为什么体验这么丝滑？
不是因为功能多，而是因为**细节做对了**：
- **标签容错**：`<qq_img>`、`<image>`、甚至中文尖括号 `＜qqimg＞` 等 30 多种变体写法均可自动纠正为标准标签
- **上传缓存**：相同文件短时间内发给同一目标，自动复用上次的上传结果，避免重复传输
- **有序发送**：一条消息里混着文字、图片、语音，系统自动拆解成队列按顺序发，某一项失败不影响其他
- **分层降级**：音频格式转换会自动尝试多种方式，确保语音正常送达
这些细节不会出现在功能列表里，但它们决定了实际使用时顺不顺手。
---
## 快速回顾
```
接收 语音 → STT 自动转录，用户发语音 AI 就能懂
文件 → 自动下载识别内容
图片 → 需主模型支持视觉（非插件功能）
发送 图片 → <qqimg> 标签，本地文件/URL 均可
语音 → <qqvoice> 标签，TTS 合成或已有音频
文件 → <qqfile> 标签，任意格式最大 20MB
视频 → <qqvideo> 标签，本地文件/URL
```
配置 STT/TTS 后语音双向打通，其余能力开箱即用。