@cxyhhhhh/openclaw-qqbot 1.6.7-alpha.1 → 1.7.1-dev.202606041635

package/README.md

@@ -10,7 +10,7 @@
 
 **Connect your AI assistant to QQ — private chat, group chat, and rich media, all in one plugin.**
 
-### 🚀 Current Version: `v1.6.5`
+### 🚀 Current Version: `v1.7.1`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
@@ -25,7 +25,7 @@
 
 Scan to join the QQ group chat
 
-<img width="400" alt="QQ QR Code" src="./docs/images/developer_group.png" />
+<img width="400" alt="QQ QR Code" src="./docs/images/developer-group.png" />
 
 
 </div>
@@ -37,6 +37,7 @@ Scan to join the QQ group chat
 | Feature | Description |
 |---------|-------------|
 | 🔒 **Multi-Scene** | C2C private chat, group @messages |
+| 🌐 **Dual Transport** | WebSocket (default) or Webhook (HTTP callback) — switch via config |
 | 🖼️ **Rich Media** | Send & receive images, voice, video, and files |
 | 🎙️ **Voice (STT/TTS)** | Speech-to-text transcription & text-to-speech replies |
 | 🔥 **One-Click Hot Upgrade** | Send `/bot-upgrade` in private chat to upgrade — no server login needed |
@@ -45,7 +46,9 @@ Scan to join the QQ group chat
 | ⌨️ **Typing Indicator** | "Bot is typing..." status shown in real-time |
 | 📝 **Markdown** | Full Markdown formatting support |
 | 🛠️ **Commands** | Native OpenClaw command integration |
-| 💬 **Quoted Context** | Resolve QQ `REFIDX_*` quoted messages and inject quote body into AI context |
+| 💬 **Quoted Context** | Parses the original message a user is replying to and injects it into AI context, so the model always knows exactly which message is being referenced |
+| 📦 **Large File Support** | Auto chunked upload for large files (parallel upload with retry), up to 100 MB |
+| 🔐 **Command Execution Approval** | AI requests approval via Inline Keyboard buttons before executing commands — tap to allow or deny |
 
 ---
 
@@ -53,15 +56,11 @@ 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.
 
-### 💬 Quoted Message Context (REFIDX)
+### 💬 Quoted Message Context
 
-QQ quote events carry index keys (e.g. `REFIDX_xxx`) instead of full original message body. The plugin now resolves these indices from a local persistent store and injects quote context into AI input, so replies better understand “which message is being quoted”.
+When a user quotes a message in QQ, the plugin automatically parses the quoted message content and injects it into the AI context, so the model clearly knows "which message the user is replying to" and gives more accurate responses. Supports text and media messages (image/voice/video/file), and works across devices.
 
-- Inbound and outbound messages with `ref_idx` are automatically indexed.
-- Store path: `~/.openclaw/qqbot/data/ref-index.jsonl` (survives gateway restart).
-- Quote body may include text + media summary (image/voice/video/file).
-
-<img width="360" src="docs/images/ref_msg.png" alt="Quoted Message Context Demo" />
+<img width="360" src="docs/images/ref-msg.png" alt="Quoted Message Context Demo" />
 
 ### 🎙️ Voice Messages (STT)
 
@@ -71,7 +70,7 @@ With STT configured, the plugin automatically transcribes voice messages to text
 >
 > **QQBot**: Tomorrow (March 7, Saturday) Shenzhen weather forecast 🌤️ ...
 
-<img width="360" src="docs/images/fc7b2236896cfba3a37c94be5d59ce3e_720.jpg" alt="Voice STT Demo" />
+<img width="360" src="docs/images/voice-stt.jpg" alt="Voice STT Demo" />
 
 ### 📄 File Understanding
 
@@ -81,7 +80,7 @@ Send any file to the bot — novels, reports, spreadsheets — AI automatically
 >
 > **QQBot**: Got it! You uploaded the Chinese version of "War and Peace" by Leo Tolstoy. This appears to be the opening of Chapter 1...
 
