openclaw/docs/plugins/manage-plugins.md at f45390416565253dfd686c8ea68bddd0f85ecbb9

vrr/openclaw

Fork 0

mirror of https://github.com/openclaw/openclaw.git synced 2026-05-18 05:59:31 +00:00

Peter Steinberger 15b0d43412

docs: clarify plugin gateway auto-restart

2026-05-16 17:11:53 +01:00

8 KiB

Raw Blame History

summary

read_when

title

sidebarTitle

doc-schema-version

Quick examples for listing, installing, updating, inspecting, and uninstalling OpenClaw plugins

You want quick plugin list, install, update, inspect, or uninstall examples

You want to choose a plugin install source

You want the right reference for publishing plugin packages

Manage plugins

Use this page for common plugin management commands. For the exhaustive command contract, flags, source-selection rules, and edge cases, see openclaw plugins.

Most install workflows are:

find a package
install it from ClawHub, npm, git, or a local path
let the managed Gateway auto-restart, or restart it manually when unmanaged
verify the plugin's runtime registrations

List and search plugins

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search "calendar"

Use --json for scripts:

openclaw plugins list --json \
  | jq '.plugins[] | {id, enabled, format, source, dependencyStatus}'

plugins list is a cold inventory check. It shows what OpenClaw can discover from config, manifests, and the plugin registry; it does not prove that an already-running Gateway imported the plugin runtime. The JSON output includes registry diagnostics and each plugin's static dependencyStatus when the plugin package declares dependencies or optionalDependencies.

plugins search queries ClawHub for installable plugin packages and prints install hints such as openclaw plugins install clawhub:<package>.

Install plugins

# Search ClawHub for plugin packages.
openclaw plugins search "calendar"

# Install from ClawHub.
openclaw plugins install clawhub:<package>
openclaw plugins install clawhub:<package>@1.2.3
openclaw plugins install clawhub:<package>@beta

# Install from npm.
openclaw plugins install npm:<package>
openclaw plugins install npm:@scope/openclaw-plugin@1.2.3
openclaw plugins install npm:@openclaw/codex

# Install from a local npm pack artifact.
openclaw plugins install npm-pack:<path.tgz>

# Install from git or a local development checkout.
openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin

Bare package specs install from npm during the launch cutover. Use clawhub:, npm:, git:, or npm-pack: when you need deterministic source selection. If the bare name matches an official plugin id, OpenClaw can install the catalog entry directly.

Use --force only when you intentionally want to overwrite an existing install target. For routine upgrades of tracked npm, ClawHub, or hook-pack installs, use openclaw plugins update.

Restart and inspect

After installing, updating, or uninstalling plugin code, a running managed Gateway with config reload enabled restarts automatically. If the Gateway is not managed or reload is disabled, restart it yourself before checking live runtime surfaces:

openclaw gateway restart
openclaw plugins inspect <plugin-id> --runtime --json

Use inspect --runtime when you need proof that the plugin registered runtime surfaces such as tools, hooks, services, Gateway methods, HTTP routes, or plugin-owned CLI commands. Plain inspect and list are cold manifest, config, and registry checks.

Update plugins

openclaw plugins update <plugin-id>
openclaw plugins update <npm-package-or-spec>
openclaw plugins update --all
openclaw plugins update <plugin-id> --dry-run

When you pass a plugin id, OpenClaw reuses the tracked install spec. Stored dist-tags such as @beta and exact pinned versions continue to be used on later update <plugin-id> runs.

For npm installs, you can pass an explicit package spec to switch the tracked record:

openclaw plugins update @scope/openclaw-plugin@beta
openclaw plugins update @scope/openclaw-plugin

The second command moves a plugin back to the registry's default release line when it was previously pinned to an exact version or tag.

When openclaw update runs on the beta channel, plugin records can prefer matching @beta releases. For the exact fallback and pinning rules, see openclaw plugins.

Uninstall plugins

openclaw plugins uninstall <plugin-id> --dry-run
openclaw plugins uninstall <plugin-id>
openclaw plugins uninstall <plugin-id> --keep-files

Uninstall removes the plugin's config entry, persisted plugin index record, allow/deny list entries, and linked load paths when applicable. Managed install directories are removed unless you pass --keep-files. A running managed Gateway restarts automatically when the uninstall changes plugin source.

In Nix mode (OPENCLAW_NIX_MODE=1), plugin install, update, uninstall, enable, and disable commands are disabled. Manage those choices in the Nix source for the install instead.

Choose a source

Source	Use when	Example
ClawHub	You want OpenClaw-native discovery, scan summaries, versions, and hints	`openclaw plugins install clawhub:<package>`
npmjs.com	You already ship JavaScript packages or need npm dist-tags/private registry	`openclaw plugins install npm:@acme/openclaw-plugin`
git	You want a branch, tag, or commit from a repository	`openclaw plugins install git:github.com/<owner>/<repo>@<ref>`
local path	You are developing or testing a plugin on the same machine	`openclaw plugins install --link ./my-plugin`
npm pack	You are proving a local package artifact through npm install semantics	`openclaw plugins install npm-pack:<path.tgz>`
marketplace	You are installing a Claude-compatible marketplace plugin	`openclaw plugins install <plugin> --marketplace <source>`

Publish plugins

ClawHub is the primary public discovery surface for OpenClaw plugins. Publish there when you want users to find plugin metadata, version history, registry scan results, and install hints before they install.

npm i -g clawhub
clawhub login
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
clawhub package publish your-org/your-plugin@v1.0.0

Native npm plugins must include a plugin manifest and package metadata before publishing:

{
  "name": "@acme/openclaw-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

npm publish --access public
openclaw plugins install npm:@acme/openclaw-plugin
openclaw plugins install npm:@acme/openclaw-plugin@beta
openclaw plugins install npm:@acme/openclaw-plugin@1.0.0

Use these pages for the full publishing contract instead of treating this page as the publishing reference:

ClawHub publishing explains owners, scopes, releases, review, package validation, and package transfer.
Building plugins shows the plugin package shape and first publish workflow.
Plugin manifest defines native plugin manifest fields.

If the same package is available on both ClawHub and npm, use the explicit clawhub: or npm: prefix when you need to force one source.

Plugins - install, configure, restart, and troubleshoot
openclaw plugins - full CLI reference
Community plugins - public discovery and ClawHub publishing
ClawHub - registry CLI operations
Building plugins - create a plugin package
Plugin manifest - manifest and package metadata

8 KiB Raw Blame History