docs(plugins): clarify clawhub npm migration

docs/channels/line.md

@@ -20,13 +20,17 @@ are not supported.
 LINE ships as a bundled plugin in current OpenClaw releases, so normal
 packaged builds do not need a separate install.
 
-If you are on an older build or a custom install that excludes LINE, install it
-manually:
+If you are on an older build or a custom install that excludes LINE, install a
+current npm package when one is published:
 
 ```bash
 openclaw plugins install @openclaw/line
 ```
 
+If npm reports the OpenClaw-owned package as deprecated or missing, use a
+current packaged OpenClaw build or a local checkout until the npm package train
+catches up.
+
 Local checkout (when running from a git repo):
 
 ```bash

docs/channels/matrix-migration.md

@@ -211,6 +211,9 @@ If the old store reports room keys that were never backed up, OpenClaw warns ins
 
 - Meaning: OpenClaw found old encrypted Matrix state, but it could not load the helper entrypoint from the Matrix plugin that normally inspects that store.
 - What to do: reinstall or repair the Matrix plugin (`openclaw plugins install @openclaw/matrix`, or `openclaw plugins install ./path/to/local/matrix-plugin` for a repo checkout), then rerun `openclaw doctor --fix` or restart the gateway.
+- If npm reports the OpenClaw-owned Matrix package as deprecated, use the bundled
+  plugin from a current packaged OpenClaw build or the local checkout path until
+  a newer npm package is published.
 
 `Matrix plugin helper path is unsafe: ... Reinstall @openclaw/matrix and try again.`
 
@@ -233,6 +236,9 @@ If the old store reports room keys that were never backed up, OpenClaw warns ins
 
 - Meaning: Matrix is pinned to a path install, so mainline updates do not automatically replace it with the repo's standard Matrix package.
 - What to do: reinstall with `openclaw plugins install @openclaw/matrix` when you want to return to the default Matrix plugin.
+- If npm reports the OpenClaw-owned Matrix package as deprecated, use the bundled
+  plugin from a current packaged OpenClaw build until a newer npm package is
+  published.
 
 ### Encrypted-state recovery messages
 
@@ -336,6 +342,9 @@ new backup key can load correctly after restart.
 
 - Meaning: your plugin install record points at a local path that is gone.
 - What to do: reinstall with `openclaw plugins install @openclaw/matrix`, or if you are running from a repo checkout, `openclaw plugins install ./path/to/local/matrix-plugin`.
+- If npm reports the OpenClaw-owned Matrix package as deprecated, use the bundled
+  plugin from a current packaged OpenClaw build or the local checkout path until
+  a newer npm package is published.
 
 ## If encrypted history still does not come back
 

docs/channels/matrix.md

@@ -13,11 +13,19 @@ It uses the official `matrix-js-sdk` and supports DMs, rooms, threads, media, re
 
 Current packaged OpenClaw releases ship the Matrix plugin in the box. You do not need to install anything; configuring `channels.matrix.*` (see [Setup](#setup)) is what activates it.
 
-For older builds or custom installs that exclude Matrix, install manually first:
+For older builds or custom installs that exclude Matrix, install a current npm
+package when one is published:
 
 ```bash
 openclaw plugins install @openclaw/matrix
-# or, from a local checkout
+```
+
+If npm reports the OpenClaw-owned package as deprecated, use a current packaged
+OpenClaw build or a local checkout until a newer npm package is published.
+
+From a local checkout:
+
+```bash
 openclaw plugins install ./path/to/local/matrix-plugin
 ```
 

docs/channels/mattermost.md

@@ -15,7 +15,7 @@ Status: bundled plugin (bot token + WebSocket events). Channels, groups, and DMs
 Mattermost ships as a bundled plugin in current OpenClaw releases, so normal packaged builds do not need a separate install.
 </Note>
 
-If you are on an older build or a custom install that excludes Mattermost, install it manually:
+If you are on an older build or a custom install that excludes Mattermost, install a current npm package when one is published:
 
 <Tabs>
   <Tab title="npm registry">
@@ -30,6 +30,10 @@ If you are on an older build or a custom install that excludes Mattermost, insta
   </Tab>
 </Tabs>
 
+If npm reports the OpenClaw-owned package as deprecated, use a current packaged
+OpenClaw build or the local checkout path until a newer npm package is
+published.
+
 Details: [Plugins](/tools/plugin)
 
 ## Quick setup

docs/channels/msteams.md

@@ -13,12 +13,16 @@ Microsoft Teams ships as a bundled plugin in current OpenClaw releases, so no
 separate install is required in the normal packaged build.
 
 If you are on an older build or a custom install that excludes bundled Teams,
-install it manually:
+install a current npm package when one is published:
 
 ```bash
 openclaw plugins install @openclaw/msteams
 ```
 
+If npm reports the OpenClaw-owned package as deprecated, use a current packaged
+OpenClaw build or the local checkout path until a newer npm package is
+published.
+
 Local checkout (when running from a git repo):
 
 ```bash

