qq-messenger Skill

主动向 QQ 发送消息和文件的能力。

原理

qqrebot 使用 go-cqhttp HTTP API (send_private_msg / send_group_msg) 发送消息。NapCat4 扩展支持 upload_group_file / upload_private_file 发送文件。本技能包装了这些 API 为命令行脚本，方便 qq-agent 在需要时主动推送。

自动回复 vs 主动发送

	回复场景	主动发信
触发	用户在 QQ 上发消息给你	你自己决定要推送
方式	系统自动将回复转发到 QQ	调用本脚本
示例	用户问"服务器状态"，你回答"正常"	你发现磁盘快满了，主动给管理员发告警

即使不调用本脚本，用户发给你的消息你回复后，系统会自动转发回 QQ。 本脚本只用于"非回复"场景的主动推送。

脚本清单

脚本	用途	特点
`qq_send_msg.py`	发送文本消息	即时发送，阻塞直到返回
`qq_send_file.py`	发送文件/图片	异步执行，调用后立即返回，后台复制→发送→清理

用法

发送私聊消息

import subprocess
subprocess.run(["python3", "YOUR_WORKSPACE_PATH/scripts/qq_send_msg.py",
    "--private", "YOUR_ADMIN_QQ", "--message", "消息内容"], text=True, timeout=15, capture_output=True)

发送群聊消息

subprocess.run(["python3", "YOUR_WORKSPACE_PATH/scripts/qq_send_msg.py",
    "--group", "YOUR_GROUP_ID", "--message", "消息内容"], text=True, timeout=15, capture_output=True)

发送文件（后台发送，立即返回）

import subprocess
# 私聊发文件
subprocess.run(["python3", "YOUR_WORKSPACE_PATH/scripts/qq_send_file.py",
    "--private", "YOUR_ADMIN_QQ", "/path/to/file"], text=True, timeout=5, capture_output=True)
# 群聊发文件
subprocess.run(["python3", "YOUR_WORKSPACE_PATH/scripts/qq_send_file.py",
    "--group", "YOUR_GROUP_ID", "/path/to/file"], text=True, timeout=5, capture_output=True)

特点：调用后立即返回（~75ms），后台独立进程处理复制→发送。完成后通过 OpenClaw Gateway 的 /v1/chat/completions API 发送 [系统通知] 消息给 qq-agent，agent 在会话历史中看到通知。

发送图片

import subprocess
subprocess.run(["python3", "YOUR_WORKSPACE_PATH/scripts/qq_send_file.py",
    "--group", "YOUR_GROUP_ID", "--image", "/tmp/screenshot.png"], text=True, timeout=5, capture_output=True)

特点：图片用 [CQ:image] 发送，QQ 直接显示缩略图，不会进群文件。

subprocess.run(["python3", "YOUR_WORKSPACE_PATH/scripts/qq_send_file.py",
    "--group", "YOUR_GROUP_ID", "--image", "/tmp/screenshot.png"], text=True, timeout=5, capture_output=True)

图片说明：用 [CQ:image,file=...] 发送，QQ 直接显示缩略图，不会进群文件。

参数说明

参数	说明
`--private <QQ号>`	发送私聊，默认管理员 YOUR_ADMIN_QQ
`--group <群号>`	发送群聊
`--message <内容>`	消息文本（qq_send_msg.py）
`--file <路径>`	从文件读消息内容（qq_send_msg.py）
`--auto_escape`	转义 CQ 码（默认不转义）
`<文件路径>`	要发送的本地文件路径（qq_send_file.py）
`--name <显示名>`	群文件内显示的文件名（qq_send_file.py）
`--image`	作为图片发送，QQ 直接显示缩略图（qq_send_file.py）

通知机制

文件发送完成/失败后，后台进程通过 OpenClaw Gateway 的 /v1/chat/completions API 推送 [系统通知] 给 qq-agent：

内容格式：[系统通知] 给uid=YOUR_ADMIN_QQ发送文件的任务已上传完毕：文件名.ext (1.0MB) ✅
使用 Gateway Token 鉴权
Fire-and-forget：timeout=3，仅确认投递
这是 openclaw_bridge 插件用的同一个 API
agent 在自己的会话历史中看到通知

注意事项

消息尽量简洁，QQ 消息太长可读性差
不要滥用主动推送，避免打扰管理员
正常回复由系统自动转发，无需调用本脚本
连接失败时检查 go-cqhttp 是否在运行（http://YOUR_NAPCAT_HOST:25570）
文件发送依赖 YOUR_SHARED_DIR 目录（映射到 NapCat 容器内 /app/files）
通知走 OpenClaw Gateway API，不走 QQ 本身

4.3 KiB Raw Blame History Unescape Escape