# OpenClaw WeCom 插件 v2.3.27 变更简报

> [!TIP]
> `v2.3.27` 是一个以“升级兼容”和“接入恢复”为主的修复版本。重点解决三类真实会挡住使用的问题：第一，`channel add` 里 `wecom` 又能正常被识别和添加了；第二，修复了部分用户在配置或选择渠道时遇到的 `ReferenceError: installedCatalogById is not defined`；第三，把这轮 OpenClaw 升级后 `wecom` 插件里几处已经失效的 SDK 旧入口统一迁到了当前可用的公共接口，避免出现“有的地方能跑、有的地方一升级就炸”的割裂状态。

## 2026-03-27（v2.3.27）
- 【恢复 `channel add` 接入】**[重要修复]** 之前在 OpenClaw 的渠道添加流程里，`wecom` 虽然已经安装，但仍可能被显示成 “does not support guided setup yet”，导致用户无法直接从 `channel add` 走完接入。现在插件已经切到 OpenClaw 当前识别的 `setupWizard` 接口，`wecom` 会重新出现在正常的 guided setup 流程中。
- 【修复 `installedCatalogById is not defined`】**[重要修复]** 某些用户在渠道选择或安装判断阶段会直接撞到 `ReferenceError: installedCatalogById is not defined`，表现上像是“选了渠道就报错”或“添加流程突然失效”。这次已经把对应的渠道目录访问逻辑改稳，不再依赖容易失效的解构引用。
- 【迁移失效的插件 SDK 入口】OpenClaw 升级后，`wecom` 插件里原来直接从 `openclaw/plugin-sdk` 根入口拿的一些类型和能力，已经不再按旧方式导出。`v2.3.27` 已经把这几处高风险点迁到当前公开可用的子路径，重点覆盖了工具上下文、outbound 适配器和媒体发送相关接口。
- 【修复 `wecom_mcp` 工具返回协议】随着 OpenClaw 新版工具结果协议收紧，`wecom_mcp` 这类插件工具如果还按旧格式返回，就会在注册或执行阶段出现类型或运行时不匹配。现在该工具返回结果已经补齐新版要求的 `details` 字段，和当前工具调用协议保持一致。
- 【修复 Bot WS 媒体发送对旧导出的依赖】之前 Bot WebSocket 媒体发送链路依赖了一个在当前发布版 OpenClaw 中已经不可直接使用的媒体加载导出，升级后容易出现“代码看起来没问题，但媒体链路单独报错”的情况。现在媒体读取改为基于当前仍然公开可用的远程抓取、本地路径校验和 MIME 识别能力自行组装，兼容当前版本的 OpenClaw 发布面。
- 【补齐严格类型下的 WS 回复头处理】随着依赖和 SDK 类型变严格，Bot WS 主动回复和命令回复链路里对 `req_id` 头部的处理更容易暴露问题。这一版顺手把回复头的兜底生成与返回值收窄一起补齐，减少升级后只在某些路径上报类型错误或运行时异常的概率。

## 升级后你会直接感受到

- 在 OpenClaw 里重新执行 `channel add` 时，`wecom` 不会再被误判成“不支持 guided setup”。
- 遇到 `ReferenceError: installedCatalogById is not defined` 的用户，渠道添加和选择流程会恢复正常。
- OpenClaw 升级后，`wecom` 插件不再那么依赖旧版 SDK 的根入口导出，单独安装或混合运行时更稳。
- Bot WS 的媒体发送链路不再因为旧导出失效而单独掉链子。

## 这次版本背后的最小理解模型

把这次更新理解成三句话就够了：

1. OpenClaw 的渠道接入面已经变了，`wecom` 不能再继续挂在旧的 onboarding 接口上。
2. 插件如果直接依赖 `openclaw/plugin-sdk` 根入口里那些历史上“顺手可用”的符号，升级后迟早会踩到导出面收缩的问题。
3. 真正稳定的兼容修复，不只是把一个 import 改过去，而是把接入流程、工具返回协议、outbound 类型和媒体链路一起对齐到当前公开接口。

## 升级提示

- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.27`。
- 如果你刚升级 OpenClaw 后发现 `wecom` 在 `channel add` 里突然不能配置，或者用户侧开始报 `installedCatalogById is not defined`，这一版就是对应修复。
- 如果你是“全局安装的 OpenClaw + 本地 `wecom` 源码插件”混合运行，升级后建议完整重启一次 gateway，确保新的 setup 和 outbound 逻辑都已生效。
