From 40fa750b4fdce43b021f7f3ecd70cf4947e6dcf5 Mon Sep 17 00:00:00 2001 From: fuller-stack-dev <263060202+fuller-stack-dev@users.noreply.github.com> Date: Mon, 25 May 2026 23:13:19 -0600 Subject: [PATCH] docs: explain bundled plugin npm override --- docs/cli/plugins.md | 11 +++++++---- docs/tools/plugin.md | 15 ++++++++++----- 2 files changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md index 9317e7eec14..90e3e2df8f1 100644 --- a/docs/cli/plugins.md +++ b/docs/cli/plugins.md @@ -103,7 +103,7 @@ rewriting files. ```bash openclaw plugins search "calendar" # search ClawHub plugins -openclaw plugins install # npm by default +openclaw plugins install # source auto-detection openclaw plugins install clawhub: # ClawHub only openclaw plugins install npm: # npm only openclaw plugins install npm-pack: # local npm pack through npm install semantics @@ -123,7 +123,7 @@ sources with guarded environment variables. See [Plugin install overrides](/plugins/install-overrides). -Bare package names install from npm by default during the launch cutover. Use `clawhub:` for ClawHub. Treat plugin installs like running code. Prefer pinned versions. +Bare package names install from npm by default during the launch cutover, unless they match an official plugin id. Raw `@openclaw/*` package specs that match bundled plugins use the bundled copy that shipped with the current OpenClaw build. Use `npm:` when you deliberately want an external npm package instead. Use `clawhub:` for ClawHub. Treat plugin installs like running code. Prefer pinned versions. `plugins search` queries ClawHub for installable plugin packages and prints @@ -171,7 +171,9 @@ is available, then fall back to `latest`. Npm specs are **registry-only** (package name + optional **exact version** or **dist-tag**). Git/URL/file specs and semver ranges are rejected. Dependency installs run project-local with `--ignore-scripts` for safety, even when your shell has global npm install settings. Managed plugin npm roots inherit OpenClaw's package-level npm `overrides`, so host security pins apply to hoisted plugin dependencies too. - Use `npm:` when you want to make npm resolution explicit. Bare package specs also install directly from npm during the launch cutover. + Use `npm:` when you want to make npm resolution explicit. Bare package specs also install directly from npm during the launch cutover unless they match an official plugin id. + + Raw `@openclaw/*` package specs that match bundled plugins resolve to the image-owned bundled copy before npm fallback. For example, `openclaw plugins install @openclaw/discord@2026.5.20 --pin` uses the bundled Discord plugin from the current OpenClaw build instead of creating a managed npm override. To force the external npm package, use `openclaw plugins install npm:@openclaw/discord@2026.5.20 --pin`. Bare specs and `@latest` stay on the stable track. OpenClaw date-stamped correction versions such as `2026.5.3-1` are stable releases for this check. If npm resolves either of those to a prerelease, OpenClaw stops and asks you to opt in explicitly with a prerelease tag such as `@beta`/`@rc` or an exact prerelease version such as `@1.2.3-beta.4`. @@ -207,7 +209,7 @@ openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -Bare npm-safe plugin specs install from npm by default during the launch cutover: +Bare npm-safe plugin specs install from npm by default during the launch cutover unless they match an official plugin id: ```bash openclaw plugins install openclaw-codex-app-server @@ -217,6 +219,7 @@ Use `npm:` to make npm-only resolution explicit: ```bash openclaw plugins install npm:openclaw-codex-app-server +openclaw plugins install npm:@openclaw/discord@2026.5.20 openclaw plugins install npm:@scope/plugin-name@1.0.1 ``` diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index 8b7796d117d..819e64355bc 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -40,7 +40,9 @@ Before installing a plugin, make sure you have: ``` ClawHub is the primary discovery surface for community plugins. During the - launch cutover, ordinary bare package specs still install from npm. Use an + launch cutover, ordinary bare package specs still install from npm unless + they match an official plugin id. Raw `@openclaw/*` package specs that match + bundled plugins use the bundled copy from the current OpenClaw build. Use an explicit prefix when you need one source. @@ -126,10 +128,13 @@ Before installing a plugin, make sure you have: Bare package specs have special compatibility behavior. If the bare name matches a bundled plugin id, OpenClaw uses that bundled source. If it matches an official external plugin id, OpenClaw uses the official package catalog. Other -ordinary bare package specs install through npm during the launch cutover. Use -`clawhub:`, `npm:`, `git:`, or `npm-pack:` when you need deterministic source -selection. See [`openclaw plugins`](/cli/plugins#install) for the full command -contract. +ordinary bare package specs install through npm during the launch cutover. Raw +`@openclaw/*` package specs that match bundled plugins also resolve to the +bundled copy before npm fallback. Use `npm:@openclaw/@` when +you deliberately want the external npm package instead of the image-owned +bundled copy. Use `clawhub:`, `npm:`, `git:`, or `npm-pack:` when you need +deterministic source selection. See [`openclaw plugins`](/cli/plugins#install) +for the full command contract. ### Configure plugin policy