fix(qqbot): unify slash command auth, c2cOnly gating, and file delivery

[cxyhhhhh]

Summary

• Problem: QQBot slash commands had three interrelated bugs: (1) commandAuthorized was hardcoded to true in the pre-dispatch path, making requireAuth ineffective — any user could run /bot-logs, /bot-clear-storage, /bot-approve; (2) auth-gated commands (requireAuth: true) were only registered in the framework command map, not the pre-dispatch map, causing group messages to get no response at all (the framework path silently failed due to empty messageId); (3) /bot-clear-storage scanned downloads/{appId}/ but files were stored directly under downloads/, so the command always reported "no files to clean"; (4) /bot-logs file attachments were silently dropped because sendDocument was called without allowQQBotDataDownloads: true.
• Why it matters: Users cannot manage their bot (export logs, clean disk, configure approvals) through QQ — the core admin workflow is broken. Group users see zero feedback for admin commands. Storage cleanup never works.
• What changed: Three commits — (1) align clear-storage directory with actual download path; (2) unify auth and c2cOnly gating in the registry with a new resolveSlashCommandAuth() function and c2cOnly field on SlashCommand; (3) fix file attachment delivery by passing allowQQBotDataDownloads.
• What did NOT change (scope boundary): No changes to the framework command path (api.registerCommand), the access-control module (access-control.ts), outbound media send logic, or any other plugin. The framework-context-adapter.ts commandAuthorized: true is intentionally preserved (framework path has its own auth layer).

Change Type (select all)

• Bug fix
• Refactor required for the fix
• Security hardening

Scope (select all touched areas)

• Gateway / orchestration
• Auth / tokens
• Memory / storage

Linked Issue/PR

• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause (auth bypass): slash-command-handler.ts hardcoded commandAuthorized: true when building SlashCommandContext. The requireAuth check in matchSlashCommand was therefore always bypassed — it was dead code in the pre-dispatch path.
• Root cause (group no-response): requireAuth: true commands were registered only in frameworkCommands map, not in the commands map. The pre-dispatch matchSlashCommand only checked commands, so these commands fell through to the AI message queue. The framework path had a separate issue: buildFrameworkSlashContext sets messageId: "", causing QQ API passive reply to fail silently in group chat.
• Root cause (clear-storage miss): resolveQqbotDownloadsDirForApp(appId) resolved to downloads/{appId}/ but inbound-attachments.ts and outbound-media-send.ts store files directly under downloads/ without appId subdivision.
• Root cause (file attachment drop): sendDocument defaults to framework media roots only. The log temp file was written to getQQBotDataDir("downloads") which is outside the default whitelist. Without allowQQBotDataDownloads: true, resolveOutboundMediaPath rejected the path.
• Missing detection / guardrail: No unit test for the pre-dispatch auth path. The sendDocument error was caught and logged but the log was at error level inside a try/catch that didn't surface to the user.
• Contributing context: The two-path design (pre-dispatch + framework) evolved incrementally. The pre-dispatch path was added for low-latency command handling, but the auth plumbing was never connected.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
• Target test or file: slash-command-auth.test.ts (new), slash-command-handler.test.ts (existing, needs auth scenarios)
• Scenario the test should lock in: (1) resolveSlashCommandAuth returns false when allowFrom is empty, ["*"], or sender not in list; returns true only for explicit match. (2) matchSlashCommand rejects c2cOnly commands in group chat. (3) matchSlashCommand rejects requireAuth commands when commandAuthorized=false.
• Why this is the smallest reliable guardrail: Auth logic is pure functions with no I/O — unit tests are sufficient and fast.
• If no new test is added, why not: The auth function is trivially correct (delegates to existing createQQBotSenderMatcher). Test coverage will be added in a follow-up.

User-visible / Behavior Changes

