@openclaw/qqbot 2026.5.1-beta.1

package/src/bridge/tools/channel.ts

@@ -0,0 +1,58 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { getAccessToken } from "../../engine/messaging/sender.js";
+import { ChannelApiSchema, executeChannelApi } from "../../engine/tools/channel-api.js";
+import type { ChannelApiParams } from "../../engine/tools/channel-api.js";
+import { listQQBotAccountIds, resolveQQBotAccount } from "../config.js";
+
+/**
+ * Register the QQ channel API proxy tool.
+ *
+ * The tool acts as an authenticated HTTP proxy for the QQ Open Platform
+ * channel APIs. Agents learn endpoint details from the skill docs and
+ * send requests through this proxy.
+ */
+export function registerChannelTool(api: OpenClawPluginApi): void {
+  const cfg = api.config;
+  if (!cfg) {
+    return;
+  }
+
+  const accountIds = listQQBotAccountIds(cfg);
+  if (accountIds.length === 0) {
+    return;
+  }
+
+  const firstAccountId = accountIds[0];
+  const account = resolveQQBotAccount(cfg, firstAccountId);
+
+  if (!account.appId || !account.clientSecret) {
+    return;
+  }
+
+  api.registerTool(
+    {
+      name: "qqbot_channel_api",
+      label: "QQBot Channel API",
+      description:
+        "Authenticated HTTP proxy for QQ Open Platform channel APIs. " +
+        "Common endpoints: " +
+        "list guilds GET /users/@me/guilds | " +
+        "list channels GET /guilds/{guild_id}/channels | " +
+        "get channel GET /channels/{channel_id} | " +
+        "create channel POST /guilds/{guild_id}/channels | " +
+        "list members GET /guilds/{guild_id}/members?after=0&limit=100 | " +
+        "get member GET /guilds/{guild_id}/members/{user_id} | " +
+        "list threads GET /channels/{channel_id}/threads | " +
+        "create thread PUT /channels/{channel_id}/threads | " +
+        "create announce POST /guilds/{guild_id}/announces | " +
+        "create schedule POST /channels/{channel_id}/schedules. " +
+        "See the qqbot-channel skill for full endpoint details.",
+      parameters: ChannelApiSchema,
+      async execute(_toolCallId, params) {
+        const accessToken = await getAccessToken(account.appId, account.clientSecret);
+        return executeChannelApi(params as ChannelApiParams, { accessToken });
+      },
+    },
+    { name: "qqbot_channel_api" },
+  );
+}

package/src/bridge/tools/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Aggregate QQBot plugin tool registrations.
+ *
+ * New tools should be added here rather than in the channel-entry contract
+ * file so that the plugin-level `index.ts` stays a pure declaration.
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { registerChannelTool } from "./channel.js";
+import { registerRemindTool } from "./remind.js";
+
+export function registerQQBotTools(api: OpenClawPluginApi): void {
+  registerChannelTool(api);
+  registerRemindTool(api);
+}

package/src/bridge/tools/remind.test.ts

