@tencent-connect/openclaw-qqbot 1.7.1 → 1.7.2

package/src/gateway.ts

@@ -1,8 +1,9 @@
 import WebSocket from "ws";
 import path from "node:path";
 import fs from "node:fs";
-import type { ResolvedQQBotAccount, WSPayload, C2CMessageEvent, GuildMessageEvent, GroupMessageEvent, InteractionEvent, MsgElement } from "./types.js";
+import type { ResolvedQQBotAccount, WSPayload, C2CMessageEvent, GuildMessageEvent, GroupMessageEvent, InteractionEvent, MsgElement, TransportMode } from "./types.js";
 import { MSG_TYPE_QUOTE } from "./types.js";
+import { startWebhookTransport } from "./transport/index.js";
 import { getAccessToken, getGatewayUrl, sendC2CMessage, sendChannelMessage, sendGroupMessage, clearTokenCache, initApiConfig, startBackgroundTokenRefresh, stopBackgroundTokenRefresh, sendC2CInputNotify, onMessageSent, getPluginUserAgent, sendProactiveGroupMessage, acknowledgeInteraction, getApiPluginVersion, setApiLogger } from "./api.js";
 import { loadSession, saveSession, clearSession } from "./session-store.js";
 import { recordKnownUser, flushKnownUsers } from "./known-users.js";
@@ -418,6 +419,21 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
     throw new Error("QQBot not configured (missing appId or clientSecret)");
   }
 
+  // 安全网：捕获 approval-handler / SDK 内部 WS 握手异步错误（如 403），避免进程崩溃
+  const wsUncaughtHandler = (err: Error) => {
+    if (err.message?.includes("Unexpected server response")) {
+      log?.error(`[qqbot:${account.accountId}] Caught WS handshake error (non-fatal): ${err.message}`);
+      // 不重新抛出，防止进程退出
+    } else {
+      // 非 WS 握手错误，重新抛出交给上层处理
+      throw err;
+    }
+  };
+  process.on("uncaughtException", wsUncaughtHandler);
+  abortSignal.addEventListener("abort", () => {
+    process.removeListener("uncaughtException", wsUncaughtHandler);
+  }, { once: true });
+
   // 启动环境诊断（首次连接时执行）
   const diag = await runDiagnostics();
   if (diag.warnings.length > 0) {
@@ -511,6 +527,13 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
     log?.info(`[qqbot:${account.accountId}] Image server disabled (no imageServerBaseUrl configured)`);
   }
 
+  // ============ Transport 模式标记 ============
+  const transportMode: TransportMode = account.config.transport ?? "websocket";
+  if (transportMode === "webhook") {
+    log?.info(`[qqbot:${account.accountId}] Using webhook transport mode`);
+  }
+
+  // ============ WebSocket / Webhook 公共初始化 ============
   let reconnectAttempts = 0;
   let isAborted = false;
   let currentWs: WebSocket | null = null;
@@ -545,7 +568,9 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
     log,
   });
   registerApprovalHandler(account.accountId, approvalHandler);
-  void approvalHandler.start();
+  approvalHandler.start().catch((err) => {
+    log?.error(`[qqbot:${account.accountId}] approval-handler: uncaught start error: ${err}`);
+  });
 
   // ============ 消息队列（复用 createMessageQueue，内置群消息合并/淘汰策略） ============
   const msgQueue = createMessageQueue({
@@ -739,15 +764,6 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
         clearTokenCache(account.appId);
         shouldRefreshToken = false;
       }
-      
-      const accessToken = await getAccessToken(account.appId, account.clientSecret);
-      log?.info(`[qqbot:${account.accountId}] ✅ Access token obtained successfully`);
-      const gatewayUrl = await getGatewayUrl(accessToken);
-
-      log?.info(`[qqbot:${account.accountId}] Connecting to ${gatewayUrl}`);
-
-      const ws = new WebSocket(gatewayUrl, { headers: { "User-Agent": getPluginUserAgent() } });
-      currentWs = ws;
 
       const pluginRuntime = getQQBotRuntime();
 
@@ -1502,6 +1518,9 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
             });
           }
 