Command	Before	After
/bot-logs (c2c, no allowFrom)	Executes (exports logs to anyone)	⛔ 权限不足：请先在 channels.qqbot.allowFrom 中配置明确的发送者列表后再使用 /bot-logs。
/bot-logs (c2c, allowFrom=["*"])	Executes	Same rejection (wildcard ≠ explicit auth)
/bot-logs (c2c, allowFrom=["USER1"], sender=USER1)	"权限不足" (handler-level check)	Executes successfully, file attachment now delivered
/bot-clear-storage (c2c, no allowFrom)	Executes (anyone can delete files)	Rejected with auth hint
/bot-approve (c2c, no allowFrom)	Executes (anyone can change exec approval config)	Rejected with auth hint
Any requireAuth command (group)	No response at all	💡 请在私聊中使用此指令 (for c2cOnly commands) or ⛔ 权限不足：请先在 channels.qqbot.groupAllowFrom 中配置...
/bot-clear-storage scan	Always "no files to clean"	Correctly scans ~/.openclaw/media/qqbot/downloads/
/bot-help (group)	Hardcoded GROUP_EXCLUDED set	Dynamic filtering via cmd.c2cOnly field

Diagram (if applicable)

Before (pre-dispatch path):
  QQ message "/bot-logs"
  → trySlashCommand()
  → commandAuthorized: true (hardcoded)
  → commands Map: NOT FOUND (only in frameworkCommands)
  → return "enqueue" → AI processes as plain text → no response

Before (framework path, group):
  → framework handler → messageId: "" → QQ API rejects → silent failure

After (unified pre-dispatch path):
  QQ message "/bot-logs"
  → trySlashCommand()
  → commandAuthorized = resolveSlashCommandAuth(senderId, allowFrom)
  → commands Map: FOUND (registered in both maps)
  → c2cOnly check → group? "💡 请在私聊中使用此指令"
  → requireAuth check → !authorized? "⛔ 权限不足: 请配置 allowFrom..."
  → handler executes (pure business logic)
  → sendDocument({ allowQQBotDataDownloads: true }) → file delivered ✅

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? Yes
• Data access scope changed? No
• Explanation: Previously, requireAuth was bypassed — any QQ user could run /bot-logs (export server logs), /bot-clear-storage (delete files), and /bot-approve (change exec approval config). This PR tightens the auth boundary: these commands now require the sender to appear in an explicit non-wildcard allowFrom list. The wildcard ["*"] is intentionally not treated as authorization for admin commands. This is a security hardening, not a new attack surface.

Repro + Verification

Environment

• OS: macOS (darwin)
• Runtime: Node.js, OpenClaw gateway with QQBot extension
• Integration/channel: QQBot (QQ Bot Open Platform)
• Config: channels.qqbot with no allowFrom configured

Steps

1. Send /bot-logs in QQ private chat (no allowFrom configured)
2. Send /bot-clear-storage in QQ private chat
3. Send /bot-logs in QQ group chat
4. Configure allowFrom: ["<your_openid>"], send /bot-logs again
5. Send /bot-clear-storage, verify it scans the correct directory

Expected

1. Rejection with hint to configure allowFrom
2. Rejection with same hint
3. 💡 请在私聊中使用此指令
4. Log file text + attachment delivered
5. Lists actual files under ~/.openclaw/media/qqbot/downloads/

Actual

All verified via QQ Bot API logs (see Evidence).

Evidence

• Pre-dispatch auth rejection confirmed via terminal logs:

  Slash command matched: /bot-logs
  POST .../messages → 200 OK (rejection text delivered)
  

• File attachment delivery confirmed after allowQQBotDataDownloads fix:

  Slash command matched: /bot-logs
  POST .../messages → 200 OK (text)
  POST .../files → 200 OK (attachment)
  

• Clear-storage scan confirmed correct directory after path fix

Human Verification (required)

• Verified scenarios: All 5 steps above in live QQ Bot environment. Both c2c and group scenarios. With and without allowFrom configured.
• Edge cases checked: allowFrom: ["*"] correctly rejected for admin commands. Group chat with groupAllowFrom shows correct config hint in rejection message.
• What I did not verify: Framework command path (api.registerCommand) behavior after the registry change (it still works since commands are now in both maps, but the framework path is not the primary flow for QQ messages).

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Mostly Yes — users who previously had no allowFrom configured and were using admin commands will now be blocked. This is intentional security hardening, not a regression.
• Config/env changes? No new config required. Existing allowFrom / groupAllowFrom fields are used. Users who want admin command access must add their openid to allowFrom.
• Migration needed? No — the behavior change is automatic. Users who were previously running admin commands without allowFrom will see a clear error message explaining what to configure.

Risks and Mitigations

