@dingxiang-me/openclaw-wechat 1.4.1 → 1.7.2

package/docs/channels/wecom.md

@@ -16,11 +16,15 @@ This channel integrates OpenClaw with WeCom (企业微信) internal apps.
 - Multi-account: supported (`channels.wecom.accounts`)
 - Voice recognition: WeCom `Recognition` first; local whisper fallback supported (`channels.wecom.voiceTranscription`)
 - Delivery fallback chain: optional (`active_stream -> response_url -> webhook_bot -> agent_push`)
-- Group trigger mode: `direct` / `mention` / `keyword` (`channels.wecom.groupChat.triggerMode`)
+- 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: 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`)
 - Bot timeout tuning: supported (`channels.wecom.bot.replyTimeoutMs`, `lateReplyWatchMs`, `lateReplyPollMs`)
+- Observability counters: supported (`channels.wecom.observability.*`, visible in `/status`)
 
 ## Callback URL
 
@@ -36,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:
@@ -49,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:
@@ -133,16 +139,35 @@ All new switches are default-off for compatibility.
           "maxConcurrentPerSession": 1
         }
       },
+      "bot": {
+        "card": {
+          "enabled": false,
+          "mode": "markdown",
+          "title": "OpenClaw-Wechat",
+          "responseUrlEnabled": true,
+          "webhookBotEnabled": true
+        }
+      },
       "observability": {
         "enabled": true,
         "logPayloadMeta": true
+      },
+      "dm": {
+        "mode": "allowlist",
+        "allowFrom": ["alice", "wecom:bob"],
+        "rejectMessage": "当前账号未授权，请联系管理员。"
+      },
+      "events": {
+        "enabled": true,
+        "enterAgentWelcomeEnabled": true,
+        "enterAgentWelcomeText": "你好，我是 AI 助手，直接发消息即可开始对话。"
       }
     }
   }
 }
 ```
 
-## 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.4.1",
+  "version": "1.7.2",
   "description": "WeCom (企业微信) channel plugin for OpenClaw (自建应用回调 + 发送 API).",
   "channels": [
     "wecom"
@@ -12,7 +12,17 @@
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
+    "patternProperties": {
+      "^(?!(name|enabled|corpId|corpSecret|agentId|callbackToken|token|callbackAesKey|encodingAesKey|webhookPath|agent|bot|delivery|webhookBot|stream|observability|outboundProxy|webhooks|allowFrom|allowFromRejectMessage|adminUsers|commandAllowlist|commandBlockMessage|commands|workspaceTemplate|groupChat|dynamicAgent|dynamicAgents|dm|debounce|streaming|voiceTranscription|accounts)$)[A-Za-z0-9_-]+$": {
+        "type": "object",
+        "description": "兼容旧配置：inline 多账户（推荐迁移到 channels.wecom.accounts.<id>）"
+      }
+    },
     "properties": {
+      "name": {
+        "type": "string",
+        "description": "兼容旧配置：渠道显示名（运行时可忽略）"
+      },
       "enabled": {
         "type": "boolean",
         "default": true,
@@ -50,7 +60,7 @@
       "token": {
         "type": "string",
         "minLength": 1,
-        "description": "兼容旧配置：等价 callbackToken（不推荐新配置继续使用）",
+        "description": "兼容字段：默认等价 callbackToken；当使用 legacy agent 配置块时可作为 Bot token 使用",
         "x-sensitive": true
       },
       "callbackAesKey": {
@@ -62,7 +72,7 @@
       "encodingAesKey": {
         "type": "string",
         "minLength": 1,
-        "description": "兼容旧配置：等价 callbackAesKey（不推荐新配置继续使用）",
+        "description": "兼容字段：默认等价 callbackAesKey；当使用 legacy agent 配置块时可作为 Bot encodingAesKey 使用",
         "x-sensitive": true
       },
       "webhookPath": {
@@ -70,6 +80,56 @@
         "description": "Webhook 路径",
         "default": "/wecom/callback"
       },
+      "agent": {
+        "type": "object",
+        "description": "兼容旧配置：自建应用凭证块（与顶层 corpId/corpSecret/agentId 等价）",
+        "additionalProperties": false,
+        "properties": {
+          "corpId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "corpSecret": {
+            "type": "string",
+            "minLength": 1,
+            "x-sensitive": true
+          },
+          "agentId": {
+            "oneOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "string",
+                "pattern": "^[0-9]+$"
+              }
+            ]
+          },
+          "callbackToken": {
+            "type": "string",
+            "minLength": 1,
+            "x-sensitive": true
+          },
+          "token": {
+            "type": "string",
+            "minLength": 1,
+            "x-sensitive": true
+          },
+          "callbackAesKey": {
+            "type": "string",
+            "minLength": 1,
+            "x-sensitive": true
+          },
+          "encodingAesKey": {
+            "type": "string",
+            "minLength": 1,
+            "x-sensitive": true
+          },
+          "webhookPath": {
+            "type": "string"
+          }
+        }
+      },
       "bot": {
         "type": "object",
         "description": "企业微信 AI 机器人（Bot API 模式）配置（JSON 回调 + 原生 stream）",
@@ -126,6 +186,56 @@
             "maximum": 10000,
             "default": 2000,
             "description": "Bot 异步补发轮询间隔（毫秒）"
+          },
+          "card": {
+            "type": "object",
+            "description": "Bot 卡片回包策略（response_url / webhook_bot）",
+            "additionalProperties": false,
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": false,
+                "description": "是否启用 Bot 卡片回包（默认关闭，保持兼容）"
+              },
+              "mode": {
+                "type": "string",
+                "enum": [
+                  "markdown",
+                  "template_card"
+                ],
+                "default": "markdown",
+                "description": "卡片模式：markdown（兼容优先）/ template_card（模板卡片）"
+              },
+              "title": {
+                "type": "string",
+                "description": "卡片标题"
+              },
+              "subtitle": {
+                "type": "string",
+                "description": "卡片副标题"
+              },
+              "footer": {
+                "type": "string",
+                "description": "卡片底部说明"
+              },
+              "maxContentLength": {
+                "type": "integer",
+                "minimum": 200,
+                "maximum": 4000,
+                "default": 1400,
+                "description": "卡片正文最大长度（超出自动截断）"
+              },
+              "responseUrlEnabled": {
+                "type": "boolean",
+                "default": true,
+                "description": "是否在 response_url 层启用卡片发送"
+              },
+              "webhookBotEnabled": {
+                "type": "boolean",
+                "default": true,
+                "description": "是否在 webhook_bot 层启用卡片发送"
+              }
+            }
           }
         }
       },
@@ -275,6 +385,18 @@
           "minLength": 1
         }
       },
+      "commandAllowlist": {
+        "type": "array",
+        "description": "兼容旧配置：命令白名单（等价 commands.allowlist）",
+        "items": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "commandBlockMessage": {
+        "type": "string",
+        "description": "兼容旧配置：命令拦截提示（等价 commands.rejectMessage）"
+      },
       "commands": {
         "type": "object",
         "description": "指令白名单控制（启用后仅允许 allowlist 内的 / 指令）",
@@ -296,9 +418,17 @@
           "rejectMessage": {
             "type": "string",
             "description": "命中未授权指令时返回给用户的提示文本"
+          },
+          "blockMessage": {
+            "type": "string",
+            "description": "兼容旧配置：等价 rejectMessage"
           }
         }
       },
+      "workspaceTemplate": {
+        "type": "string",
+        "description": "兼容旧配置：动态 Agent workspace 模板目录（等价 dynamicAgent.workspaceTemplate）"
+      },
       "groupChat": {
         "type": "object",
         "description": "群聊触发策略",
@@ -443,6 +573,76 @@
             "type": "boolean",
             "default": true,
             "description": "未命中动态映射时是否回退到 OpenClaw 默认路由"
+          },
+          "dmCreateAgentOnFirstMessage": {
+            "type": "boolean",
+            "default": true,
+            "description": "私聊是否启用动态 Agent（兼容 dm.createAgentOnFirstMessage）"
+          },
+          "groupEnabled": {
+            "type": "boolean",
+            "default": true,
+            "description": "群聊是否启用动态 Agent 路由（消息触发仍受 groupChat 配置控制）"
+          }
+        }
+      },
+      "dynamicAgents": {
+        "type": "object",
+        "description": "兼容旧配置：等价 dynamicAgent（旧项目常用命名）",
+        "additionalProperties": true
+      },
+      "dm": {
+        "type": "object",
+        "description": "私聊策略与兼容配置",
+        "additionalProperties": false,
+        "properties": {
+          "mode": {
+            "type": "string",
+            "enum": [
+              "open",
+              "allowlist",
+              "deny"
+            ],
+            "default": "open",
+            "description": "私聊策略：open=开放，allowlist=白名单，deny=关闭"
+          },
+          "rejectMessage": {
+            "type": "string",
+            "description": "私聊被拒绝时的提示文案"
+          },
+          "createAgentOnFirstMessage": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否为私聊在首条消息时创建动态 Agent（等价 dynamicAgent.dmCreateAgentOnFirstMessage）"
+          },
+          "allowFrom": {
+            "type": "array",
+            "description": "私聊白名单（mode=allowlist 时生效）",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      },
+      "events": {
+        "type": "object",
+        "description": "事件消息策略（如 enter_agent 欢迎语）",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否处理事件消息（MsgType=event）"
+          },
+          "enterAgentWelcomeEnabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否在 enter_agent 事件时自动回复欢迎语"
+          },
+          "enterAgentWelcomeText": {
+            "type": "string",
+            "description": "enter_agent 自动欢迎语文本"
           }
         }
       },
@@ -592,6 +792,10 @@
               "type": "boolean",
               "default": true
             },
+            "name": {
+              "type": "string",
+              "description": "兼容旧配置：账户显示名"
+            },
             "corpId": {
               "type": "string",
               "minLength": 1
@@ -636,7 +840,188 @@
             },
             "webhookPath": {
               "type": "string",
-              "default": "/wecom/callback"
+              "default": "/wecom/callback",
+              "description": "Agent 回调路径；非 default 账户未填写时自动使用 /wecom/<accountId>/callback"
+            },
+            "agent": {
+              "type": "object",
+              "description": "兼容旧配置：该账户自建应用凭证块（与账户顶层 corpId/corpSecret/agentId 等价）",
+              "additionalProperties": false,
+              "properties": {
+                "corpId": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "corpSecret": {
+                  "type": "string",
+                  "minLength": 1,
+                  "x-sensitive": true
+                },
+                "agentId": {
+                  "oneOf": [
+                    {
+                      "type": "number"
+                    },
+                    {
+                      "type": "string",
+                      "pattern": "^[0-9]+$"
+                    }
+                  ]
+                },
+                "callbackToken": {
+                  "type": "string",
+                  "minLength": 1,
+                  "x-sensitive": true
+                },
+                "token": {
+                  "type": "string",
+                  "minLength": 1,
+                  "x-sensitive": true
+                },
+                "callbackAesKey": {
+                  "type": "string",
+                  "minLength": 1,
+                  "x-sensitive": true
+                },
+                "encodingAesKey": {
+                  "type": "string",
+                  "minLength": 1,
+                  "x-sensitive": true
+                },
+                "webhookPath": {
+                  "type": "string"
+                }
+              }
+            },
+            "bot": {
+              "type": "object",
+              "description": "该账户专用 Bot 模式配置（覆盖 channels.wecom.bot）",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "是否启用该账户 Bot 模式"
+                },
+                "token": {
+                  "type": "string",
+                  "description": "Bot 模式回调 Token"
+                },
+                "callbackToken": {
+                  "type": "string",
+                  "description": "兼容旧配置：等价 token"
+                },
+                "encodingAesKey": {
+                  "type": "string",
+                  "description": "Bot 模式回调 EncodingAESKey（43 位）",
+                  "x-sensitive": true
+                },
+                "callbackAesKey": {
+                  "type": "string",
+                  "description": "兼容旧配置：等价 encodingAesKey",
+                  "x-sensitive": true
+                },
+                "webhookPath": {
+                  "type": "string",
+                  "default": "/wecom/bot/callback",
+                  "description": "Bot 模式 webhook 路径；非 default 账户未填写时自动使用 /wecom/<accountId>/bot/callback"
+                },
+                "placeholderText": {
+                  "type": "string",
+                  "default": "消息已收到，正在处理中，请稍等片刻。",
+                  "description": "Bot 模式初始 stream 占位文本"
+                },
+                "streamExpireMs": {
+                  "type": "integer",
+                  "minimum": 30000,
+                  "maximum": 3600000,
+                  "default": 600000,
+                  "description": "Bot 流式会话保留时长（毫秒）"
+                },
+                "replyTimeoutMs": {
+                  "type": "integer",
+                  "minimum": 15000,
+                  "maximum": 600000,
+                  "default": 90000,
+                  "description": "Bot 模式等待模型回包超时（毫秒）"
+                },
+                "lateReplyWatchMs": {
+                  "type": "integer",
+                  "minimum": 30000,
+                  "maximum": 600000,
+                  "default": 180000,
+                  "description": "Bot 超时后异步补发观察窗口（毫秒）"
+                },
+                "lateReplyPollMs": {
+                  "type": "integer",
+                  "minimum": 500,
+                  "maximum": 10000,
+                  "default": 2000,
+                  "description": "Bot 异步补发轮询间隔（毫秒）"
+                },
+                "card": {
+                  "type": "object",
+                  "description": "该账户 Bot 卡片回包策略（覆盖 channels.wecom.bot.card）",
+                  "additionalProperties": false,
+                  "properties": {
+                    "enabled": {
+                      "type": "boolean",
+                      "default": false,
+                      "description": "是否启用该账户 Bot 卡片回包"
+                    },
+                    "mode": {
+                      "type": "string",
+                      "enum": [
+                        "markdown",
+                        "template_card"
+                      ],
+                      "default": "markdown",
+                      "description": "卡片模式：markdown / template_card"
+                    },
+                    "title": {
+                      "type": "string",
+                      "description": "卡片标题"
+                    },
+                    "subtitle": {
+                      "type": "string",
+                      "description": "卡片副标题"
+                    },
+                    "footer": {
+                      "type": "string",
+                      "description": "卡片底部说明"
+                    },
+                    "maxContentLength": {
+                      "type": "integer",
+                      "minimum": 200,
+                      "maximum": 4000,
+                      "default": 1400,
+                      "description": "卡片正文最大长度（超出自动截断）"
+                    },
+                    "responseUrlEnabled": {
+                      "type": "boolean",
+                      "default": true,
+                      "description": "是否在 response_url 层启用卡片发送"
+                    },
+                    "webhookBotEnabled": {
+                      "type": "boolean",
+                      "default": true,
+                      "description": "是否在 webhook_bot 层启用卡片发送"
+                    }
+                  }
+                },
+                "outboundProxy": {
+                  "type": "string",
+                  "description": "可选：该账户 Bot 回调媒体下载/回包专用代理（覆盖 channels.wecom.bot/outboundProxy）"
+                },
+                "proxyUrl": {
+                  "type": "string",
+                  "description": "兼容字段：等价 outboundProxy"
+                },
+                "proxy": {
+                  "type": "string",
+                  "description": "兼容字段：等价 outboundProxy"
+                }
+              }
             },
             "outboundProxy": {
               "type": "string",
@@ -661,13 +1046,58 @@
             "allowFromRejectMessage": {
               "type": "string",
               "description": "可选：该账户发送者未授权时的拒绝文案（覆盖 channels.wecom.allowFromRejectMessage）"
+            },
+            "dm": {
+              "type": "object",
+              "description": "可选：该账户私聊策略（覆盖 channels.wecom.dm）",
+              "additionalProperties": false,
+              "properties": {
+                "mode": {
+                  "type": "string",
+                  "enum": [
+                    "open",
+                    "allowlist",
+                    "deny"
+                  ],
+                  "default": "open",
+                  "description": "私聊策略：open=开放，allowlist=白名单，deny=关闭"
+                },
+                "allowFrom": {
+                  "type": "array",
+                  "description": "私聊白名单（mode=allowlist 时生效）",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "rejectMessage": {
+                  "type": "string",
+                  "description": "私聊被拒绝时的提示文案"
+                }
+              }
+            },
+            "events": {
+              "type": "object",
+              "description": "可选：该账户事件策略（覆盖 channels.wecom.events）",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "是否处理该账户事件消息（MsgType=event）"
+                },
+                "enterAgentWelcomeEnabled": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "是否在 enter_agent 事件自动回复欢迎语"
+                },
+                "enterAgentWelcomeText": {
+                  "type": "string",
+                  "description": "该账户 enter_agent 自动欢迎语文本"
+                }
+              }
             }