docs/channels/nextcloud-talk.md

@@ -13,14 +13,18 @@ Nextcloud Talk ships as a bundled plugin in current OpenClaw releases, so
 normal packaged builds do not need a separate install.
 
 If you are on an older build or a custom install that excludes Nextcloud Talk,
-install it manually:
+install a current npm package when one is published:
 
-Install via CLI (npm registry):
+Install via CLI (npm registry, when a current package exists):
 
 ```bash
 openclaw plugins install @openclaw/nextcloud-talk
 ```
 
+If npm reports the OpenClaw-owned package as deprecated, use a current packaged
+OpenClaw build or the local checkout path until a newer npm package is
+published.
+
 Local checkout (when running from a git repo):
 
 ```bash

docs/channels/nostr.md

@@ -19,12 +19,16 @@ builds do not need a separate install.
 
 - Onboarding (`openclaw onboard`) and `openclaw channels add` still surface
   Nostr from the shared channel catalog.
-- If your build excludes bundled Nostr, install it manually.
+- If your build excludes bundled Nostr, install a current npm package when one
+  is published.
 
 ```bash
 openclaw plugins install @openclaw/nostr
 ```
 
+If npm reports the OpenClaw-owned package as deprecated, use a current packaged
+OpenClaw build or a local checkout until a newer npm package is published.
+
 Use a local checkout (dev workflows):
 
 ```bash

docs/channels/tlon.md

@@ -17,15 +17,19 @@ image uploads are supported. Reactions and polls are not yet supported.
 Tlon ships as a bundled plugin in current OpenClaw releases, so normal packaged
 builds do not need a separate install.
 
-If you are on an older build or a custom install that excludes Tlon, install it
-manually:
+If you are on an older build or a custom install that excludes Tlon, install a
+current npm package when one is published:
 
-Install via CLI (npm registry):
+Install via CLI (npm registry, when a current package exists):
 
 ```bash
 openclaw plugins install @openclaw/tlon
 ```
 
+If npm reports the OpenClaw-owned package as deprecated, use a current packaged
+OpenClaw build or the local checkout path until a newer npm package is
+published.
+
 Local checkout (when running from a git repo):
 
 ```bash

docs/channels/twitch.md

@@ -14,7 +14,7 @@ Twitch chat support via IRC connection. OpenClaw connects as a Twitch user (bot
 Twitch ships as a bundled plugin in current OpenClaw releases, so normal packaged builds do not need a separate install.
 </Note>
 
-If you are on an older build or a custom install that excludes Twitch, install it manually:
+If you are on an older build or a custom install that excludes Twitch, install a current npm package when one is published:
 
 <Tabs>
   <Tab title="npm registry">
@@ -29,6 +29,10 @@ If you are on an older build or a custom install that excludes Twitch, install i
   </Tab>
 </Tabs>
 
+If npm reports the OpenClaw-owned package as deprecated, use a current packaged
+OpenClaw build or the local checkout path until a newer npm package is
+published.
+
 Details: [Plugins](/tools/plugin)
 
 ## Quick setup (beginner)

docs/channels/whatsapp.md

@@ -14,7 +14,8 @@ Status: production-ready via WhatsApp Web (Baileys). Gateway owns linked session
 - `openclaw channels login --channel whatsapp` also offers the install flow when
   the plugin is not present yet.
 - Dev channel + git checkout: defaults to the local plugin path.
-- Stable/Beta: defaults to the npm package `@openclaw/whatsapp`.
+- Stable/Beta: uses the npm package `@openclaw/whatsapp` when a current package
+  is published.
 
 Manual install stays available:
 
@@ -22,6 +23,10 @@ Manual install stays available:
 openclaw plugins install @openclaw/whatsapp
 ```
 