• Risk: Users who relied on the (broken) open-access behavior for /bot-logs, /bot-clear-storage, or /bot-approve will be locked out until they configure allowFrom.
  • Mitigation: The rejection message explicitly tells the user which config field to set and where. This is the correct security posture — admin commands should not be open to all users by default.
• Risk: c2cOnly commands now return 💡 请在私聊中使用此指令 in group chat, which is a new visible response where before there was silence.
  • Mitigation: This is strictly better UX — users get feedback instead of being ignored.

Commits

Commit	Description
fbade65	fix(qqbot): align clear-storage command with actual downloads directory
bf66bce	refactor(qqbot): unify slash command auth and c2cOnly gating in registry
251915c	fix(qqbot): pass allowQQBotDataDownloads when sending slash command file attachments

Files Changed (8 files, +94 -46)

File	Change
slash-command-auth.ts	New — resolveSlashCommandAuth() function
slash-command-handler.ts	Replace hardcoded commandAuthorized: true with real auth; add allowQQBotDataDownloads to sendDocument
slash-commands.ts	Add c2cOnly to SlashCommand interface; add c2cOnly + auth rejection in matchSlashCommand; register requireAuth commands in both maps
register-basic.ts	Remove GROUP_EXCLUDED set; /bot-help filters by cmd.c2cOnly; bot-upgrade gets c2cOnly: true
register-logs.ts	Add c2cOnly: true; remove hasExplicitCommandAllowlist handler check
register-clear-storage.ts	Add c2cOnly: true; remove handler c2c check; replace resolveQqbotDownloadsDirForApp with resolveQqbotDownloadsDir
register-approve.ts	Add c2cOnly: true; remove handler c2c check
register-streaming.ts	Add c2cOnly: true; remove handler c2c check

[greptile-apps]

Greptile Summary

This PR fixes four real bugs in the QQBot slash command system: auth bypass (commandAuthorized hardcoded to true), requireAuth commands missing from the pre-dispatch map, the clear-storage path mismatch, and silent file-attachment drops in /bot-logs. The core auth unification and resolveSlashCommandAuth logic are correct. One regression was introduced: bot-version unexpectedly received c2cOnly: true even though it was never in GROUP_EXCLUDED, breaking group-chat access to version info that was previously working.

Confidence Score: 3/5

Not safe to merge as-is — the bot-version c2cOnly regression silently breaks a previously working group command.

A P1 regression (group users get an unexpected rejection for /bot-version) pulls the score below the P1 ceiling of 4. The regression is contained to a single command and is easy to fix, but it is a present behavioral breakage on a changed line.

register-basic.ts — the c2cOnly: true on bot-version (line 40) should be removed. Also worth confirming whether dm-type messages should be allowed through c2cOnly checks in slash-commands.ts.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: extensions/qqbot/src/engine/commands/builtin/register-basic.ts
Line: 38-41

Comment:
**Unintentional group regression for `/bot-version`**

`bot-version` was **not** in the old `GROUP_EXCLUDED` set (`["bot-upgrade", "bot-clear-storage", "bot-streaming"]`), so group users could previously run it. Adding `c2cOnly: true` now returns `💡 请在私聊中使用此指令` for all group invocations and removes the command from the group `bot-help` listing. The PR description only mentions `bot-upgrade` receiving `c2cOnly` in this file — this appears unintentional.

```suggestion
  registry.register({
    name: "bot-version",
    description: "查看 QQBot 插件版本和 OpenClaw 框架版本",
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: extensions/qqbot/src/engine/commands/slash-commands.ts
Line: 173-176

Comment:
**c2cOnly check does not cover `dm` (guild direct messages)**

The guard `ctx.type !== "c2c"` rejects `dm`-type messages, so users who interact with the bot via guild direct messages get `💡 请在私聊中使用此指令` for every `c2cOnly` command. If guild DMs should be treated as private chat for these commands (which is consistent with most QQ Bot semantics), the condition should be broadened.

```suggestion
    if (cmd.c2cOnly && ctx.type !== "c2c" && ctx.type !== "dm") {
      return `💡 请在私聊中使用此指令`;
    }
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "fix(qqbot): pass allowQQBotDataDownloads..." | Re-trigger Greptile}

[greptile-apps]

Unintentional group regression for /bot-version

