name: qqbot-file-sender
description: QQ Bot 文件发送工具。支持私聊和群聊发送图片、视频、语音文件，提供简单易用的API接口。

QQ Bot 文件发送工具

📋 功能概述

本skill提供QQ Bot文件发送能力，支持：

✅ 私聊（C2C）发送文件
✅ 群聊（Group）发送文件
✅ 多种文件类型：图片、视频、语音
✅ 多种上传方式：本地文件、网络URL

🔍 调研结果

支持的文件类型

根据QQ Bot API代码分析，支持的媒体文件类型包括：

类型	枚举值	说明
IMAGE	1	图片文件（jpg, png, gif, webp等）
VIDEO	2	视频文件
VOICE	3	语音文件
FILE	4	普通文件（暂未开放）⚠️

上传方式

本地文件：读取文件并转换为Base64编码
网络URL：提供公网可访问的文件URL

支持场景

私聊（C2C）：与用户一对一聊天
群聊（Group）：群组内发送文件

文件大小限制

重要：在API代码中未找到明确的文件大小限制。根据经验，QQ平台通常限制：

图片：建议不超过 10MB
视频：建议不超过 100MB（可能被压缩）
语音：建议不超过 5MB

建议：发送前先测试目标文件大小，避免发送失败。

🚀 使用示例

示例1：发送本地图片到私聊

// 方式1：使用skill工具函数
import { sendQQFile } from "/root/.openclaw/workspace/skills/qqbot-file-sender/index.js";

await sendQQFile({
  targetId: "33558EFB7CF362DA4A894FBE2E93DFDE",
  targetType: "c2c",  // c2c 或 group
  filePath: "/path/to/image.jpg",
  fileType: "image",
  content: "这是发给您的图片"  // 可选：附加文字说明
});

示例2：发送网络图片到群聊

await sendQQFile({
  targetId: "group_openid_here",
  targetType: "group",
  fileUrl: "https://example.com/image.png",
  fileType: "image",
  content: "群友们看看这个"
});

示例3：发送视频文件

await sendQQFile({
  targetId: "33558EFB7CF362DA4A894FBE2E93DFDE",
  targetType: "c2c",
  filePath: "/path/to/video.mp4",
  fileType: "video",
  content: "分享一个视频"
});

示例4：直接在工具调用中使用

openclaw run --skill qqbot-file-sender --params '{
  "targetId": "33558EFB7CF362DA4A894FBE2E93DFDE",
  "targetType": "c2c",
  "filePath": "/path/to/file.jpg",
  "fileType": "image",
  "content": "测试发送图片"
}'

📦 API参考

函数签名

async function sendQQFile(options: {
  targetId: string;        // 目标ID（用户openid或群openid）
  targetType: 'c2c' | 'group'; // 目标类型：c2c=私聊，group=群聊
  fileType: 'image' | 'video' | 'voice'; // 文件类型
  filePath?: string;       // 本地文件路径（与fileUrl二选一）
  fileUrl?: string;        // 网络文件URL（与filePath二选一）
  content?: string;        // 附加文字内容（可选）
  msgId?: string;          // 回复的消息ID（可选，用于被动回复）
}): Promise<{ id: string; timestamp: number | string }>

参数说明

参数	类型	必填	说明
targetId	string	是	用户的OpenID或群组的OpenID
targetType	'c2c' \| 'group'	是	目标类型：c2c=私聊，group=群聊
fileType	'image' \| 'video' \| 'voice'	是	文件类型
filePath	string	二选一	本地文件的绝对路径
fileUrl	string	二选一	公网可访问的文件URL
content	string	否	附加的文字说明
msgId	string	否	要回复的消息ID（用于被动回复）

返回结果

{
  id: string;        // 消息ID
  timestamp: number | string;  // 时间戳
}

⚠️ 重要注意事项

1. 文件类型限制

FILE类型（普通文件）在API中标记为"暂未开放"
目前只能发送图片、视频、语音被识别为富媒体消息

2. 消息发送限制

被动回复：同一消息ID在1小时内最多回复4次，超过需要转为主动消息
主动消息：使用sendProactive*Message函数，无回复次数限制

3. 上传方式限制

本地文件：必须是绝对路径，会被转换为Base64编码
网络URL：必须是公网可访问，不能是局域网或本地地址

4. 文件大小建议

虽然API未明确限制，但建议：

图片：≤ 10MB
视频：≤ 100MB
语音：≤ 5MB

过大的文件可能导致：

上传超时
QQ平台拒绝接收
传输失败

5. 错误处理

函数会抛出以下类型的错误：

File not found：本地文件不存在
Invalid file type：不支持的文件类型
Upload failed：上传失败（网络问题或文件过大）
Network error：网络请求失败

🔧 内部实现细节

使用的API函数

本skill基于QQ Bot官方API封装：

uploadC2CMedia() - 上传私聊媒体文件
uploadGroupMedia() - 上传群聊媒体文件
sendC2CMediaMessage() - 发送私聊富媒体消息
sendGroupMediaMessage() - 发送群聊富媒体消息

消息类型

msg_type: 7 - 富媒体消息（包含文件）
media: { file_info: string } - 文件信息

文件上传流程

检查参数（filePath或fileUrl必须提供其一）
如果是本地文件，读取并转换为Base64
调用QQ Bot API上传媒体文件
获取file_info（上传后的文件标识）
调用发送消息API，附带file_info
返回消息ID和时间戳

📝 更新日志

2026-02-20: 创建skill，支持基础文件发送功能

🔗 相关链接

QQ Bot官方文档：https://bot.q.qq.com/wiki/
OpenClaw QQ Bot插件：https://github.com/sliverp/qqbot

注意：本skill基于逆向工程分析QQ Bot API代码创建，如有API变更请及时更新

📄 SKILL.md

name: qqbot-file-senderdescription: QQ Bot 文件发送工具。支持私聊和群聊发送图片、视频、语音文件，提供简单易用的API接口。