@@ -0,0 +1,124 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { callGatewayToolMock } = vi.hoisted(() => ({
+  callGatewayToolMock: vi.fn(),
+}));
+
+vi.mock("openclaw/plugin-sdk/agent-harness-runtime", () => ({
+  callGatewayTool: callGatewayToolMock,
+}));
+
+import { createRemindTool } from "./remind.js";
+
+describe("bridge/tools/remind", () => {
+  beforeEach(() => {
+    callGatewayToolMock.mockReset();
+    callGatewayToolMock.mockResolvedValue({ ok: true });
+  });
+
+  it("marks qqbot_remind as owner-only", () => {
+    const tool = createRemindTool();
+    expect(tool.ownerOnly).toBe(true);
+  });
+
+  it("schedules reminders directly through Gateway cron with ambient QQ delivery context", async () => {
+    callGatewayToolMock.mockResolvedValue({ id: "job-1" });
+    const tool = createRemindTool({
+      senderIsOwner: true,
+      deliveryContext: { to: "qqbot:c2c:user-openid", accountId: "bot2" },
+    });
+
+    const result = await tool.execute("tool-call-1", {
+      action: "add",
+      content: "drink water",
+      time: "5m",
+    });
+
+    expect(callGatewayToolMock).toHaveBeenCalledWith(
+      "cron.add",
+      { timeoutMs: 60_000 },
+      {
+        job: expect.objectContaining({
+          sessionTarget: "isolated",
+          payload: { kind: "agentTurn", message: expect.stringContaining("drink water") },
+          delivery: {
+            mode: "announce",
+            channel: "qqbot",
+            to: "qqbot:c2c:user-openid",
+            accountId: "bot2",
+          },
+        }),
+      },
+    );
+    expect(result.details).toEqual({
+      ok: true,
+      action: "add",
+      summary: '⏰ Reminder in 5m: "drink water"',
+      cronResult: { id: "job-1" },
+    });
+  });
+
+  it("routes list and remove through Gateway cron without exposing generic cron to the model", async () => {
+    const tool = createRemindTool({ senderIsOwner: true });
+
+    await tool.execute("tool-call-1", { action: "list" });
+    await tool.execute("tool-call-2", { action: "remove", jobId: "job-1" });
+
+    expect(callGatewayToolMock).toHaveBeenNthCalledWith(1, "cron.list", { timeoutMs: 60_000 }, {});
+    expect(callGatewayToolMock).toHaveBeenNthCalledWith(
+      2,
+      "cron.remove",
+      { timeoutMs: 60_000 },
+      { jobId: "job-1" },
+    );
+  });
+
+  it("supports injected cron scheduler dependencies for engine-level tests", async () => {
+    const callCron = vi.fn(async () => ({ id: "job-1" }));
+    const tool = createRemindTool(
+      {
+        senderIsOwner: true,
+        deliveryContext: { to: "qqbot:c2c:user-openid", accountId: "bot2" },
+      },
+      { callCron },
+    );
+
+    await tool.execute("tool-call-1", {
+      action: "add",
+      content: "drink water",
+      time: "5m",
+    });
+
+    expect(callCron).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "add",
+        job: expect.objectContaining({
+          delivery: expect.objectContaining({ to: "qqbot:c2c:user-openid", accountId: "bot2" }),
+        }),
+      }),
+    );
+    expect(callGatewayToolMock).not.toHaveBeenCalled();
+  });
+
+  it("does not schedule when sender ownership is missing", async () => {
+    const callCron = vi.fn(async () => ({ id: "job-1" }));
+    const tool = createRemindTool(
+      {
+        deliveryContext: { to: "qqbot:c2c:user-openid", accountId: "bot2" },
+      },
+      { callCron },
+    );
+
+    const result = await tool.execute("tool-call-1", {
+      action: "add",
+      content: "drink water",
+      time: "5m",
+    });
+
+    expect(callCron).not.toHaveBeenCalled();
+    expect(callGatewayToolMock).not.toHaveBeenCalled();
+    expect(result.details).toEqual({
+      error: "QQ reminders require an owner-authorized sender.",
+    });
+  });
+});

package/src/bridge/tools/remind.ts

