@tencent-weixin/openclaw-weixin 1.0.3 → 2.0.1

package/README.md

@@ -4,10 +4,22 @@
 
 OpenClaw's WeChat channel plugin, supporting login authorization via QR code scanning.
 
+## Compatibility
+
+| Plugin Version | OpenClaw Version       | npm dist-tag | Status      |
+|---------------|------------------------|--------------|-------------|
+| 2.0.x         | >=2026.3.22            | `latest`     | Active      |
+| 1.0.x         | >=2026.1.0 <2026.3.22  | `legacy`     | Maintenance |
+
+> The plugin checks the host version at startup and will refuse to load if the
+> running OpenClaw version is outside the supported range.
+
 ## Prerequisites
 
 [OpenClaw](https://docs.openclaw.ai/install) must be installed (the `openclaw` CLI needs to be available).
 
+Check your version: `openclaw --version`
+
 ## Quick Install
 
 ```bash
@@ -269,3 +281,34 @@ All media types (image/voice/file/video) are transferred via CDN using AES-128-E
 6. Use the returned `encrypt_query_param` to construct a `CDNMedia` reference, include it in the `MessageItem`, and send
 
 > For complete type definitions, see [`src/api/types.ts`](src/api/types.ts). For API call implementations, see [`src/api/api.ts`](src/api/api.ts).
+
+## Uninstall
+
+```bash
+openclaw openclaw-weixin uninstall
+```
+
+## Troubleshooting
+
+### "requires OpenClaw >=2026.3.22" error
+
+Your OpenClaw version is too old for this plugin version. Check with:
+
+```bash
+openclaw --version
+```
+
+Install the legacy plugin line instead:
+
+```bash
+openclaw plugins install @tencent-weixin/openclaw-weixin@legacy
+```
+
+### Channel shows "OK" but doesn't connect
+
+Ensure `plugins.entries.openclaw-weixin.enabled` is `true` in `~/.openclaw/openclaw.json`:
+
+```bash
+openclaw config set plugins.entries.openclaw-weixin.enabled true
+openclaw gateway restart
+```

package/README.zh_CN.md

@@ -4,10 +4,21 @@
 
 OpenClaw 的微信渠道插件，支持通过扫码完成登录授权。
 
+## 兼容性
+
+| 插件版本 | OpenClaw 版本            | npm dist-tag | 状态   |
+|---------|--------------------------|--------------|--------|
+| 2.0.x   | >=2026.3.22              | `latest`     | 活跃   |
+| 1.0.x   | >=2026.1.0 <2026.3.22    | `legacy`     | 维护中 |
+
+> 插件在启动时会检查宿主版本，如果运行的 OpenClaw 版本超出支持范围，插件将拒绝加载。
+
 ## 前提条件
 
 已安装 [OpenClaw](https://docs.openclaw.ai/install)（需要 `openclaw` CLI 可用）。
 
+查看版本：`openclaw --version`
+
 ## 一键安装
 
 ```bash
@@ -269,3 +280,34 @@ openclaw config set agents.mode per-channel-per-peer
 6. 使用返回的 `encrypt_query_param` 构造 `CDNMedia` 引用，放入 `MessageItem` 发送
 
 > 完整的类型定义见 [`src/api/types.ts`](src/api/types.ts)，API 调用实现见 [`src/api/api.ts`](src/api/api.ts)。
+
+## 卸载
+
+```bash
+openclaw openclaw-weixin uninstall
+```
+
+## 故障排查
+
+### "requires OpenClaw >=2026.3.22" 报错
+
+你的 OpenClaw 版本太旧，不兼容当前插件版本。检查版本：
+
+```bash
+openclaw --version
+```
+
+安装旧版插件线：
+
+```bash
+openclaw plugins install @tencent-weixin/openclaw-weixin@legacy
+```
+
+### Channel 显示 "OK" 但未连接
+
+确保 `~/.openclaw/openclaw.json` 中 `plugins.entries.openclaw-weixin.enabled` 为 `true`：
+
+```bash
+openclaw config set plugins.entries.openclaw-weixin.enabled true
+openclaw gateway restart
+```

package/index.ts

@@ -1,27 +1,33 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { buildChannelConfigSchema } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
 
 import { weixinPlugin } from "./src/channel.js";
+import { assertHostCompatibility } from "./src/compat.js";
 import { WeixinConfigSchema } from "./src/config/config-schema.js";
 import { registerWeixinCli } from "./src/log-upload.js";
 import { setWeixinRuntime } from "./src/runtime.js";
 
-const plugin = {
+export default {
   id: "openclaw-weixin",
   name: "Weixin",
   description: "Weixin channel (getUpdates long-poll + sendMessage)",
   configSchema: buildChannelConfigSchema(WeixinConfigSchema),
   register(api: OpenClawPluginApi) {
-    if (!api?.runtime) {
-      throw new Error("[weixin] api.runtime is not available in register()");
+    // Fail-fast: reject incompatible host versions before any side-effects.
+    assertHostCompatibility(api.runtime?.version);
+
+    if (api.runtime) {
+      setWeixinRuntime(api.runtime);
     }
-    setWeixinRuntime(api.runtime);
 
     api.registerChannel({ plugin: weixinPlugin });
+
+    // registrationMode exists in 2026.3.22+; skip heavy registrations in setup-only mode.
+    const mode = (api as { registrationMode?: string }).registrationMode;
+    if (mode && mode !== "full") return;
+
     api.registerCli(({ program, config }) => registerWeixinCli({ program, config }), {
       commands: ["openclaw-weixin"],
     });
   },
 };
-
-export default plugin;

package/openclaw.plugin.json

@@ -1,5 +1,6 @@
 {
   "id": "openclaw-weixin",
+  "version": "2.0.0",
   "channels": ["openclaw-weixin"],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-weixin/openclaw-weixin",
-  "version": "1.0.3",
+  "version": "2.0.1",
   "description": "OpenClaw Weixin channel",
   "license": "MIT",
   "author": "Tencent",
@@ -29,8 +29,13 @@
     "qrcode-terminal": "0.12.0",
     "zod": "4.3.6"
   },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.22"
+  },
   "devDependencies": {
     "@vitest/coverage-v8": "^3.1.0",
+    "openclaw": "2026.3.23",
+    "silk-wasm": "^3.7.1",
     "typescript": "^5.8.0",
     "vitest": "^3.1.0"
   },
@@ -49,7 +54,8 @@
     },
     "install": {
       "npmSpec": "@tencent-weixin/openclaw-weixin",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.22"
     }
   }
 }