-<img width="360" src="docs/images/07bff56ab68e03173d2af586eeb3bcee_720.jpg" alt="File Understanding Demo" />
+<img width="360" src="docs/images/file-understand.jpg" alt="File Understanding Demo" />
 
 ### 🖼️ Image Understanding
 
@@ -91,7 +90,7 @@ If your main model supports vision (e.g. Tencent Hunyuan `hunyuan-vision`), AI c
 >
 > **QQBot**: Haha, so cute! Is that a QQ penguin in a lobster costume? 🦞🐧 ...
 
-<img width="360" src="docs/images/59d421891f813b0d3c0cbe12574b6a72_720.jpg" alt="Image Understanding Demo" />
+<img width="360" src="docs/images/image-understand.jpg" alt="Image Understanding Demo" />
 
 ### 🎨 Image Sending
 
@@ -101,7 +100,7 @@ If your main model supports vision (e.g. Tencent Hunyuan `hunyuan-vision`), AI c
 
 AI can send images directly. Supports local paths and URLs. Formats: jpg/png/gif/webp/bmp.
 
-<img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="Image Generation Demo" />
+<img width="360" src="docs/images/image-send.jpg" alt="Image Generation Demo" />
 
 ### 🔊 Voice Sending
 
@@ -111,7 +110,7 @@ AI can send images directly. Supports local paths and URLs. Formats: jpg/png/gif
 
 AI can send voice messages directly. Formats: mp3/wav/silk/ogg. No ffmpeg required.
 
-<img width="360" src="docs/images/21dce8bfc553ce23d1bd1b270e9c516c.jpg" alt="TTS Voice Demo" />
+<img width="360" src="docs/images/voice-send.jpg" alt="TTS Voice Demo" />
 
 ### ⏰ Scheduled Reminder (Proactive Message)
 
@@ -129,9 +128,21 @@ This capability depends on OpenClaw cron scheduling and proactive messaging. If
 >
 > **QQBot**: *(sends a .txt file)*
 
-AI can send files directly. Any format, up to 20MB.
+AI can send files directly, in any format.
+
+<img width="360" src="docs/images/file-send.jpg" alt="File Sending Demo" />
+
+Since v1.6.6, large file transfer is supported: images up to 20MB, videos up to 30MB, attachments up to 100MB, with a daily transfer limit of 2GB.
+
+<img width="360" src="docs/images/large-file-transfer.jpg" alt="Large File Transfer Demo" />
+
+### 🔐 Command Execution Approval
 
-<img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="File Sending Demo" />
+When the AI needs to execute a command, the plugin sends an approval request via QQ message with interactive buttons — tap **✅ Allow Once**, **⭐ Always Allow**, or **❌ Deny** to control whether the command runs. 
+
+Use the `/bot-approve` command to manage the approval mode (allowlist / off / strict).
+
+<img width="360" src="docs/images/approve.png" alt="Command Execution Approval Demo" />
 
 ### 🎬 Video Sending
 
@@ -141,7 +152,7 @@ AI can send files directly. Any format, up to 20MB.
 
 AI can send videos directly. Supports local files and URLs.
 
-<img width="360" src="docs/images/85d03b8a216f267ab7b2aee248a18a41_720.jpg" alt="Video Sending Demo" />
+<img width="360" src="docs/images/video-send.jpg" alt="Video Sending Demo" />
 
 > **Under the hood:** Upload dedup caching, ordered queue delivery, and multi-layer audio format fallback.
 
@@ -187,6 +198,11 @@ Credentials are automatically backed up before upgrade. Version existence is ver
 
 > ⚠️ Hot upgrade is currently not supported on Windows. Sending `/bot-upgrade` on Windows will return a manual upgrade guide instead.
 
