@dingxiang-me/openclaw-wechat 1.7.1 → 1.7.2

package/CHANGELOG.md

@@ -52,6 +52,17 @@ All notable changes to this project will be documented in this file.
 - 远端 E2E 兼容增强：`test:e2e:remote` 支持 `WECOM_E2E_*` 与 legacy `E2E_WECOM_*` 两套环境变量
 - 语法检查范围增强：`test:syntax` 从仅 `src` 扩展到 `src + scripts + tests`，降低脚本/测试回归漏检风险
 
+## [1.7.2] - 2026-03-05
+
+### Changed
+- Bot 群聊触发策略收紧：在企业微信官方 Bot 模式下，`groupChat.triggerMode=direct/keyword` 会自动规范为 `mention` 并输出告警，避免“配置可写但平台不回调”的误导
+- Bot `/status` 与 `/help` 文案增强：明确“群聊通常仅 @ 机器人消息触发（平台限制）”
+- 文档更新：README 与 `docs/channels/wecom.md` 明确 Bot 群聊触发限制与配置降级行为
+
+### Added
+- 新增回归测试 `tests/wecom-bot-inbound-executor-helpers.test.mjs`，覆盖 Bot 群聊策略规范化
+- 更新命令处理测试，覆盖 Bot 状态文案中的平台限制提示
+
 ## [1.7.1] - 2026-03-05
 
 ### Added

package/README.md

@@ -299,6 +299,9 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | `lateReplyPollMs` | integer | `2000` | Bot 异步补发轮询间隔（500ms~10s） |
 | `card` | object | 见下方 | Bot 卡片回包策略（`response_url` / `webhook_bot`） |
 
+> 重要限制：企业微信官方 Bot 在群聊里通常仅对 `@机器人` 消息触发回调。  
+> 因此 Bot 模式下即使配置 `groupChat.triggerMode=direct/keyword`，也会按 `mention` 处理（插件会输出告警）。
+
 #### Bot 卡片配置（`channels.wecom.bot.card`）
 
 | 键 | 类型 | 默认 | 说明 |
@@ -340,7 +343,7 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | 命令白名单 | `commands.enabled` + `commands.allowlist` | 限制 `/` 指令 |
 | 私聊策略 | `dm.mode` + `dm.allowFrom` + `dm.rejectMessage` | 控制私聊开放/白名单/拒绝 |
 | 事件策略 | `events.enabled` + `events.enterAgentWelcomeEnabled` + `events.enterAgentWelcomeText` | 控制事件处理与 enter_agent 欢迎语 |
-| 群聊触发 | `groupChat.enabled` + `triggerMode` + `mentionPatterns` + `triggerKeywords` | 控制群消息触发条件 |
+| 群聊触发 | `groupChat.enabled` + `triggerMode` + `mentionPatterns` + `triggerKeywords` | 控制群消息触发条件（自建应用支持 `direct/mention/keyword`；Bot 模式按平台限制固定 `mention`） |
 | 动态路由 | `dynamicAgent.*`（兼容 `dynamicAgents.*`、`dm.createAgentOnFirstMessage`） | 动态 Agent + workspace bootstrap 播种 |
 
 ### 吞吐与稳定性
@@ -633,10 +636,10 @@ npm run wecom:bot:selfcheck -- --all-accounts
 
 ### Q6：自建应用群聊怎么开？为什么群里不 @ 就不触发？
 先区分两种通道能力：
-1. **群机器人（Webhook Bot）**：可直接添加到企微群，天然适合群聊收发。
+1. **群机器人（Webhook Bot）**：可直接添加到企微群，天然适合群聊收发；但群聊通常仅 `@机器人` 时才会回调。
 2. **自建应用（Agent 回调）**：插件支持处理 `ChatId` 群消息；但是否能收到“普通群消息”取决于企业微信实际下发能力（很多租户里普通群只能加机器人，无法像成员一样加自建应用）。
 
-如果你的场景是“普通群里直接聊天并稳定触发”，优先用 **Webhook Bot 模式**。  
+如果你的场景是“普通群里稳定对话”，优先用 **Webhook Bot 模式**（注意通常仍需 `@机器人` 才触发）。  
 如果你确认企业微信会把群消息回调到自建应用（日志里有 `chatId=...`），再配置触发模式：
 
 ```json

package/docs/channels/wecom.md

@@ -19,7 +19,7 @@ This channel integrates OpenClaw with WeCom (企业微信) internal apps.
 - Bot card replies: supported (`channels.wecom.bot.card`, `markdown/template_card`)
 - Direct-message policy: supported (`channels.wecom.dm.mode=open|allowlist|deny`, account-level override via `accounts.<id>.dm`)
 - Event handling: supported (`channels.wecom.events.*`, supports `enter_agent` welcome reply)
-- Group trigger mode: `direct` / `mention` / `keyword` (`channels.wecom.groupChat.triggerMode`)
+- Group trigger mode: Agent callback supports `direct` / `mention` / `keyword`; Bot mode is effectively `mention` (WeCom platform callback constraint)
 - Dynamic agent route mode: `deterministic` / `mapping` / `hybrid` (`channels.wecom.dynamicAgent.mode`)
 - Dynamic workspace seeding: supported via `channels.wecom.dynamicAgent.workspaceTemplate`
 - Session queue / stream manager: optional (`channels.wecom.stream.manager`)
@@ -40,7 +40,7 @@ Named webhook targets (optional):
 
 WeCom has two different integration shapes:
 
-1. **Webhook Bot**: can be added directly to regular group chats.
+1. **Webhook Bot**: can be added directly to regular group chats, but callbacks are typically triggered only when the bot is mentioned (`@机器人`).
 2. **Self-built App callback**: plugin supports group processing when callback payload contains `ChatId`.
 
 To enable direct group trigger (`triggerMode=direct`) for self-built app callback, ensure:
@@ -53,6 +53,8 @@ To enable direct group trigger (`triggerMode=direct`) for self-built app callbac
 If logs never show `chatId`, WeCom is not delivering group messages to this callback route.  
 In that case, use **Webhook Bot mode** for regular group chat scenarios.
 
+Note: In Bot mode, `groupChat.triggerMode=direct/keyword` is normalized to `mention` by the plugin to avoid misleading config.
+
 ## Selfcheck
 
 Run:
@@ -165,7 +167,7 @@ All new switches are default-off for compatibility.
 }
 ```
 