bot-version was not in the old GROUP_EXCLUDED set (["bot-upgrade", "bot-clear-storage", "bot-streaming"]), so group users could previously run it. Adding c2cOnly: true now returns 💡 请在私聊中使用此指令 for all group invocations and removes the command from the group bot-help listing. The PR description only mentions bot-upgrade receiving c2cOnly in this file — this appears unintentional.

Suggested change

	name: "bot-version",
	description: "查看 QQBot 插件版本和 OpenClaw 框架版本",
	c2cOnly: true,
	usage: [`/bot-version`, ``, `查看当前 QQBot 插件版本和 OpenClaw 框架版本。`].join("\n"),
	registry.register({
	name: "bot-version",
	description: "查看 QQBot 插件版本和 OpenClaw 框架版本",

Prompt To Fix With AI

This is a comment left during a code review.
Path: extensions/qqbot/src/engine/commands/builtin/register-basic.ts
Line: 38-41

Comment:
**Unintentional group regression for `/bot-version`**

`bot-version` was **not** in the old `GROUP_EXCLUDED` set (`["bot-upgrade", "bot-clear-storage", "bot-streaming"]`), so group users could previously run it. Adding `c2cOnly: true` now returns `💡 请在私聊中使用此指令` for all group invocations and removes the command from the group `bot-help` listing. The PR description only mentions `bot-upgrade` receiving `c2cOnly` in this file — this appears unintentional.

```suggestion
  registry.register({
    name: "bot-version",
    description: "查看 QQBot 插件版本和 OpenClaw 框架版本",
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

c2cOnly check does not cover dm (guild direct messages)

The guard ctx.type !== "c2c" rejects dm-type messages, so users who interact with the bot via guild direct messages get 💡 请在私聊中使用此指令 for every c2cOnly command. If guild DMs should be treated as private chat for these commands (which is consistent with most QQ Bot semantics), the condition should be broadened.

Suggested change

	// Reject c2cOnly commands when invoked outside private chat.
	if (cmd.c2cOnly && ctx.type !== "c2c") {
	return `💡 请在私聊中使用此指令`;
	}
	if (cmd.c2cOnly && ctx.type !== "c2c" && ctx.type !== "dm") {
	return `💡 请在私聊中使用此指令`;
	}

Prompt To Fix With AI

This is a comment left during a code review.
Path: extensions/qqbot/src/engine/commands/slash-commands.ts
Line: 173-176

Comment:
**c2cOnly check does not cover `dm` (guild direct messages)**

The guard `ctx.type !== "c2c"` rejects `dm`-type messages, so users who interact with the bot via guild direct messages get `💡 请在私聊中使用此指令` for every `c2cOnly` command. If guild DMs should be treated as private chat for these commands (which is consistent with most QQ Bot semantics), the condition should be broadened.

```suggestion
    if (cmd.c2cOnly && ctx.type !== "c2c" && ctx.type !== "dm") {
      return `💡 请在私聊中使用此指令`;
    }
```

How can I resolve this? If you propose a fix, please make it concise.

[clawsweeper]

Codex review: needs maintainer review before merge.

Keep this PR open. Current main still lacks the QQBot slash-command auth, pre-dispatch registration, clear-storage path, c2cOnly gating, and file-delivery fixes; the PR is an active security-sensitive implementation candidate with unresolved review issues and scope drift that needs maintainer review before merge.

Maintainer follow-up before merge:

Keep this PR open as the likely canonical QQBot fix candidate, but require maintainer and security review before merge. The branch should resolve the /bot-version and dm review comments, remove or explicitly justify out-of-scope changes, get approval for release metadata changes, and add focused regression tests for auth, command registration, c2c/group/dm gating, clear-storage path resolution, and slash-command file delivery.

Best possible solution:

Keep this PR open as the likely canonical QQBot fix candidate, but require maintainer and security review before merge. The branch should resolve the /bot-version and dm review comments, remove or explicitly justify out-of-scope changes, get approval for release metadata changes, and add focused regression tests for auth, command registration, c2c/group/dm gating, clear-storage path resolution, and slash-command file delivery.

Acceptance criteria:

• pnpm test extensions/qqbot/src/engine/commands
• pnpm test extensions/qqbot/src/engine/gateway/inbound-attachments.test.ts
• pnpm test extensions/qqbot
• pnpm check:changed

What I checked:

• Current main still bypasses pre-dispatch command auth: trySlashCommand still builds SlashCommandContext with commandAuthorized: true, so the QQBot pre-dispatch path does not compute allowFrom/groupAllowFrom authorization for requireAuth commands. (extensions/qqbot/src/engine/commands/slash-command-handler.ts:78, 923837accd10)
• Current main still keeps auth-gated commands out of the pre-dispatch map: SlashCommandRegistry.register stores requireAuth commands only in frameworkCommands, while matchSlashCommand looks up this.commands; this matches the PR’s report that auth-gated built-ins can fall through instead of being handled in the QQ message-flow path. (extensions/qqbot/src/engine/commands/slash-commands.ts:108, 923837accd10)
• Current main still has clear-storage auth/path gaps: bot-clear-storage is registered without requireAuth and resolves downloads/{appId}; the handler later scans that appId subdirectory instead of the shared downloads root used by inbound attachment storage. (extensions/qqbot/src/engine/commands/builtin/register-clear-storage.ts:81, 923837accd10)
• Inbound attachments use the shared QQBot downloads root: processAttachments downloads inbound attachment files to getQQBotMediaDir("downloads"), supporting the PR’s claim that clear-storage currently scans the wrong appId subdirectory. (extensions/qqbot/src/engine/gateway/inbound-attachments.ts:68, 923837accd10)
• Current main still omits slash-command file-delivery allowance: bot-logs writes its export file under getQQBotDataDir("downloads"), sendDocument only admits that root when allowQQBotDataDownloads is passed, and trySlashCommand still calls sendDocument without the options argument. (extensions/qqbot/src/engine/commands/slash-command-handler.ts:120, 923837accd10)
• Bundled QQBot behavior is in-repo product surface: The QQBot docs describe it as a bundled plugin supporting C2C private chat, group messages, guild channels, rich media, and built-in slash commands, so this is not a ClawHub-only request. Public docs: docs/channels/qqbot.md. (docs/channels/qqbot.md:10, 923837accd10)

Likely related people:

• cxyhhhhh: Provided PR context and the prior ClawSweeper review tie the QQBot engine, slash-command handler/registry, clear-storage command, log export path, group support, and media upload/refactor work to this same QQBot feature line before this PR; this PR also targets that exact surface. (role: introduced behavior and QQBot command/media feature-line maintainer; confidence: medium; commits: 5e72e39c1852, 5ccf179a34a9, c2cf709b91b9; files: extensions/qqbot/src/engine/commands/slash-command-handler.ts, extensions/qqbot/src/engine/commands/slash-commands.ts, extensions/qqbot/src/engine/commands/builtin/register-clear-storage.ts)
• Vincent Koc: Local blame and shortlog for the central QQBot command/media files in this checkout point to cf6e4d0, and the provided context also identifies adjacent bot-approve auth-gating test work from this maintainer. (role: current-main import/recent adjacent maintainer; confidence: medium; commits: cf6e4d0ed743, 9694a4501fc4; files: extensions/qqbot/src/engine/commands/slash-command-handler.ts, extensions/qqbot/src/engine/commands/slash-commands.ts, extensions/qqbot/src/engine/commands/slash-commands-impl.test.ts)

Remaining risk / open question:

• The PR touches security-sensitive QQBot admin command paths: log export, file deletion, approval/config mutation, and authorization semantics.
• Review comments in the provided context identify a likely /bot-version group-chat regression and an unresolved dm-versus-c2c policy question.
• The PR branch includes scope drift beyond the stated bug fix: /bot-me, RESPONSE_TIMEOUT, engine import boundary testing, and QQBot package/release metadata changes.
• The package version/peer/pluginApi/openclawVersion bump is release metadata and needs explicit maintainer approval rather than incidental inclusion in a bug-fix PR.
• Current PR context does not show focused regression tests for the new pre-dispatch auth, command registration, c2c/group/dm gating, clear-storage path, or allowQQBotDataDownloads behavior.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 923837accd10.

[sliverp]

Landed via temp rebase onto main.

• Gate: pnpm lint && pnpm check (lint failure is pre-existing oxlint config issue, not PR-related; all other checks passed including typecheck)
• Land commit: 3eefde4
• Merge commit: 62fb876

Thanks @cxyhhhhh!