thisnick · thisnick · Aug 31, 2026 · Aug 31, 2026 · Aug 31, 2026 · Aug 31, 2026
diff --git a/.changeset/config.json b/.changeset/config.json
@@ -2,7 +2,7 @@
   "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
   "changelog": ["@changesets/changelog-github", { "repo": "thisnick/agent-wechat" }],
   "commit": false,
-  "fixed": [["@agent-wechat/cli", "@agent-wechat/wechat", "@agent-wechat/wechaty-puppet", "@agent-wechat/wechaty-gateway", "@agent-wechat/agent-server"]],
+  "fixed": [["@agent-wechat/cli", "@agent-wechat/agent-wechat", "@agent-wechat/wechaty-puppet", "@agent-wechat/wechaty-gateway", "@agent-wechat/agent-server"]],
   "linked": [],
   "access": "public",
   "baseBranch": "main",

diff --git a/.changeset/openclaw-2026.5-compat.md b/.changeset/openclaw-2026.5-compat.md
@@ -1,5 +1,5 @@
 ---
-"@agent-wechat/wechat": minor
+"@agent-wechat/agent-wechat": minor
 ---
 
 Update for openclaw 2026.5+ compatibility:

diff --git a/.changeset/rename-channel-id-agent-wechat.md b/.changeset/rename-channel-id-agent-wechat.md
@@ -0,0 +1,17 @@
+---
+"@agent-wechat/agent-wechat": minor
+---
+
+Rename the OpenClaw plugin/channel id from `wechat` to `agent-wechat` and restore compatibility with OpenClaw 2026.8.x.
+
+OpenClaw's bundled official plugin catalog now reserves `wechat` (and `weixin`) as aliases of Tencent's `@tencent-weixin/openclaw-weixin` plugin, and the catalog is compiled into the openclaw JS bundle — so the id `wechat` gets hijacked: `plugins install` writes `plugins.entries.openclaw-weixin`, and `channels add --channel wechat` tries to install the Tencent plugin instead of this one. Patching `dist/channel-catalog.json` no longer helps.
+
+Changes:
+
+- Plugin id and channel id are now `agent-wechat`; config lives under `channels.agent-wechat`.
+- Dropped the `weixin` alias (catalog-reserved).
+- Imports moved from the removed bare `openclaw/plugin-sdk` export to `openclaw/plugin-sdk/core` (works on hosts >=2026.5.12, required on 2026.8.x).
+- `channelConfigs` metadata added to `package.json#openclaw` so 2026.8.x setup surfaces get the config schema.
+- `wechat:`-prefixed targets and allowlist entries are still accepted.
+
+Migration: rename the `channels.wechat` key to `channels.agent-wechat` and `plugins.entries.wechat` (or a stray `plugins.entries.openclaw-weixin`) to `plugins.entries.agent-wechat` in `openclaw.json`, then restart the gateway. Session/routing keys change with the channel id, so active conversation sessions reset.
diff --git a/AGENT.md b/AGENT.md
@@ -258,7 +258,7 @@ Always add a changeset when making user-facing changes (features, fixes, behavio
 
 ```markdown
 ---
-"@agent-wechat/wechat": patch
+"@agent-wechat/agent-wechat": patch
 ---
 
 Short description of the change.

diff --git a/README.md b/README.md
@@ -9,8 +9,8 @@ A programmable WeChat interface. Controls a WeChat client running in a Docker co
 | Package | npm | Description |
 |---------|-----|-------------|
 | [`@agent-wechat/cli`](./packages/cli) | [![npm](https://img.shields.io/npm/v/@agent-wechat/cli)](https://www.npmjs.com/package/@agent-wechat/cli) | CLI for managing the Docker container and interacting with WeChat |
-| [`@agent-wechat/wechaty-puppet`](./packages/wechaty-puppet) | [![npm](https://img.shields.io/npm/v/@agent-wechat/wechaty-puppet)](https://www.npmjs.com/package/@agent-wechat/wechaty-puppet) | [Wechaty](https://wechaty.js.org) puppet for agent-wechat |
-| [`@agent-wechat/wechat`](./packages/openclaw-extension) | [![npm](https://img.shields.io/npm/v/@agent-wechat/wechat)](https://www.npmjs.com/package/@agent-wechat/wechat) | [OpenClaw](https://openclaw.ai) extension for AI agent integration |
+| [`@agent-wechat/agent-wechaty-puppet`](./packages/wechaty-puppet) | [![npm](https://img.shields.io/npm/v/@agent-wechat/agent-wechaty-puppet)](https://www.npmjs.com/package/@agent-wechat/agent-wechaty-puppet) | [Wechaty](https://wechaty.js.org) puppet for agent-wechat |
+| [`@agent-wechat/agent-wechat`](./packages/openclaw-extension) | [![npm](https://img.shields.io/npm/v/@agent-wechat/agent-wechat)](https://www.npmjs.com/package/@agent-wechat/agent-wechat) | [OpenClaw](https://openclaw.ai) extension for AI agent integration |
 
 ## What It Does
 

diff --git a/dev-notes/release.md b/dev-notes/release.md
@@ -1,9 +1,12 @@
 # Release Process
 
+> **Package renamed (2026-08-31):** the OpenClaw extension moved from `@agent-wechat/wechat` to `@agent-wechat/agent-wechat` so the unscoped package basename matches the plugin id `agent-wechat` (OpenClaw validates plugin ids against the npm basename and hard-fails updates on mismatch; the official catalog also reserves the `wechat` id). The first version (0.11.15) was published manually with a one-off granular token — OIDC trusted publishing only covers packages that already exist — and the token was revoked afterward. The trusted publisher for the new package is configured at https://www.npmjs.com/package/@agent-wechat/agent-wechat/access (GitHub Actions: thisnick/agent-wechat, workflow release.yml), so CI publishes via OIDC as before. Once rollout is done, deprecate the old `@agent-wechat/wechat`: `npm deprecate @agent-wechat/wechat "Renamed to @agent-wechat/agent-wechat (plugin id agent-wechat); openclaw >=2026.8 reserves the wechat id for the official Tencent plugin."`
+
+
 This repo releases three artifacts together:
 
 1. npm CLI package: `@agent-wechat/cli`
-2. npm OpenClaw extension: `@agent-wechat/wechat`
+2. npm OpenClaw extension: `@agent-wechat/agent-wechat`
 3. Docker image: `ghcr.io/thisnick/agent-wechat`
 
 ## Prepare A Release
@@ -24,7 +27,7 @@ pnpm changeset
 
 On merge of the Version Packages PR:
 
-- Publishes `@agent-wechat/cli` and `@agent-wechat/wechat` to npm with provenance.
+- Publishes `@agent-wechat/cli` and `@agent-wechat/agent-wechat` to npm with provenance.
 - Builds and pushes `amd64` and `arm64` Docker images.
 - Publishes a multi-arch manifest tag.
 
@@ -43,7 +46,7 @@ npm trusted publishing lets GitHub Actions publish without a long-lived token. S
    - **Repository**: `agent-wechat`
    - **Workflow**: `release.yml`
    - **Environment**: (leave blank)
-3. Repeat for https://www.npmjs.com/package/@agent-wechat/wechat/access
+3. Repeat for https://www.npmjs.com/package/@agent-wechat/agent-wechat/access
 
 Once configured, delete the `NPM_TOKEN` secret from GitHub repo settings. The workflow uses OIDC automatically (requires npm >= 11.5.1, installed in CI).
 

diff --git a/docs/src/content/docs/getting-started/overview.mdx b/docs/src/content/docs/getting-started/overview.mdx
@@ -34,5 +34,5 @@ There are several ways to interact with agent-wechat:
 | Package | Description |
 |---------|-------------|
 | [`@agent-wechat/cli`](https://www.npmjs.com/package/@agent-wechat/cli) | CLI for managing the container and interacting with WeChat |
-| [`@agent-wechat/wechat`](https://www.npmjs.com/package/@agent-wechat/wechat) | OpenClaw plugin for AI agent integration |
-| [`@agent-wechat/wechaty-puppet`](https://www.npmjs.com/package/@agent-wechat/wechaty-puppet) | Wechaty puppet implementation |
+| [`@agent-wechat/agent-wechat`](https://www.npmjs.com/package/@agent-wechat/agent-wechat) | OpenClaw plugin for AI agent integration |
+| [`@agent-wechat/agent-wechaty-puppet`](https://www.npmjs.com/package/@agent-wechat/agent-wechaty-puppet) | Wechaty puppet implementation |
diff --git a/docs/src/content/docs/integrations/openclaw/local-setup.mdx b/docs/src/content/docs/integrations/openclaw/local-setup.mdx
@@ -17,7 +17,7 @@ wx up
 ### 2. Install and configure the plugin
 
 ```bash
-openclaw plugins install @agent-wechat/wechat
+openclaw plugins install @agent-wechat/agent-wechat
 openclaw channels add --channel wechat
 ```
 

diff --git a/docs/src/content/docs/integrations/openclaw/setup.mdx b/docs/src/content/docs/integrations/openclaw/setup.mdx
@@ -3,7 +3,7 @@ title: OpenClaw Setup
 description: Add WeChat as a channel in your OpenClaw AI agent.
 ---
 
-The `@agent-wechat/wechat` plugin connects [OpenClaw](https://openclaw.ai) to WeChat via agent-wechat.
+The `@agent-wechat/agent-wechat` plugin connects [OpenClaw](https://openclaw.ai) to WeChat via agent-wechat.
 
 ## Prerequisites
 
@@ -27,7 +27,7 @@ wx up
 ### 2. Install the plugin
 
 ```bash
-openclaw plugins install @agent-wechat/wechat
+openclaw plugins install @agent-wechat/agent-wechat
 ```
 
 ### 3. Add the WeChat channel
@@ -50,7 +50,7 @@ If you don't want to run Docker or manage infrastructure, use [Managed Hosting](
 ### 1. Install the plugin
 
 ```bash
-openclaw plugins install @agent-wechat/wechat
+openclaw plugins install @agent-wechat/agent-wechat
 ```
 
 ### 2. Add the WeChat channel

diff --git a/packages/openclaw-extension/README.md b/packages/openclaw-extension/README.md
@@ -1,4 +1,4 @@
-# @agent-wechat/wechat
+# @agent-wechat/agent-wechat
 
 OpenClaw channel plugin for WeChat. Connects your OpenClaw bot to WeChat using [agent-wechat](https://github.com/thisnick/agent-wechat).
 
@@ -65,25 +65,25 @@ If running alongside OpenClaw on the same Docker network, set `serverUrl` to `ht
 ### 2. Install the extension
 
 ```bash
-openclaw plugins install @agent-wechat/wechat
+openclaw plugins install @agent-wechat/agent-wechat
 ```
 
 ### 3. Configure the channel
 
 ```bash
 # Uses defaults (localhost:6174, token from ~/.config/agent-wechat/token)
-openclaw channels add --channel wechat
+openclaw channels add --channel agent-wechat
 
 # Override server URL and token
-openclaw channels add --channel wechat --url <url> --token <token>
+openclaw channels add --channel agent-wechat --url <url> --token <token>
 ```
 
 Or edit `~/.openclaw/openclaw.json` directly:
 
 ```json
 {
   "channels": {
-    "wechat": {
+    "agent-wechat": {
       "enabled": true,
       "serverUrl": "http://localhost:6174",
       "dmPolicy": "open",
@@ -93,6 +93,8 @@ Or edit `~/.openclaw/openclaw.json` directly:
 }
 ```
 
+> **Upgrading from ≤0.11.x?** The channel id changed from `wechat` to `agent-wechat` (OpenClaw's official plugin registry now reserves `wechat`/`weixin` as aliases of Tencent's `openclaw-weixin` plugin, which hijacked this channel's id). Rename the `channels.wechat` key to `channels.agent-wechat` and any `plugins.entries.wechat` key to `plugins.entries.agent-wechat` in `openclaw.json`, then restart the gateway. Allowlist entries and group settings carry over unchanged.
+
 For local setups, the token is automatically read from `~/.config/agent-wechat/token` (shared with the CLI and container), so you don't need to set it in the config. When connecting to a remote server, add the `token` field.
 
 ### 4. Restart the gateway
@@ -112,7 +114,7 @@ Ask your bot to log in to WeChat:
 Your bot should generate a QR code image. Alternatively, use the CLI:
 
 ```bash
-openclaw channels login --channel wechat
+openclaw channels login --channel agent-wechat
 ```
 
 ### 6. Scan the QR code
@@ -137,7 +139,7 @@ Once connected, configure how the bot handles direct messages and group chats. Y
 
 ## Configuration Reference
 
-All config lives under `channels.wechat` in OpenClaw's config file:
+All config lives under `channels.agent-wechat` in OpenClaw's config file:
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|

diff --git a/packages/openclaw-extension/index.ts b/packages/openclaw-extension/index.ts
@@ -1,5 +1,5 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/core";
 import { wechatPlugin } from "./src/channel.js";
 import { setWeChatRuntime } from "./src/runtime.js";
 
@@ -10,7 +10,7 @@ const plugin: {
   configSchema: ReturnType<typeof emptyPluginConfigSchema>;
   register: (api: OpenClawPluginApi) => void;
 } = {
-  id: "wechat",
+  id: "agent-wechat",
   name: "WeChat",
   description: "WeChat channel via agent-wechat container",
   configSchema: emptyPluginConfigSchema(),

diff --git a/packages/openclaw-extension/openclaw.plugin.json b/packages/openclaw-extension/openclaw.plugin.json
@@ -1,49 +1,97 @@
 {
-  "id": "wechat",
-  "channels": ["wechat"],
+  "id": "agent-wechat",
+  "legacyPluginIds": [
+    "wechat"
+  ],
+  "channels": [
+    "agent-wechat"
+  ],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
     "properties": {}
   },
   "channelConfigs": {
-    "wechat": {
+    "agent-wechat": {
       "label": "WeChat",
       "description": "WeChat messaging via agent-wechat container.",
       "schema": {
         "type": "object",
         "additionalProperties": false,
         "properties": {
-          "enabled": { "type": "boolean" },
-          "serverUrl": { "type": "string" },
-          "token": { "type": "string" },
+          "enabled": {
+            "type": "boolean"
+          },
+          "serverUrl": {
+            "type": "string"
+          },
+          "token": {
+            "type": "string"
+          },
           "dmPolicy": {
             "type": "string",
-            "enum": ["open", "allowlist", "disabled"]
+            "enum": [
+              "open",
+              "allowlist",
+              "disabled"
+            ]
+          },
+          "allowFrom": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
           },
-          "allowFrom": { "type": "array", "items": { "type": "string" } },
           "groupPolicy": {
             "type": "string",
-            "enum": ["open", "allowlist", "disabled"]
+            "enum": [
+              "open",
+              "allowlist",
+              "disabled"
+            ]
+          },
+          "groupAllowFrom": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
           },
-          "groupAllowFrom": { "type": "array", "items": { "type": "string" } },
           "groups": {
             "type": "object",
             "additionalProperties": {
               "type": "object",
               "properties": {
-                "enabled": { "type": "boolean" },
-                "requireMention": { "type": "boolean" },
+                "enabled": {
+                  "type": "boolean"
+                },
+                "requireMention": {
+                  "type": "boolean"
+                },
                 "groupPolicy": {
                   "type": "string",
-                  "enum": ["open", "allowlist", "disabled"]
+                  "enum": [
+                    "open",
+                    "allowlist",
+                    "disabled"
+                  ]
                 },
-                "allowFrom": { "type": "array", "items": { "type": "string" } }
+                "allowFrom": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
               }
             }
           },
-          "pollIntervalMs": { "type": "integer", "minimum": 100 },
-          "authPollIntervalMs": { "type": "integer", "minimum": 1000 }
+          "pollIntervalMs": {
+            "type": "integer",
+            "minimum": 100
+          },
+          "authPollIntervalMs": {
+            "type": "integer",
+            "minimum": 1000
+          }
         }
       }
     }