docs: update plugin npm distribution guidance

steipete · steipete · commit fd83c49cffc0 · 2026-05-02T22:00:37.000+01:00
diff --git a/docs/channels/matrix-migration.md b/docs/channels/matrix-migration.md
@@ -211,9 +211,6 @@ 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.`
 
@@ -236,9 +233,6 @@ 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
 
@@ -342,9 +336,6 @@ 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
 
diff --git a/docs/channels/msteams.md b/docs/channels/msteams.md
@@ -13,15 +13,14 @@ 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 a current npm package when one is published:
+install the npm package directly:
 
 ```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.
+Use `@openclaw/msteams@beta` when following the OpenClaw beta channel and npmjs
+shows `beta` ahead of `latest`.
 
 Local checkout (when running from a git repo):
 
diff --git a/docs/channels/nextcloud-talk.md b/docs/channels/nextcloud-talk.md
@@ -13,17 +13,16 @@ 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 a current npm package when one is published:
+install the npm package directly:
 
-Install via CLI (npm registry, when a current package exists):
+Install via CLI (npm registry):
 
 ```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.
+Use `@openclaw/nextcloud-talk@beta` when following the OpenClaw beta channel and
+npmjs shows `beta` ahead of `latest`.
 
 Local checkout (when running from a git repo):
 
diff --git a/docs/channels/nostr.md b/docs/channels/nostr.md
@@ -19,15 +19,14 @@ 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 a current npm package when one
-  is published.
+- If your build excludes bundled Nostr, install the npm package directly.
 
 ```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 `@openclaw/nostr@beta` when following the OpenClaw beta channel and npmjs
+shows `beta` ahead of `latest`.
 
 Use a local checkout (dev workflows):
 
diff --git a/docs/channels/tlon.md b/docs/channels/tlon.md
@@ -18,17 +18,16 @@ 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 a
-current npm package when one is published:
+current npm package:
 
-Install via CLI (npm registry, when a current package exists):
+Install via CLI (npm registry):
 
 ```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.
+Use `@openclaw/tlon@beta` when following the OpenClaw beta channel and npmjs
+shows `beta` ahead of `latest`.
 
 Local checkout (when running from a git repo):
 
diff --git a/docs/channels/twitch.md b/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 a current npm package when one is published:
+If you are on an older build or a custom install that excludes Twitch, install the npm package directly:
 
 <Tabs>
   <Tab title="npm registry">
@@ -29,9 +29,8 @@ If you are on an older build or a custom install that excludes Twitch, install a
   </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.
+Use `@openclaw/twitch@beta` when following the OpenClaw beta channel and npmjs
+shows `beta` ahead of `latest`.
 
 Details: [Plugins](/tools/plugin)
 
diff --git a/docs/channels/whatsapp.md b/docs/channels/whatsapp.md
@@ -14,18 +14,17 @@ 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: uses the npm package `@openclaw/whatsapp` when a current package
-  is published.
+- Stable/Beta: uses the npm package `@openclaw/whatsapp`; beta-channel updates
+  prefer `@openclaw/whatsapp@beta` when that tag is available.
 
 Manual install stays available:
 
 ```bash
 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.
+Use `@openclaw/whatsapp@beta` when following the OpenClaw beta channel and npmjs
+shows `beta` ahead of `latest`.
 
 <CardGroup cols={3}>
   <Card title="Pairing" icon="link" href="/channels/pairing">
diff --git a/docs/channels/zalo.md b/docs/channels/zalo.md
@@ -12,17 +12,14 @@ 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 a
-current npm package when one is published:
+If you are on an older build or a custom install that excludes Zalo, install the
+npm package directly:
 
 - Install via CLI: `openclaw plugins install @openclaw/zalo`
+- Beta channel: `openclaw plugins install @openclaw/zalo@beta`
 - 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.
diff --git a/docs/channels/zalouser.md b/docs/channels/zalouser.md
@@ -18,16 +18,13 @@ 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 a current npm package when one is published:
+install the npm package directly:
 
 - Install via CLI: `openclaw plugins install @openclaw/zalouser`
+- Beta channel: `openclaw plugins install @openclaw/zalouser@beta`
 - 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)
diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md
@@ -95,12 +95,12 @@ not skills. Use `openclaw skills search` for ClawHub skills.
 
 <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.
+remains a supported fallback and direct-install path. OpenClaw-owned
+`@openclaw/*` plugin packages are published on npm again; see the current list
+on [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) or the
+[plugin inventory](/plugins/plugin-inventory). Stable installs use `latest`.
+Beta-channel installs and updates prefer the npm `beta` dist-tag when that tag
+is available, then fall back to `latest`.
 </Note>
 
 <AccordionGroup>
diff --git a/docs/gateway/config-channels.md b/docs/gateway/config-channels.md
@@ -500,9 +500,9 @@ WhatsApp runs through the gateway's web channel (Baileys Web). It starts automat
 
 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.
+`openclaw plugins install @openclaw/mattermost`. Check
+[npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost)
+for the current dist-tags before pinning a version.
 
 ```json5
 {
diff --git a/docs/plugins/voice-call.md b/docs/plugins/voice-call.md
@@ -41,9 +41,8 @@ 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.
+    Use `@openclaw/voice-call@beta` when following the OpenClaw beta channel and
+    npmjs shows `beta` ahead of `latest`.
 
     Restart the Gateway afterwards so the plugin loads.
 
diff --git a/docs/plugins/zalouser.md b/docs/plugins/zalouser.md
@@ -34,9 +34,8 @@ 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.
+Use `@openclaw/zalouser@beta` when following the OpenClaw beta channel and npmjs
+shows `beta` ahead of `latest`.
 
 Restart the Gateway afterwards.
 