@@ -0,0 +1,91 @@
+import { callGatewayTool } from "openclaw/plugin-sdk/agent-harness-runtime";
+import type {
+  AnyAgentTool,
+  OpenClawPluginApi,
+  OpenClawPluginToolContext,
+} from "openclaw/plugin-sdk/core";
+import { RemindSchema, executeScheduledRemind } from "../../engine/tools/remind-logic.js";
+import type { RemindCronAction, RemindParams } from "../../engine/tools/remind-logic.js";
+import { getRequestContext } from "../../engine/utils/request-context.js";
+
+type CronGatewayCaller = (params: RemindCronAction) => Promise<unknown>;
+
+type RemindToolDeps = {
+  callCron: CronGatewayCaller;
+};
+
+const DEFAULT_GATEWAY_TIMEOUT_MS = 60_000;
+
+function unexpectedCronParams(params: never): never {
+  throw new Error(`Unsupported reminder cron action: ${JSON.stringify(params)}`);
+}
+
+const defaultDeps: RemindToolDeps = {
+  callCron: async (params) => {
+    switch (params.action) {
+      case "list":
+        return await callGatewayTool("cron.list", { timeoutMs: DEFAULT_GATEWAY_TIMEOUT_MS }, {});
+      case "remove":
+        return await callGatewayTool(
+          "cron.remove",
+          { timeoutMs: DEFAULT_GATEWAY_TIMEOUT_MS },
+          { jobId: params.jobId },
+        );
+      case "add":
+        return await callGatewayTool(
+          "cron.add",
+          { timeoutMs: DEFAULT_GATEWAY_TIMEOUT_MS },
+          { job: params.job },
+        );
+    }
+    return unexpectedCronParams(params);
+  },
+};
+
+export function createRemindTool(
+  toolContext: OpenClawPluginToolContext = {},
+  deps: RemindToolDeps = defaultDeps,
+): AnyAgentTool {
+  return {
+    name: "qqbot_remind",
+    label: "QQBot Reminder",
+    ownerOnly: true,
+    description:
+      "Create, list, and remove QQ reminders. " +
+      "This tool schedules Gateway cron jobs directly; do not call the cron tool after it succeeds.\n" +
+      "Create: action=add, content=message, time=schedule (to is optional, " +
+      "resolved automatically from the current conversation)\n" +
+      "List: action=list\n" +
+      "Remove: action=remove, jobId=job id from list\n" +
+      'Time examples: "5m", "1h", "0 8 * * *"',
+    parameters: RemindSchema,
+    async execute(_toolCallId, params) {
+      if (toolContext.senderIsOwner !== true) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({
+                error: "QQ reminders require an owner-authorized sender.",
+              }),
+            },
+          ],
+          details: { error: "QQ reminders require an owner-authorized sender." },
+        };
+      }
+      const ctx = getRequestContext();
+      return await executeScheduledRemind(
+        params as RemindParams,
+        {
+          fallbackTo: ctx?.target ?? toolContext.deliveryContext?.to,
+          fallbackAccountId: ctx?.accountId ?? toolContext.deliveryContext?.accountId,
+        },
+        deps.callCron,
+      );
+    },
+  };
+}
+
+export function registerRemindTool(api: OpenClawPluginApi): void {
+  api.registerTool((ctx) => createRemindTool(ctx), { name: "qqbot_remind" });
+}

package/src/channel.setup.ts

@@ -0,0 +1,33 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+import "./bridge/bootstrap.js";
+import { qqbotConfigAdapter, qqbotMeta, qqbotSetupAdapterShared } from "./bridge/config-shared.js";
+import { qqbotSetupWizard } from "./bridge/setup/surface.js";
+import { qqbotChannelConfigSchema } from "./config-schema.js";
+import type { ResolvedQQBotAccount } from "./types.js";
+
+/**
+ * Setup-only QQBot plugin — lightweight subset used during `openclaw onboard`
+ * and `openclaw configure` without pulling the full runtime dependencies.
+ */
+export const qqbotSetupPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
+  id: "qqbot",
+  setupWizard: qqbotSetupWizard,
+  meta: {
+    ...qqbotMeta,
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+    reactions: false,
+    threads: false,
+    blockStreaming: true,
+  },
+  reload: { configPrefixes: ["channels.qqbot"] },
+  configSchema: qqbotChannelConfigSchema,
+  config: {
+    ...qqbotConfigAdapter,
+  },
+  setup: {
+    ...qqbotSetupAdapterShared,
+  },
+};

package/src/channel.ts

