@tencent-connect/openclaw-qqbot 1.7.0 → 1.7.2

package/dist/src/api.js

@@ -5,6 +5,8 @@
 import os from "node:os";
 import { computeFileHash, getCachedFileInfo, setCachedFileInfo } from "./utils/upload-cache.js";
 import { sanitizeFileName } from "./utils/platform.js";
+import { resolveUserAgentSuffix } from "./config.js";
+import { getQQBotRuntime } from "./runtime.js";
 /** 默认使用 console，外部可通过 setApiLogger 注入框架 log */
 let log = {
     info: (msg) => console.log(msg),
@@ -38,8 +40,9 @@ export class ApiError extends Error {
         this.name = "ApiError";
     }
 }
-const API_BASE = "https://api.sgroup.qq.com";
-const TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
+// 支持环境变量覆盖，用于私有化部署/测试环境
+export const API_BASE = (process.env.QQBOT_BASE_URL?.replace(/\/+$/, "") || "https://api.sgroup.qq.com");
+export const TOKEN_URL = `${process.env.QQBOT_TOKEN_BASE_URL?.replace(/\/+$/, "") || "https://bots.qq.com"}/app/getAppAccessToken`;
 // ============ Plugin User-Agent ============
 // 格式: QQBotPlugin/{version} (Node/{nodeVersion}; {os}; OpenClaw/{openclawVersion})
 // 示例: QQBotPlugin/1.6.0 (Node/22.14.0; darwin; OpenClaw/2026.3.31)
@@ -53,7 +56,17 @@ export function setOpenClawVersion(version) {
         _openclawVersion = version;
 }
 export function getPluginUserAgent() {
-    return `QQBotPlugin/${_pluginVersion} (Node/${process.versions.node}; ${os.platform()}; OpenClaw/${_openclawVersion})`;
+    const base = `QQBotPlugin/${_pluginVersion} (Node/${process.versions.node}; ${os.platform()}; OpenClaw/${_openclawVersion})`;
+    let suffix = "";
+    try {
+        const rt = getQQBotRuntime();
+        // rt.config 是配置管理器，调用 .current() 获取实际配置数据
+        const cfgMgr = rt.config;
+        const cfg = typeof cfgMgr.current === "function" ? cfgMgr.current() : cfgMgr;
+        suffix = resolveUserAgentSuffix(cfg);
+    }
+    catch { /* runtime 未初始化时返回无后缀 UA */ }
+    return suffix ? `${base} ${suffix}` : base;
 }
 // 运行时配置
 let currentMarkdownSupport = false;
@@ -495,7 +508,7 @@ async function sendAndNotify(accessToken, method, path, body, meta) {
     }
     return result;
 }
