vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-06-10 19:42:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: explain bundled plugin npm override

Browse Source
This commit is contained in:
fuller-stack-dev
2026-05-25 23:13:19 -06:00
committed by Peter Steinberger
parent 669bfdd9b0
commit 40fa750b4f
2 changed files with 17 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/cli/plugins.md
View File

@@ -103,7 +103,7 @@ rewriting files.
```bash
openclaw plugins search "calendar" # search ClawHub plugins
openclaw plugins install <package> # npm by default
openclaw plugins install <package> # source auto-detection
openclaw plugins install clawhub:<package> # ClawHub only
openclaw plugins install npm:<package> # npm only
openclaw plugins install npm-pack:<path.tgz> # local npm pack through npm install semantics
@@ -123,7 +123,7 @@ sources with guarded environment variables. See
[Plugin install overrides](/plugins/install-overrides).
<Warning>
Bare package names install from npm by default during the launch cutover. Use `clawhub:<package>` 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:<package>` when you deliberately want an external npm package instead. Use `clawhub:<package>` for ClawHub. Treat plugin installs like running code. Prefer pinned versions.
</Warning>
`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:<package>` when you want to make npm resolution explicit. Bare package specs also install directly from npm during the launch cutover.
Use `npm:<package>` 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
```

15
docs/tools/plugin.md
View File

@@ -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.
</Step>
@@ -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/<plugin>@<version>` 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