package/src/auth/accounts.ts

@@ -1,8 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import { normalizeAccountId } from "openclaw/plugin-sdk";
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
 
 import { getWeixinRuntime } from "../runtime.js";
 import { resolveStateDir } from "../storage/state-dir.js";
@@ -291,9 +291,32 @@ export function loadConfigRouteTag(accountId?: string): string | undefined {
 }
 
 /**
- * No-op stub — config reload is now handled externally via `openclaw gateway restart`.
+ * Ensure the openclaw-weixin channel section exists in openclaw.json so the gateway
+ * recognises it as a configured channel at startup, then trigger a config reload.
  */
-export async function triggerWeixinChannelReload(): Promise<void> {}
+export async function triggerWeixinChannelReload(): Promise<void> {
+  try {
+    const { loadConfig, writeConfigFile } = await import("openclaw/plugin-sdk/config-runtime");
+    const cfg = loadConfig();
+    const channels = (cfg.channels ?? {}) as Record<string, unknown>;
+    if (!channels["openclaw-weixin"] || Object.keys(channels["openclaw-weixin"] as Record<string, unknown>).every((k) => k === "enabled")) {
+      const updated: OpenClawConfig = {
+        ...cfg,
+        channels: {
+          ...channels,
+          "openclaw-weixin": {
+            ...(channels["openclaw-weixin"] as Record<string, unknown> ?? {}),
+            accounts: {},
+          },
+        },
+      };
+      await writeConfigFile(updated);
+      logger.info("triggerWeixinChannelReload: wrote channel config to openclaw.json");
+    }
+  } catch (err) {
+    logger.warn(`triggerWeixinChannelReload: failed to update config: ${String(err)}`);
+  }
+}
 
 // ---------------------------------------------------------------------------
 // Account resolution (merge config + stored credentials)

