@tencent-connect/openclaw-qqbot 1.7.1 → 1.7.2

package/README.md

@@ -36,7 +36,9 @@ Scan to join the QQ group chat
 
 | Feature | Description |
 |---------|-------------|
-| 🔒 **Multi-Scene** | C2C private chat, group @messages |
+| 🔒 **Multi-Scene** | C2C private chat, group chat (@mention / autonomous dual mode) |
+| 👥 **Group Fine-Tuning** | Per-group @trigger rules, tool policies, custom prompts, message filtering |
+| 🌐 **Dual Transport** | WebSocket (default) or Webhook (HTTP callback) — switch via config |
 | 🖼️ **Rich Media** | Send & receive images, voice, video, and files |
 | 🎙️ **Voice (STT/TTS)** | Speech-to-text transcription & text-to-speech replies |
 | 🔥 **One-Click Hot Upgrade** | Send `/bot-upgrade` in private chat to upgrade — no server login needed |
@@ -242,6 +244,22 @@ Manage the AI command execution approval policy. Supported subcommands:
 
 `/bot-clear-storage` lists files generated by the conversation and files in the downloaded resources directory. Use `/bot-clear-storage --force` to confirm deletion.
 
+#### `/bot-group-allways` — Group Response Mode Toggle
+
+> **You**: `/bot-group-allways`
+>
+> **QQBot**: 🤖 Group autonomous mode: ❌ @mention required
+
+Toggle group @trigger behavior at runtime — changes persist instantly, no restart needed:
+
+| Subcommand | Description |
+|------------|-------------|
+| `/bot-group-allways on` | AI decides when to speak autonomously (no @ needed) |
+| `/bot-group-allways off` | Only respond when @mentioned |
+| `/bot-group-allways` (no arg) | View current setting |
+
+> ⚠️ This command modifies the account-level `defaultRequireMention`. It has lower priority than per-group `groups.{groupId}.requireMention` settings.
+
 ---
 
 ## 🚀 Getting Started
@@ -408,13 +426,180 @@ openclaw message send --channel "qqbot" \
 
 #### How It Works
 
-- When `openclaw gateway` starts, all accounts with `enabled: true` launch their own WebSocket connections
+- When `openclaw gateway` starts, all accounts with `enabled: true` launch their own connections (WebSocket or Webhook depending on `transport` config)
 - Each account maintains an independent Token cache (isolated by `appId`), preventing cross-contamination
 - Incoming message logs are prefixed with `[qqbot:accountId]` for easy debugging
 
 ---
 
