跳到主要内容

QQ Bot 发送文件踩坑记录

问题描述​

调用 openclaw message send --channel qqbot --media <路径> 发送文件时，返回 ✅ Sent 且有 message ID，但实际收不到文件。

根因分析​

1️⃣ 文件必须放在 media/ 目录下​

平台安全策略限制了文件上传路径：仅允许从 ~/.openclaw/media/ 及其子目录上传文件。放在 ~/.openclaw/workspace/ 或其它路径会被静默拦截。

正确的做法：

# 1. 将文件复制到指定目录
mkdir -p ~/.openclaw/media/qqbot
cp /path/to/file.md ~/.openclaw/media/qqbot/

# 2. 使用 --media 发送
openclaw message send --channel qqbot -t "用户ID" \
  --media "~/.openclaw/media/qqbot/file.md" \
  --message "文件名"

2️⃣ 小心文件名中的 . 字符​

QQ Bot 对文件名中带 . 的字符处理有 Bug（可能被截断导致发送失败）。解决方案：确保文件落入 media/ 目录后用 --media 发送，可规避此问题。

验证方法​

  • 确认文件确实在 ~/.openclaw/media/ 路径下
  • 使用 --media 参数而不是 buffer 方式
  • 检查返回的 message ID 是否非空

小结​

方式文件位置结果
--mediaworkspace/ 下❌ 返回成功但实际未收到
buffer + filename通过 base64 传内容⚠️ 需要同时传 message 字段
--mediamedia/qqbot/ 下✅ 正常接收

额外提示​

QQ Bot 插件 skill 文档位于：

~/.openclaw/npm/node_modules/@openclaw/qqbot/skills/qqbot-media/SKILL.md

文档中明确说明：

待发送的本地文件须落在 OpenClaw 媒体目录下：生成、下载或复制出的文件应写入 ~/.openclaw/media/qqbot/（或其子目录），再写进 <qqmedia>。不要只放在 ~/.openclaw/workspace/ 等工作区根目录——平台安全策略只允许从 ~/.openclaw/media/（含 media/qqbot）等受信根路径上传，否则会拦截、发不出去。