+          // 打印 runId 用于调试
+          log?.info?.(`[qqbot:${account.accountId}] Dispatching with runId: ${event.messageId}`);
+
           const dispatchPromise = pluginRuntime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
             ctx: ctxPayload,
             cfg,
@@ -1772,7 +1791,10 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                 }
               },
             },
+          
             replyOptions: {
+              // 使用消息ID作为 runId，用于追踪一次完整的 AI 对话运行
+              runId: event.messageId,
               // 流式模式时禁用 block streaming
               disableBlockStreaming: !useStreaming,
               // 流式模式下注册 onPartialReply 回调，接收流式文本增量
@@ -1868,6 +1890,99 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
         }); // end runWithRequestContext
       };
 
+      // ============ 统一事件分发（WebSocket/Webhook 共用） ============
+      const dispatchInboundEvent = async (t: string, d: unknown): Promise<void> => {
+        if (t === "C2C_MESSAGE_CREATE") {
+          const ev = d as C2CMessageEvent;
+          recordKnownUser({ openid: ev.author.user_openid, type: "c2c", accountId: account.accountId });
+          const refs = parseRefIndices(ev.message_scene?.ext, ev.message_type, ev.msg_elements);
+          await trySlashCommandOrEnqueue({ type: "c2c", senderId: ev.author.user_openid, content: ev.content, messageId: ev.id, timestamp: ev.timestamp, attachments: ev.attachments, refMsgIdx: refs.refMsgIdx, msgIdx: refs.msgIdx, msgElements: ev.msg_elements, msgType: ev.message_type });
+        } else if (t === "AT_MESSAGE_CREATE") {
+          const ev = d as GuildMessageEvent;
+          recordKnownUser({ openid: ev.author.id, type: "c2c", nickname: ev.author.username, accountId: account.accountId });
+          const refs = parseRefIndices((ev as any).message_scene?.ext, (ev as any).message_type, (ev as any).msg_elements);
+          await trySlashCommandOrEnqueue({ type: "guild", senderId: ev.author.id, senderName: ev.author.username, content: ev.content, messageId: ev.id, timestamp: ev.timestamp, channelId: ev.channel_id, guildId: ev.guild_id, attachments: ev.attachments, refMsgIdx: refs.refMsgIdx, msgIdx: refs.msgIdx, msgType: (ev as any).message_type });
+        } else if (t === "DIRECT_MESSAGE_CREATE") {
+          const ev = d as GuildMessageEvent;
+          recordKnownUser({ openid: ev.author.id, type: "c2c", nickname: ev.author.username, accountId: account.accountId });
+          const refs = parseRefIndices((ev as any).message_scene?.ext, (ev as any).message_type, (ev as any).msg_elements);
+          await trySlashCommandOrEnqueue({ type: "dm", senderId: ev.author.id, senderName: ev.author.username, content: ev.content, messageId: ev.id, timestamp: ev.timestamp, guildId: ev.guild_id, attachments: ev.attachments, refMsgIdx: refs.refMsgIdx, msgIdx: refs.msgIdx, msgType: (ev as any).message_type });
+        } else if (t === "GROUP_AT_MESSAGE_CREATE" || t === "GROUP_MESSAGE_CREATE") {
+          const ev = d as GroupMessageEvent;
+          recordKnownUser({ openid: ev.author.member_openid, type: "group", nickname: ev.author.username, groupOpenid: ev.group_openid, accountId: account.accountId });
+          const refs = parseRefIndices(ev.message_scene?.ext, ev.message_type, ev.msg_elements);
+          await trySlashCommandOrEnqueue({ type: "group", senderId: ev.author.member_openid, senderName: ev.author.username, senderIsBot: ev.author.bot, content: ev.content, messageId: ev.id, timestamp: ev.timestamp, groupOpenid: ev.group_openid, attachments: ev.attachments, refMsgIdx: refs.refMsgIdx, msgIdx: refs.msgIdx, eventType: t, mentions: ev.mentions, messageScene: ev.message_scene, msgElements: ev.msg_elements, msgType: ev.message_type });
+        } else if (t === "GROUP_ADD_ROBOT") {
+          const ev = d as { timestamp: string; group_openid: string; op_member_openid: string };
+          log?.info(`[qqbot:${account.accountId}] Bot added to group: ${ev.group_openid} by ${ev.op_member_openid}`);
+          recordKnownUser({ openid: ev.op_member_openid, type: "group", groupOpenid: ev.group_openid, accountId: account.accountId });
+        } else if (t === "GROUP_DEL_ROBOT") {
+          const ev = d as { timestamp: string; group_openid: string; op_member_openid: string };
+          log?.info(`[qqbot:${account.accountId}] Bot removed from group: ${ev.group_openid} by ${ev.op_member_openid}`);
+        } else if (t === "GROUP_MSG_REJECT") {
+          const ev = d as { timestamp: number; group_openid: string; op_member_openid: string };
+          log?.info(`[qqbot:${account.accountId}] Group ${ev.group_openid} rejected bot proactive messages (by ${ev.op_member_openid})`);
+        } else if (t === "GROUP_MSG_RECEIVE") {
+          const ev = d as { timestamp: number; group_openid: string; op_member_openid: string };
+          log?.info(`[qqbot:${account.accountId}] Group ${ev.group_openid} accepted bot proactive messages (by ${ev.op_member_openid})`);
+        } else if (t === "INTERACTION_CREATE") {
+          const ev = d as InteractionEvent;
+          const resolved = ev.data?.resolved;
+          const sceneDesc = ev.scene ?? (ev.chat_type === 0 ? "guild" : ev.chat_type === 1 ? "group" : "c2c");
+          log?.info(`[qqbot:${account.accountId}] Interaction: scene=${sceneDesc}, type=${ev.data?.type}, button_id=${resolved?.button_id}, button_data=${resolved?.button_data}`);
+          handleInteractionCreate({ event: ev, account, cfg, log }).catch((err) => {
+            log?.error(`[qqbot:${account.accountId}] Failed to handle interaction ${ev.id}: ${err}`);
+          });
+        }
+      };
+
+      // ============ Webhook 模式：共享 handleMessage，不走 WS ============
+      if (transportMode === "webhook") {
+        isConnecting = false;
+        msgQueue.startProcessor(handleMessage);
+        startBackgroundTokenRefresh(account.appId, account.clientSecret, {
+          log: log as { info: (msg: string) => void; error: (msg: string) => void; debug?: (msg: string) => void },
+        });
+
+        await startWebhookTransport({
+          account,
+          abortSignal,
+          onEvent: async (event) => {
+            const { eventType: t, data: d } = event;
+            log?.info(`[qqbot:${account.accountId}:webhook] 📩 Dispatch event: t=${t}, d=${JSON.stringify(d)}`);
+            await dispatchInboundEvent(t, d);
+          },
+          onReady: () => {
+            log?.info(`[qqbot:${account.accountId}:webhook] Transport ready`);
+            log?.info(`[qqbot:${account.accountId}] ✅ Webhook transport started successfully (path: ${account.config.webhook?.path ?? "/qqbot/webhook"})`);
+            onReady?.({ transport: "webhook" });
+            if (_pendingFirstReady.has(account.accountId)) {
+              _pendingFirstReady.delete(account.accountId);
+              sendStartupGreetings(adminCtx, "READY");
+            }
+          },
+          onError: (error) => {
+            log?.error(`[qqbot:${account.accountId}:webhook] Error: ${error.message}`);
+            onError?.(error);
+          },
+          log,
+        });
+
+        stopBackgroundTokenRefresh();
+        unregisterApprovalHandler(account.accountId);
+        return; // webhook transport 结束，不继续 WS 逻辑
+      }
+
+      // ============ WebSocket 模式：获取 token 并建立 WS 连接 ============
+      const accessToken = await getAccessToken(account.appId, account.clientSecret);
+      log?.info(`[qqbot:${account.accountId}] ✅ Access token obtained successfully`);
+      const gatewayUrl = await getGatewayUrl(accessToken);
+
+      log?.info(`[qqbot:${account.accountId}] Connecting to ${gatewayUrl}`);
+
+      const ws = new WebSocket(gatewayUrl, { headers: { "User-Agent": getPluginUserAgent() } });
+      currentWs = ws;
+
       ws.on("open", () => {
         log?.info(`[qqbot:${account.accountId}] WebSocket connected`);
         isConnecting = false; // 连接完成，释放锁
@@ -1990,159 +2105,10 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                     appId: account.appId,
                   });
                 }