@@ -0,0 +1,288 @@
+import { getExecApprovalReplyMetadata } from "openclaw/plugin-sdk/approval-runtime";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+// Register the PlatformAdapter before any core/ module is used.
+import "./bridge/bootstrap.js";
+import { getQQBotApprovalCapability } from "./bridge/approval/capability.js";
+import { qqbotConfigAdapter, qqbotMeta, qqbotSetupAdapterShared } from "./bridge/config-shared.js";
+import {
+  applyQQBotAccountConfig,
+  DEFAULT_ACCOUNT_ID,
+  resolveQQBotAccount,
+} from "./bridge/config.js";
+import type { GatewayContext } from "./bridge/gateway.js";
+import { toGatewayAccount, writeOpenClawConfigThroughRuntime } from "./bridge/narrowing.js";
+import { getQQBotRuntime } from "./bridge/runtime.js";
+import { qqbotSetupWizard } from "./bridge/setup/surface.js";
+import { qqbotChannelConfigSchema } from "./config-schema.js";
+import { loadCredentialBackup, saveCredentialBackup } from "./engine/config/credential-backup.js";
+import { clearAccountCredentials } from "./engine/config/credentials.js";
+import {
+  normalizeTarget as coreNormalizeTarget,
+  looksLikeQQBotTarget,
+} from "./engine/messaging/target-parser.js";
+import type { ResolvedQQBotAccount } from "./types.js";
+
+// Shared promise so concurrent multi-account startups serialize the dynamic
+// import of the gateway module, avoiding an ESM circular-dependency race.
+let _gatewayModulePromise: Promise<typeof import("./bridge/gateway.js")> | undefined;
+function loadGatewayModule(): Promise<typeof import("./bridge/gateway.js")> {
+  _gatewayModulePromise ??= import("./bridge/gateway.js");
+  return _gatewayModulePromise;
+}
+
+const EXEC_APPROVAL_COMMAND_RE =
+  /\/approve(?:@[^\s]+)?\s+[A-Za-z0-9][A-Za-z0-9._:-]*\s+(?:allow-once|allow-always|always|deny)\b/i;
+
+function persistAccountCredentialSnapshot(account: ResolvedQQBotAccount): void {
+  if (account.appId && account.clientSecret) {
+    saveCredentialBackup(account.accountId, account.appId, account.clientSecret);
+  }
+}
+
+function shouldSuppressLocalQQBotApprovalPrompt(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+  payload: { text?: string; channelData?: unknown };
+  hint?: { kind: "approval-pending" | "approval-resolved"; approvalKind: "exec" | "plugin" };
+}): boolean {
+  if (params.hint?.kind !== "approval-pending" || params.hint.approvalKind !== "exec") {
+    return false;
+  }
+  const account = resolveQQBotAccount(params.cfg, params.accountId);
+  if (!account.enabled || account.secretSource === "none") {
+    return false;
+  }
+  if (getExecApprovalReplyMetadata(params.payload as never)) {
+    return true;
+  }
+  const text = typeof params.payload.text === "string" ? params.payload.text : "";
+  return EXEC_APPROVAL_COMMAND_RE.test(text);
+}
+
+export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
+  id: "qqbot",
+  setupWizard: qqbotSetupWizard,
+  meta: {
+    ...qqbotMeta,
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+    reactions: false,
+    threads: false,
+    blockStreaming: true,
+  },
+  reload: { configPrefixes: ["channels.qqbot"] },
+  configSchema: qqbotChannelConfigSchema,
+  config: {
+    ...qqbotConfigAdapter,
+    /**
+     * Treat an account as configured when either the live config has
+     * credentials OR a recoverable credential backup exists. This mirrors
+     * the standalone plugin and lets the gateway survive a hot upgrade
+     * that wiped openclaw.json mid-flight.
+     */
+    isConfigured: (account: ResolvedQQBotAccount | undefined) => {
+      if (qqbotConfigAdapter.isConfigured(account)) {
+        return true;
+      }
+      if (!account) {
+        return false;
+      }
+      const backup = loadCredentialBackup(account.accountId);
+      return Boolean(backup?.appId && backup?.clientSecret);
+    },
+  },
+  setup: {
+    ...qqbotSetupAdapterShared,
+  },
+  approvalCapability: getQQBotApprovalCapability(),
+  messaging: {
+    targetPrefixes: ["qqbot"],
+    /** Normalize common QQ Bot target formats into the canonical qqbot:... form. */
+    normalizeTarget: coreNormalizeTarget,
+    targetResolver: {
+      /** Return true when the id looks like a QQ Bot target. */
+      looksLikeId: looksLikeQQBotTarget,
+      hint: "QQ Bot target format: qqbot:c2c:openid (direct) or qqbot:group:groupid (group)",
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: (text, limit) => getQQBotRuntime().channel.text.chunkMarkdownText(text, limit),
+    chunkerMode: "markdown",
+    textChunkLimit: 5000,
+    shouldSuppressLocalPayloadPrompt: ({ cfg, accountId, payload, hint }) =>
+      shouldSuppressLocalQQBotApprovalPrompt({
+        cfg,
+        accountId,
+        payload,
+        hint,
+      }),
+    sendText: async ({ to, text, accountId, replyToId, cfg }) => {
+      // Ensure bridge/gateway.ts module-level registrations (audio adapter factory,
+      // platform adapter, etc.) have executed before engine code runs.
+      await loadGatewayModule();
+      const account = resolveQQBotAccount(cfg, accountId);
+      const { sendText } = await import("./engine/messaging/outbound.js");
+      const result = await sendText({
+        to,
+        text,
+        accountId,
+        replyToId,
+        account: toGatewayAccount(account),
+      });
+      return {
+        channel: "qqbot" as const,
+        messageId: result.messageId ?? "",
+        meta: result.error ? { error: result.error } : undefined,
+      };
+    },
+    sendMedia: async ({ to, text, mediaUrl, accountId, replyToId, cfg }) => {
+      // Same guard as sendText — ensure adapters are registered.
+      await loadGatewayModule();
+      const account = resolveQQBotAccount(cfg, accountId);
+      const { sendMedia } = await import("./engine/messaging/outbound.js");
+      const result = await sendMedia({
+        to,
+        text: text ?? "",
+        mediaUrl: mediaUrl ?? "",
+        accountId,
+        replyToId,
+        account: toGatewayAccount(account),
+      });
+      return {
+        channel: "qqbot" as const,
+        messageId: result.messageId ?? "",
+        meta: result.error ? { error: result.error } : undefined,
+      };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      let { account, cfg } = ctx;
+      const { abortSignal, log } = ctx;
+
+      // Recover credentials from the per-account backup if the live
+      // config is missing appId/secret (e.g. a hot-upgrade wiped
+      // openclaw.json). We only restore when both fields are empty so a
+      // user's intentional clear isn't silently undone.
+      if (!account.appId || !account.clientSecret) {
+        const backup = loadCredentialBackup(account.accountId);
+        if (backup?.appId && backup?.clientSecret) {
+          try {
+            const nextCfg = applyQQBotAccountConfig(cfg, account.accountId, {
+              appId: backup.appId,
+              clientSecret: backup.clientSecret,
+            });
+            await writeOpenClawConfigThroughRuntime(getQQBotRuntime(), nextCfg);
+            cfg = nextCfg;
+            account = resolveQQBotAccount(nextCfg, account.accountId);
+            log?.info(
+              `[qqbot:${account.accountId}] Restored credentials from backup (appId=${account.appId})`,
+            );
+          } catch (err) {
+            log?.error(
+              `[qqbot:${account.accountId}] Failed to restore credentials from backup: ${err instanceof Error ? err.message : String(err)}`,
+            );
+          }
+        }
+      }
+
+      // Serialize the dynamic import so concurrent multi-account startups
+      // do not hit an ESM circular-dependency race where the gateway chunk's
+      // transitive imports have not finished evaluating yet.
+      const { startGateway } = await loadGatewayModule();
+
+      log?.info(
+        `[qqbot:${account.accountId}] Starting gateway — appId=${account.appId}, enabled=${account.enabled}, name=${account.name ?? "unnamed"}`,
+      );
+
+      await startGateway({
+        account,
+        abortSignal,
+        cfg,
+        log,
+        channelRuntime: ctx.channelRuntime as GatewayContext["channelRuntime"],
+        onReady: () => {
+          log?.info(`[qqbot:${account.accountId}] Gateway ready`);
+          ctx.setStatus({
+            ...ctx.getStatus(),
+            running: true,
+            connected: true,
+            lastConnectedAt: Date.now(),
+          });
+          // Snapshot credentials so we can recover from the next hot
+          // upgrade that might wipe openclaw.json mid-flight.
+          persistAccountCredentialSnapshot(account);
+        },
+        onResumed: () => {
+          log?.info(`[qqbot:${account.accountId}] Gateway resumed`);
+          ctx.setStatus({
+            ...ctx.getStatus(),
+            running: true,
+            connected: true,
+            lastConnectedAt: Date.now(),
+          });
+          persistAccountCredentialSnapshot(account);
+        },
+        onError: (error) => {
+          log?.error(`[qqbot:${account.accountId}] Gateway error: ${error.message}`);
+          ctx.setStatus({
+            ...ctx.getStatus(),
+            lastError: error.message,
+          });
+        },
+      });
+    },
+    logoutAccount: async ({ accountId, cfg }) => {
+      const { nextCfg, cleared, changed } = clearAccountCredentials(
+        cfg as unknown as Record<string, unknown>,
+        accountId,
+      );
+
+      if (changed) {
+        await writeOpenClawConfigThroughRuntime(getQQBotRuntime(), nextCfg as OpenClawConfig);
+      }
+
+      const resolved = resolveQQBotAccount((changed ? nextCfg : cfg) as OpenClawConfig, accountId);
+      const loggedOut = resolved.secretSource === "none";
+      const envToken = Boolean(process.env.QQBOT_CLIENT_SECRET);
+
+      return { ok: true, cleared, envToken, loggedOut };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      connected: false,
+      lastConnectedAt: null,
+      lastError: null,
+      lastInboundAt: null,
+      lastOutboundAt: null,
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      tokenSource: snapshot.tokenSource ?? "none",
+      running: snapshot.running ?? false,
+      connected: snapshot.connected ?? false,
+      lastConnectedAt: snapshot.lastConnectedAt ?? null,
+      lastError: snapshot.lastError ?? null,
+    }),
+    buildAccountSnapshot: ({ account, runtime }) => ({
+      accountId: account?.accountId ?? DEFAULT_ACCOUNT_ID,
+      name: account?.name,
+      enabled: account?.enabled ?? false,
+      configured: Boolean(account?.appId && account?.clientSecret),
+      tokenSource: account?.secretSource,
+      running: runtime?.running ?? false,
+      connected: runtime?.connected ?? false,
+      lastConnectedAt: runtime?.lastConnectedAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+    }),
+  },
+};