-### Voice Configuration (STT / TTS)
+### Webhook Transport Mode
+
+By default, the plugin connects to QQ via **WebSocket** (outbound connection, no public IP required). You can switch to **Webhook** mode where QQ platform POSTs events to your HTTP endpoint.
+
+| | WebSocket (default) | Webhook |
+|---|---|---|
+| Connection | Plugin connects to QQ gateway | QQ platform POSTs to your server |
+| Public IP | Not required | Required |
+| Use case | Development, single instance | Production, horizontal scaling, Serverless |
+| Session resume | Supported (RESUME) | Stateless, no resume needed |
+| Signature | Built-in | Ed25519 auto-verified by plugin |
+
+#### Configuration
+
+```json
+{
+  "channels": {
+    "qqbot": {
+      "appId": "111111111",
+      "clientSecret": "your-secret",
+      "transport": "webhook",
+      "webhook": {
+        "path": "/qqbot/webhook"
+      }
+    }
+  }
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `transport` | `"websocket"` | `"websocket"` or `"webhook"` |
+| `webhook.path` | `"/qqbot/webhook"` | HTTP path for receiving callbacks |
+
+#### Platform Setup
+
+1. Go to [QQ Open Platform](https://q.qq.com/) → Bot Settings → Message Receiving
+2. Select **HTTP Callback**
+3. Enter your callback URL: `https://your-domain.com/qqbot/webhook`
+4. The platform sends an `op:13` validation request — the plugin handles it automatically
+5. Once validated, all events will be POSTed to your endpoint
+
+---
+
+### Group Chat Configuration
+
+The plugin provides flexible group chat controls, allowing you to customize trigger rules, tool permissions, and AI behavior per group.
+
+#### @Mention Trigger Mode (`requireMention`)
+
+By default, the bot **only responds when @mentioned** in a group. You can configure it to autonomously decide when to speak:
+
+| Mode | Config Value | Behavior |
+|------|-------------|----------|
+| **@ only** | `true` (default) | Only messages that @mention the bot trigger a reply |
+| **Autonomous** | `false` | AI decides on its own whether each message needs a reply — no @ required |
+
+**Priority chain** (highest to lowest):
+
+```
+groups.{groupOpenid}.requireMention
+  > groups."*".requireMention
+    > account-level defaultRequireMention
+      > default value true
+```
+
+**Example:**
+
+```json
+{
+  "channels": {
+    "qqbot": {
+      // Account-level default for all groups
+      "defaultRequireMention": false,
+
+      "accounts": {
+        "default": {
+          "groups": {
+            "*": {
+              // Wildcard fallback for all groups
+              "requireMention": false
+            },
+            "GROUP_OPENID": {
+              // Per-group override — this group still requires @
+              "requireMention": true
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+> **Use cases:**
+>
+> - Work groups → `requireMention: true` — avoid AI chiming in on every casual message
+> - Dedicated AI companion groups → `requireMention: false` — participate naturally like a real person
+> - Use [`/bot-group-allways`](#bot-group-allways--group-response-mode-toggle) to toggle account-level defaults at runtime
+
+#### Additional Group Config Fields
+
+Besides `requireMention`, each group supports these settings:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `ignoreOtherMentions` | `boolean` | `false` | If enabled, messages that @mention others but not the bot are silently dropped (not recorded, no AI trigger) |
+| `toolPolicy` | `"full" \| "restricted" \| "none"` | `"restricted"` | Tool scope available to AI in this group. `full`=all tools; `restricted`=sensitive tools restricted (e.g., command execution, file ops); `none`=no tool calls allowed |
+| `prompt` | `string` | built-in default | Group-specific system prompt, appended after global systemPrompt |
+| `historyLimit` | `number` | `50` | Cached group history message count |
+
+**Full example with multiple groups:**
+
+```json
+{
+  "channels": {
+    "qqbot": {
+      "defaultRequireMention": false,
+      "accounts": {
+        "default": {
+          "groups": {
+            "*": {
+              "requireMention": true,
+              "toolPolicy": "restricted",
+              "ignoreOtherMentions": true
+            },
+            "WORK_GROUP_OPENID": {
+              "requireMention": true,
+              "toolPolicy": "none",
+              "prompt": "You are a work assistant. Only answer work-related questions."
+            },
+            "FRIEND_GROUP_OPENID": {
+              "requireMention": false,
+              "toolPolicy": "full",
+              "prompt": "You are a friend in the group. Chat casually and naturally."
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+#### Group Access Control (`groupPolicy`)
+
+Control which groups are allowed via `groupPolicy`:
+
+| Policy | Description |
+|--------|-------------|
+| `"open"` (default) | All groups are allowed |
+| `"allowlist"` | Only groups in `groupAllowFrom` are allowed |
+| `"disabled"` | Group chats are disabled entirely |
+
+```json
+{
+  "channels": {
+    "qqbot": {
+      "groupPolicy": "allowlist",
+      "groupAllowFrom": ["ALLOWED_GROUP_OPENID_1", "ALLOWED_GROUP_OPENID_2"]
+    }
+  }
+}
+```
+
+> You can also use [**`/bot-group-allways`**](#bot-group-allways--group-response-mode-toggle) to toggle account-level defaults at runtime without restarting.
+
+---
 
 #### STT (Speech-to-Text) — Transcribe Incoming Voice Messages
 

package/README.zh.md

@@ -31,7 +31,9 @@
 
 | 功能 | 说明 |
 |------|------|
-| 🔒 **多场景支持** | C2C 私聊、群聊 @消息 |
+| 🔒 **多场景支持** | C2C 私聊、群聊（@提及 / 自主发言双模式） |
+| 👥 **群聊精细管控** | 按群配置 @触发规则、工具权限、自定义提示词、消息过滤 |
+| 🌐 **双传输模式** | WebSocket（默认）或 Webhook（HTTP 回调）— 配置切换 |
 | 🖼️ **富媒体消息** | 支持图片、语音、视频、文件的收发 |
 | 🎙️ **语音能力 (STT/TTS)** | 语音转文字自动转录 & 文字转语音回复 |
 | 🔥 **一键热更新** | 私聊发送 `/bot-upgrade` 即可完成版本升级，无需登录服务器 |
@@ -237,6 +239,24 @@ AI 可直接发送视频，支持本地文件和公网 URL。
 
 `/bot-clear-storage` 列出对话产生的文件以及下载的资源目录里的文件，使用`/bot-clear-storage -- force`确定删除。
 
+#### `/bot-group-allways` — 群消息响应模式切换
+
+> **你**：`/bot-group-allways`
+>
+> **QQBot**：🤖 群自主发言状态：❌ 仅被 @ 时回复
+
+运行时动态切换群聊默认 @触发行为，修改即时持久化，无需重启：
+
+| 子命令 | 说明 |
+|--------|------|
+| `/bot-group-allways on` | AI 自主判断何时发言（无需 @） |
+| `/bot-group-allways off` | 仅在被 @ 时回复 |
+| `/bot-group-allways`（无参数） | 查看当前设置 |
+
+> ⚠️ 此指令修改账户级 `defaultRequireMention`，优先级低于具体群的 `groups.{groupId}.requireMention` 配置。
+
+---
+
 ---
 
 ## 🚀 快速开始
@@ -403,13 +423,180 @@ openclaw message send --channel "qqbot" \
 
 #### 工作原理
 
-- 启动 `openclaw gateway` 后，所有 `enabled: true` 的账户会同时启动 WebSocket 连接
+- 启动 `openclaw gateway` 后，所有 `enabled: true` 的账户会同时启动连接（WebSocket 或 Webhook，取决于 `transport` 配置）
 - 每个账户独立维护 Token 缓存（基于 `appId` 隔离），互不干扰
 - 接收消息时，日志会带上 `[qqbot:accountId]` 前缀方便排查
 
 ---
 
-### 语音能力配置（STT / TTS）
+### Webhook 传输模式
+
+默认情况下，插件通过 **WebSocket** 连接 QQ 平台（出站连接，无需公网 IP）。你也可以切换为 **Webhook** 模式，由 QQ 平台主动 POST 事件到你的 HTTP 端点。
+
+| | WebSocket（默认） | Webhook |
+|---|---|---|
+| 连接方式 | 插件主动连接 QQ 网关 | QQ 平台 POST 到你的服务器 |
+| 公网 IP | 不需要 | 需要 |
+| 适用场景 | 开发调试、单实例部署 | 生产环境、水平扩展、Serverless |
+| 会话恢复 | 支持 RESUME | 无状态，无需恢复 |
+| 签名验证 | 平台内置 | 插件自动 Ed25519 验签 |
+
+#### 配置方式
+
+```json
+{
+  "channels": {
+    "qqbot": {
+      "appId": "111111111",
+      "clientSecret": "your-secret",
+      "transport": "webhook",
+      "webhook": {
+        "path": "/qqbot/webhook"
+      }
+    }
+  }
+}
+```
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `transport` | `"websocket"` | `"websocket"` 或 `"webhook"` |
+| `webhook.path` | `"/qqbot/webhook"` | 接收回调的 HTTP 路径 |
+
+#### 平台配置步骤
+
+1. 登录 [QQ 开放平台](https://q.qq.com/) → 开发设置 → 消息接收方式
+2. 选择 **HTTP 回调**
+3. 填写回调 URL：`https://your-domain.com/qqbot/webhook`
+4. 平台发送 `op:13` 验证请求，插件自动处理签名验证
+5. 验证通过后，所有事件将以 POST 方式推送到该地址
+
+---
+
+### 群聊配置
+
+插件提供灵活的群聊管控能力，支持按群定制触发规则、工具权限和 AI 行为策略。
+
+#### @提及触发模式（requireMention）
+
+默认情况下，群聊中**必须 @机器人**才会触发 AI 回复。你可以通过配置让 AI 自主判断是否需要发言：
+
+| 模式 | 配置值 | 行为 |
+|------|--------|------|
+| **仅 @时回复** | `true`（默认） | 群消息中只有 @了机器人才会触发回复 |
+| **自主发言** | `false` | AI 自主判断每条消息是否需要回复，无需 @ |
+
+**优先级链**（从高到低）：
+
+```
+具体群 groups.{groupOpenid}.requireMention
+  > 通配符 groups."*".requireMention
+    > 账户级 defaultRequireMention
+      > 默认值 true
+```
+
+**配置示例：**
+
+```json
+{
+  "channels": {
+    "qqbot": {
+      // 账户级：所有群的默认行为
+      "defaultRequireMention": false,
+
+      "accounts": {
+        "default": {
+          "groups": {
+            "*": {
+              // 通配符：所有群的兜底规则
+              "requireMention": false
+            },
+            "GROUP_OPENID": {
+              // 单群覆盖：这个群仍然需要 @
+              "requireMention": true
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+> **使用场景举例：**
+>
+> - 工作群设为 `requireMention: true` — 避免 AI 对每条闲聊都插嘴
+> - 专属 AI 陪伴群设为 `requireMention: false` — 像真人一样自然参与对话
+> - 通过 `/bot-group-allways on|off` 指令可在运行时动态切换账户级默认值
+
+#### 其他群配置项
+
+除 `requireMention` 外，每个群还支持以下配置：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `ignoreOtherMentions` | `boolean` | `false` | 是否忽略 @了其他人但没 @机器人的消息。开启后这类消息直接丢弃，不记录历史、不触发 AI |
+| `toolPolicy` | `"full" \| "restricted" \| "none"` | `"restricted"` | 群聊中 AI 可使用的工具范围。`full`=全部可用；`restricted`=限制敏感工具（如命令执行、文件操作）；`none`=禁止所有工具调用 |
+| `prompt` | `string` | 内置默认提示词 | 该群专属的系统提示词，会追加到全局 systemPrompt 之后 |
+| `historyLimit` | `number` | `50` | 群历史消息缓存条数 |
+
+**完整群配置示例：**
+
+```json
+{
+  "channels": {
+    "qqbot": {
+      "defaultRequireMention": false,
+      "accounts": {
+        "default": {
+          "groups": {
+            "*": {
+              "requireMention": true,
+              "toolPolicy": "restricted",
+              "ignoreOtherMentions": true
+            },
+            "WORK_GROUP_OPENID": {
+              "requireMention": true,
+              "toolPolicy": "none",
+              "prompt": "你是工作助手，只回答与工作相关的问题"
+            },
+            "FRIEND_GROUP_OPENID": {
+              "requireMention": false,
+              "toolPolicy": "full",
+              "prompt": "你是群里的朋友，轻松随意地聊天"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+#### 群访问控制（groupPolicy）
+
+通过 `groupPolicy` 控制哪些群允许机器人加入并接收消息：
+
+| 策略 | 说明 |
+|------|------|
+| `"open"`（默认） | 所有群均可使用 |
+| `"allowlist"` | 仅 `groupAllowFrom` 白名单中的群可使用 |
+| `"disabled"` | 禁止所有群聊 |
+
+```json
+{
+  "channels": {
+    "qqbot": {
+      "groupPolicy": "allowlist",
+      "groupAllowFrom": ["ALLOWED_GROUP_OPENID_1", "ALLOWED_GROUP_OPENID_2"]
+    }
+  }
+}
+```
+
+> 也可通过 [**`/bot-group-allways`** 指令](#bot-group-allways--群消息响应模式切换) 在运行时动态切换账户级默认值，无需重启。
+
+---
 
 #### STT（语音转文字）— 自动转录用户发来的语音消息
 

package/dist/index.d.ts

@@ -15,3 +15,4 @@ export * from "./src/api.js";
 export * from "./src/config.js";
 export * from "./src/gateway.js";
 export * from "./src/outbound.js";
+export * from "./src/transport/index.js";

package/dist/index.js

@@ -24,3 +24,4 @@ export * from "./src/api.js";
 export * from "./src/config.js";
 export * from "./src/gateway.js";
 export * from "./src/outbound.js";
+export * from "./src/transport/index.js";

package/dist/src/api.d.ts

@@ -27,6 +27,8 @@ export declare class ApiError extends Error {
     /** 回包中的原始 message 字段（用于向用户展示兜底文案） */
     bizMessage?: string | undefined);
 }
+export declare const API_BASE: string;
+export declare const TOKEN_URL: string;
 /** 由 setQQBotRuntime 调用，将 api.runtime.version 注入到 User-Agent */
 export declare function setOpenClawVersion(version: string): void;
 export declare function getPluginUserAgent(): string;

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;

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,
     };
 }