——
OpenClaw QQBot 三大更新：统一权限管理、C2C 隔离与文件传输修复
OpenClaw 最新版本针对 QQBot 插件进行了三项关键改进：统一斜杠命令权限认证机制、引入 C2C（私聊）专属命令隔离策略，以及修复文件传输路径匹配问题。这些更新解决了此前权限校验分散、群聊命令响应不一致、以及日志文件下载失败等实际痛点，让 AI Agent 的 QQ 机器人部署更加稳定可靠。
—
一、存储清理命令路径修复：解决”无文件可清理”误报
问题背景
此前 /bot-clear-storage 命令存在路径不匹配问题。命令尝试清理 ~/.openclaw/media/qqbot/downloads/{appId}/ 目录，但实际文件下载路径并未按 appId 细分，而是直接存放在 ~/.openclaw/media/qqbot/downloads/ 根目录下。这导致命令始终报告”无文件可清理”，而磁盘空间却被持续占用。
核心改动
// 修复前：按 appId 拼接路径（错误）
const downloadsDir = resolveQqbotDownloadsDirForApp(appId);
// 修复后：直接使用 downloads 根目录
const downloadsDir = resolveQqbotDownloadsDir(); // 返回 ~/.openclaw/media/qqbot/downloads/
关键变更点：
- 替换
resolveQqbotDownloadsDirForApp(appId)为resolveQqbotDownloadsDir() - 使用
getQQBotMediaPath('downloads')统一获取路径 - 移除基于
appId的路径验证逻辑 - 更新命令提示文本，明确清理范围
—
二、统一权限认证与 C2C 隔离机制
2.1 旧架构的问题
此前的权限管理存在多处不一致：
| 问题场景 | 具体表现 |
|———|———|
| 权限校验分散 | commandAuthorized 在预分发路径被硬编码为 true |
| 群聊处理混乱 | 部分 handler 检查 allowFrom，部分不检查 |
| 无响应场景 | 群聊用户触发权限受限命令时，没有任何反馈 |
| 硬编码排除 | GROUP_EXCLUDED 集合维护困难，容易遗漏 |
2.2 新架构设计
#### 步骤 1：集中权限解析（slash-command-auth.ts）
// 新的统一权限解析函数
function resolveSlashCommandAuth(ctx, command): boolean {
// 关键规则：通配符 ['*'] 不授予管理员命令权限
// 必须显式配置在非通配符 allowFrom 列表中
const allowList = ctx.type === 'group'
? (command.groupAllowFrom ?? command.allowFrom) // 群聊优先使用 groupAllowFrom
: command.allowFrom;
return hasExplicitNonWildcardMatch(ctx.sender, allowList);
}
#### 步骤 2：C2C 专属命令声明
// SlashCommand 接口新增 c2cOnly 字段
interface SlashCommand {
name: string;
handler: Function;
allowFrom: string[];
groupAllowFrom?: string[]; // 群聊专用白名单
c2cOnly?: boolean; // 新增：标记为私聊专属
}
// 使用示例：标记管理员命令为私聊专属
{
name: 'bot-upgrade',
c2cOnly: true, // 群聊中直接拒绝，无需检查权限
allowFrom: ['admin-user-001', 'admin-user-002']
}
#### 步骤 3：注册表统一拦截
// slash-command-handler.ts 中的分发逻辑
async function dispatchSlashCommand(ctx, command) {
// 1. 先检查 C2C 限制（在权限检查之前）
if (command.c2cOnly && ctx.type !== 'c2c') {
return ctx.reply(该命令仅支持私聊使用，请添加机器人为好友后单独发送);
}
// 2. 统一权限认证（替换硬编码 true）
const authorized = resolveSlashCommandAuth(ctx, command);
if (!authorized) {
const configField = ctx.type === 'group' ? 'groupAllowFrom' : 'allowFrom';
return ctx.reply(您没有权限执行此命令，请联系管理员配置 ${configField});
}
// 3. 执行 handler（无需再处理权限和场景检查）
return command.handler(ctx);
}
2.3 已标记为 C2C 专属的管理员命令
| 命令 | 用途 | 为何需要 C2C 隔离 |
|—–|——|—————|
| /bot-upgrade | 升级机器人版本 | 避免群聊中误触发升级 |
| /bot-streaming | 切换流式响应模式 | 配置类操作适合私聊 |
| /bot-logs | 获取运行日志 | 日志可能包含敏感信息 |
| /bot-clear-storage | 清理存储空间 | 影响全局状态，需谨慎 |
| /bot-approve | 审批入群/好友申请 | 涉及安全审核流程 |
—
三、文件传输路径权限修复
问题现象
/bot-logs 命令生成临时日志文件到 ~/.openclaw/qqbot/downloads/，但调用 sendDocument 时未声明 allowQQBotDataDownloads: true，导致 resolveOutboundMediaPath 判定路径超出允许的媒体根目录，文件附件发送静默失败（仅文本回复成功）。
修复方案
// slash-command-handler.ts
if (result.filePath) {
await ctx.sendDocument(result.filePath, {
caption: result.message,
// 关键修复：允许访问 QQBot 数据下载目录
allowQQBotDataDownloads: true
});
}
路径权限体系说明
允许的文件根目录（按优先级）：
├── ~/.openclaw/media/ # 通用媒体目录（默认允许）
├── ~/.openclaw/qqbot/downloads/ # QQBot 数据目录（需显式声明）
└── 其他路径 # 默认拒绝，防止目录遍历攻击
—
四、升级建议与配置示例
4.1 配置文件更新（openclaw.config.js）
module.exports = {
plugins: {
qqbot: {
slashCommands: {
// 私聊白名单（支持通配符，但管理员命令除外）
allowFrom: ['*'],
// 群聊白名单（覆盖 allowFrom，或单独配置）
groupAllowFrom: ['group-admin-001'],
// 管理员命令必须显式配置（不能仅用通配符）
adminCommands: {
'bot-upgrade': {
allowFrom: ['your-qq-number'], // 必须显式指定
// groupAllowFrom 未配置，群聊中自动拒绝
}
}
}
}
}
};
4.2 迁移检查清单
- [ ] 确认
bot-clear-storage能正确清理历史下载文件 - [ ] 验证所有管理员命令在群聊中返回友好提示（而非无响应）
- [ ] 测试
/bot-logs命令能正常发送日志文件附件 - [ ] 检查自定义斜杠命令是否需添加
c2cOnly标记
—
常见问题 FAQ
Q1: 为什么我的管理员命令在群聊中没有反应？
之前版本会静默拒绝权限不足的命令，现在会明确提示”您没有权限执行此命令”。如需在群聊中使用，请配置 groupAllowFrom 字段，或将命令标记为 c2cOnly: true 以明确限制私聊使用。
Q2: C2C 专属命令和 allowFrom 是什么关系？
c2cOnly: true 是场景限制（仅私聊），在权限检查之前执行；allowFrom 是身份限制（谁可以执行）。两者独立：一个私聊专属命令仍需配置 allowFrom 才能被特定用户调用。
Q3: 通配符 ['*'] 为什么不能用于管理员命令？
这是安全设计。管理员命令通常涉及敏感操作（升级、日志导出、存储清理），必须显式配置操作者身份，防止配置疏漏导致权限扩散。
Q4: 如何调试文件传输失败问题？
启用 DEBUG=openclaw:media:* 环境变量，查看 resolveOutboundMediaPath 的路径解析日志。确保 allowQQBotDataDownloads 或相应的媒体权限标志已正确设置。
Q5: 旧版本的 GROUP_EXCLUDED 配置如何迁移？
无需手动迁移。新版本中 /bot-help 已改为动态过滤 c2cOnly 命令，只需在命令定义中添加 c2cOnly: true 即可，不再需要维护单独的排除集合。
—
总结
本次更新通过统一权限认证层、显式 C2C 隔离声明、修复文件路径匹配三个维度，显著提升了 OpenClaw QQBot 插件的可维护性和用户体验。建议所有使用 QQBot 集成的 AI Agent 开发者尽快升级，并根据本文的配置示例调整权限设置。
下一步行动：
1. 查看 OpenClaw 文档 获取完整配置参考
2. 访问 GitHub Releases 下载最新版本
3. 在 OpenClaw 社区 分享你的迁移经验
—
相关阅读
—
参考来源
