skip to content

How does `openclaw plugins install` treat ClawHub, npm, git and local `--link` sources differently?

level: middleimportance: should knowfreq 8%

answer

  1. four prefixes, different trust
  2. bare names default to npm
  3. arbitrary sources need review
  4. --pin is npm-only
  5. --link adds to plugins.load.paths

basics

~20 s

In OpenClaw 2026.9.9, clawhub: and the official catalog are trusted sources; other npm packages, git repositories and local paths are arbitrary sources that warn first and need --force in noninteractive installs. --link points at a local directory without copying it.

solid answer

~40 s

`openclaw plugins install clawhub:<package>` resolves through ClawHub, checks the release's trust record and verifies the artifact digest. `npm:<package>` takes a registry name with an exact version or dist-tag (ranges are rejected), installs dependencies in a per-plugin managed npm project with `--ignore-scripts`, and `--pin` records the resolved exact version. `git:github.com/<owner>/<repo>@<ref>` clones, checks out the ref and records the resolved commit; pin it by ref, because `--pin` is npm-only. A local path is copied, while `--link` adds the directory to `plugins.load.paths` for development and does not inherit official trust. A bare name installs from npm unless it matches a bundled or official plugin id. Arbitrary sources warn and ask first; a noninteractive install needs `--force` after review, and `--force` never bypasses `security.installPolicy`.

code

bash · 14 lines
bash
# ClawHub, pinned to one release
openclaw plugins install clawhub:[email protected]

# npm, recording the resolved exact version
openclaw plugins install npm:@acme/openclaw-calendar --pin

# git, pinned by tag (reviewed source, noninteractive)
openclaw plugins install git:github.com/acme/[email protected] --force

# local development checkout, linked instead of copied
openclaw plugins install --link ./openclaw-calendar --force

# prove what the plugin registers
openclaw plugins inspect acme-calendar --runtime --json

go deeper

for a junior

Recall the four locators, clawhub:, npm:, git: and a local path, and that --link is for a plugin you are developing.

for a middle

Explain how each source verifies and pins: ClawHub trust record and digest, npm exact version or --pin, git ref plus recorded commit, and why bare names fall to npm.

for a senior

Show that --force only confirms a reviewed arbitrary source, never install policy or capability consent, and that linked local copies lose official trust.

for a principal

Decide which sources a team accepts at all, how versions are pinned in config, and who reviews an arbitrary source before a script is allowed to pass --force.

## One command, several locators From the CLI, an OpenClaw plugin install goes through `openclaw plugins install <path-or-spec>`. The prefix on the spec picks the source, and each source carries its own verification and pinning rules. This describes OpenClaw 2026.9.9; install rules have changed across recent releases. | Source | Locator | What OpenClaw does | How to pin | | --- | --- | --- | --- | | ClawHub | `clawhub:<package>` | Checks a community release's trust record, verifies the artifact digest | `clawhub:<package>@1.2.3` | | npm | `npm:<package>` | Registry name plus exact version or dist-tag; ranges rejected | `--pin` records `name@version` | | git | `git:github.com/<owner>/<repo>@<ref>` | Clones, checks out the ref, records the resolved commit | the ref in the spec | | local path | `./my-plugin` | Copies the directory or archive into the plugin root | not applicable | | local link | `--link ./my-plugin` | Adds the path to `plugins.load.paths`, no copy | not applicable | ## Trusted versus arbitrary sources OpenClaw treats **ClawHub packages and its bundled or official catalog** as trusted install sources. Everything else is an **arbitrary source**: a new npm package, an `npm-pack:` tarball, a git repository, a local path or archive, or a marketplace. - An arbitrary source warns and asks before continuing. A noninteractive install (a script, CI) must pass `--force` after someone has reviewed the source. - `--force` confirms provenance and permits overwriting an existing install. It does **not** bypass `security.installPolicy`, approve new capabilities, or skip the remaining safety checks. - Community ClawHub releases are checked against ClawHub's trust record before download: a Review outcome is informational, while a disabled download or blocking moderation outcome refuses the release. - npm dependency installs run in one managed npm project per plugin with `--ignore-scripts`, even if your shell's npm settings differ. ## Bare names and the npm default A spec with no prefix has compatibility behaviour. If it matches a bundled plugin id, the bundled copy is used; if it matches an official external plugin id, the official catalog decides the source; **any other bare name installs from npm**. That is why the docs recommend explicit prefixes (`clawhub:`, `npm:`, `git:`, `npm-pack:`) when you care which registry you hit. For unpinned npm specs or `@latest`, OpenClaw reads the package's declared plugin API and minimum host version and installs the newest stable release compatible with the running build, scanning older versions if the latest is too new. Exact versions and explicit tags such as `@beta` stay strict and fail when incompatible. ## Local development: copy versus link A plain local path is copied into the plugin root and treated as a self-contained package: OpenClaw does not run `npm install` for it, so local dependencies are your job. `--link` (short `-l`) instead records the directory in `plugins.load.paths` so edits are picked up after `openclaw plugins reload <id>`. - `--link` needs a local path that exists; it is rejected with `git:` installs, npm specs and `--marketplace`. - A linked or local copy never inherits official trust, even if its name matches an official plugin. Features that need trusted plugin state, such as a channel's durable ingress queue, refuse to start on it. ## After the install 1. If `plugins.allow` is set, the install adds the plugin id to it and removes the id from `plugins.deny`; `--no-enable` leaves activation policy alone. 2. If the plugin needs config that is missing, the install is recorded **disabled**; add `plugins.entries.<id>.config` and run `openclaw plugins enable <id>`. 3. With a local Gateway running, the install is applied without a restart. 4. Verify with `openclaw plugins inspect <id> --runtime --json`, then trigger the tool or hook through the live Gateway. ## Updating what you installed The install record remembers the source, which is what `openclaw plugins update <id>` follows later: - an unversioned `clawhub:` install keeps an unversioned spec, so updates follow newer ClawHub releases, while `clawhub:<package>@1.2.3` stays on that release; - a `git:` install records the URL, ref and resolved commit, so an update re-resolves the same source; - an npm install pinned with `--pin` keeps its exact `name@version` until you choose another. Running `install` again for an id that is already installed stops and points you to `openclaw plugins update <id>` for a normal upgrade, or `install ... --force` to overwrite from a different source.

  • Why might an unpinned `npm:` plugin install pick an older version than npm's latest?
    For an unpinned spec or `@latest`, OpenClaw checks the package's declared plugin API and minimum host version. If the newest stable release needs a newer OpenClaw than the one running, it scans older stable versions and installs the newest compatible one. Exact versions and explicit tags stay strict and fail instead.
  • Does a `--link` install of a local copy of an official plugin get official trust?
    No. Local copies selected through `plugins.load.paths`, including `--link` installs, do not inherit official package trust, and `--force` does not change that. Features that require trusted plugin state, such as a channel's durable ingress queue, stay blocked until you install the official npm or ClawHub package and remove the local override.

  • A bare package name installs from ClawHub by default.
  • Passing --force skips the operator install policy and safety checks.
  • --pin works the same for npm, git and ClawHub installs.
  • A --link install copies the directory into the plugin root.
  • An npm plugin install runs its dependencies' install scripts.

Assumes OpenClaw 2026.9.9; plugin install trust rules, consent and pinning behaviour have changed across recent releases.