+If npm reports the OpenClaw-owned package as deprecated or missing, use a
+current packaged OpenClaw build or a local checkout until the npm package train
+catches up.
+
 <CardGroup cols={3}>
   <Card title="Pairing" icon="link" href="/channels/pairing">
     Default DM policy is pairing for unknown senders.

docs/channels/zalo.md

@@ -12,13 +12,17 @@ Status: experimental. DMs are supported. The [Capabilities](#capabilities) secti
 Zalo ships as a bundled plugin in current OpenClaw releases, so normal packaged
 builds do not need a separate install.
 
-If you are on an older build or a custom install that excludes Zalo, install it
-manually:
+If you are on an older build or a custom install that excludes Zalo, install a
+current npm package when one is published:
 
 - Install via CLI: `openclaw plugins install @openclaw/zalo`
 - Or from a source checkout: `openclaw plugins install ./path/to/local/zalo-plugin`
 - Details: [Plugins](/tools/plugin)
 
+If npm reports the OpenClaw-owned package as deprecated, use a current packaged
+OpenClaw build or the local checkout path until a newer npm package is
+published.
+
 ## Quick setup (beginner)
 
 1. Ensure the Zalo plugin is available.

docs/channels/zalouser.md

@@ -18,12 +18,16 @@ Zalo Personal ships as a bundled plugin in current OpenClaw releases, so normal
 packaged builds do not need a separate install.
 
 If you are on an older build or a custom install that excludes Zalo Personal,
-install it manually:
+install a current npm package when one is published:
 
 - Install via CLI: `openclaw plugins install @openclaw/zalouser`
 - Or from a source checkout: `openclaw plugins install ./path/to/local/zalouser-plugin`
 - Details: [Plugins](/tools/plugin)
 
+If npm reports the OpenClaw-owned package as deprecated, use a current packaged
+OpenClaw build or the local checkout path until a newer npm package is
+published.
+
 No external `zca`/`openzca` CLI binary is required.
 
 ## Quick setup (beginner)

docs/cli/plugins.md

@@ -79,6 +79,16 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
 Bare package names are checked against ClawHub first, then npm. Treat plugin installs like running code. Prefer pinned versions.
 </Warning>
 
+<Note>
+ClawHub is the primary distribution and discovery surface for most plugins. Npm
+remains a supported fallback and direct-install path. During the migration to
+ClawHub, OpenClaw still ships some OpenClaw-owned `@openclaw/*` plugin packages
+on npm; those package versions can lag the bundled source between plugin release
+trains. If npm reports an OpenClaw-owned plugin package as deprecated, that
+published version is an old external artifact; use the plugin bundled with
+current OpenClaw or a local checkout until a newer npm package is published.
+</Note>
+
 <AccordionGroup>
   <Accordion title="Config includes and invalid-config recovery">
     If your `plugins` section is backed by a single-file `$include`, `plugins install/update/enable/disable/uninstall` write through to that included file and leave `openclaw.json` untouched. Root includes, include arrays, and includes with sibling overrides fail closed instead of flattening. See [Config includes](/gateway/configuration) for the supported shapes.

docs/gateway/config-channels.md

@@ -491,7 +491,11 @@ WhatsApp runs through the gateway's web channel (Baileys Web). It starts automat
 
 ### Mattermost
 
-Mattermost ships as a plugin: `openclaw plugins install @openclaw/mattermost`.
+Mattermost ships as a bundled plugin in current OpenClaw releases. Older or
+custom builds can install a current npm package with
+`openclaw plugins install @openclaw/mattermost`; if npm reports the
+OpenClaw-owned package as deprecated, use the bundled plugin or a local checkout
+until a newer npm package is published.
 
 ```json5
 {

docs/plugins/building-plugins.md

@@ -14,9 +14,9 @@ generation, video generation, web fetch, web search, agent tools, or any
 combination.
 
 You do not need to add your plugin to the OpenClaw repository. Publish to
-[ClawHub](/tools/clawhub) or npm and users install with
+[ClawHub](/tools/clawhub) and users install with
 `openclaw plugins install <package-name>`. OpenClaw tries ClawHub first and
-falls back to npm automatically.
+falls back to npm automatically for packages that still use npm distribution.
 
 ## Prerequisites
 
@@ -136,7 +136,8 @@ and provider plugins have dedicated guides linked above.
     ```
 
     OpenClaw also checks ClawHub before npm for bare package specs like
-    `@myorg/openclaw-my-plugin`.
+    `@myorg/openclaw-my-plugin`; npm remains a fallback for packages that have
+    not migrated to ClawHub yet.
 
     **In-repo plugins:** place under the bundled plugin workspace tree — automatically discovered.
 

docs/plugins/community.md

@@ -8,8 +8,9 @@ title: "Community plugins"
 
 Community plugins are third-party packages that extend OpenClaw with new
 channels, tools, providers, or other capabilities. They are built and maintained
-by the community, published on [ClawHub](/tools/clawhub) or npm, and
-installable with a single command.
+by the community, usually published on [ClawHub](/tools/clawhub), and installable
+with a single command. Npm remains a supported fallback for packages that have
+not moved to ClawHub yet.
 
 ClawHub is the canonical discovery surface for community plugins. Do not open
 docs-only PRs just to add your plugin here for discoverability; publish it on
@@ -151,7 +152,8 @@ We welcome community plugins that are useful, documented, and safe to operate.
 <Steps>
   <Step title="Publish to ClawHub or npm">
     Your plugin must be installable via `openclaw plugins install \<package-name\>`.
-    Publish to [ClawHub](/tools/clawhub) (preferred) or npm.
+    Publish to [ClawHub](/tools/clawhub) unless you specifically need npm-only
+    distribution.
     See [Building Plugins](/plugins/building-plugins) for the full guide.
 
   </Step>

docs/plugins/sdk-setup.md

@@ -477,7 +477,7 @@ The `ChannelSetupWizard` type supports `credentials`, `textInputs`, `dmPolicy`,
 
 ## Publishing and installing
 
-**External plugins:** publish to [ClawHub](/tools/clawhub) or npm, then install:
+**External plugins:** publish to [ClawHub](/tools/clawhub), then install:
 
 <Tabs>
   <Tab title="Auto (ClawHub then npm)">
@@ -494,10 +494,11 @@ The `ChannelSetupWizard` type supports `credentials`, `textInputs`, `dmPolicy`,
     ```
   </Tab>
   <Tab title="npm package spec">
-    There is no matching `npm:` override. Use the normal npm package spec when you want the npm path after ClawHub fallback:
+    Use npm when a package has not moved to ClawHub yet, or when you need a
+    direct npm install path during migration:
 
     ```bash
-    openclaw plugins install @myorg/openclaw-my-plugin
+    openclaw plugins install npm:@myorg/openclaw-my-plugin
     ```
 
   </Tab>

docs/plugins/voice-call.md

@@ -27,7 +27,7 @@ the Gateway, then restart the Gateway to load it.
 <Steps>
   <Step title="Install the plugin">
     <Tabs>
-      <Tab title="From npm (recommended)">
+      <Tab title="From npm">
         ```bash
         openclaw plugins install @openclaw/voice-call
         ```
@@ -41,6 +41,10 @@ the Gateway, then restart the Gateway to load it.
       </Tab>
     </Tabs>
 
+    If npm reports the OpenClaw-owned package as deprecated, that package version
+    is from an older external package train; use a current packaged OpenClaw
+    build or the local folder path until a newer npm package is published.
+
     Restart the Gateway afterwards so the plugin loads.
 
   </Step>

docs/plugins/zalouser.md

@@ -34,6 +34,10 @@ No external `zca`/`openzca` CLI binary is required.
 openclaw plugins install @openclaw/zalouser
 ```
 
+If npm reports the OpenClaw-owned package as deprecated, that package version is
+from an older external package train; use a current packaged OpenClaw build or
+the local folder path until a newer npm package is published.
+
 Restart the Gateway afterwards.
 
 ### Option B: install from a local folder (dev)

docs/tools/plugin.md

@@ -12,7 +12,9 @@ Plugins extend OpenClaw with new capabilities: channels, model providers,
 agent harnesses, tools, skills, speech, realtime transcription, realtime
 voice, media-understanding, image generation, video generation, web fetch, web
 search, and more. Some plugins are **core** (shipped with OpenClaw), others
-are **external** (published on npm by the community).
+are **external**. Most external plugins are published and discovered through
+[ClawHub](/tools/clawhub). Npm remains supported for direct installs and for a
+temporary set of OpenClaw-owned plugin packages while that migration finishes.
 
 ## Quick start
 
@@ -26,7 +28,7 @@ are **external** (published on npm by the community).
   <Step title="Install a plugin">
     ```bash
     # From npm
-    openclaw plugins install @openclaw/voice-call
+    openclaw plugins install npm:@acme/openclaw-plugin
 
     # From a local directory or archive
     openclaw plugins install ./my-plugin
@@ -48,9 +50,9 @@ are **external** (published on npm by the community).
 If you prefer chat-native control, enable `commands.plugins: true` and use:
 
 ```text
-/plugin install clawhub:@openclaw/voice-call
-/plugin show voice-call
-/plugin enable voice-call
+/plugin install clawhub:<package>
+/plugin show <plugin-id>
+/plugin enable <plugin-id>
 ```
 
 The install path uses the same resolver as the CLI: local path/archive, explicit
@@ -130,16 +132,33 @@ plugin discovery rather than silently falling back to source paths.
 
 ## Official plugins
 
-### Installable (npm)
+### OpenClaw-owned npm packages during migration
 
-| Plugin          | Package                | Docs                                 |
-| --------------- | ---------------------- | ------------------------------------ |
-| Matrix          | `@openclaw/matrix`     | [Matrix](/channels/matrix)           |
-| Microsoft Teams | `@openclaw/msteams`    | [Microsoft Teams](/channels/msteams) |
-| Nostr           | `@openclaw/nostr`      | [Nostr](/channels/nostr)             |
-| Voice Call      | `@openclaw/voice-call` | [Voice Call](/plugins/voice-call)    |
-| Zalo            | `@openclaw/zalo`       | [Zalo](/channels/zalo)               |
-| Zalo Personal   | `@openclaw/zalouser`   | [Zalo Personal](/plugins/zalouser)   |
+ClawHub is the primary distribution path for most plugins. Current packaged
+OpenClaw releases already bundle many official plugins, so those do not need
+separate npm installs in normal setups. Until every OpenClaw-owned plugin has
+migrated to ClawHub, OpenClaw still ships some `@openclaw/*` plugin packages on
+npm for older/custom installs and direct npm workflows.
+
+If npm reports an `@openclaw/*` plugin package as deprecated, that package
+version is from an older external package train. Use the bundled plugin from
+current OpenClaw or a local checkout until a newer npm package is published.
+
+| Plugin          | Package                    | Docs                                       |
+| --------------- | -------------------------- | ------------------------------------------ |
+| BlueBubbles     | `@openclaw/bluebubbles`    | [BlueBubbles](/channels/bluebubbles)       |
+| Discord         | `@openclaw/discord`        | [Discord](/channels/discord)               |
+| Feishu          | `@openclaw/feishu`         | [Feishu](/channels/feishu)                 |
+| Matrix          | `@openclaw/matrix`         | [Matrix](/channels/matrix)                 |
+| Mattermost      | `@openclaw/mattermost`     | [Mattermost](/channels/mattermost)         |
+| Microsoft Teams | `@openclaw/msteams`        | [Microsoft Teams](/channels/msteams)       |
+| Nextcloud Talk  | `@openclaw/nextcloud-talk` | [Nextcloud Talk](/channels/nextcloud-talk) |
+| Nostr           | `@openclaw/nostr`          | [Nostr](/channels/nostr)                   |
+| Synology Chat   | `@openclaw/synology-chat`  | [Synology Chat](/channels/synology-chat)   |
+| Tlon            | `@openclaw/tlon`           | [Tlon](/channels/tlon)                     |
+| WhatsApp        | `@openclaw/whatsapp`       | [WhatsApp](/channels/whatsapp)             |
+| Zalo            | `@openclaw/zalo`           | [Zalo](/channels/zalo)                     |
+| Zalo Personal   | `@openclaw/zalouser`       | [Zalo Personal](/plugins/zalouser)         |
 
 ### Core (shipped with OpenClaw)