-              } else if (t === "C2C_MESSAGE_CREATE") {
-                const event = d as C2CMessageEvent;
-                // P1-3: 记录已知用户
-                recordKnownUser({
-                  openid: event.author.user_openid,
-                  type: "c2c",
-                  accountId: account.accountId,
-                });
-                // 解析引用索引
-                const c2cRefs = parseRefIndices(event.message_scene?.ext, event.message_type, event.msg_elements);
-                // 斜杠指令拦截 → 不匹配则入队
-                trySlashCommandOrEnqueue({
-                  type: "c2c",
-                  senderId: event.author.user_openid,
-                  content: event.content,
-                  messageId: event.id,
-                  timestamp: event.timestamp,
-                  attachments: event.attachments,
-                  refMsgIdx: c2cRefs.refMsgIdx,
-                  msgIdx: c2cRefs.msgIdx,
-                  msgElements: event.msg_elements,
-                  msgType: event.message_type,
-                });
-              } else if (t === "AT_MESSAGE_CREATE") {
-                const event = d as GuildMessageEvent;
-                // P1-3: 记录已知用户（频道用户）
-                recordKnownUser({
-                  openid: event.author.id,
-                  type: "c2c", // 频道用户按 c2c 类型存储
-                  nickname: event.author.username,
-                  accountId: account.accountId,
-                });
-                const guildRefs = parseRefIndices((event as any).message_scene?.ext, (event as any).message_type, (event as any).msg_elements);
-                trySlashCommandOrEnqueue({
-                  type: "guild",
-                  senderId: event.author.id,
-                  senderName: event.author.username,
-                  content: event.content,
-                  messageId: event.id,
-                  timestamp: event.timestamp,
-                  channelId: event.channel_id,
-                  guildId: event.guild_id,
-                  attachments: event.attachments,
-                  refMsgIdx: guildRefs.refMsgIdx,
-                  msgIdx: guildRefs.msgIdx,
-                  msgType: (event as any).message_type,
-                });
-              } else if (t === "DIRECT_MESSAGE_CREATE") {
-                const event = d as GuildMessageEvent;
-                // P1-3: 记录已知用户（频道私信用户）
-                recordKnownUser({
-                  openid: event.author.id,
-                  type: "c2c",
-                  nickname: event.author.username,
-                  accountId: account.accountId,
-                });
-                const dmRefs = parseRefIndices((event as any).message_scene?.ext, (event as any).message_type, (event as any).msg_elements);
-                trySlashCommandOrEnqueue({
-                  type: "dm",
-                  senderId: event.author.id,
-                  senderName: event.author.username,
-                  content: event.content,
-                  messageId: event.id,
-                  timestamp: event.timestamp,
-                  guildId: event.guild_id,
-                  attachments: event.attachments,
-                  refMsgIdx: dmRefs.refMsgIdx,
-                  msgIdx: dmRefs.msgIdx,
-                  msgType: (event as any).message_type,
-                });
-              } else if (t === "GROUP_AT_MESSAGE_CREATE") {
-                const event = d as GroupMessageEvent;
-                // 被 @ 的消息，直接入队回复
-                recordKnownUser({
-                  openid: event.author.member_openid,
-                  type: "group",
-                  nickname: event.author.username,
-                  groupOpenid: event.group_openid,
-                  accountId: account.accountId,
-                });
-                const groupRefs = parseRefIndices(event.message_scene?.ext, event.message_type, event.msg_elements);
-                trySlashCommandOrEnqueue({
-                  type: "group",
-                  senderId: event.author.member_openid,
-                  senderName: event.author.username,
-                  content: event.content,
-                  messageId: event.id, 
-                  timestamp: event.timestamp,
-                  groupOpenid: event.group_openid,
-                  attachments: event.attachments,
-                  refMsgIdx: groupRefs.refMsgIdx,
-                  msgIdx: groupRefs.msgIdx,
-                  eventType: "GROUP_AT_MESSAGE_CREATE",
-                  mentions: event.mentions,
-                  messageScene: event.message_scene,
-                  msgElements: event.msg_elements,
-                  msgType: event.message_type,
-                });
-              } else if (t === "GROUP_MESSAGE_CREATE") {
-                const event = d as GroupMessageEvent;
-                recordKnownUser({
-                  openid: event.author.member_openid,
-                  type: "group",
-                  nickname: event.author.username,
-                  groupOpenid: event.group_openid,
-                  accountId: account.accountId,
-                });
-                const groupRefs = parseRefIndices(event.message_scene?.ext, event.message_type, event.msg_elements);
-                trySlashCommandOrEnqueue({
-                  type: "group",
-                  senderId: event.author.member_openid,
-                  senderName: event.author.username,
-                  senderIsBot: event.author.bot,
-                  content: event.content,
-                  messageId: event.id,
-                  timestamp: event.timestamp,
-                  groupOpenid: event.group_openid,
-                  attachments: event.attachments,
-                  refMsgIdx: groupRefs.refMsgIdx,
-                  msgIdx: groupRefs.msgIdx,
-                  eventType: "GROUP_MESSAGE_CREATE",
-                  mentions: event.mentions,
-                  messageScene: event.message_scene,
-                  msgElements: event.msg_elements,
-                  msgType: event.message_type,
-                });
-              } else if (t === "GROUP_ADD_ROBOT") {
-                const event = d as { timestamp: string; group_openid: string; op_member_openid: string };
-                log?.info(`[qqbot:${account.accountId}] Bot added to group: ${event.group_openid} by ${event.op_member_openid}`);
-                recordKnownUser({
-                  openid: event.op_member_openid,
-                  type: "group",
-                  groupOpenid: event.group_openid,
-                  accountId: account.accountId,
-                });
-
-              } else if (t === "GROUP_DEL_ROBOT") {
-                const event = d as { timestamp: string; group_openid: string; op_member_openid: string };
-                log?.info(`[qqbot:${account.accountId}] Bot removed from group: ${event.group_openid} by ${event.op_member_openid}`);
-              } else if (t === "GROUP_MSG_REJECT") {
-                const event = d as { timestamp: number; group_openid: string; op_member_openid: string };
-                log?.info(`[qqbot:${account.accountId}] Group ${event.group_openid} rejected bot proactive messages (by ${event.op_member_openid})`);
-              } else if (t === "GROUP_MSG_RECEIVE") {
-                const event = d as { timestamp: number; group_openid: string; op_member_openid: string };
-                log?.info(`[qqbot:${account.accountId}] Group ${event.group_openid} accepted bot proactive messages (by ${event.op_member_openid})`);
-              } else if (t === "INTERACTION_CREATE") {
-                const event = d as InteractionEvent;
-                const resolved = event.data?.resolved;
-                const sceneDesc = event.scene ?? (event.chat_type === 0 ? "guild" : event.chat_type === 1 ? "group" : "c2c");
-                log?.info(`[qqbot:${account.accountId}] Interaction: scene=${sceneDesc}, type=${event.data?.type}, button_id=${resolved?.button_id}, button_data=${resolved?.button_data}, user=${event.group_member_openid || event.user_openid || resolved?.user_id || "unknown"}`);
-
-                handleInteractionCreate({ event, account, cfg, log }).catch((err) => {
-                  log?.error(`[qqbot:${account.accountId}] Failed to handle interaction ${event.id}: ${err}`);
+              } else {
+                // 所有其他事件统一分发
+                dispatchInboundEvent(t!, d).catch((err) => {
+                  log?.error(`[qqbot:${account.accountId}] Event dispatch error (t=${t}): ${err}`);
                 });
               }
               break;
@@ -2297,8 +2263,10 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
   // 开始连接
   await connect();
 
-  // 等待 abort 信号
-  return new Promise((resolve) => {
-    abortSignal.addEventListener("abort", () => resolve());
+  // 等待 abort 信号（如果 connect() 返回时 signal 已经 aborted，直接 resolve）
+  if (abortSignal.aborted) return;
+  return new Promise<void>((resolve) => {
+    abortSignal.addEventListener("abort", () => resolve(), { once: true });
   });
 }
+

package/src/onboarding.ts

@@ -23,6 +23,14 @@ interface QQBotChannelConfig {
   imageServerBaseUrl?: string;
   markdownSupport?: boolean;
   allowFrom?: string[];
+  /** HTTP/WebSocket User-Agent 追加后缀 */
+  userAgentSuffix?: string;
+  /** 群消息是否默认需要 @提及才触发回复 */
+  defaultRequireMention?: boolean;
+  /** 消息接收传输方式：websocket（默认）| webhook */
+  transport?: string;
+  /** webhook 传输配置（transport="webhook" 时生效） */
+  webhook?: { path?: string };
   accounts?: Record<string, {
     enabled?: boolean;
     appId?: string;

package/src/slash-commands.ts

@@ -34,11 +34,16 @@ export function getFrameworkVersion(): string {
     // Windows 上 npm 安装的 CLI 通常是 .cmd wrapper，execFileSync 需要 shell:true 才能执行
     for (const cli of ["openclaw", "clawdbot", "moltbot"]) {
       try {
-        const out = execFileSync(cli, ["--version"], {
+        const rawOut = execFileSync(cli, ["--version"], {
           timeout: 3000, encoding: "utf8",
           ...(isWindows() ? { shell: true } : {}),
         }).trim();
         // 输出格式: "OpenClaw 2026.3.13 (61d171a)"
+        // CLI 启动时可能输出 proxy 等初始化日志到 stdout，需过滤出真正的版本行
+        const out = rawOut
+          .split("\n")
+          .find((line) => /^(OpenClaw|clawdbot|moltbot)\s/i.test(line))
+          ?.trim() ?? rawOut;
         if (out) {
           return out;
         }
@@ -332,7 +337,7 @@ registerCommand({
   ].join("\n"),
   handler: (ctx) => {
     // 群聊场景排除仅限私聊的指令
-    const GROUP_EXCLUDED_COMMANDS = new Set(["bot-upgrade", "bot-clear-storage"]);
+    const GROUP_EXCLUDED_COMMANDS = new Set(["bot-upgrade", "bot-clear-storage", "bot-logs", "bot-approve", "bot-group-allways", "bot-streaming"]);
     const isGroup = ctx.type === "group";
 
     const lines = [`### QQBot插件内置调试指令`, ``];
@@ -1637,7 +1642,12 @@ registerCommand({
     `导出最近的 OpenClaw 日志文件（最多 4 个）。`,
     `每个文件最多保留最后 1000 行，以文件形式返回。`,
   ].join("\n"),
-  handler: () => {
+  handler: (ctx) => {
+    // 日志导出仅在私聊中可用
+    if (ctx.type !== "c2c") {
+      return `💡 请在私聊中使用此指令`;
+    }
+
     const logDirs = collectCandidateLogDirs();
     const recentFiles = collectRecentLogFiles(logDirs).slice(0, 4);
 
@@ -2037,6 +2047,11 @@ registerCommand({
     `/bot-approve status     查看当前审批配置`,
   ].join("\n"),
   handler: async (ctx) => {
+    // 审批管理仅在私聊中可用
+    if (ctx.type !== "c2c") {
+      return `💡 请在私聊中使用此指令`;
+    }
+
     const arg = ctx.args.trim().toLowerCase();
 
     // 审批功能需要 openclaw >= 3.22（gateway-runtime 模块）
@@ -2259,6 +2274,125 @@ registerCommand({
   },
 });
 
+// ============ /bot-group-allways ============
+
+/**
+ * /bot-group-allways on|off — 修改群消息默认响应模式
+ *
+ * 直接修改当前账户的 defaultRequireMention 配置项并持久化到 openclaw.json。
+ * 修改后即时生效（下一条消息起按新配置处理）。
+ *
+ * on = AI 自主判断何时发言（无需 @），off = 仅被 @ 时回复
+ */
+registerCommand({
+  name: "bot-group-allways",
+  description: "修改群消息默认响应模式",
+  usage: [
+    `/bot-group-allways on   AI 自主判断何时发言（无需 @）`,
+    `/bot-group-allways off  仅在被 @ 时回复`,
+    `/bot-group-allways      查看当前设置`,
+    ``,
+    `设为 on 后，AI 会自主判断每条消息是否需要回复（无需 @）。`,
+    `仍可通过 groups.{groupId}.requireMention 对单个群覆盖。`,
+    ``,
+    `优先级：具体群配置 > 通配符 "*" > defaultRequireMention（本指令）> 默认 true`,
+  ].join("\n"),
+  handler: async (ctx) => {
+    // 群响应模式设置仅在私聊中可用
+    if (ctx.type !== "c2c") {
+      return `💡 请在私聊中使用此指令`;
+    }
+
+    const arg = ctx.args.trim().toLowerCase();
+
+    // 读取当前 defaultRequireMention 状态
+    const currentVal = ctx.accountConfig?.defaultRequireMention;
+    const currentRequireMention = currentVal ?? true; // 未设置时硬编码默认为 true
+
+    // 无参数：查看当前状态
+    if (!arg) {
+      return [
+        `🤖 群自主发言状态：${currentRequireMention ? "❌ 仅被 @ 时回复" : "✅ 自主判断何时发言"}`,
+        `使用 <qqbot-cmd-input text="/bot-group-allways on" show="/bot-group-allways on"/> 设为自主发言`,
+        `使用 <qqbot-cmd-input text="/bot-group-allways off" show="/bot-group-allways off"/> 设为仅被 @ 时回复`,
+      ].join("\n");
+    }
+
+    if (arg !== "on" && arg !== "off") {
+      return `❌ 参数错误，请使用 on 或 off\n\n示例：/bot-group-allways on`;
+    }
+
+    const newRequireMention = arg === "off"; // on=自主发言(requireMention=false), off=仅被@时回复(requireMention=true)
+
+    // 如果状态没变，直接返回
+    if (newRequireMention === currentRequireMention) {
+      return `🤖 群自主发言已经是"${arg}"状态，无需操作`;
+    }
+
+    // 更新配置
+    try {
+      const runtime = getQQBotRuntime();
+      const configApi = runtime.config as {
+        loadConfig: () => Record<string, unknown>;
+        writeConfigFile: (cfg: unknown) => Promise<void>;
+      };
+
+      const currentCfg = structuredClone(configApi.loadConfig()) as Record<string, unknown>;
+      const qqbot = ((currentCfg.channels ?? {}) as Record<string, unknown>).qqbot as Record<string, unknown> | undefined;
+
+      if (!qqbot) {
+        return `❌ 配置文件中未找到 qqbot 通道配置`;
+      }
+
+      const accountId = ctx.accountId;
+      const isNamedAccount = accountId !== "default" && (qqbot.accounts as Record<string, Record<string, unknown>> | undefined)?.[accountId];
+
+      if (isNamedAccount) {
+        // 命名账户：更新 accounts.{accountId}.defaultRequireMention
+        const accounts = qqbot.accounts as Record<string, Record<string, unknown>>;
+        const acct = accounts[accountId] ?? {};
+        acct.defaultRequireMention = newRequireMention;
+        accounts[accountId] = acct;
+        qqbot.accounts = accounts;
+      } else {
+        // 默认账户：更新 qqbot.defaultRequireMention
+        qqbot.defaultRequireMention = newRequireMention;
+      }
+
+      await configApi.writeConfigFile(currentCfg);
+
+      return [
+        `✅ 群自主发言已设置为 ${newRequireMention ? "**off**（仅被 @ 时回复）" : "**on**（AI 自主判断何时发言）"}`,
+        ``,
+        newRequireMention
+          ? `仅在被 @ 机器人才会回复。`
+          : `AI 将自主判断群消息是否需要回复，无需被 @ 即可发言。`,
+        ``,
+      ].join("\n");
+    } catch (err) {
+      const fwVer = getFrameworkVersion();
+      return [
+        `❌ 当前版本不支持该指令`,
+        ``,
+        `🦞框架版本：${fwVer}`,
+        `🤖QQBot 插件版本：v${PLUGIN_VERSION}`,
+        ``,
+        `可通过以下命令手动设置：`,
+        ``,
+        `\`\`\`shell`,
+        `# 设为 AI 自主判断何时发言（defaultRequireMention=false）`,
+        `openclaw config set channels.qqbot.defaultRequireMention false`,
+        `# 或设为仅被 @ 时回复（defaultRequireMention=true）`,
+        `openclaw config set channels.qqbot.defaultRequireMention true`,
+        ``,
+        `# 重启网关使配置生效`,
+        `openclaw gateway restart`,
+        `\`\`\``,
+      ].join("\n");
+    }
+  },
+});
+
 // ============ 匹配入口 ============
 
 /**

package/src/tools/channel.ts

@@ -1,11 +1,7 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { resolveQQBotAccount } from "../config.js";
 import { listQQBotAccountIds } from "../config.js";
-import { getAccessToken } from "../api.js";
-
-// ========== 常量 ==========
-
-const API_BASE = "https://api.sgroup.qq.com";
+import { getAccessToken, API_BASE } from "../api.js";
 
 const DEFAULT_TIMEOUT_MS = 30000;
 
@@ -276,6 +272,4 @@ export function registerChannelTool(api: OpenClawPluginApi): void {
     },
     { name: "qqbot_channel_api" },
   );
-
-  console.log("[qqbot-channel-api] Registered QQ channel API proxy tool");
 }

package/src/tools/remind.ts

@@ -303,6 +303,4 @@ export function registerRemindTool(api: OpenClawPluginApi): void {
     },
     { name: "qqbot_remind" },
   );
-
-  console.log("[qqbot-remind] Registered QQBot remind tool");
 }

package/src/transport/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Transport module — QQ Bot event receiving mechanisms.
+ *
+ * Supports two transport modes:
+ *   - **WebSocket** (default): long-lived WS connection with heartbeat, RESUME, etc.
+ *   - **Webhook** (HTTP callback): QQ platform POSTs events to registered path.
+ */
+
+export type { WebhookInboundEvent, WebhookTransportOptions, QQBotWebhookTarget } from "./webhook-transport.js";
+export { startWebhookTransport, resolveWebhookPath } from "./webhook-transport.js";
+export { verifyWebhookSignature, signValidationResponse, ed25519Sign } from "./webhook-verify.js";