package/src/auth/pairing.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import { withFileLock } from "openclaw/plugin-sdk";
+import { withFileLock } from "openclaw/plugin-sdk/infra-runtime";
 
 import { resolveStateDir } from "../storage/state-dir.js";
 import { logger } from "../util/logger.js";

package/src/channel.ts

@@ -1,7 +1,8 @@
 import path from "node:path";
 
-import type { ChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk";
-import { normalizeAccountId, resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk";
+import type { ChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk/core";
+import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/infra-runtime";
 
 import {
   registerWeixinAccountId,

package/src/compat.ts

@@ -0,0 +1,79 @@
+/**
+ * Runtime host-version compatibility check for openclaw-weixin.
+ *
+ * OpenClaw uses a date-based version format: YYYY.M.DD (e.g. 2026.3.22).
+ * This module parses that format and validates the running host is within
+ * the supported range for this plugin version.
+ */
+
+import { logger } from "./util/logger.js";
+
+export const PLUGIN_VERSION = "2.0.0";
+
+export const SUPPORTED_HOST_MIN = "2026.3.22";
+
+export interface OpenClawVersion {
+  year: number;
+  month: number;
+  day: number;
+}
+
+/**
+ * Parse an OpenClaw date version string (e.g. "2026.3.22") into components.
+ * Returns null for unparseable strings.
+ */
+export function parseOpenClawVersion(version: string): OpenClawVersion | null {
+  // Strip any pre-release suffix (e.g. "2026.3.22-beta.1" -> "2026.3.22")
+  const base = version.trim().split("-")[0];
+  const parts = base.split(".");
+  if (parts.length !== 3) return null;
+  const [year, month, day] = parts.map(Number);
+  if (Number.isNaN(year) || Number.isNaN(month) || Number.isNaN(day)) return null;
+  return { year, month, day };
+}
+
+/**
+ * Compare two parsed versions.  Returns -1 | 0 | 1.
+ */
+export function compareVersions(a: OpenClawVersion, b: OpenClawVersion): -1 | 0 | 1 {
+  for (const key of ["year", "month", "day"] as const) {
+    if (a[key] < b[key]) return -1;
+    if (a[key] > b[key]) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Check whether a host version string is >= SUPPORTED_HOST_MIN.
+ */
+export function isHostVersionSupported(hostVersion: string): boolean {
+  const host = parseOpenClawVersion(hostVersion);
+  if (!host) return false;
+  const min = parseOpenClawVersion(SUPPORTED_HOST_MIN)!;
+  return compareVersions(host, min) >= 0;
+}
+
+/**
+ * Fail-fast guard.  Call at the very start of `register()` to prevent the
+ * plugin from loading on an incompatible host.
+ *
+ * @throws {Error} with a human-readable message when the host is out of range.
+ */
+export function assertHostCompatibility(hostVersion: string | undefined): void {
+  if (!hostVersion || hostVersion === "unknown") {
+    logger.warn(
+      `[compat] Could not determine host OpenClaw version; skipping compatibility check.`,
+    );
+    return;
+  }
+  if (isHostVersionSupported(hostVersion)) {
+    logger.info(`[compat] Host OpenClaw ${hostVersion} >= ${SUPPORTED_HOST_MIN}, OK.`);
+    return;
+  }
+  throw new Error(
+    `openclaw-weixin@${PLUGIN_VERSION} requires OpenClaw >=${SUPPORTED_HOST_MIN}, ` +
+    `but found ${hostVersion}. ` +
+    `Please upgrade OpenClaw, or install openclaw-weixin@1.x (legacy) for older hosts:\n` +
+    `  openclaw plugins install @tencent-weixin/openclaw-weixin@legacy`,
+  );
+}

package/src/log-upload.ts

@@ -1,8 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
-import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/infra-runtime";
 
 
 /** Minimal subset of commander's Command used by registerWeixinCli. */
@@ -51,12 +51,34 @@ function getConfiguredUploadUrl(config: OpenClawConfig): string | undefined {
   return section?.logUploadUrl;
 }
 
-/** Register the `openclaw openclaw-weixin logs-upload` CLI subcommand. */
+/** Register the `openclaw openclaw-weixin` CLI subcommands. */
 export function registerWeixinCli(params: { program: CliCommand; config: OpenClawConfig }): void {
   const { program, config } = params;
 
   const root = program.command("openclaw-weixin").description("Weixin channel utilities");
 
+  root
+    .command("uninstall")
+    .description("Uninstall the Weixin plugin (cleans up channel config automatically)")
+    .action(async () => {
+      // 1. Remove channels.openclaw-weixin from config
+      const { loadConfig, writeConfigFile } = await import("openclaw/plugin-sdk/config-runtime");
+      const cfg = loadConfig();
+      const channels = (cfg.channels ?? {}) as Record<string, unknown>;
+      if (channels["openclaw-weixin"]) {
+        delete channels["openclaw-weixin"];
+        await writeConfigFile({ ...cfg, channels });
+        console.log("[weixin] Cleaned up channel config.");
+      }
+      // 2. Run the actual uninstall
+      const { execSync } = await import("node:child_process");
+      try {
+        execSync("openclaw plugins uninstall openclaw-weixin", { stdio: "inherit" });
+      } catch {
+        // uninstall command handles its own error output
+      }
+    });
+
   root
     .command("logs-upload")
     .description("Upload a Weixin log file to a remote URL via HTTP POST")

package/src/messaging/process-message.ts

@@ -1,12 +1,12 @@
 import path from "node:path";
 
+import { createTypingCallbacks } from "openclaw/plugin-sdk/channel-runtime";
 import {
-  createTypingCallbacks,
   resolveSenderCommandAuthorizationWithRuntime,
   resolveDirectDmAuthorizationOutcome,
-  resolvePreferredOpenClawTmpDir,
-} from "openclaw/plugin-sdk";
-import type { PluginRuntime } from "openclaw/plugin-sdk";
+} from "openclaw/plugin-sdk/command-auth";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/infra-runtime";
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
 
 import { sendTyping } from "../api/api.js";
 import type { WeixinMessage } from "../api/types.js";

package/src/messaging/send.ts

@@ -1,5 +1,5 @@
-import type { ReplyPayload } from "openclaw/plugin-sdk";
-import { stripMarkdown } from "openclaw/plugin-sdk";
+import type { ReplyPayload } from "openclaw/plugin-sdk/reply-runtime";
+import { stripMarkdown } from "openclaw/plugin-sdk/text-runtime";
 
 import { sendMessage as sendMessageApi } from "../api/api.js";
 import type { WeixinApiOptions } from "../api/api.js";

package/src/monitor/monitor.ts

@@ -1,4 +1,5 @@
-import type { ChannelAccountSnapshot, PluginRuntime } from "openclaw/plugin-sdk";
+import type { ChannelAccountSnapshot } from "openclaw/plugin-sdk/channel-contract";
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
 
 import { getUpdates } from "../api/api.js";
 import { WeixinConfigManager } from "../api/config-cache.js";

package/src/runtime.ts

@@ -1,4 +1,4 @@
-import type { PluginRuntime } from "openclaw/plugin-sdk";
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
 
 import { logger } from "./util/logger.js";
 

package/src/util/logger.ts

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/infra-runtime";
 
 /**
  * Plugin logger — writes JSON lines to the main openclaw log file: