@yanhaidao/wecom 2.3.2 → 2.3.4

package/.github/workflows/release.yml

@@ -4,6 +4,7 @@ on:
   push:
     tags:
       - 'v*'
+      - 'wecom-v*'
 
 jobs:
   publish:
@@ -34,6 +35,51 @@ jobs:
         run: |
           npm i -g npm@^11.5.1
           npm -v
+          npm config delete always-auth || true
+
+      - name: Resolve release metadata
+        id: meta
+        run: |
+          set -euo pipefail
+          TAG="${GITHUB_REF_NAME}"
+          if [[ "${TAG}" == wecom-v* ]]; then
+            VERSION="${TAG#wecom-v}"
+          elif [[ "${TAG}" == v* ]]; then
+            VERSION="${TAG#v}"
+          else
+            echo "::error::Unsupported tag format: ${TAG}. Use v<version> or wecom-v<version>."
+            exit 1
+          fi
+          PKG_NAME="$(node -p "require('./package.json').name")"
+          PKG_VERSION="$(node -p "require('./package.json').version")"
+
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "pkg_name=${PKG_NAME}" >> "$GITHUB_OUTPUT"
+          echo "pkg_version=${PKG_VERSION}" >> "$GITHUB_OUTPUT"
+
+          echo "tag=${TAG}"
+          echo "version_from_tag=${VERSION}"
+          echo "package=${PKG_NAME}@${PKG_VERSION}"
+
+          if [ "${VERSION}" != "${PKG_VERSION}" ]; then
+            echo "::error::Tag version (${VERSION}) does not match package.json version (${PKG_VERSION})."
+            exit 1
+          fi
+
+      - name: Check npm version already published
+        id: npm_check
+        run: |
+          set -euo pipefail
+          PKG="${{ steps.meta.outputs.pkg_name }}"
+          VER="${{ steps.meta.outputs.pkg_version }}"
+          if npm view "${PKG}@${VER}" version >/dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+            echo "npm version already published: ${PKG}@${VER}"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+            echo "npm version not published yet: ${PKG}@${VER}"
+          fi
 
       - name: Install Dependencies
         run: npm install --legacy-peer-deps || npm install
@@ -43,13 +89,35 @@ jobs:
 
       # 🚀 自动发布到 npm (使用 OIDC 自动授权，无需 Token)
       - name: Publish to npm
+        if: steps.npm_check.outputs.exists != 'true'
         run: npm publish --access public
 
+      - name: Prepare release notes body
+        id: notes
+        run: |
+          set -euo pipefail
+          CHANGELOG_FILE="changelog/v${{ steps.meta.outputs.version }}.md"
+          if [ -f "${CHANGELOG_FILE}" ]; then
+            echo "Using changelog file: ${CHANGELOG_FILE}"
+            cp "${CHANGELOG_FILE}" /tmp/release-body.md
+          else
+            echo "Changelog file missing: ${CHANGELOG_FILE}; using fallback notes."
+            {
+              echo "# @yanhaidao/wecom v${{ steps.meta.outputs.version }}"
+              echo
+              if [ "${{ steps.npm_check.outputs.exists }}" = "true" ]; then
+                echo "- npm publish skipped: version already exists."
+              else
+                echo "- npm publish completed."
+              fi
+            } > /tmp/release-body.md
+          fi
+
       # 自动同步发布 GitHub Release
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
-          body_path: changelog/${{ github.ref_name }}.md
+          body_path: /tmp/release-body.md
           draft: false
           prerelease: false
         env:

package/README.md

@@ -1,5 +1,8 @@
 # OpenClaw 企业微信（WeCom）Channel 插件
 
+> [!WARNING]
+> **OpenClaw 3.1+ 升级必读**：升级到 OpenClaw `3.1` 及以上版本的用户务必同步升级本插件，并将企业微信回调 URL 更新为 OpenClaw 推荐路径：`/plugins/wecom/bot/{accountId}` 与 `/plugins/wecom/agent/{accountId}`（旧 `/wecom/*` 仍兼容但不再维护）。
+
 <p align="center">
   <img src="https://img.shields.io/badge/Original%20Project-YanHaidao-orange?style=for-the-badge&logo=github" alt="Original Project" />
   <img src="https://img.shields.io/badge/License-ISC-blue?style=for-the-badge" alt="License" />
@@ -80,7 +83,6 @@
 ## 一、🚀 快速开始
 
 > 默认推荐：**多账号 + 多 Agent（matrix）**。  
-> 单账号 Bot/Agent 配置仍然支持，但建议仅用于兼容或小规模场景。
 > 建议 OpenClaw 使用 **2026.2.24+** 版本以获得完整生命周期与多账号行为修复。
 
 ### 1.1 安装插件
@@ -152,19 +154,12 @@ openclaw channels status
 ```
 
 Webhook 回调建议按账号分别配置：
-- Bot：`/wecom/bot/{accountId}`
-- Agent：`/wecom/agent/{accountId}`
+- Bot（推荐）：`/plugins/wecom/bot/{accountId}`
+- Agent（推荐）：`/plugins/wecom/agent/{accountId}`
 
 > 提示：如果你已有 `bindings`，请先备份并按需合并，避免覆盖其它通道绑定。
 
-### 1.3 兼容模式（单账号）
-
-为降低主线认知负担，README 默认仅展示多账号配置。  
-如果你在维护历史部署或只需单账号，请查看兼容文档：
-
-- [单账号兼容模式配置指南](./compat-single-account.md)
-
-### 1.4 高级网络配置（公网出口代理）
+### 1.3 高级网络配置（公网出口代理）
 如果您的服务器使用 **动态 IP** (如家庭宽带、内网穿透) 或 **无公网 IP**，企业微信 API 会因 IP 变动报错 `60020 not allow to access from your ip`。
 此时需配置一个**固定 IP 的正向代理** (如 Squid)，让插件通过该代理访问企微 API。
 
@@ -172,7 +167,7 @@ Webhook 回调建议按账号分别配置：
 openclaw config set channels.wecom.network.egressProxyUrl "http://proxy.company.local:3128"
 ```
 
-### 1.5 验证
+### 1.4 验证
 
 ```bash
 openclaw config set gateway.bind lan
@@ -286,38 +281,32 @@ openclaw channels status
 }
 ```
 
-### 2.2 兼容模式文档（单账号）
-
-- [单账号兼容模式配置指南](./compat-single-account.md)
-
-### 2.3 路由第一性原则
+### 2.2 路由第一性原则
 
 - `accountId` 是会话隔离边界：不同账号不共享会话、不共享动态 Agent。
 - Bot 无法交付时，只回退到**同组** Agent，不跨账号兜底。
 - 只有在未显式指定 `accountId` 时，才使用 `defaultAccount`。
 
-### 2.4 Webhook 路径（优先使用账号路径）
+### 2.3 Webhook 路径（必须使用账号路径）
 
 | 模式 | 路径 | 说明 |
 |:---|:---|:---|
-| Bot（推荐，多账号） | `/wecom/bot/{accountId}` | 指定账号回调（例如 `/wecom/bot/default`） |
-| Agent（推荐，多账号） | `/wecom/agent/{accountId}` | 指定账号回调（例如 `/wecom/agent/default`） |
-| Bot（兼容，单账号 legacy） | `/wecom/bot` 或 `/wecom` | 历史路径，仅单账号模式建议保留 |
-| Agent（兼容，单账号 legacy） | `/wecom/agent` | 历史路径，单账号模式可用 |
+| Bot（推荐，多账号） | `/plugins/wecom/bot/{accountId}` | 指定账号回调（例如 `/plugins/wecom/bot/default`） |
+| Agent（推荐，多账号） | `/plugins/wecom/agent/{accountId}` | 指定账号回调（例如 `/plugins/wecom/agent/default`） |
 
-### 2.5 从单账号迁移到多账号（4 步）
+### 2.4 从单账号迁移到多账号（4 步）
 
 1. 把原来的 `channels.wecom.bot` / `channels.wecom.agent` 拆到 `channels.wecom.accounts.default.bot/agent`。
 2. 按业务继续新增 `channels.wecom.accounts.<accountId>`（例如 `ops`、`sales`）。
 3. 为每个账号增加 `bindings[].match.accountId`，映射到对应 OpenClaw agent。
-4. 企业微信后台把回调 URL 改成账号路径：`/wecom/bot/{accountId}`、`/wecom/agent/{accountId}`，然后执行 `openclaw channels status` 验证。
+4. 企业微信后台把回调 URL 改成账号路径：`/plugins/wecom/bot/{accountId}`、`/plugins/wecom/agent/{accountId}`，然后执行 `openclaw channels status` 验证。
 
-### 2.6 DM 策略
+### 2.5 DM 策略
 
 - **不配置 `dm.allowFrom`** → 所有人可用（默认）
 - **配置 `dm.allowFrom: ["user1", "user2"]`** → 白名单模式，仅列表内用户可私聊
 
-### 2.7 常用指令
+### 2.6 常用指令
 
 | 指令 | 说明 | 示例 |
 |:---|:---|:---|
@@ -335,7 +324,7 @@ openclaw channels status
 1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#/manageTools)
 2. 进入「安全与管理」→「管理工具」→「智能机器人」
 3. 创建机器人，选择 **API 模式**
-4. 填写回调 URL：`https://your-domain.com/wecom/bot/{accountId}`（例如默认账号：`https://your-domain.com/wecom/bot/default`）
+4. 填写回调 URL：`https://your-domain.com/plugins/wecom/bot/{accountId}`（例如默认账号：`https://your-domain.com/plugins/wecom/bot/default`）
 5. 记录 Token 和 EncodingAESKey
 
 ### 3.2 Agent 模式（自建应用）
@@ -346,7 +335,7 @@ openclaw channels status
 4. **重要：** 进入「企业可信IP」→「配置」→ 添加你服务器的 IP 地址
    - 如果你使用内网穿透/动态 IP，建议配置 `channels.wecom.network.egressProxyUrl` 走固定出口代理，否则可能出现：`60020 not allow to access from your ip`
 5. 在应用详情中设置「接收消息 - 设置API接收」
-6. 填写回调 URL：`https://your-domain.com/wecom/agent/{accountId}`（例如默认账号：`https://your-domain.com/wecom/agent/default`）
+6. 填写回调 URL：`https://your-domain.com/plugins/wecom/agent/{accountId}`（例如默认账号：`https://your-domain.com/plugins/wecom/agent/default`）
 7. 记录回调 Token 和 EncodingAESKey
 
 <div align="center">
@@ -511,6 +500,24 @@ Agent 输出 `{"template_card": ...}` 时自动渲染为交互卡片：
 <a id="sec-10"></a>
 ## 八、📝 更新日志
 
+### 2026.3.3（今日更新简报）
+
+- 【SDK适配】♻️ **插件 HTTP 注册升级**：入口改为 `registerHttpRoute`（`/plugins/wecom` + `match=prefix` + `auth=plugin`），适配 OpenClaw 新版插件接口。
+- 【兼容修复】🔁 **旧入口保持可达**：同步注册 `/wecom` 前缀路由，保障历史 Bot/Agent 回调地址继续可用。
+- 【兼容性修复】🧩 **OpenClaw 3.1 路由抢占问题修复**：推荐回调地址升级为 `/plugins/wecom/bot/{accountId}`、`/plugins/wecom/agent/{accountId}`，规避根路径 Control UI fallback 抢占 webhook。
+- 【引导收敛】🧭 **Onboarding 仅支持账号化配置**：配置向导统一写入 `channels.wecom.accounts.<accountId>`，不再引导单账号旧结构。
+- 【兼容策略】🔁 **旧路径兼容保留**：`/wecom/*` 历史回调路径保留兼容能力，但不再作为维护主路径。
+- 【分流稳定性】🧭 **路由识别增强**：monitor 按插件命名空间账号路径识别，确保 Bot/Agent 分支稳定命中。
+- 【链路一致性】🔒 **Bot 回复不再误走 Agent**：修复 Bot 上下文通道标识，避免 `routeReply` 误触发到 outbound 主动发送链路。
+- 【验证结果】✅ WeCom 插件测试通过：`10` files / `41` tests。
+
+### 2026.3.2（版本更新简报）
+
+- 【交付收口】🔄 修复 Bot 会话“正在搜索相关内容”不结束的问题，并在可用时推送最终流帧结束状态。  
+- 【媒体兜底】📎 统一非图片文件、媒体失败和超时场景为“Bot 提示 + Agent 私信兜底”闭环，确保结果可达。  
+- 【类型兼容】🧠 扩展 `txt/docx/xlsx/pptx/csv/zip` 等常见文件类型识别，并保留 `application/octet-stream` 自动重试。  
+- 【工具治理】🛡 修复 Bot 会话 `message` 工具禁用策略，避免绕过 Bot 交付链路导致会话错位。  
+
 ### 2026.2.28
 
 - 【重磅更新】🎯 **多账号/多智能体可用性增强**：支持按 `accountId` 做组内隔离（Bot + Agent + 路由绑定同组生效），动态 Agent 与会话键增加 `accountId` 维度，避免跨账号串会话。

package/changelog/v2.3.2.md

@@ -1,70 +1,28 @@
-# 🚀 OpenClaw 企业微信 (WeCom) 插件 v2.3.2 - Bot/Agent 交付收口与文件发送兼容性增强
-
-本次 v2.3.2 版本聚焦修复企业微信 Bot 模式在复杂交付场景下的稳定性问题，重点解决：
-- Bot 已收到文件但界面仍停留在“正在搜索相关内容”不结束。
-- 本地文件下发时，`txt`、`docx` 以及更多文件类型发送不稳定的问题。
-
----
-
-### 🌟 版本亮点 (Release Highlights)
-
-* ✅ **修复“正在搜索相关内容”不收口**：Agent 链路执行完成后，Bot 会主动推送最终流帧，确保企微思考态正确结束。
-* 🔒 **修复消息工具绕过链路问题**：在 WeCom Bot 会话中正确禁用顶层 `message` 工具，避免模型绕开 Bot 流式交付导致链路错位。
-* 📁 **本地路径下发能力增强**：支持识别 `/root`、`/home` 等 Linux 常见路径，减少文件请求误分流。
-* 📄 **文件类型兼容大幅提升**：补齐 `txt`、`docx`、`xlsx`、`pptx`、`csv`、`zip` 等常见类型 MIME，并增强入站媒体类型推断准确率。
-* 🛟 **未知类型自动兜底**：上传失败时自动回退到 `application/octet-stream` 重试，提高“能发出去”的成功率。
-
----
-
-### 📝 详细更新日志 (Changelog)
-
-#### 【交付稳定性】🔄 Bot/Agent 链路收口修复
-- 增加统一“最终流帧”主动推送逻辑，确保 `response_url` 可用时会主动收口。
-- 当回复内容为空时增加最终可见兜底文案，避免企微前端悬空态。
-- 非图片文件、媒体处理失败、超时切换等场景统一走“Bot 提示 + Agent 私信兜底”闭环。
-
-#### 【链路一致性】🧭 工具策略修复
-- 在 WeCom Bot 会话中将 `message` 工具写入 `tools.deny`（并同步 sandbox deny），修复错误禁用位置造成的链路绕过。
-- 避免“文件已发出但 Bot 思考流未结束”的链路错位。
-
-#### 【文件兼容性】📎 MIME 与上传兜底增强
-- 扩展本地文件 MIME 推断覆盖：`txt/csv/tsv/md/json/xml/yaml/yml/pdf/doc/docx/xls/xlsx/ppt/pptx/zip/rar/7z/tar/gz/tgz/rtf/odt`。
-- 上传 multipart 时增加文件名规范化，降低特殊文件名导致的兼容性问题。
-- 新增“首选 MIME 失败 -> octet-stream 自动重试”机制，提升未知/边缘类型上传成功率。
-
-#### 【类型识别优化】🧠 入站文件名与后缀判定更准确
-- 下载并解密媒体时保留源信息（`content-type`、`content-disposition`、最终 URL），用于后续精确判断。
-- 新增三层文件类型判定策略（按优先级）：
-  - 二进制内容特征（Magic Number / 文件头）
-  - 非泛型响应头 `content-type`
-  - 文件名后缀映射
-- 文件名确定策略（按优先级）：
-  - 回调体显式文件名字段
-  - 下载响应 `content-disposition` 文件名
-  - URL 路径 basename（仅在看起来是有效文件名时采用）
-  - 兜底默认名（自动补扩展名）
-- 对 OOXML（`docx/xlsx/pptx`）增加 ZIP 内容探测，降低仅靠 URL 无后缀时误判为 `zip/bin` 的概率。
-
-#### 【质量保障】✅ 回归测试补充
-- 新增上传链路单测，覆盖：
-  - `.txt` 使用 `text/plain`
-  - `.docx` 使用官方 MIME
-  - 首次 MIME 失败时自动回退重试
-- 同步通过 WeCom monitor/outbound 相关回归测试，确保无行为回退。
-
----
-
-### 💾 安装与升级 (Install & Update)
-
-使用 **OpenClaw** CLI 一键升级 **插件**：
-
-```bash
-openclaw plugins upgrade wecom
-```
-
-或手动更新版本至 `v2.3.2`。
-
----
-
-### 📮 联系我们
-如果您在 **企业微信 / 微信** 接入过程中遇到任何问题，欢迎提交 Issue 反馈日志与复现场景。
+# OpenClaw WeCom 插件 v2.3.2 变更简报
+
+> [!WARNING]
+> **OpenClaw 3.1+ 升级必读**：升级到 OpenClaw `3.1` 及以上版本的用户务必同步升级本插件，并将企业微信回调 URL 更新为 OpenClaw 推荐路径：`/plugins/wecom/bot/{accountId}` 与 `/plugins/wecom/agent/{accountId}`（旧 `/wecom/*` 仍兼容但不再维护）。
+
+## 2026-03-03（今日）
+- 【路由兼容】🧩 修复 OpenClaw 3.1 下 Control UI fallback 可能抢占 `/wecom/*` webhook 的路由冲突问题。  
+- 【引导收敛】🧭 将 WeCom onboarding 统一为账号化配置写入 `channels.wecom.accounts.<accountId>`，不再引导单账号旧结构。  
+- 【回调路径】🔁 将 WeCom 回调路径的推荐方案统一为 `/plugins/wecom/bot/{accountId}` 与 `/plugins/wecom/agent/{accountId}`。  
+- 【兼容策略】🔁 保留 `/wecom/*` 历史回调路径兼容能力，但不再维护旧路径分支。  
+- 【分流稳定】🧭 将 monitor 分流升级为按插件命名空间账号路径识别，确保 Bot/Agent 稳定命中。  
+- 【链路一致】🔒 将 Bot 上下文 `Surface` 对齐为 `wecom`，避免核心误判后错误走到 Agent outbound。  
+- 【账号必填】🧱 在 matrix 模式下对无 accountId 的基础路径返回 `wecom_matrix_path_required`，强制使用账号化回调路径。  
+- 【文档同步】📘 将回调地址文档与 onboarding 提示统一为 `/plugins/wecom/*/{accountId}` 唯一推荐路径。  
+
+## 2026-03-02（v2.3.2 主体）
+- 【交付收口】🔄 修复 Bot 结果回写后“正在搜索相关内容”不收口的问题，并在可用时推送最终流帧结束思考态。  
+- 【媒体兜底】📎 统一非图片文件、媒体失败和超时场景为“Bot 提示 + Agent 私信兜底”闭环，保证结果可达。  
+- 【工具治理】🛡 修复 WeCom Bot 会话中 `message` 工具禁用位置，避免模型绕过 Bot 交付链路直接主动发送。  
+- 【类型兼容】🧠 扩展本地与远端文件 MIME 识别覆盖 `txt/docx/xlsx/pptx/csv/zip` 等常见类型，并保留 `octet-stream` 重试兜底。  
+- 【判定增强】🔍 将入站文件类型推断升级为“文件头特征 + 响应头 + 文件名后缀”多层判定，提升无后缀和异常 URL 的识别准确率。  
+
+## 验证结果
+- WeCom 插件测试通过 `10` 个测试文件共 `41` 条用例，覆盖 webhook 生命周期、路径分流、媒体兜底与回归场景。  
+
+## 升级提示
+- 推荐在企业微信后台使用 `https://<your-domain>/plugins/wecom/bot/{accountId}` 与 `https://<your-domain>/plugins/wecom/agent/{accountId}` 作为回调地址。  
+- 旧地址 `/wecom/bot/{accountId}` 与 `/wecom/agent/{accountId}` 仍兼容但不再维护，建议尽快迁移到 `/plugins/wecom/*/{accountId}`。  

package/changelog/v2.3.4.md

@@ -0,0 +1,20 @@
+# OpenClaw WeCom 插件 v2.3.4 变更简报
+
+> [!WARNING]
+> **可用性热修复版本**：`v2.3.4` 重点修复 OpenClaw 3.1+ 下 WeCom webhook 路由兼容与可达性问题，保障历史配置可继续使用。
+
+## 2026-03-03（v2.3.4 热修复）
+- 【SDK适配】♻️ 插件入口从 `registerHttpHandler` 迁移为 `registerHttpRoute`（`/plugins/wecom` + `match=prefix` + `auth=plugin`），兼容 OpenClaw 新版插件 HTTP 注册模型。  
+- 【兼容修复】🔁 补回旧路径入口注册：新增 `/wecom` 前缀路由注册，确保历史 Bot/Agent webhook 继续可达。  
+- 【模式兼容】🧭 保持 legacy 单账号配置可运行，并明确 matrix 模式必须使用带 `accountId` 的回调路径。  
+
+## 影响说明
+- WeCom Bot/Agent 业务链路保持兼容；核心变化为插件 HTTP 注册 API 的升级适配与旧路径可达性恢复。  
+
+## 兼容矩阵（单账号/多账号）
+| 场景 | 配置形态 | 回调地址 | 兼容状态 | 说明 |
+|---|---|---|---|---|
+| 历史单账号（legacy） | `channels.wecom.bot/agent` | Bot: `/wecom`（默认）或 `/wecom/bot`；Agent: `/wecom/agent` | ✅ 兼容保留 | 适用于存量部署，不作为新引导方案。 |
+| 多账号（matrix）错误用法 | `channels.wecom.accounts.*` | `/wecom/bot`、`/wecom/agent`（无 accountId） | ❌ 不可用 | 会返回 `wecom_matrix_path_required`。 |
+| 多账号（matrix）兼容路径 | `channels.wecom.accounts.*` | `/wecom/bot/{accountId}`、`/wecom/agent/{accountId}` | ✅ 兼容保留 | 历史路径可用，但不再维护。 |
+| 多账号（matrix）推荐路径 | `channels.wecom.accounts.*` | `/plugins/wecom/bot/{accountId}`、`/plugins/wecom/agent/{accountId}` | ✅ 推荐 | 当前主维护路径。 |

package/compat-single-account.md

@@ -108,7 +108,7 @@ openclaw channels status
 
 ## A.4 Webhook 路径
 
-- Bot: `/wecom/bot`
+- Bot: `/wecom`（默认）或 `/wecom/bot`
 - Agent: `/wecom/agent`
 
 ## A.5 迁移建议

package/index.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it, vi } from "vitest";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import plugin from "./index.js";
+
+describe("wecom plugin register", () => {
+  it("registers both recommended and legacy webhook route prefixes", () => {
+    const registerChannel = vi.fn();
+    const registerHttpRoute = vi.fn();
+    const api = {
+      runtime: {},
+      registerChannel,
+      registerHttpRoute,
+    } as unknown as OpenClawPluginApi;
+
+    plugin.register(api);
+
+    expect(registerChannel).toHaveBeenCalledTimes(1);
+    expect(registerHttpRoute).toHaveBeenCalledTimes(2);
+    expect(registerHttpRoute).toHaveBeenCalledWith(
+      expect.objectContaining({
+        path: "/plugins/wecom",
+        auth: "plugin",
+        match: "prefix",
+      }),
+    );
+    expect(registerHttpRoute).toHaveBeenCalledWith(
+      expect.objectContaining({
+        path: "/wecom",
+        auth: "plugin",
+        match: "prefix",
+      }),
+    );
+  });
+});

package/index.ts

@@ -15,16 +15,24 @@ const plugin = {
   configSchema: emptyPluginConfigSchema(),
   /**
    * **register (注册插件)**
-   * 
+   *
    * OpenClaw 插件入口点。
    * 1. 注入 Runtime 环境 (api.runtime)。
    * 2. 注册 WeCom 渠道插件 (ChannelPlugin)。
-   * 3. 注册 Webhook HTTP 处理器 (handleWecomWebhookRequest)。
+   * 3. 注册 Webhook HTTP 路由（推荐 /plugins/wecom/*，兼容 /wecom*）。
    */
   register(api: OpenClawPluginApi) {
     setWecomRuntime(api.runtime);
     api.registerChannel({ plugin: wecomPlugin });
-    api.registerHttpHandler(handleWecomWebhookRequest);
+    const routes = ["/plugins/wecom", "/wecom"];
+    for (const path of routes) {
+      api.registerHttpRoute({
+        path,
+        handler: handleWecomWebhookRequest,
+        auth: "plugin",
+        match: "prefix",
+      });
+    }
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
   "repository": {

package/src/channel.lifecycle.test.ts

@@ -178,26 +178,44 @@ describe("wecomPlugin gateway lifecycle", () => {
     const startPromise = wecomPlugin.gateway!.startAccount!(ctx);
     await Promise.resolve();
 
-    const active = await sendWecomGetVerify({
+    const activeLegacyRoute = await sendWecomGetVerify({
       path: "/wecom/bot",
       token,
       encodingAESKey,
       receiveId,
     });
-    expect(active.handled).toBe(true);
-    expect(active.status).toBe(200);
-    expect(active.body).toBe("ping");
+    expect(activeLegacyRoute.handled).toBe(true);
+    expect(activeLegacyRoute.status).toBe(200);
+    expect(activeLegacyRoute.body).toBe("ping");
+
+    const activePluginRoute = await sendWecomGetVerify({
+      path: "/plugins/wecom/bot",
+      token,
+      encodingAESKey,
+      receiveId,
+    });
+    expect(activePluginRoute.handled).toBe(true);
+    expect(activePluginRoute.status).toBe(200);
+    expect(activePluginRoute.body).toBe("ping");
 
     abortController.abort();
     await startPromise;
 
-    const inactive = await sendWecomGetVerify({
+    const inactiveLegacyRoute = await sendWecomGetVerify({
       path: "/wecom/bot",
       token,
       encodingAESKey,
       receiveId,
     });
-    expect(inactive.handled).toBe(false);
+    expect(inactiveLegacyRoute.handled).toBe(false);
+
+    const inactivePluginRoute = await sendWecomGetVerify({
+      path: "/plugins/wecom/bot",
+      token,
+      encodingAESKey,
+      receiveId,
+    });
+    expect(inactivePluginRoute.handled).toBe(false);
   });
 
   it("rejects startup when matrix account credentials conflict", async () => {

package/src/channel.ts

@@ -19,6 +19,7 @@ import type { ResolvedWecomAccount } from "./types/index.js";
 import { monitorWecomProvider } from "./gateway-monitor.js";
 import { wecomOnboardingAdapter } from "./onboarding.js";
 import { wecomOutbound } from "./outbound.js";
+import { WEBHOOK_PATHS } from "./types/constants.js";
 
 const meta = {
   id: "wecom",
@@ -108,10 +109,10 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
         enabled: account.enabled,
         configured: account.configured && !conflict,
         webhookPath: account.bot?.config
-          ? (matrixMode ? `/wecom/bot/${account.accountId}` : "/wecom/bot")
+          ? (matrixMode ? `${WEBHOOK_PATHS.BOT_PLUGIN}/${account.accountId}` : WEBHOOK_PATHS.BOT_PLUGIN)
           : account.agent?.config
-            ? (matrixMode ? `/wecom/agent/${account.accountId}` : "/wecom/agent")
-            : "/wecom",
+            ? (matrixMode ? `${WEBHOOK_PATHS.AGENT_PLUGIN}/${account.accountId}` : WEBHOOK_PATHS.AGENT_PLUGIN)
+            : WEBHOOK_PATHS.BOT_PLUGIN,
       };
     },
     resolveAllowFrom: ({ cfg, accountId }) => {
@@ -176,10 +177,14 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
         enabled: account.enabled,
         configured: account.configured && !conflict,
         webhookPath: account.bot?.config
-          ? (account.accountId === DEFAULT_ACCOUNT_ID ? "/wecom/bot" : `/wecom/bot/${account.accountId}`)
+          ? (account.accountId === DEFAULT_ACCOUNT_ID
+              ? WEBHOOK_PATHS.BOT_PLUGIN
+              : `${WEBHOOK_PATHS.BOT_PLUGIN}/${account.accountId}`)
           : account.agent?.config
-            ? (account.accountId === DEFAULT_ACCOUNT_ID ? "/wecom/agent" : `/wecom/agent/${account.accountId}`)
-            : "/wecom",
+            ? (account.accountId === DEFAULT_ACCOUNT_ID
+                ? WEBHOOK_PATHS.AGENT_PLUGIN
+                : `${WEBHOOK_PATHS.AGENT_PLUGIN}/${account.accountId}`)
+            : WEBHOOK_PATHS.BOT_PLUGIN,
         running: runtime?.running ?? false,
         lastStartAt: runtime?.lastStartAt ?? null,
         lastStopAt: runtime?.lastStopAt ?? null,

package/src/gateway-monitor.ts

@@ -12,10 +12,11 @@ import {
 } from "./config/index.js";
 import { registerAgentWebhookTarget, registerWecomWebhookTarget } from "./monitor.js";
 import type { ResolvedWecomAccount, WecomConfig } from "./types/index.js";
+import { WEBHOOK_PATHS } from "./types/constants.js";
 
 type AccountRouteRegistryItem = {
   botPaths: string[];
-  agentPath?: string;
+  agentPaths: string[];
 };
 
 const accountRouteRegistry = new Map<string, AccountRouteRegistryItem>();
@@ -41,7 +42,7 @@ function logRegisteredRouteSummary(
       const routes = accountRouteRegistry.get(accountId);
       if (!routes) return undefined;
       const botText = routes.botPaths.length > 0 ? routes.botPaths.join(", ") : "未启用";
-      const agentText = routes.agentPath ?? "未启用";
+      const agentText = routes.agentPaths.length > 0 ? routes.agentPaths.join(", ") : "未启用";
       return `accountId=${accountId}（Bot: ${botText}；Agent: ${agentText}）`;
     })
     .filter((entry): entry is string => Boolean(entry));
@@ -74,6 +75,30 @@ function waitForAbortSignal(abortSignal: AbortSignal): Promise<void> {
   });
 }
 
+function uniquePaths(paths: string[]): string[] {
+  return Array.from(new Set(paths.map((path) => path.trim()).filter(Boolean)));
+}
+
+function resolveBotRegistrationPaths(params: { accountId: string; matrixMode: boolean }): string[] {
+  if (params.matrixMode) {
+    return uniquePaths([
+      `${WEBHOOK_PATHS.BOT_PLUGIN}/${params.accountId}`,
+      `${WEBHOOK_PATHS.BOT_ALT}/${params.accountId}`,
+    ]);
+  }
+  return uniquePaths([WEBHOOK_PATHS.BOT_PLUGIN, WEBHOOK_PATHS.BOT, WEBHOOK_PATHS.BOT_ALT]);
+}
+
+function resolveAgentRegistrationPaths(params: { accountId: string; matrixMode: boolean }): string[] {
+  if (params.matrixMode) {
+    return uniquePaths([
+      `${WEBHOOK_PATHS.AGENT_PLUGIN}/${params.accountId}`,
+      `${WEBHOOK_PATHS.AGENT}/${params.accountId}`,
+    ]);
+  }
+  return uniquePaths([WEBHOOK_PATHS.AGENT_PLUGIN, WEBHOOK_PATHS.AGENT]);
+}
+
 /**
  * Keeps WeCom webhook targets registered for the account lifecycle.
  * The promise only settles after gateway abort/reload signals shutdown.
@@ -129,12 +154,13 @@ export async function monitorWecomProvider(
 
   const unregisters: Array<() => void> = [];
   const botPaths: string[] = [];
-  let agentPath: string | undefined;
+  const agentPaths: string[] = [];
   try {
     if (bot && botConfigured) {
-      const paths = matrixMode
-        ? [`/wecom/bot/${account.accountId}`]
-        : ["/wecom", "/wecom/bot"];
+      const paths = resolveBotRegistrationPaths({
+        accountId: account.accountId,
+        matrixMode,
+      });
       for (const path of paths) {
         unregisters.push(
           registerWecomWebhookTarget({
@@ -154,20 +180,25 @@ export async function monitorWecomProvider(
     }
 
     if (agent && agentConfigured) {
-      const path = matrixMode ? `/wecom/agent/${account.accountId}` : "/wecom/agent";
-      unregisters.push(
-        registerAgentWebhookTarget({
-          agent,
-          config: cfg,
-          runtime: ctx.runtime,
-          path,
-        }),
-      );
-      agentPath = path;
-      ctx.log?.info(`[${account.accountId}] wecom agent webhook registered at ${path}`);
+      const paths = resolveAgentRegistrationPaths({
+        accountId: account.accountId,
+        matrixMode,
+      });
+      for (const path of paths) {
+        unregisters.push(
+          registerAgentWebhookTarget({
+            agent,
+            config: cfg,
+            runtime: ctx.runtime,
+            path,
+          }),
+        );
+      }
+      agentPaths.push(...paths);
+      ctx.log?.info(`[${account.accountId}] wecom agent webhook registered at ${paths.join(", ")}`);
     }
 
-    accountRouteRegistry.set(account.accountId, { botPaths, agentPath });
+    accountRouteRegistry.set(account.accountId, { botPaths, agentPaths });
     const shouldLogSummary =
       expectedRouteSummaryAccountIds.length <= 1 ||
       expectedRouteSummaryAccountIds.every((accountId) => accountRouteRegistry.has(accountId));
@@ -180,8 +211,8 @@ export async function monitorWecomProvider(
       running: true,
       configured: true,
       webhookPath: botConfigured
-        ? (matrixMode ? `/wecom/bot/${account.accountId}` : "/wecom/bot")
-        : (matrixMode ? `/wecom/agent/${account.accountId}` : "/wecom/agent"),
+        ? (botPaths[0] ?? WEBHOOK_PATHS.BOT_PLUGIN)
+        : (agentPaths[0] ?? WEBHOOK_PATHS.AGENT_PLUGIN),
       lastStartAt: Date.now(),
     });