openclaw
diff --git a/‎CHANGELOG.md‎
Lines changed: 1 addition & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎extensions/qqbot/openclaw.plugin.json‎
Lines changed: 8 additions & 0 deletions b/‎extensions/qqbot/openclaw.plugin.json‎
Lines changed: 8 additions & 0 deletions
diff --git a/‎extensions/qqbot/package.json‎
Lines changed: 4 additions & 4 deletions b/‎extensions/qqbot/package.json‎
Lines changed: 4 additions & 4 deletions
diff --git a/‎extensions/qqbot/skills/qqbot-media/SKILL.md‎
Lines changed: 6 additions & 5 deletions b/‎extensions/qqbot/skills/qqbot-media/SKILL.md‎
Lines changed: 6 additions & 5 deletions
diff --git a/‎extensions/qqbot/src/bridge/config.ts‎
Lines changed: 9 additions & 1 deletion b/‎extensions/qqbot/src/bridge/config.ts‎
Lines changed: 9 additions & 1 deletion
diff --git a/‎extensions/qqbot/src/bridge/gateway.ts‎
Lines changed: 64 additions & 73 deletions b/‎extensions/qqbot/src/bridge/gateway.ts‎
Lines changed: 64 additions & 73 deletions
diff --git a/‎extensions/qqbot/src/bridge/narrowing.ts‎
Lines changed: 31 additions & 0 deletions b/‎extensions/qqbot/src/bridge/narrowing.ts‎
Lines changed: 31 additions & 0 deletions
diff --git a/‎extensions/qqbot/src/bridge/runtime.ts‎
Lines changed: 2 additions & 1 deletion b/‎extensions/qqbot/src/bridge/runtime.ts‎
Lines changed: 2 additions & 1 deletion
@@ -7,6 +7,7 @@ Docs: https://docs.openclaw.ai
 ### Changes
 
 - Channels/Yuanbao: register the Tencent Yuanbao external channel plugin (`openclaw-plugin-yuanbao`) in the official channel catalog, contract suites, and community plugin docs, with a new `docs/channels/yuanbao.md` quick-start guide for WebSocket bot DMs and group chats. (#72756) Thanks @loongfay.
+- Channels/QQBot: add full group chat support (history tracking, @-mention gating, activation modes, per-group config, FIFO message queue with deliver debounce), C2C `stream_messages` streaming with a `StreamingController` lifecycle manager, unified `sendMedia` with chunked upload for large files, and refactor the engine into pipeline stages, focused outbound submodules, builtin slash-command modules, and explicit DI ports via `createEngineAdapters()`. (#70624) Thanks @cxyhhhhh.
 
 ## 2026.4.26
 
 
@@ -91,6 +91,10 @@
                     "type": "string",
                     "enum": ["off", "partial"],
                     "default": "partial"
+                  },
+                  "c2cStreamApi": {
+                    "type": "boolean",
+                    "description": "Use QQ C2C official stream_messages API (single-message typing-style updates)."
                   }
                 }
               }
@@ -136,6 +140,10 @@
                 "type": "string",
                 "enum": ["off", "partial"],
                 "default": "partial"
+              },
+              "c2cStreamApi": {
+                "type": "boolean",
+                "description": "Use QQ C2C official stream_messages API (single-message typing-style updates)."
               }
             }
           }
 
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/qqbot",
-  "version": "2026.4.25",
+  "version": "2026.4.26",
   "private": false,
   "description": "OpenClaw QQ Bot channel plugin",
   "type": "module",
@@ -17,7 +17,7 @@
     "openclaw": "workspace:*"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.4.25"