-function buildMessageBody(content, msgId, msgSeq, messageReference) {
+function buildMessageBody(content, msgId, msgSeq, messageReference, inlineKeyboard) {
     const body = currentMarkdownSupport
         ? {
             markdown: { content },
@@ -513,6 +526,10 @@ function buildMessageBody(content, msgId, msgSeq, messageReference) {
     if (messageReference && !currentMarkdownSupport) {
         body.message_reference = { message_id: messageReference };
     }
+    // Inline Keyboard（内嵌按钮，需审核）：字段名 keyboard，结构 { content: { rows } }
+    if (inlineKeyboard) {
+        body.keyboard = inlineKeyboard;
+    }
     return body;
 }
 export async function sendC2CMessage(accessToken, openid, content, msgId, messageReference) {
@@ -556,6 +573,18 @@ export async function sendGroupMessage(accessToken, groupOpenid, content, msgId,
     const body = buildMessageBody(content, msgId, msgSeq, messageReference);
     return sendAndNotify(accessToken, "POST", `/v2/groups/${groupOpenid}/messages`, body, { text: content });
 }
+/** 发送带 Inline Keyboard 的 C2C 消息（回调型按钮，触发 INTERACTION_CREATE） */
+export async function sendC2CMessageWithInlineKeyboard(accessToken, openid, content, inlineKeyboard, msgId) {
+    const msgSeq = msgId ? getNextMsgSeq(msgId) : 1;
+    const body = buildMessageBody(content, msgId, msgSeq, undefined, inlineKeyboard);
+    return sendAndNotify(accessToken, "POST", `/v2/users/${openid}/messages`, body, { text: content });
+}
+/** 发送带 Inline Keyboard 的 Group 消息（回调型按钮，触发 INTERACTION_CREATE） */
+export async function sendGroupMessageWithInlineKeyboard(accessToken, groupOpenid, content, inlineKeyboard, msgId) {
+    const msgSeq = msgId ? getNextMsgSeq(msgId) : 1;
+    const body = buildMessageBody(content, msgId, msgSeq, undefined, inlineKeyboard);
+    return sendAndNotify(accessToken, "POST", `/v2/groups/${groupOpenid}/messages`, body, { text: content });
+}
 function buildProactiveMessageBody(content) {
     if (!content || content.trim().length === 0) {
         throw new Error("主动消息内容不能为空 (markdown.content is empty)");

package/dist/src/approval-handler.d.ts

@@ -0,0 +1,47 @@
+/**
+ * QQBot Approval Handler
+ *
+ * 监听 Gateway 的 exec/plugin approval 事件，
+ * 直接调用 QQ API 发送带 Inline Keyboard 的审批消息。
+ * 参考 DiscordExecApprovalHandler 的实现模式。
+ *
+ * 兼容性：gateway-runtime / approval-runtime 模块在 openclaw < 3.22 上不存在，
+ * 使用动态 import 避免插件整体加载失败，旧版框架上审批功能自动降级（不可用）。
+ */
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+export interface QQBotApprovalHandlerOpts {
+    accountId: string;
+    appId: string;
+    clientSecret: string;
+    cfg: OpenClawConfig;
+    gatewayUrl?: string;
+    log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+        debug?: (msg: string) => void;
+    };
+}
+export declare class QQBotApprovalHandler {
+    private gatewayClient;
+    private pending;
+    private requestCache;
+    private opts;
+    private started;
+    constructor(opts: QQBotApprovalHandlerOpts);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** 检查是否有指定 shortId 对应的 pending 审批 */
+    hasShortId(shortId: string): boolean;
+    /** 解析审批请求（供 Interaction 回调或 /approve 命令调用） */
+    resolveApproval(approvalId: string, decision: "allow-once" | "allow-always" | "deny"): Promise<boolean>;
+    private handleGatewayEvent;
+    private handleRequested;
+    private handleResolved;
+    private handleTimeout;
+}
+export declare function isApprovalFeatureAvailable(): boolean;
+export declare function setApprovalFeatureAvailable(available: boolean): void;
+export declare function registerApprovalHandler(accountId: string, handler: QQBotApprovalHandler): void;
+export declare function unregisterApprovalHandler(accountId: string): void;
+export declare function getApprovalHandler(accountId: string): QQBotApprovalHandler | undefined;
+export declare function findApprovalHandlerForShortId(shortId: string): QQBotApprovalHandler | undefined;

package/dist/src/approval-handler.js

@@ -0,0 +1,372 @@
+/**
+ * QQBot Approval Handler
+ *
+ * 监听 Gateway 的 exec/plugin approval 事件，
+ * 直接调用 QQ API 发送带 Inline Keyboard 的审批消息。
+ * 参考 DiscordExecApprovalHandler 的实现模式。
+ *
+ * 兼容性：gateway-runtime / approval-runtime 模块在 openclaw < 3.22 上不存在，
+ * 使用动态 import 避免插件整体加载失败，旧版框架上审批功能自动降级（不可用）。
+ */
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAccessToken, sendC2CMessageWithInlineKeyboard, sendGroupMessageWithInlineKeyboard, } from "./api.js";
+// ─── 动态加载 gateway-runtime（兼容不同安装环境） ────────
+function loadGatewayRuntime() {
+    const req = createRequire(import.meta.url);
+    const currentFile = fileURLToPath(import.meta.url);
+    const pluginRoot = path.resolve(path.dirname(currentFile), "..", "..");
+    const fs = req("node:fs");
+    // 尝试从找到的 openclaw 根目录加载 gateway-runtime.js
+    const tryLoadFromRoot = (root) => {
+        for (const rel of ["dist/plugin-sdk/gateway-runtime.js", "plugin-sdk/gateway-runtime.js"]) {
+            const p = path.join(root, rel);
+            try {
+                if (fs.existsSync(p))
+                    return req(p);
+            }
+            catch { /* try next */ }
+        }
+        return null;
+    };
+    // 策略 1: link-sdk-core.cjs findOpenclawRoot
+    try {
+        const { findOpenclawRoot } = req(path.join(pluginRoot, "scripts", "link-sdk-core.cjs"));
+        const root = findOpenclawRoot(pluginRoot);
+        if (root) {
+            const mod = tryLoadFromRoot(root);
+            if (mod)
+                return mod;
+        }
+    }
+    catch { /* fallback */ }
+    // 策略 2: process.argv[1] 反推（当前进程就是 openclaw）
+    try {
+        const entry = process.argv[1];
+        if (entry) {
+            const realEntry = fs.realpathSync(entry);
+            let dir = path.dirname(realEntry);
+            for (let i = 0; i < 6; i++) {
+                const mod = tryLoadFromRoot(dir);
+                if (mod)
+                    return mod;
+                const parent = path.dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+        }
+    }
+    catch { /* fallback */ }
+    throw new Error("Cannot find openclaw/plugin-sdk/gateway-runtime (all strategies failed)");
+}
+// ─── 辅助函数 ───────────────────────────────────────────────
+function toShortId(approvalId) {
+    return approvalId.replace(/^(exec|plugin):/, "").slice(0, 8);
+}
+function resolveApprovalKind(approvalId) {
+    return approvalId.startsWith("plugin:") ? "plugin" : "exec";
+}
+function buildExecApprovalText(request) {
+    const expiresIn = Math.max(0, Math.round((request.expiresAtMs - Date.now()) / 1000));
+    const lines = ["🔐 命令执行审批", ""];
+    const cmd = request.request.commandPreview ?? request.request.command ?? "";
+    if (cmd)
+        lines.push(`\`\`\`\n${cmd.slice(0, 300)}\n\`\`\``);
+    if (request.request.cwd)
+        lines.push(`📁 目录: ${request.request.cwd}`);
+    if (request.request.agentId)
+        lines.push(`🤖 Agent: ${request.request.agentId}`);
+    lines.push("", `⏱️ 超时: ${expiresIn} 秒`);
+    return lines.join("\n");
+}
+function buildPluginApprovalText(request) {
+    const timeoutSec = Math.round((request.request.timeoutMs ?? 120_000) / 1000);
+    const severityIcon = request.request.severity === "critical" ? "🔴"
+        : request.request.severity === "info" ? "🔵"
+            : "🟡";
+    const lines = [`${severityIcon} 审批请求`, ""];
+    lines.push(`📋 ${request.request.title}`);
+    if (request.request.description)
+        lines.push(`📝 ${request.request.description}`);
+    if (request.request.toolName)
+        lines.push(`🔧 工具: ${request.request.toolName}`);
+    if (request.request.pluginId)
+        lines.push(`🔌 插件: ${request.request.pluginId}`);
+    if (request.request.agentId)
+        lines.push(`🤖 Agent: ${request.request.agentId}`);
+    lines.push("", `⏱️ 超时: ${timeoutSec} 秒`);
+    return lines.join("\n");
+}
+/**
+ * Inline Keyboard（内嵌回调型按钮）
+ * type=1(Callback)：点击触发 INTERACTION_CREATE，button_data = data 字段
+ * group_id 相同 → 点一个后其余变灰（三选一语义）
+ * click_limit=1 → 每人只能点一次
+ * permission.type=2 → 所有人可操作
+ */
+function buildApprovalKeyboard(approvalId) {
+    const makeBtn = (id, label, visitedLabel, data, style) => ({
+        id,
+        render_data: { label, visited_label: visitedLabel, style },
+        action: {
+            type: 1,
+            data,
+            permission: { type: 2 },
+            click_limit: 1,
+        },
+        group_id: "approval",
+    });
+    return {
+        content: {
+            rows: [
+                {
+                    buttons: [
+                        makeBtn("allow", "✅ 允许一次", "已允许", `approve:${approvalId}:allow-once`, 1),
+                        makeBtn("always", "⭐ 始终允许", "已始终允许", `approve:${approvalId}:allow-always`, 1),
+                        makeBtn("deny", "❌ 拒绝", "已拒绝", `approve:${approvalId}:deny`, 0),
+                    ],
+                },
+            ],
+        },
+    };
+}
+/** 从 sessionKey 或 turnSourceTo 提取投递目标 */
+function resolveTarget(sessionKey, turnSourceTo) {
+    // 优先从 sessionKey 解析（如 agent:main:qqbot:direct:OPENID）
+    const sk = sessionKey ?? turnSourceTo;
+    if (!sk)
+        return null;
+    const m = sk.match(/qqbot:(c2c|direct|group):([A-F0-9]+)/i);
+    if (!m)
+        return null;
+    const type = m[1].toLowerCase() === "group" ? "group" : "c2c";
+    return { type, id: m[2] };
+}
+// ─── Handler 类 ──────────────────────────────────────────────
+export class QQBotApprovalHandler {
+    gatewayClient = null;
+    pending = new Map();
+    requestCache = new Map();
+    opts;
+    started = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        const { log } = this.opts;
+        log?.info(`[qqbot:${this.opts.accountId}] approval-handler: starting`);
+        // 动态加载 gateway-runtime（兼容旧版框架 / pnpm 环境）
+        let gatewayRuntime;
+        try {
+            gatewayRuntime = loadGatewayRuntime();
+        }
+        catch (err) {
+            log?.error(`[qqbot:${this.opts.accountId}] approval-handler: gateway-runtime module not available, approval feature disabled. Error: ${err}`);
+            this.started = false;
+            return;
+        }
+        try {
+            this.gatewayClient = await gatewayRuntime.createOperatorApprovalsGatewayClient({
+                config: this.opts.cfg,
+                gatewayUrl: this.opts.gatewayUrl,
+                clientDisplayName: "QQBot Approval Handler",
+                onEvent: (evt) => this.handleGatewayEvent(evt),
+                onHelloOk: () => log?.info(`[qqbot:${this.opts.accountId}] approval-handler: connected to gateway`),
+                onConnectError: (err) => log?.error(`[qqbot:${this.opts.accountId}] approval-handler: connect error: ${err.message}`),
+                onClose: (code, reason) => log?.debug?.(`[qqbot:${this.opts.accountId}] approval-handler: gateway closed: ${code} ${reason}`),
+            });
+            this.gatewayClient.start();
+            setApprovalFeatureAvailable(true);
+        }
+        catch (err) {
+            log?.error(`[qqbot:${this.opts.accountId}] approval-handler: failed to create gateway client: ${err}`);
+            this.started = false;
+        }
+    }
+    async stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        for (const entry of this.pending.values())
+            clearTimeout(entry.timeoutId);
+        this.pending.clear();
+        this.requestCache.clear();
+        this.gatewayClient?.stop();
+        this.gatewayClient = null;
+        this.opts.log?.info(`[qqbot:${this.opts.accountId}] approval-handler: stopped`);
+    }
+    /** 检查是否有指定 shortId 对应的 pending 审批 */
+    hasShortId(shortId) {
+        for (const id of this.pending.keys()) {
+            if (toShortId(id) === shortId)
+                return true;
+        }
+        return false;
+    }
+    /** 解析审批请求（供 Interaction 回调或 /approve 命令调用） */
+    async resolveApproval(approvalId, decision) {
+        if (!this.gatewayClient)
+            return false;
+        // 查找完整 ID：支持完整 ID（exec:uuid / plugin:uuid）、纯 UUID、或 shortId（8位）
+        let fullId = approvalId;
+        if (this.pending.has(approvalId)) {
+            fullId = approvalId;
+        }
+        else {
+            // 尝试在 pending keys 中匹配：纯 UUID 可能对应 exec:uuid 或 plugin:uuid
+            for (const id of this.pending.keys()) {
+                if (id === approvalId) {
+                    fullId = id;
+                    break;
+                }
+                // 纯 UUID 匹配：pending key 的 uuid 部分等于传入值
+                if (id.replace(/^(exec|plugin):/, "") === approvalId) {
+                    fullId = id;
+                    break;
+                }
+                // shortId 匹配
+                if (toShortId(id) === approvalId) {
+                    fullId = id;
+                    break;
+                }
+            }
+            // 也在 requestCache 中查找（handleResolved 可能已清除 pending）
+            if (fullId === approvalId && !this.requestCache.has(approvalId)) {
+                for (const id of this.requestCache.keys()) {
+                    if (id.replace(/^(exec|plugin):/, "") === approvalId) {
+                        fullId = id;
+                        break;
+                    }
+                }
+            }
+        }
+        const kind = resolveApprovalKind(fullId);
+        const method = kind === "plugin" ? "plugin.approval.resolve" : "exec.approval.resolve";
+        const isPending = this.pending.has(fullId);
+        const isCached = this.requestCache.has(fullId);
+        this.opts.log?.info(`[qqbot:${this.opts.accountId}] approval-handler: resolving ${fullId} (input=${approvalId}) kind=${kind} → ${decision}, pending=${isPending}, cached=${isCached}`);
+        try {
+            await this.gatewayClient.request(method, { id: fullId, decision });
+            this.opts.log?.info(`[qqbot:${this.opts.accountId}] approval-handler: RPC success ${toShortId(fullId)} → ${decision} (method=${method})`);
+            return true;
+        }
+        catch (err) {
+            this.opts.log?.error(`[qqbot:${this.opts.accountId}] approval-handler: resolve failed: ${err}`);
+            return false;
+        }
+    }
+    handleGatewayEvent(evt) {
+        if (evt.event === "exec.approval.requested") {
+            void this.handleRequested(evt.payload, "exec");
+        }
+        else if (evt.event === "plugin.approval.requested") {
+            void this.handleRequested(evt.payload, "plugin");
+        }
+        else if (evt.event === "exec.approval.resolved") {
+            void this.handleResolved(evt.payload);
+        }
+        else if (evt.event === "plugin.approval.resolved") {
+            void this.handleResolved(evt.payload);
+        }
+    }
+    async handleRequested(request, kind) {
+        const { log, appId, clientSecret, accountId } = this.opts;
+        const shortId = toShortId(request.id);
+        // 只处理本账号的请求
+        const reqAccountId = request.request.turnSourceAccountId?.trim();
+        if (reqAccountId && reqAccountId !== accountId)
+            return;
+        // 解析投递目标
+        const sessionKey = request.request.sessionKey;
+        const turnSourceTo = request.request.turnSourceTo;
+        const target = resolveTarget(sessionKey, turnSourceTo);
+        if (!target) {
+            log?.info(`[qqbot:${accountId}] approval-handler: no QQ target for ${shortId} (session=${sessionKey})`);
+            return;
+        }
+        // 缓存请求
+        this.requestCache.set(request.id, kind === "plugin"
+            ? { kind: "plugin", request: request }
+            : { kind: "exec", request: request });
+        log?.info(`[qqbot:${accountId}] approval-handler: sending ${kind} approval ${shortId} to ${target.type}:${target.id}`);
+        const text = kind === "plugin"
+            ? buildPluginApprovalText(request)
+            : buildExecApprovalText(request);
+        const keyboard = buildApprovalKeyboard(request.id);
+        const timeoutMs = kind === "plugin"
+            ? (request.request.timeoutMs ?? 120_000)
+            : Math.max(0, request.expiresAtMs - Date.now());
+        // 短暂延迟，确保框架侧 waitDecision 已就绪，避免时序竞争
+        await new Promise((r) => setTimeout(r, 2000));
+        try {
+            const token = await getAccessToken(appId, clientSecret);
+            if (target.type === "c2c") {
+                await sendC2CMessageWithInlineKeyboard(token, target.id, text, keyboard);
+            }
+            else {
+                await sendGroupMessageWithInlineKeyboard(token, target.id, text, keyboard);
+            }
+            log?.info(`[qqbot:${accountId}] approval-handler: sent ${kind} approval ${shortId}`);
+            const timeoutId = setTimeout(() => {
+                this.handleTimeout(request.id, target);
+            }, timeoutMs + 2_000);
+            this.pending.set(request.id, { targets: [target], timeoutId });
+        }
+        catch (err) {
+            this.requestCache.delete(request.id);
+            log?.error(`[qqbot:${accountId}] approval-handler: failed to send approval ${shortId}: ${err}`);
+        }
+    }
+    async handleResolved(resolved) {
+        const entry = this.pending.get(resolved.id);
+        const resolvedBy = resolved.resolvedBy ?? "unknown";
+        const kind = resolveApprovalKind(resolved.id);
+        this.opts.log?.info(`[qqbot:${this.opts.accountId}] approval-handler: gateway confirmed ${toShortId(resolved.id)} → ${resolved.decision} (kind=${kind}, resolvedBy=${resolvedBy}, wasPending=${!!entry})`);
+        if (!entry)
+            return;
+        clearTimeout(entry.timeoutId);
+        this.pending.delete(resolved.id);
+        this.requestCache.delete(resolved.id);
+        // 框架 Forwarder 负责发送 resolved 通知（已通过 buildResolvedPayload=null 抑制），此处不重复发送
+    }
+    async handleTimeout(approvalId, target) {
+        const { log, accountId } = this.opts;
+        if (!this.pending.has(approvalId))
+            return;
+        this.pending.delete(approvalId);
+        this.requestCache.delete(approvalId);
+        log?.info(`[qqbot:${accountId}] approval-handler: timeout ${toShortId(approvalId)}`);
+        // 超时由框架处理，此处仅清理状态，不重复发消息
+    }
+}
+// ─── 模块级 handler 注册 ────────────────────────────────────
+const _handlers = new Map();
+/** 审批功能是否可用（gateway-runtime 模块加载成功则为 true） */
+let _approvalFeatureAvailable = false;
+export function isApprovalFeatureAvailable() {
+    return _approvalFeatureAvailable;
+}
+export function setApprovalFeatureAvailable(available) {
+    _approvalFeatureAvailable = available;
+}
+export function registerApprovalHandler(accountId, handler) {
+    _handlers.set(accountId, handler);
+}
+export function unregisterApprovalHandler(accountId) {
+    _handlers.delete(accountId);
+}
+export function getApprovalHandler(accountId) {
+    return _handlers.get(accountId);
+}
+export function findApprovalHandlerForShortId(shortId) {
+    for (const handler of _handlers.values()) {
+        if (handler.hasShortId(shortId))
+            return handler;
+    }
+    return undefined;
+}

package/dist/src/channel.js

@@ -6,6 +6,24 @@ import { qqbotOnboardingAdapter } from "./onboarding.js";
 import { getQQBotRuntime } from "./runtime.js";
 import { saveCredentialBackup, loadCredentialBackup } from "./credential-backup.js";
 import { initApiConfig } from "./api.js";
+import { getApprovalHandler } from "./approval-handler.js";
+/** 检查 payload 是否为审批消息（与 getExecApprovalReplyMetadata 等效，内联避免版本兼容问题） */
+function isApprovalPayload(payload) {
+    if (!payload || typeof payload !== "object")
+        return false;
+    const p = payload;
+    // channelData.execApproval 存在 → exec/plugin approval pending/resolved
+    const cd = p.channelData;
+    if (cd && typeof cd === "object" && !Array.isArray(cd)) {
+        const execApproval = cd.execApproval;
+        if (execApproval && typeof execApproval === "object" && !Array.isArray(execApproval)) {
+            return true;
+        }
+    }
+    // text 匹配兜底：框架渲染的审批纯文本通知
+    const text = typeof p.text === "string" ? p.text : "";
+    return /(?:Plugin|Exec) approval (?:required|allowed|denied|expired)/i.test(text);
+}
 /** QQ Bot 单条消息文本长度上限 */
 export const TEXT_CHUNK_LIMIT = 5000;
 /**
@@ -251,6 +269,9 @@ export const qqbotPlugin = {
         chunker: (text, limit) => getQQBotRuntime().channel.text.chunkMarkdownText(text, limit),
         chunkerMode: "markdown",
         textChunkLimit: 5000,
+        // 3.31+ outbound 路径：dispatch-from-config → shouldSuppressLocalExecApprovalPrompt → outbound.shouldSuppressLocalPayloadPrompt
+        shouldSuppressLocalPayloadPrompt: ({ accountId, payload }) => getApprovalHandler(accountId ?? "") != null &&
+            isApprovalPayload(payload),
         sendText: async ({ to, text, accountId, replyToId, cfg }) => {
             console.log(`[qqbot:channel] sendText called — accountId=${accountId}, to=${to}, replyToId=${replyToId}, text.length=${text?.length ?? 0}`);
             console.log(`[qqbot:channel] sendText text preview: ${text?.slice(0, 100)}${(text?.length ?? 0) > 100 ? "..." : ""}`);
@@ -412,6 +433,57 @@ export const qqbotPlugin = {
             lastOutboundAt: runtime?.lastOutboundAt ?? null,
         }),
     },
+    // QQBot approval-handler 通过独立 WS 连接自行处理 exec + plugin 审批消息投递（带 Inline Keyboard），
+    // 完全屏蔽框架 Forwarder 的纯文本通知。
+    //
+    // ── 3.28 扁平结构 ──
+    execApprovals: {
+        // 3.28 框架通过此方法判断 channel 是否支持审批
+        getInitiatingSurfaceState: ({ accountId }) => {
+            return getApprovalHandler(accountId ?? "") != null
+                ? { kind: "enabled" }
+                : { kind: "disabled" };
+        },
+        shouldSuppressForwardingFallback: (...args) => {
+            console.log("[QQBot] shouldSuppressForwardingFallback called", JSON.stringify(args?.[0]?.target ?? null));
+            return true;
+        },
+        shouldSuppressLocalPrompt: ({ accountId, payload }) => getApprovalHandler(accountId ?? "") != null &&
+            isApprovalPayload(payload),
+        buildPendingPayload: () => null,
+        buildResolvedPayload: () => null,
+    },
+    // ── 3.31+ 嵌套结构 ──
+    // auth 和 approvals 是 ChannelPlugin 顶层平级字段
+    //
+    // QQBot 审批模型：
+    //   - QQBotApprovalHandler 通过独立 WS 自行投递带 Inline Keyboard 的审批消息
+    //   - 用户点击按钮 → INTERACTION_CREATE → resolveApproval → gateway RPC
+    //   - /approve 文本命令作为 URGENT_COMMAND 直接入队交给框架处理
+    auth: {
+        authorizeActorAction: () => ({ authorized: true }),
+        getActionAvailabilityState: ({ accountId }) => {
+            return getApprovalHandler(accountId ?? "") != null
+                ? { kind: "enabled" }
+                : { kind: "disabled" };
+        },
+    },
+    approvals: {
+        delivery: {
+            hasConfiguredDmRoute: () => true,
+            shouldSuppressForwardingFallback: () => true,
+        },
+        render: {
+            exec: {
+                buildPendingPayload: () => null,
+                buildResolvedPayload: () => null,
+            },
+            plugin: {
+                buildPendingPayload: () => null,
+                buildResolvedPayload: () => null,
+            },
+        },
+    },
 };
 // ============ 独立的 mention 工具函数（供 gateway.ts 等直接调用） ============
 /** 清理 @mention：替换 <@openid> 为 @用户名，去除 @机器人自身 */

package/dist/src/config.d.ts

@@ -17,7 +17,7 @@ export declare function resolveGroupAllowFrom(cfg: OpenClawConfig, accountId?: s
 /** 检查指定群是否被允许（使用标准策略引擎） */
 export declare function isGroupAllowed(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): boolean;
 type ResolvedGroupConfig = Omit<Required<GroupConfig>, "prompt"> & Pick<GroupConfig, "prompt">;
-/** 解析指定群配置（具体 groupOpenid > 通配符 "*" > 默认值） */
+/** 解析指定群配置（具体 groupOpenid > 通配符 "*" > 账户级 defaultRequireMention > 硬编码默认值） */
 export declare function resolveGroupConfig(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): ResolvedGroupConfig;
 /** 解析群历史消息缓存条数 */
 export declare function resolveHistoryLimit(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): number;
@@ -31,6 +31,10 @@ export declare function resolveIgnoreOtherMentions(cfg: OpenClawConfig, groupOpe
 export declare function resolveToolPolicy(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): ToolPolicy;
 /** 解析群名称（优先配置，fallback 为 openid 前 8 位） */
 export declare function resolveGroupName(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): string;
+/**
+ * 解析 User-Agent 追加后缀（仅通道级：channels.qqbot.userAgentSuffix）
+ */
+export declare function resolveUserAgentSuffix(cfg: OpenClawConfig): string;
 /**
  * 列出所有 QQBot 账户 ID
  */

package/dist/src/config.js

@@ -81,14 +81,16 @@ export function isGroupAllowed(cfg, groupOpenid, accountId) {
         allowlistMatched,
     }).allowed;
 }
-/** 解析指定群配置（具体 groupOpenid > 通配符 "*" > 默认值） */
+/** 解析指定群配置（具体 groupOpenid > 通配符 "*" > 账户级 defaultRequireMention > 硬编码默认值） */
 export function resolveGroupConfig(cfg, groupOpenid, accountId) {
     const account = resolveQQBotAccount(cfg, accountId);
     const groups = account.config?.groups ?? {};
     const wildcardCfg = groups["*"] ?? {};
     const specificCfg = groups[groupOpenid] ?? {};
+    // 账户级默认值：defaultRequireMention 配置 > 硬编码默认 true
+    const accountDefaultRequireMention = account.config?.defaultRequireMention ?? DEFAULT_GROUP_CONFIG.requireMention;
     return {
-        requireMention: specificCfg.requireMention ?? wildcardCfg.requireMention ?? DEFAULT_GROUP_CONFIG.requireMention,
+        requireMention: specificCfg.requireMention ?? wildcardCfg.requireMention ?? accountDefaultRequireMention,
         ignoreOtherMentions: specificCfg.ignoreOtherMentions ?? wildcardCfg.ignoreOtherMentions ?? DEFAULT_GROUP_CONFIG.ignoreOtherMentions,
         toolPolicy: specificCfg.toolPolicy ?? wildcardCfg.toolPolicy ?? DEFAULT_GROUP_CONFIG.toolPolicy,
         name: specificCfg.name ?? wildcardCfg.name ?? DEFAULT_GROUP_CONFIG.name,
@@ -123,6 +125,13 @@ export function resolveGroupName(cfg, groupOpenid, accountId) {
     const name = resolveGroupConfig(cfg, groupOpenid, accountId).name;
     return name || groupOpenid.slice(0, 8);
 }
+/**
+ * 解析 User-Agent 追加后缀（仅通道级：channels.qqbot.userAgentSuffix）
+ */
+export function resolveUserAgentSuffix(cfg) {
+    const qqbot = cfg.channels?.qqbot;
+    return qqbot?.userAgentSuffix ? String(qqbot.userAgentSuffix).trim() : "";
+}
 function normalizeAppId(raw) {
     if (raw === null || raw === undefined)
         return "";
@@ -217,6 +226,7 @@ export function resolveQQBotAccount(cfg, accountId) {
         systemPrompt: accountConfig.systemPrompt,
         imageServerBaseUrl: accountConfig.imageServerBaseUrl || process.env.QQBOT_IMAGE_SERVER_BASE_URL,
         markdownSupport: accountConfig.markdownSupport !== false,
+        userAgentSuffix: resolveUserAgentSuffix(cfg),
         config: accountConfig,
     };
 }