-          },
-          "required": [
-            "corpId",
-            "corpSecret",
-            "agentId"
-          ]
+          }
         }
       }
     }
@@ -688,12 +1118,39 @@
     "encodingAesKey": {
       "sensitive": true
     },
+    "agent.corpSecret": {
+      "sensitive": true
+    },
+    "agent.callbackToken": {
+      "sensitive": true
+    },
+    "agent.token": {
+      "sensitive": true
+    },
+    "agent.callbackAesKey": {
+      "sensitive": true
+    },
+    "agent.encodingAesKey": {
+      "sensitive": true
+    },
     "bot.token": {
       "sensitive": true
     },
     "bot.encodingAesKey": {
       "sensitive": true
     },
+    "accounts.*.bot.token": {
+      "sensitive": true
+    },
+    "accounts.*.bot.callbackToken": {
+      "sensitive": true
+    },
+    "accounts.*.bot.encodingAesKey": {
+      "sensitive": true
+    },
+    "accounts.*.bot.callbackAesKey": {
+      "sensitive": true
+    },
     "webhookBot.key": {
       "sensitive": true
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dingxiang-me/openclaw-wechat",
-  "version": "1.4.1",
+  "version": "1.7.2",
   "type": "module",
   "description": "WeCom (企业微信) channel plugin for OpenClaw (自建应用回调 + 发送 API).",
   "license": "MIT",
@@ -33,17 +33,28 @@
         "qiwei",
         "wxwork"
       ]
+    },
+    "install": {
+      "defaultChoice": "npm",
+      "npmSpec": "@dingxiang-me/openclaw-wechat"
     }
   },
   "scripts": {
     "lint": "npm run test:syntax",
-    "test:syntax": "find src -name '*.js' -print0 | xargs -0 -n1 node -c",
+    "test:syntax": "find src scripts tests -type f \\( -name '*.js' -o -name '*.mjs' \\) -print0 | xargs -0 -n1 node -c",
     "test": "npm run test:syntax && node --test tests/*.test.mjs",
+    "test:e2e": "node --test tests/e2e/*.test.mjs",
     "test:e2e:remote": "node --test tests/e2e/*.test.mjs",
+    "test:e2e:matrix": "node --test tests/e2e/remote-wecom.matrix.test.mjs",
+    "test:e2e:prepare-browser": "bash ./tests/e2e/prepare-browser-sandbox.sh",
+    "test:e2e:collect-pdf": "bash ./tests/e2e/collect-browser-pdf.sh",
     "wecom:selfcheck": "node ./scripts/wecom-selfcheck.mjs",
     "wecom:agent:selfcheck": "node ./scripts/wecom-agent-selfcheck.mjs",
     "wecom:bot:selfcheck": "node ./scripts/wecom-bot-selfcheck.mjs",
     "wecom:remote:e2e": "node ./scripts/wecom-remote-e2e.mjs",
+    "wecom:e2e:scenario": "node ./scripts/wecom-e2e-scenario.mjs",
+    "wecom:e2e:full": "node ./scripts/wecom-e2e-scenario.mjs --scenario full-smoke --prepare-browser --collect-pdf",
+    "wecom:e2e:compat": "node ./scripts/wecom-e2e-scenario.mjs --scenario compat-smoke",
     "wecom:smoke": "bash ./scripts/wecom-smoke.sh"
   },
   "dependencies": {