+> ⚠️ v1.6.6 and below do not support hot upgrade via `/bot-upgrade`. Please upgrade using the following command:
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
+> ```
+
 <img width="360" src="docs/images/hot-update.jpg" alt="Hot Upgrade Demo" />
 
 #### `/bot-logs` — Log Export
@@ -207,6 +223,26 @@ All commands support a `?` suffix to show usage:
 >
 > **QQBot**: 📖 /bot-upgrade usage: …
 
+#### `/bot-approve` — Approval Configuration
+
+> **You**: `/bot-approve`
+>
+> **QQBot**: 🔐 Command Execution Approval — Enable / Disable / Strict mode / Reset / View current config
+
+Manage the AI command execution approval policy. Supported subcommands:
+
+| Subcommand | Description |
+|------------|-------------|
+| `/bot-approve on` | Enable approval (allowlist mode, recommended) |
+| `/bot-approve off` | Disable approval — commands execute directly |
+| `/bot-approve always` | Strict mode — every execution requires approval |
+| `/bot-approve reset` | Restore framework defaults |
+| `/bot-approve status` | View current approval config |
+
+#### `/bot-clear-storage` — Clear files generated through QQBot conversations and downloaded resources (stored on the host running OpenClaw)
+
+`/bot-clear-storage` lists files generated by the conversation and files in the downloaded resources directory. Use `/bot-clear-storage --force` to confirm deletion.
+
 ---
 
 ## 🚀 Getting Started
@@ -220,15 +256,15 @@ All commands support a `?` suffix to show usage:
 2. After scanning, tap **Agree** on your phone — you'll land on the bot configuration page.
 3. Click **Create Bot** to create a new QQ bot.
 
-<img width="720" alt="Create Bot" src="docs/images/create_robot.png" />
+<img width="720" alt="Create Bot" src="docs/images/create-robot.png" />
 
 > ⚠️ 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.
 
-<img width="400" alt="Bot Say Hello" src="docs/images/bot_say_hello.jpg" />
+<img width="400" alt="Bot Say Hello" src="docs/images/bot-say-hello.jpg" />
 
 4. Find **AppID** and **AppSecret** on the bot's page, click **Copy** for each, and save them somewhere safe (e.g., a notepad). **AppSecret is not stored in plaintext — if you leave the page without saving it, you'll have to regenerate a new one.**
 
-<img width="720" alt="Find AppID and AppSecret" src="docs/images/find_appid_secret.png" />
+<img width="720" alt="Find AppID and AppSecret" src="docs/images/find-appid-secret.png" />
 
 > For a step-by-step walkthrough with screenshots, see the [official guide](https://cloud.tencent.com/developer/article/2626045).
 
@@ -243,7 +279,7 @@ curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main
 
 One command does it all: download script → cleanup old plugins → install → configure channel → restart service. Once done, open QQ and start chatting!
 
-> `--appid` and `--secret` are **required for first-time install**. For subsequent upgrades:
+> `--appid` and `--secret` are **required for first-time install**. For subsequent upgrades, run the following command to upgrade to the latest version:
 > ```bash
 > curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
 > ```
@@ -373,12 +409,56 @@ openclaw message send --channel "qqbot" \
 
 #### How It Works
 
-- When `openclaw gateway` starts, all accounts with `enabled: true` launch their own WebSocket connections
+- When `openclaw gateway` starts, all accounts with `enabled: true` launch their own connections (WebSocket or Webhook depending on `transport` config)
 - Each account maintains an independent Token cache (isolated by `appId`), preventing cross-contamination
 - Incoming message logs are prefixed with `[qqbot:accountId]` for easy debugging
 
 ---
 
+### Webhook Transport Mode
+
+By default, the plugin connects to QQ via **WebSocket** (outbound connection, no public IP required). You can switch to **Webhook** mode where QQ platform POSTs events to your HTTP endpoint.
+
+| | WebSocket (default) | Webhook |
+|---|---|---|
+| Connection | Plugin connects to QQ gateway | QQ platform POSTs to your server |
+| Public IP | Not required | Required |
+| Use case | Development, single instance | Production, horizontal scaling, Serverless |
+| Session resume | Supported (RESUME) | Stateless, no resume needed |
+| Signature | Built-in | Ed25519 auto-verified by plugin |
+
+#### Configuration
+
+```json
+{
+  "channels": {
+    "qqbot": {
+      "appId": "111111111",
+      "clientSecret": "your-secret",
+      "transport": "webhook",
+      "webhook": {
+        "path": "/qqbot/webhook"
+      }
+    }
+  }
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `transport` | `"websocket"` | `"websocket"` or `"webhook"` |
+| `webhook.path` | `"/qqbot/webhook"` | HTTP path for receiving callbacks |
+
+#### Platform Setup
+
+1. Go to [QQ Open Platform](https://q.qq.com/) → Bot Settings → Message Receiving
+2. Select **HTTP Callback**
+3. Enter your callback URL: `https://your-domain.com/qqbot/webhook`
+4. The platform sends an `op:13` validation request — the plugin handles it automatically
+5. Once validated, all events will be POSTed to your endpoint
+
+---
+
 ### Voice Configuration (STT / TTS)
 
 #### STT (Speech-to-Text) — Transcribe Incoming Voice Messages
@@ -458,7 +538,7 @@ Special thanks to [@sliverp](https://github.com/sliverp) for outstanding contrib
 Thanks to [Tencent Cloud Lighthouse](https://cloud.tencent.com/product/lighthouse) for the deep collaboration. For raising crawfish, choose Tencent Cloud Lighthouse!
 
 <a href="https://cloud.tencent.com/product/lighthouse">
-  <img alt="Tencent Cloud Lighthouse" src="./docs/images/lighthouse_head.png" height="500" style="max-width:80%; height:auto;"/>
+  <img alt="Tencent Cloud Lighthouse" src="./docs/images/lighthouse-head.png" height="500" style="max-width:80%; height:auto;"/>
 </a>
 
 ## ⭐ Star History

package/README.zh.md

@@ -9,7 +9,7 @@
 
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
-### 🚀 当前版本： `v1.6.5`
+### 🚀 当前版本： `v1.7.1`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
@@ -21,7 +21,7 @@
 
 扫描二维码加入群聊，一起交流
 
-<img width="400" alt="QQ 群二维码" src="./docs/images/developer_group.png" />
+<img width="400" alt="QQ 群二维码" src="./docs/images/developer-group.png" />
 
 </div>
 
@@ -32,6 +32,7 @@
 | 功能 | 说明 |
 |------|------|
 | 🔒 **多场景支持** | C2C 私聊、群聊 @消息 |
+| 🌐 **双传输模式** | WebSocket（默认）或 Webhook（HTTP 回调）— 配置切换 |
 | 🖼️ **富媒体消息** | 支持图片、语音、视频、文件的收发 |
 | 🎙️ **语音能力 (STT/TTS)** | 语音转文字自动转录 & 文字转语音回复 |
 | 🔥 **一键热更新** | 私聊发送 `/bot-upgrade` 即可完成版本升级，无需登录服务器 |
@@ -40,7 +41,9 @@
 | ⌨️ **输入状态** | 实时显示"Bot 正在输入中…"状态 |
 | 📝 **Markdown** | 完整支持 Markdown 格式消息 |
 | 🛠️ **原生命令** | 支持 OpenClaw 原生命令 |
-| 💬 **引用上下文** | 解析 QQ `REFIDX_*` 引用消息，并将引用内容注入 AI 上下文 |
+| 💬 **引用上下文** | 解析用户回复的原始消息内容，注入 AI 上下文，让模型准确理解"在回复哪条消息" |
+| 📦 **大文件支持** | 大文件自动分片并行上传，最大支持 100 MB |
+| 🔐 **命令执行审批** | AI 执行命令前通过按钮消息请求审批，点击即可允许或拒绝 |
 
 ---
 
@@ -48,15 +51,11 @@
 
 > **说明：** 本插件仅作为**消息通道**，负责在 QQ 和 OpenClaw 之间传递消息。图片理解、语音转录、AI 画图等能力取决于你配置的 **AI 模型**以及在 OpenClaw 中安装的 **skill**，而非插件本身提供。
 
-### 💬 引用消息上下文（REFIDX）
+### 💬 引用消息上下文
 
-QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返回原始消息全文。插件已支持从本地持久化索引中解析引用内容，并注入 AI 上下文，帮助模型更准确理解“用户引用的是哪条消息”。
+用户在 QQ 中引用某条消息发送时，插件会自动解析被引用的消息内容并注入 AI 上下文，让模型清楚地知道"用户在回复哪条消息"，从而给出更准确的回复。支持文本及媒体消息（图片/语音/视频/文件），换设备后同样可用。
 
-- 入站/出站消息中的 `ref_idx` 会自动建立索引。
-- 存储位置：`~/.openclaw/qqbot/data/ref-index.jsonl`（网关重启后仍可恢复）。
-- 引用内容支持文本 + 媒体摘要（图片/语音/视频/文件）。
-
-<img width="360" src="docs/images/ref_msg.png" alt="引用消息上下文演示" />
+<img width="360" src="docs/images/ref-msg.png" alt="引用消息上下文演示" />
 
 ### 🎙️ 语音消息（STT）
 
@@ -66,7 +65,7 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 >
 > **QQBot**：明天（3月7日 周六）深圳的天气预报 🌤️ ...
 
-<img width="360" src="docs/images/fc7b2236896cfba3a37c94be5d59ce3e_720.jpg" alt="听语音演示" />
+<img width="360" src="docs/images/voice-stt.jpg" alt="听语音演示" />
 
 ### 📄 文件理解
 
@@ -76,7 +75,7 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 >
 > **QQBot**：收到！你上传了列夫·托尔斯泰的《战争与和平》中文版文本。从内容来看，这是第一章的开头……你想让我做什么？
 
-<img width="360" src="docs/images/07bff56ab68e03173d2af586eeb3bcee_720.jpg" alt="AI理解用户发送的文件" />
+<img width="360" src="docs/images/file-understand.jpg" alt="AI理解用户发送的文件" />
 
 ### 🖼️ 图片理解
 
@@ -86,7 +85,7 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 >
 > **QQBot**：哈哈，好可爱！这是QQ企鹅穿上小龙虾套装吗？🦞🐧 ...
 
-<img width="360" src="docs/images/59d421891f813b0d3c0cbe12574b6a72_720.jpg" alt="图片理解演示" />
+<img width="360" src="docs/images/image-understand.jpg" alt="图片理解演示" />
 
 ### 🎨 图片发送
 
@@ -96,7 +95,7 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 
 AI 可直接发送图片，支持本地文件路径和网络 URL。格式：jpg/png/gif/webp/bmp。
 
-<img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="发图片演示" />
+<img width="360" src="docs/images/image-send.jpg" alt="发图片演示" />
 
 ### 🔊 语音发送
 
@@ -106,7 +105,7 @@ AI 可直接发送图片，支持本地文件路径和网络 URL。格式：jpg/
 
 AI 可直接发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg。
 
-<img width="360" src="docs/images/21dce8bfc553ce23d1bd1b270e9c516c.jpg" alt="发语音演示" />
+<img width="360" src="docs/images/voice-send.jpg" alt="发语音演示" />
 
 ### ⏰ 定时提醒（主动消息）
 
@@ -124,9 +123,21 @@ AI 可直接发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg
 >
 > **QQBot**：*（发送 .txt 文件）*
 
-AI 可直接发送文件。任意格式，最大 20MB。
+AI 可直接发送文件，任意格式均可。
+
+<img width="360" src="docs/images/file-send.jpg" alt="发文件演示" />
+
+v1.6.6 起支持大文件传输：图片最大 20MB，视频最大 30MB，附件最大 100MB，每日累计传输上限 2GB。
+
+<img width="360" src="docs/images/large-file-transfer.jpg" alt="大文件传输演示" />
+
+### 🔐 命令执行审批
 
-<img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="发文件演示" />
+当 AI 需要执行命令时，插件会通过 QQ 消息发送带按钮的审批请求，你可以点击 **✅ 允许一次**、**⭐ 始终允许** 或 **❌ 拒绝** 来控制命令是否执行。
+
+通过 `/bot-approve` 指令可以管理审批模式（白名单 / 关闭 / 严格模式）。
+
+<img width="360" src="docs/images/approve.png" alt="命令执行审批演示" />
 
 ### 🎬 视频发送
 
@@ -136,7 +147,7 @@ AI 可直接发送文件。任意格式，最大 20MB。
 
 AI 可直接发送视频，支持本地文件和公网 URL。
 
-<img width="360" src="docs/images/85d03b8a216f267ab7b2aee248a18a41_720.jpg" alt="发视频演示" />
+<img width="360" src="docs/images/video-send.jpg" alt="发视频演示" />
 
 > **底层细节：** 上传去重缓存、有序队列发送、音频格式多层降级。
 
@@ -182,6 +193,11 @@ AI 可直接发送视频，支持本地文件和公网 URL。
 
 > ⚠️ 热更新指令暂不支持 Windows 系统，在 Windows 上发送 `/bot-upgrade` 会返回手动升级指引。
 
+> ⚠️ v1.6.6 及以下版本暂不支持通过 `/bot-upgrade` 执行热更新，请通过以下命令升级：
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
+> ```
+
 <img width="360" src="docs/images/hot-update.jpg" alt="一键热更新演示" />
 
 #### `/bot-logs` — 日志导出
@@ -202,6 +218,26 @@ AI 可直接发送视频，支持本地文件和公网 URL。
 >
 > **QQBot**：📖 /bot-upgrade 用法：…
 
+#### `/bot-approve` — 审批配置管理
+
+> **你**：`/bot-approve`
+>
+> **QQBot**：🔐 命令执行审批配置 — 开启审批 / 关闭审批 / 严格模式 / 恢复默认 / 查看当前配置
+
+管理 AI 命令执行审批策略，支持以下子命令：
+
+| 子命令 | 说明 |
+|--------|------|
+| `/bot-approve on` | 开启审批（白名单模式，推荐） |
+| `/bot-approve off` | 关闭审批，命令直接执行 |
+| `/bot-approve always` | 严格模式，每次执行都需审批 |
+| `/bot-approve reset` | 恢复框架默认值 |
+| `/bot-approve status` | 查看当前审批配置 |
+
+#### `/bot-clear-storage` — 清理通过 QQBot 对话产生的文件以及下载的资源（保存在 OpenClaw 运行环境的主机上）
+
+`/bot-clear-storage` 列出对话产生的文件以及下载的资源目录里的文件，使用`/bot-clear-storage -- force`确定删除。
+
 ---
 
 ## 🚀 快速开始
@@ -215,15 +251,15 @@ AI 可直接发送视频，支持本地文件和公网 URL。
 2. 手机 QQ 扫码后选择**同意**，即完成注册，进入 QQ 机器人配置页。
 3. 点击**创建机器人**，即可直接新建一个 QQ 机器人。
 
-<img width="720" alt="创建机器人" src="docs/images/create_robot.png" />
+<img width="720" alt="创建机器人" src="docs/images/create-robot.png" />
 
 > ⚠️ 机器人创建后会自动出现在你的 QQ 消息列表中，并发送第一条消息。但在完成下面的配置之前，发消息会提示"该机器人去火星了"，属于正常现象。
 
-<img width="400" alt="机器人打招呼" src="docs/images/bot_say_hello.jpg" />
+<img width="400" alt="机器人打招呼" src="docs/images/bot-say-hello.jpg" />
 
 4. 在机器人页面中找到 **AppID** 和 **AppSecret**，分别点击右侧**复制**按钮，保存到记事本或备忘录中。**AppSecret 不支持明文保存，离开页面后再查看会强制重置，请务必妥善保存。**
 
-<img width="720" alt="找到 AppID 和 AppSecret" src="docs/images/find_appid_secret.png" />
+<img width="720" alt="找到 AppID 和 AppSecret" src="docs/images/find-appid-secret.png" />
 
 > 详细图文教程请参阅 [官方指南](https://cloud.tencent.com/developer/article/2626045)。
 
@@ -238,7 +274,7 @@ curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main
 
 一行命令搞定：下载脚本 → 清理旧插件 → 安装 → 配置通道 → 启动服务。完成后打开 QQ 即可开始聊天！
 
-> 首次安装**必须**传 `--appid` 和 `--secret`。后续升级如已有配置：
+> 首次安装**必须**传 `--appid` 和 `--secret`。后续升级执行此指令可以升级为最新版：
 > ```bash
 > curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
 > ```
@@ -368,12 +404,56 @@ openclaw message send --channel "qqbot" \
 
 #### 工作原理
 
-- 启动 `openclaw gateway` 后，所有 `enabled: true` 的账户会同时启动 WebSocket 连接
+- 启动 `openclaw gateway` 后，所有 `enabled: true` 的账户会同时启动连接（WebSocket 或 Webhook，取决于 `transport` 配置）
 - 每个账户独立维护 Token 缓存（基于 `appId` 隔离），互不干扰
 - 接收消息时，日志会带上 `[qqbot:accountId]` 前缀方便排查
 
 ---
 
+### Webhook 传输模式
+
+默认情况下，插件通过 **WebSocket** 连接 QQ 平台（出站连接，无需公网 IP）。你也可以切换为 **Webhook** 模式，由 QQ 平台主动 POST 事件到你的 HTTP 端点。
+
+| | WebSocket（默认） | Webhook |
+|---|---|---|
+| 连接方式 | 插件主动连接 QQ 网关 | QQ 平台 POST 到你的服务器 |
+| 公网 IP | 不需要 | 需要 |
+| 适用场景 | 开发调试、单实例部署 | 生产环境、水平扩展、Serverless |
+| 会话恢复 | 支持 RESUME | 无状态，无需恢复 |
+| 签名验证 | 平台内置 | 插件自动 Ed25519 验签 |
+
+#### 配置方式
+
+```json
+{
+  "channels": {
+    "qqbot": {
+      "appId": "111111111",
+      "clientSecret": "your-secret",
+      "transport": "webhook",
+      "webhook": {
+        "path": "/qqbot/webhook"
+      }
+    }
+  }
+}
+```
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `transport` | `"websocket"` | `"websocket"` 或 `"webhook"` |
+| `webhook.path` | `"/qqbot/webhook"` | 接收回调的 HTTP 路径 |
+
+#### 平台配置步骤
+
+1. 登录 [QQ 开放平台](https://q.qq.com/) → 开发设置 → 消息接收方式
+2. 选择 **HTTP 回调**
+3. 填写回调 URL：`https://your-domain.com/qqbot/webhook`
+4. 平台发送 `op:13` 验证请求，插件自动处理签名验证
+5. 验证通过后，所有事件将以 POST 方式推送到该地址
+
+---
+
 ### 语音能力配置（STT / TTS）
 
 #### STT（语音转文字）— 自动转录用户发来的语音消息
@@ -453,7 +533,7 @@ STT 支持两级配置，按优先级查找：
 感谢[腾讯云Lighthouse](https://cloud.tencent.com/product/lighthouse)的深度合作，养小龙虾，首选腾讯云Lighthouse！
 
 <a href="https://cloud.tencent.com/product/lighthouse">
-  <img alt="腾讯云 Lighthouse" src="./docs/images/lighthouse_head.png" height="500" style="max-width:80%; height:auto;"/>
+  <img alt="腾讯云 Lighthouse" src="./docs/images/lighthouse-head.png" height="500" style="max-width:80%; height:auto;"/>
 </a>
 
 ## ⭐ Star History

package/dist/index.d.ts

@@ -15,3 +15,4 @@ export * from "./src/api.js";
 export * from "./src/config.js";
 export * from "./src/gateway.js";
 export * from "./src/outbound.js";
+export * from "./src/transport/index.js";

package/dist/index.js

@@ -24,3 +24,4 @@ export * from "./src/api.js";
 export * from "./src/config.js";
 export * from "./src/gateway.js";
 export * from "./src/outbound.js";
+export * from "./src/transport/index.js";