package/src/command-auth.test.ts

@@ -0,0 +1,62 @@
+/**
+ * Regression tests for QQBot command authorization alignment with the shared
+ * command-auth model.
+ *
+ * Covers the regression identified in the code review:
+ *
+ *   allowFrom entries with the qqbot: prefix must normalize correctly so that
+ *   "qqbot:<id>" in channel.allowFrom matches the inbound event.senderId "<id>".
+ *   Verified against the normalization logic in the gateway.ts inbound path.
+ *
+ * Note: commands.allowFrom.qqbot precedence over channel allowFrom is enforced
+ * by the framework's resolveCommandAuthorization(). QQBot routes requireAuth:true
+ * commands through the framework (api.registerCommand), so that behavior is
+ * covered by the framework's own tests rather than duplicated here.
+ */
+
+import { describe, expect, it } from "vitest";
+import { qqbotPlugin } from "./channel.js";
+
+// ---------------------------------------------------------------------------
+// qqbot: prefix normalization for inbound commandAuthorized
+//
+// Uses qqbotPlugin.config.formatAllowFrom directly — the same function the
+// fixed gateway.ts inbound path calls — so the test stays in sync with the
+// actual implementation without duplicating the logic.
+// ---------------------------------------------------------------------------
+
+describe("qqbot: prefix normalization for inbound commandAuthorized", () => {
+  const formatAllowFrom = qqbotPlugin.config.formatAllowFrom!;
+
+  /** Mirrors the fixed gateway.ts inbound commandAuthorized computation. */
+  function resolveInboundCommandAuthorized(rawAllowFrom: string[], senderId: string): boolean {
+    const normalizedAllowFrom = formatAllowFrom({
+      cfg: {} as never,
+      accountId: null,
+      allowFrom: rawAllowFrom,
+    });
+    const normalizedSenderId = senderId.replace(/^qqbot:/i, "").toUpperCase();
+    const allowAll = normalizedAllowFrom.length === 0 || normalizedAllowFrom.some((e) => e === "*");
+    return allowAll || normalizedAllowFrom.includes(normalizedSenderId);
+  }
+
+  it("authorizes when allowFrom uses qqbot: prefix and senderId is the bare id", () => {
+    expect(resolveInboundCommandAuthorized(["qqbot:USER123"], "USER123")).toBe(true);
+  });
+
+  it("authorizes when qqbot: prefix is mixed case", () => {
+    expect(resolveInboundCommandAuthorized(["QQBot:user123"], "USER123")).toBe(true);
+  });
+
+  it("denies a sender not in the qqbot:-prefixed allowFrom list", () => {
+    expect(resolveInboundCommandAuthorized(["qqbot:USER123"], "OTHER")).toBe(false);
+  });
+
+  it("authorizes any sender when allowFrom is empty (open)", () => {
+    expect(resolveInboundCommandAuthorized([], "ANYONE")).toBe(true);
+  });
+
+  it("authorizes any sender when allowFrom contains wildcard *", () => {
+    expect(resolveInboundCommandAuthorized(["*"], "ANYONE")).toBe(true);
+  });
+});