1. 项目定位与用途
openclaw-qqbot 是 OpenClaw AI 助手平台的 QQ 通道插件，定位为消息通道（channel plugin）。其核心用途是作为中间层，将 QQ 平台的消息转发至 OpenClaw 核心处理，并将 AI 的回复回传至 QQ。它不包含任何 AI 能力，而是依赖 OpenClaw 框架中配置的模型和技能（skills）来实现智能对话、媒体理解等高级功能。开发者可通过此插件快速将 AI 机器人部署到 QQ 生态，覆盖私聊、群聊等场景。
项目档案插件 / 扩展
openclaw-qqbot：OpenClaw AI 助手的 QQ 通道插件安装、配置与使用完整指南
openclaw-qqbot 是 OpenClaw AI 平台的 QQ 通道插件，支持私聊群聊、富媒体收发、语音转文本、引用上下文解析等。本页提供项目定位、解决的问题、适用场景、详细安装配置步骤、使用方法及常见问题解答。
AI 总结
openclaw-qqbot 是 OpenClaw AI 助手平台的 QQ 通道插件，作为消息中转层连接 QQ 与 OpenClaw 核心，支持私聊、群聊、富媒体收发及语音转文本等功能，使开发者能快速将 AI 机器人部署到 QQ 生态。
中文项目介绍
openclaw-qqbot 是 OpenClaw AI 助手平台的官方 QQ 通道插件，充当 QQ 与 OpenClaw 核心之间的消息中转层。它解决了 AI 助手与 QQ 平台集成的问题，无需开发者直接对接复杂的 QQ 机器人 API，即可实现功能丰富的 QQ 机器人。
该插件支持私聊（C2C）和群聊 @消息等多种场景，能够收发图片、语音、视频和文件等富媒体。结合 OpenClaw 的技能系统，可实现语音转文本（STT）、文件内容理解、图片理解、Markdown 格式回复、引用上下文解析、大文件自动分片上传（最大 100 MB）、命令执行审批、定时主动推送等特性。插件本身不包含 AI 能力，依赖 OpenClaw 配置的模型和技能实现智能回复。
技术实现上，项目采用 TypeScript 编写，编译目标为 ES2022，依赖 mpg123-decoder 和 silk-wasm 处理 QQ 语音格式，使用 ws 库进行 WebSocket 网关连接。提供 CLI 工具和辅助脚本简化部署与管理，并通过 postinstall 和 postbuild 脚本自动完成 SDK 链接和构建产物同步。
详细信息与使用说明
2. 解决的问题
该插件主要解决 AI 助手与 QQ 平台集成的问题。QQ 机器人开发涉及复杂的协议、事件处理和媒体格式（如 silk 语音、分片上传），直接对接门槛高。openclaw-qqbot 封装了这些细节，提供稳定的消息通道，处理网关连接、消息路由、富媒体收发、语音转码、大文件分片上传等底层逻辑，使开发者能专注于 OpenClaw 技能和模型配置，无需关心 QQ 特定实现。
3. 适用场景
适用场景包括：个人 AI 助手通过 QQ 私聊提供对话服务；群组中 AI 机器人响应成员 @消息并参与讨论；发送图片、语音、文件让 AI 进行内容理解与分析（需模型支持多模态）；需要定时提醒或推送的场景（如天气预报、新闻）；需要安全审批的命令执行（如系统操作，通过内联键盘按钮批准）；大文件传输场景（如文档分享，支持自动分片上传至 100 MB）。
4. 安装方式
安装需在插件根目录执行 OpenClaw 命令：`openclaw plugins install .`。注意：qqbot 为自定义插件，不能使用 `openclaw channels add` 配置。必须通过 `openclaw config set` 命令或直接编辑 `~/.openclaw/openclaw.json` 文件进行通道配置，包括设置 `channels.qqbot.appId`（你的 AppID）、`channels.qqbot.clientSecret`（你的 AppSecret）和 `channels.qqbot.enabled true` 启用通道。构建后，postbuild 脚本会自动将编译产物同步到用户扩展目录。
5. 使用方式
在 QQ 中私聊或群聊 @机器人即可交互，支持发送文本、图片、语音、视频、文件。语音消息将自动转文本（需提前配置 STT 技能）；引用回复时，插件会解析引用内容并注入 AI 上下文，使模型明确对话指向；发送 `/bot-upgrade` 命令可在私聊中热升级插件，无需服务器登录；通过 OpenClaw 的定时任务功能可实现主动推送；回复支持 Markdown 格式，并实时显示“正在输入”状态。AI 发送图片支持本地路径和 URL，格式包括 jpg/png/gif/webp/bmp。
6. 补充说明与实现特点
项目基于 OpenClaw 插件系统，通过 `preload.cjs` 在平台启动时注册通道。技术栈为 TypeScript 5.9，严格类型检查，模块解析采用 NodeNext。依赖 `mpg123-decoder` 和 `silk-wasm` 处理 QQ 特有的语音编解码，`ws` 用于 WebSocket 网关通信。提供 CLI 工具（`openclaw-qqbot` 或 `qqbot` 命令）和多个辅助脚本：`upgrade-via-source.sh` 一键源码升级，`set-markdown.sh` 管理 Markdown 设置，`cleanup-legacy-plugins.sh` 清理旧版残留。插件自身不存储敏感信息，依赖 OpenClaw 配置系统管理凭据。
思维导图
openclaw-qqbot
核心文件
preload.cjs（插件预加载）
index.ts（主入口）
openclaw.plugin.json（元数据）
package.json（依赖与脚本）
tsconfig.json（编译配置）
功能模块（src/）
channel.ts（通道核心）
gateway.ts（网关连接）
stt.ts（语音转文本）
inbound-attachments.ts（附件下载）
outbound-deliver.ts（消息投递）
proactive.ts（定时推送）
slash-commands.ts（斜杠命令）
utils/media-send.ts（媒体发送）
依赖与构建
runtime dependencies
scripts/build（TypeScript 编译）
scripts/postbuild（同步到扩展目录）
scripts/postinstall（链接 SDK）
辅助脚本（scripts/）
upgrade-via-source.sh（一键升级）
set-markdown.sh（Markdown 配置）
cleanup-legacy-plugins.sh（清理旧版）
send-proactive.ts（主动消息测试）
技能扩展（skills/）
qqbot-channel（通道技能）
qqbot-media（媒体处理技能）
qqbot-remind（提醒技能）
qqbot-upgrade（升级技能）
文档与资源
README.md（英文介绍）
README.zh.md（中文介绍）
docs/commands.md（命令手册）
docs/images/（功能截图）
常见问题
如何安装 openclaw-qqbot 插件？
在插件项目根目录下执行命令：`openclaw plugins install .`。安装后需通过 `openclaw config set` 配置 AppID、AppSecret 并启用通道，具体步骤见 docs/commands.md。
如何配置 QQ 通道的 AppID 和密钥？
使用 OpenClaw 配置命令：`openclaw config set channels.qqbot.appId "你的appid"` 和 `openclaw config set channels.qqbot.clientSecret "你的appsecret"`，然后通过 `openclaw config set channels.qqbot.enabled true` 启用。注意：qqbot 为自定义插件，不能使用 `channels add` 命令。
插件是否支持语音消息？如何处理？
支持。收到语音消息时，插件会自动进行语音转文本（STT）处理，将语音转为文字后再传递给 AI。该功能依赖 OpenClaw 中配置的 STT 技能，整个过程对用户透明。发送语音与发送文本体验一致。
如何升级 openclaw-qqbot 插件？
在 QQ 私聊中向机器人发送命令 `/bot-upgrade` 即可触发热升级，无需服务器登录。此外，也可使用脚本 `scripts/upgrade-via-source.sh` 从源码一键升级，或通过 npm 包更新后重新安装。
是否支持大文件传输？最大多少？
支持。插件实现自动分片上传（chunked upload），并行上传并支持重试，最大支持 100 MB 的文件。发送文件时，AI 可自动识别内容并给出智能回复，如分析文档、表格等。