-## P2 Routing Config (Recommended)
+## P2 Routing Config (Recommended, Agent callback)
 
 ```json
 {

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-wechat",
   "name": "OpenClaw-Wechat",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "WeCom (企业微信) channel plugin for OpenClaw (自建应用回调 + 发送 API).",
   "channels": [
     "wecom"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dingxiang-me/openclaw-wechat",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "type": "module",
   "description": "WeCom (企业微信) channel plugin for OpenClaw (自建应用回调 + 发送 API).",
   "license": "MIT",

package/src/wecom/bot-inbound-executor-helpers.js

@@ -4,6 +4,45 @@ function assertFunction(name, value) {
   }
 }
 
+const UNSUPPORTED_BOT_GROUP_TRIGGER_WARNED = new Set();
+
+function warnUnsupportedBotGroupTriggerOnce(triggerMode, logger) {
+  const mode = String(triggerMode ?? "").trim().toLowerCase();
+  if (!mode || UNSUPPORTED_BOT_GROUP_TRIGGER_WARNED.has(mode)) return;
+  UNSUPPORTED_BOT_GROUP_TRIGGER_WARNED.add(mode);
+  logger?.warn?.(
+    `wecom(bot): groupChat.triggerMode=${mode} is not supported by WeCom Bot group callbacks; forcing mention mode (@).`,
+  );
+}
+
+export function normalizeWecomBotGroupChatPolicy(groupChatPolicy = {}, logger) {
+  const policy = groupChatPolicy && typeof groupChatPolicy === "object" ? groupChatPolicy : {};
+  const enabled = policy.enabled !== false;
+  const mentionPatterns =
+    Array.isArray(policy.mentionPatterns) && policy.mentionPatterns.length > 0 ? policy.mentionPatterns : ["@"];
+
+  if (!enabled) {
+    return {
+      ...policy,
+      enabled: false,
+      mentionPatterns,
+    };
+  }
+
+  const triggerMode = String(policy.triggerMode ?? "").trim().toLowerCase();
+  if (triggerMode && triggerMode !== "mention") {
+    warnUnsupportedBotGroupTriggerOnce(triggerMode, logger);
+  }
+
+  return {
+    ...policy,
+    enabled: true,
+    triggerMode: "mention",
+    requireMention: true,
+    mentionPatterns,
+  };
+}
+
 export function assertWecomBotInboundFlowDeps({ api, ...deps } = {}) {
   if (!api || typeof api !== "object") {
     throw new Error("executeWecomBotInboundFlow: api is required");
@@ -104,7 +143,7 @@ export function createWecomBotInboundFlowState({
           .filter(Boolean),
       ),
     ),
-    groupChatPolicy: resolveWecomGroupChatPolicy(api),
+    groupChatPolicy: normalizeWecomBotGroupChatPolicy(resolveWecomGroupChatPolicy(api), api?.logger),
     dynamicAgentPolicy: resolveWecomDynamicAgentPolicy(api),
     isAdminUser: false,
   };

package/src/wecom/command-status-text.js

@@ -180,11 +180,7 @@ export function buildBotStatusText({
   const dmPolicyLine = buildDmPolicyStatusLine(dmPolicy);
   const eventPolicyLine = buildEventPolicyStatusLine(eventPolicy);
   const groupPolicyLine = groupPolicy.enabled
-    ? groupPolicy.triggerMode === "mention"
-      ? "✅ 群聊触发：仅 @ 命中后处理"
-      : groupPolicy.triggerMode === "keyword"
-        ? `✅ 群聊触发：关键词模式（${(groupPolicy.triggerKeywords || []).join(" / ") || "未配置关键词"}）`
-        : "✅ 群聊触发：无需 @（全部处理）"
+    ? "✅ 群聊触发：仅 @ 机器人后处理（企业微信 Bot 平台限制）"
     : "⚠️ 群聊处理未启用";
   const fallbackPolicyLine = deliveryFallbackPolicy.enabled
     ? `✅ 回包兜底链路已启用（${deliveryFallbackPolicy.order.join(" > ")}）`
@@ -237,5 +233,7 @@ export function buildWecomBotHelpText() {
 /status - 查看系统状态
 /clear - 重置会话（等价于 /reset）
 
+说明：企业微信 Bot 群聊通常仅对 @ 机器人消息触发回调。
+
 直接发送消息即可与 AI 对话。`;
 }