diff --git a/docs/channels/line.md b/docs/channels/line.md index 3cf39d0a8a1..40a59594b34 100644 --- a/docs/channels/line.md +++ b/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 diff --git a/docs/channels/matrix-migration.md b/docs/channels/matrix-migration.md index 0ca607c1f16..f56325a07ed 100644 --- a/docs/channels/matrix-migration.md +++ b/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 diff --git a/docs/channels/matrix.md b/docs/channels/matrix.md index 59c5f9dfd06..361eaa6b5f8 100644 --- a/docs/channels/matrix.md +++ b/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 ``` diff --git a/docs/channels/mattermost.md b/docs/channels/mattermost.md index 8a0713ce543..06728114745 100644 --- a/docs/channels/mattermost.md +++ b/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. -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: @@ -30,6 +30,10 @@ If you are on an older build or a custom install that excludes Mattermost, insta +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 diff --git a/docs/channels/msteams.md b/docs/channels/msteams.md index 04e02f336e2..20a5795826b 100644 --- a/docs/channels/msteams.md +++ b/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 diff --git a/docs/channels/nextcloud-talk.md b/docs/channels/nextcloud-talk.md index 44332172d6f..48ad730e19d 100644 --- a/docs/channels/nextcloud-talk.md +++ b/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 diff --git a/docs/channels/nostr.md b/docs/channels/nostr.md index bdbc9ad5f7b..617671aba23 100644 --- a/docs/channels/nostr.md +++ b/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 diff --git a/docs/channels/tlon.md b/docs/channels/tlon.md index 5ef39bcd2e2..8f702e52d44 100644 --- a/docs/channels/tlon.md +++ b/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 diff --git a/docs/channels/twitch.md b/docs/channels/twitch.md index 8864b05736e..9976a701692 100644 --- 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. -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: @@ -29,6 +29,10 @@ If you are on an older build or a custom install that excludes Twitch, install i +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) diff --git a/docs/channels/whatsapp.md b/docs/channels/whatsapp.md index 59022be259f..ee055ccf20b 100644 --- a/docs/channels/whatsapp.md +++ b/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. + Default DM policy is pairing for unknown senders. diff --git a/docs/channels/zalo.md b/docs/channels/zalo.md index 16a25f66c2e..b38564f3282 100644 --- a/docs/channels/zalo.md +++ b/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. diff --git a/docs/channels/zalouser.md b/docs/channels/zalouser.md index 84236ff8675..f40eab2b7bb 100644 --- a/docs/channels/zalouser.md +++ b/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) diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md index af563b951e1..a02c5844b0b 100644 --- a/docs/cli/plugins.md +++ b/docs/cli/plugins.md @@ -79,6 +79,16 @@ openclaw plugins install --marketplace https://github.com// + +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. + + 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. diff --git a/docs/gateway/config-channels.md b/docs/gateway/config-channels.md index 65790911f3f..dd574bf9fd8 100644 --- a/docs/gateway/config-channels.md +++ b/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 { diff --git a/docs/plugins/building-plugins.md b/docs/plugins/building-plugins.md index 70695eda068..b2af11bdb8c 100644 --- a/docs/plugins/building-plugins.md +++ b/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 `. 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. diff --git a/docs/plugins/community.md b/docs/plugins/community.md index 33bf3189df1..e63b117ea3b 100644 --- a/docs/plugins/community.md +++ b/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. Your plugin must be installable via `openclaw plugins install \`. - 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. diff --git a/docs/plugins/sdk-setup.md b/docs/plugins/sdk-setup.md index 53faf62a087..d7e8dde9e5f 100644 --- a/docs/plugins/sdk-setup.md +++ b/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: @@ -494,10 +494,11 @@ The `ChannelSetupWizard` type supports `credentials`, `textInputs`, `dmPolicy`, ``` - 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 ``` diff --git a/docs/plugins/voice-call.md b/docs/plugins/voice-call.md index 39a39f99657..874f8ab8580 100644 --- a/docs/plugins/voice-call.md +++ b/docs/plugins/voice-call.md @@ -27,7 +27,7 @@ the Gateway, then restart the Gateway to load it. - + ```bash openclaw plugins install @openclaw/voice-call ``` @@ -41,6 +41,10 @@ the Gateway, then restart the Gateway to load it. + 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. diff --git a/docs/plugins/zalouser.md b/docs/plugins/zalouser.md index 9701db9ff88..dbab514b505 100644 --- a/docs/plugins/zalouser.md +++ b/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) diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index c3b8860e47d..edece4b8363 100644 --- a/docs/tools/plugin.md +++ b/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). ```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: +/plugin show +/plugin enable ``` 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)