微信插件 1.0.3 → 2.0.1 源码 Diff 深度分析

> 包名: @tencent-weixin/openclaw-weixin

> 版本对比: 1.0.3 → 2.0.1

> 变更文件: 15 个（含 1 个新增）

> 分析方法: npm pack 下载两个版本 tgz，解压后逐文件 diff -u

> 前置报告: 1.0.2 → 1.0.3 变更分析

一句话总结

2.0.1 不是功能大更新，而是架构适配升级——适配 OpenClaw 2026.3.22 的新 Plugin SDK 子模块拆分，加上版本兼容性检查、自动写入频道配置和卸载命令。主版本号从 1 跳到 2 的原因是 Breaking Change：强制要求 OpenClaw >= 2026.3.22。

版本兼容性矩阵

变更文件清单

改动一：强制最低 OpenClaw 版本（Breaking Change）

这是主版本号跳到 2.0 的原因。新增 src/compat.ts，在插件 register() 时第一件事就检查宿主版本：

// src/compat.ts
export const SUPPORTED_HOST_MIN = "2026.3.22";

export function assertHostCompatibility(hostVersion: string | undefined): void {
  if (!hostVersion || hostVersion === "unknown") {
    // 无法确认版本，跳过检查（容错）
    logger.warn("[compat] Could not determine host version; skipping check.");
    return;
  }
  if (isHostVersionSupported(hostVersion)) {
    logger.info(`[compat] Host OpenClaw ${hostVersion} >= ${SUPPORTED_HOST_MIN}, OK.`);
    return;
  }
  // 版本不兼容，直接 throw，插件拒绝加载
  throw new Error(
    `openclaw-weixin@${PLUGIN_VERSION} requires OpenClaw >=${SUPPORTED_HOST_MIN}, ` +
    `but found ${hostVersion}. Please upgrade OpenClaw, or install legacy:\n` +
    `  openclaw plugins install @tencent-weixin/openclaw-weixin@legacy`
  );
}

版本解析支持 OpenClaw 的日期格式（YYYY.M.DD），可处理 pre-release 后缀（如 2026.3.22-beta.1）。

影响：OpenClaw 低于 2026.3.22 安装 2.0.1 会启动失败，需要用 @legacy 标签安装 1.x。

package.json 也同步声明了：

{
  "peerDependencies": {
    "openclaw": ">=2026.3.22"
  },
  "openclaw": {
    "install": {
      "minHostVersion": ">=2026.3.22"
    }
  }
}

改动二：Plugin SDK 导入路径重构

OpenClaw 2026.3.22 将 Plugin SDK 从单入口拆成了细粒度子模块。2.0.1 全面适配：

影响：这是 1.x 和 2.x 不能共存的根本原因——旧版 OpenClaw 没有这些子路径导出，import 会直接报错。

改动三：频道配置自动写入

1.0.3 的 triggerWeixinChannelReload() 是空函数（no-op），扫码后需要手动往 openclaw.json 里添加频道配置：

// 1.0.3 — 什么都不干
export async function triggerWeixinChannelReload(): Promise<void> {}

2.0.1 实现了真正的自动配置：

// 2.0.1 — 扫码后自动写入 openclaw.json
export async function triggerWeixinChannelReload(): Promise<void> {
  const { loadConfig, writeConfigFile } = await import("openclaw/plugin-sdk/config-runtime");
  const cfg = loadConfig();
  const channels = cfg.channels ?? {};

  // 确保 channels.openclaw-weixin 存在且包含 accounts 字段
  if (!channels["openclaw-weixin"] || /* 只有 enabled 字段 */) {
    const updated = {
      ...cfg,
      channels: {
        ...channels,
        "openclaw-weixin": {
          ...(channels["openclaw-weixin"] ?? {}),
          accounts: {},
        },
      },
    };
    await writeConfigFile(updated);
  }
}

意义：扫码即用，不需要手动编辑 JSON 配置文件。这依赖新 SDK 的 config-runtime 模块（1.x 没有这个能力）。

改动四：插件注册流程重构

index.ts 的 register() 函数变化较大：

1. 兼容性检查前置

// 2.0.1 — register() 第一行
assertHostCompatibility(api.runtime?.version);

2. runtime 不再强制

// 1.0.3 — 没有 runtime 直接 throw
if (!api?.runtime) {
  throw new Error("[weixin] api.runtime is not available");
}
setWeixinRuntime(api.runtime);

// 2.0.1 — 没有 runtime 也能跑（容错）
if (api.runtime) {
  setWeixinRuntime(api.runtime);
}

3. registrationMode 感知

// 2.0.1 — setup-only 模式跳过 CLI 注册，减少启动开销
const mode = (api as { registrationMode?: string }).registrationMode;
if (mode && mode !== "full") return;

OpenClaw 新 SDK 支持"setup-only"模式：只注册频道不注册 CLI 子命令。用于配置验证场景，不需要完整加载。

改动五：卸载命令

新增 openclaw openclaw-weixin uninstall：

root
  .command("uninstall")
  .description("Uninstall the Weixin plugin (cleans up channel config automatically)")
  .action(async () => {
    // 1. 从 openclaw.json 中删除 channels.openclaw-weixin
    const { loadConfig, writeConfigFile } = await import("openclaw/plugin-sdk/config-runtime");
    const cfg = loadConfig();
    delete channels["openclaw-weixin"];
    await writeConfigFile({ ...cfg, channels });

    // 2. 调用 openclaw plugins uninstall
    execSync("openclaw plugins uninstall openclaw-weixin", { stdio: "inherit" });
  });

之前：卸载需要手动删 config + 手动 uninstall，容易残留配置。

现在：一条命令清理干净。

改动六：其他

devDependencies 新增 silk-wasm

"silk-wasm": "^3.7.1"

SILK 是腾讯的语音编解码格式（微信语音消息用的）。出现在 devDependencies 说明正在准备语音消息支持，但 2.0.1 还没有相关运行时代码。

openclaw.plugin.json 新增 version

{
  "id": "openclaw-weixin",
  "version": "2.0.0"  // 新增
}

README 改进

• 新增兼容性表格（版本对应关系）
• 新增故障排查章节（"requires >=2026.3.22" 报错怎么办、Channel 不连接怎么办）
• 新增卸载说明

升级决策树

你的 OpenClaw 版本是多少？
  │
  ├── >= 2026.3.22 → 装 2.0.1（直接 npm install @tencent-weixin/openclaw-weixin@latest）
  │
  ├── < 2026.3.22 → 先 openclaw update，再装 2.0.1
  │
  └── 不想升级 OpenClaw → 装 1.0.3（npm install @tencent-weixin/openclaw-weixin@legacy）

升级命令：

# 查看当前 OpenClaw 版本
openclaw --version

# 如果需要先升级 OpenClaw
openclaw update

# 安装 2.0.1
cd ~/.openclaw/extensions/openclaw-weixin
npm install @tencent-weixin/openclaw-weixin@latest
openclaw gateway restart

1.0.x → 2.0.x 完整变更对比

评分

报告基于 npm pack 下载的 1.0.3 与 2.0.1 tgz 包逐文件 diff 生成 | 2026-03-24

来源: npm @tencent-weixin/openclaw-weixin