+    "openclaw": ">=2026.4.26"
   },
   "peerDependenciesMeta": {
     "openclaw": {
@@ -46,10 +46,10 @@
       "minHostVersion": ">=2026.4.10"
     },
     "compat": {
-      "pluginApi": ">=2026.4.25"
+      "pluginApi": ">=2026.4.26"
     },
     "build": {
-      "openclawVersion": "2026.4.25"
+      "openclawVersion": "2026.4.26"
     },
     "bundle": {
       "stageRuntimeDependencies": true
 
@@ -29,8 +29,9 @@ metadata: { "openclaw": { "emoji": "📸", "requires": { "config": ["channels.qq
 
 1. **路径必须是绝对路径**（以 `/` 或 `http` 开头）
 2. **标签必须用开闭标签包裹路径**：`<qqmedia>路径</qqmedia>`
-3. **文件大小上限 10MB**
-4. **你有能力发送本地图片/文件**，直接用标签包裹路径即可，**不要说"无法发送"**
-5. 发送语音时不要重复语音中已朗读的文字
-6. 多个媒体用多个标签
-7. 以会话上下文中的能力说明为准（如未启用语音则不要发语音）
+3. **待发送的本地文件须落在 OpenClaw 媒体目录下**：生成、下载或复制出的文件应写入 **`~/.openclaw/media/qqbot/`**（或其子目录），再写进 `<qqmedia>`。不要只放在 `~/.openclaw/workspace/` 等工作区根目录——平台安全策略只允许从 `~/.openclaw/media/`（含 `media/qqbot`）等受信根路径上传，否则会拦截、发不出去。
+4. **文件大小上限**：图片 30MB / 视频 100MB / 文件 100MB / 语音 20MB
+5. **你有能力发送本地图片/文件**，直接用标签包裹路径即可，**不要说"无法发送"**
+6. 发送语音时不要重复语音中已朗读的文字
+7. 多个媒体用多个标签
+8. 以会话上下文中的能力说明为准（如未启用语音则不要发语音）
@@ -37,9 +37,17 @@ export function resolveQQBotAccount(
   const base = resolveAccountBase(raw, accountId);
 
   const qqbot = cfg.channels?.qqbot as QQBotChannelConfig | undefined;
+  /**
+   * Legacy top-level account uses `channels.qqbot` as the base, but per-account
+   * fields (allowFrom, streaming, …) often live under `accounts.default`.
+   * Merge that slice so runtime sees `config.streaming` etc.
+   */
   const accountConfig: QQBotAccountConfig =
     base.accountId === DEFAULT_ACCOUNT_ID
-      ? (qqbot ?? {})
+      ? {
+          ...qqbot,
+          ...qqbot?.accounts?.[DEFAULT_ACCOUNT_ID],
+        }
       : (qqbot?.accounts?.[base.accountId] ?? {});
 
   let clientSecret = "";
 
@@ -1,78 +1,41 @@
 /**
- * Gateway entry point — thin shell that passes the PluginRuntime to
- * core/gateway/gateway.ts.
+ * Gateway entry point — thin bridge shell that constructs
+ * {@link EngineAdapters} and passes them to the engine's
+ * `startGateway`.
  *
- * All module dependencies are imported directly by the core gateway.
- * This file only provides the runtime object (which is dynamically
- * injected by the framework at startup).
+ * All adapter dependencies are assembled here in one place.
  */
 
 import { resolveRuntimeServiceVersion } from "openclaw/plugin-sdk/cli-runtime";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
-import {
-  registerVersionResolver,
-  registerPluginVersion,
-  registerApproveRuntimeGetter,
-} from "../engine/commands/slash-commands-impl.js";
+import type { EngineAdapters } from "../engine/adapter/index.js";
 import {
   startGateway as coreStartGateway,
   type CoreGatewayContext,
 } from "../engine/gateway/gateway.js";
-import type { GatewayAccount } from "../engine/gateway/types.js";
-import { registerOutboundAudioAdapterFactory } from "../engine/messaging/outbound.js";
+import type { GatewayPluginRuntime } from "../engine/gateway/types.js";
 import { initSender, registerAccount } from "../engine/messaging/sender.js";
 import type { EngineLogger } from "../engine/types.js";
 import * as _audioModule from "../engine/utils/audio.js";
+import { formatDuration } from "../engine/utils/format.js";
 import { debugLog, debugError } from "../engine/utils/log.js";
-import { registerTextChunker } from "../engine/utils/text-chunk.js";
 import type { ResolvedQQBotAccount } from "../types.js";
 import { ensurePlatformAdapter } from "./bootstrap.js";
 import { setBridgeLogger } from "./logger.js";
+import { toGatewayAccount } from "./narrowing.js";
 import { resolveQQBotPluginVersion } from "./plugin-version.js";
 import { getQQBotRuntime, getQQBotRuntimeForEngine } from "./runtime.js";
+import { createSdkHistoryAdapter, createSdkMentionGateAdapter } from "./sdk-adapter.js";
 
-// Register framework SDK version resolver for core/ slash commands.
-registerVersionResolver(resolveRuntimeServiceVersion);
+// ---- One-time startup initialization (module-level) ----
 
-// Inject plugin + framework versions into sender and into the slash
-// command registry. The plugin version is read from this plugin's own
-// `package.json` by walking up from this file's URL, which is robust
-// against source-vs-dist layout differences.
 const _pluginVersion = resolveQQBotPluginVersion(import.meta.url);
 initSender({
   pluginVersion: _pluginVersion,
   openclawVersion: resolveRuntimeServiceVersion(),
 });
-registerPluginVersion(_pluginVersion);
 
-// Register runtime getter for /bot-approve config management.
-registerApproveRuntimeGetter(() => {
-  const rt = getQQBotRuntime();
-  return {
-    config: rt.config as {
-      current: () => Record<string, unknown>;
-      replaceConfigFile: (params: {
-        nextConfig: Record<string, unknown>;
-        afterWrite: { mode: "auto" };
-      }) => Promise<unknown>;
-    },
-  };
-});
-
-// Register audio adapter factory so outbound.sendMedia can lazy-init even
-// when startGateway() hasn't run yet (bundler chunk-splitting scenario).
-registerOutboundAudioAdapterFactory(() => {
-  // Use a synchronous require-like approach: the audio module should already
-  // be loaded by the time the factory is invoked (gateway has started).
-  // We import it at the top and reference it here.
-  return {
-    audioFileToSilkBase64: async (p: string, f?: string[]) =>
-      (await _audioModule.audioFileToSilkBase64(p, f)) ?? undefined,
-    isAudioFile: (p: string, m?: string) => _audioModule.isAudioFile(p, m),
-    shouldTranscodeVoice: (p: string) => _audioModule.shouldTranscodeVoice(p),
-    waitForFile: (p: string, ms?: number) => _audioModule.waitForFile(p, ms),
-  };
-});
+// ============ Public types ============
 
 export interface GatewayContext {
   account: ResolvedQQBotAccount;
@@ -99,32 +62,62 @@ export interface GatewayContext {
   };
 }
 
+// ============ Adapter factory ============
+
+/**
+ * Create the full set of engine adapters from the bridge layer.
+ *
+ * This is the **single assembly point** — all SDK → engine binding
+ * happens here. The engine receives a fully-populated
+ * {@link EngineAdapters} object with zero global singletons.
+ */
+function createEngineAdapters(_runtime: GatewayPluginRuntime): EngineAdapters {
+  return {
+    history: createSdkHistoryAdapter(),
+    mentionGate: createSdkMentionGateAdapter(),
+    audioConvert: {
+      convertSilkToWav: _audioModule.convertSilkToWav,
+      isVoiceAttachment: _audioModule.isVoiceAttachment,
+      formatDuration,
+    },
+    outboundAudio: {
+      audioFileToSilkBase64: async (p: string, f?: string[]) =>
+        (await _audioModule.audioFileToSilkBase64(p, f)) ?? undefined,
+      isAudioFile: (p: string, m?: string) => _audioModule.isAudioFile(p, m),
+      shouldTranscodeVoice: (p: string) => _audioModule.shouldTranscodeVoice(p),
+      waitForFile: (p: string, ms?: number) => _audioModule.waitForFile(p, ms),
+    },
+    commands: {
+      resolveVersion: resolveRuntimeServiceVersion,
+      pluginVersion: _pluginVersion,
+      approveRuntimeGetter: () => {
+        const rt = getQQBotRuntime();
+        return { config: rt.config };
+      },
+    },
+  };
+}
+
+// ============ startGateway ============
+
 /**
  * Start the Gateway WebSocket connection.
  *
- * Passes the PluginRuntime to core/gateway/gateway.ts.
- * All other dependencies are imported directly by the core module.
+ * Assembles all adapters and passes them to the engine's core gateway.
  */
 export async function startGateway(ctx: GatewayContext): Promise<void> {
-  // Ensure the PlatformAdapter is registered before any engine code runs.
-  // When the bundler splits code into separate chunks, bootstrap.ts's
-  // side-effect registration may not have executed yet at this point.
   ensurePlatformAdapter();
 
   const runtime = getQQBotRuntimeForEngine();
-
-  // Create per-account logger with auto [qqbot:{accountId}] prefix.
   const accountLogger = createAccountLogger(ctx.log, ctx.account.accountId);
 
-  // Register into engine sender (per-appId logger + API config) and bridge layer.
+  // Per-account registration (still global — sender is a leaf utility).
   registerAccount(ctx.account.appId, {
     logger: accountLogger,
     markdownSupport: ctx.account.markdownSupport,
   });
   setBridgeLogger(accountLogger);
 
-  registerTextChunker((text, limit) => runtime.channel.text.chunkMarkdownText(text, limit));
-
   if (ctx.channelRuntime) {
     accountLogger.info("Registering approval.native runtime context");
     const lease = ctx.channelRuntime.runtimeContexts.register({
@@ -140,44 +133,42 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
   }
 
   const coreCtx: CoreGatewayContext = {
-    account: ctx.account as unknown as GatewayAccount,
+    account: toGatewayAccount(ctx.account),
     abortSignal: ctx.abortSignal,
     cfg: ctx.cfg,
     onReady: ctx.onReady,
     onResumed: ctx.onResumed,
     onError: ctx.onError,
     log: accountLogger,
     runtime,
+    adapters: createEngineAdapters(runtime),
   };
 
   return coreStartGateway(coreCtx);
 }
 
 // ============ Per-account logger factory ============
 
-/**
- * Create an EngineLogger that auto-prefixes all messages with `[qqbot:{accountId}]`.
- *
- * Follows the WhatsApp pattern of per-connection loggers — each account gets
- * its own logger instance so multi-account logs are automatically attributed.
- */
 function createAccountLogger(
   raw: GatewayContext["log"] | undefined,
   accountId: string,
 ): EngineLogger {
   const prefix = `[${accountId}]`;
+  const withMeta = (msg: string, meta?: Record<string, unknown>) =>
+    meta && Object.keys(meta).length > 0 ? `${msg} ${JSON.stringify(meta)}` : msg;
+
   if (!raw) {
     return {
-      info: (msg) => debugLog(`${prefix} ${msg}`),
-      error: (msg) => debugError(`${prefix} ${msg}`),
-      warn: (msg) => debugError(`${prefix} ${msg}`),
-      debug: (msg) => debugLog(`${prefix} ${msg}`),
+      info: (msg, meta) => debugLog(`${prefix} ${withMeta(msg, meta)}`),
+      error: (msg, meta) => debugError(`${prefix} ${withMeta(msg, meta)}`),
+      warn: (msg, meta) => debugError(`${prefix} ${withMeta(msg, meta)}`),
+      debug: (msg, meta) => debugLog(`${prefix} ${withMeta(msg, meta)}`),
     };
   }
   return {
-    info: (msg) => raw.info(`${prefix} ${msg}`),
-    error: (msg) => raw.error(`${prefix} ${msg}`),
-    warn: (msg) => raw.error(`${prefix} ${msg}`),
-    debug: (msg) => raw.debug?.(`${prefix} ${msg}`),
+    info: (msg, meta) => raw.info(`${prefix} ${withMeta(msg, meta)}`),
+    error: (msg, meta) => raw.error(`${prefix} ${withMeta(msg, meta)}`),
+    warn: (msg, meta) => raw.error(`${prefix} ${withMeta(msg, meta)}`),
+    debug: (msg, meta) => raw.debug?.(`${prefix} ${withMeta(msg, meta)}`),
   };
 }
@@ -0,0 +1,31 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+import type { GatewayAccount } from "../engine/types.js";
+import type { ResolvedQQBotAccount } from "../types.js";
+
+/**
+ * Map resolved plugin account to the engine gateway account shape (single assertion on nested config).
+ */
+export function toGatewayAccount(account: ResolvedQQBotAccount): GatewayAccount {
+  return {
+    accountId: account.accountId,
+    appId: account.appId,
+    clientSecret: account.clientSecret,
+    markdownSupport: account.markdownSupport,
+    systemPrompt: account.systemPrompt,
+    config: account.config as GatewayAccount["config"],
+  };
+}
+
+/**
+ * Persist OpenClaw config through the injected plugin runtime (typed entry point).
+ */
+export async function writeOpenClawConfigThroughRuntime(
+  runtime: PluginRuntime,
+  cfg: OpenClawConfig,
+): Promise<void> {
+  await runtime.config.replaceConfigFile({
+    nextConfig: cfg,
+    afterWrite: { mode: "auto" },
+  });
+}
@@ -3,6 +3,7 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 import type { GatewayPluginRuntime } from "../engine/gateway/types.js";
 import { setOpenClawVersion } from "../engine/messaging/sender.js";
 
+// Single plugin runtime per process — concurrent multi-tenant qqbot runtimes are not supported.
 const { setRuntime: _setRuntime, getRuntime: getQQBotRuntime } =
   createPluginRuntimeStore<PluginRuntime>({
     pluginId: "qqbot",
@@ -20,5 +21,5 @@ export { getQQBotRuntime, setQQBotRuntime };
 
 /** Type-narrowed getter for engine/ modules that need GatewayPluginRuntime. */
 export function getQQBotRuntimeForEngine(): GatewayPluginRuntime {
-  return getQQBotRuntime() as unknown as GatewayPluginRuntime;
+  return getQQBotRuntime() as GatewayPluginRuntime;
 }
Original file line number	Diff line number	Diff line change
`@@ -91,6 +91,10 @@`
`91`	`91`	`"type": "string",`
`92`	`92`	`"enum": ["off", "partial"],`
`93`	`93`	`"default": "partial"`
	`94`	`+ },`
	`95`	`+ "c2cStreamApi": {`
	`96`	`+ "type": "boolean",`
	`97`	`+ "description": "Use QQ C2C official stream_messages API (single-message typing-style updates)."`
`94`	`98`	`}`
`95`	`99`	`}`
`96`	`100`	`}`
`@@ -136,6 +140,10 @@`
`136`	`140`	`"type": "string",`
`137`	`141`	`"enum": ["off", "partial"],`
`138`	`142`	`"default": "partial"`
	`143`	`+ },`
	`144`	`+ "c2cStreamApi": {`
	`145`	`+ "type": "boolean",`
	`146`	`+ "description": "Use QQ C2C official stream_messages API (single-message typing-style updates)."`
`139`	`147`	`}`
`140`	`148`	`}`
`141`	`149`	`}`