From f8a59794693f41dc0c49247d7a3653222608aa6d Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 2 May 2026 20:03:52 +0100 Subject: [PATCH] docs(plugins): add management quickstart --- docs/cli/plugins.md | 3 + docs/docs.json | 1 + docs/plugins/manage-plugins.md | 180 +++++++++++++++++++++++++++++++++ docs/tools/plugin.md | 3 + 4 files changed, 187 insertions(+) create mode 100644 docs/plugins/manage-plugins.md diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md index db97a9a062b..028d0eb1e88 100644 --- a/docs/cli/plugins.md +++ b/docs/cli/plugins.md @@ -13,6 +13,9 @@ Manage Gateway plugins, hook packs, and compatible bundles. End-user guide for installing, enabling, and troubleshooting plugins. + + Quick examples for install, list, update, uninstall, and publishing. + Bundle compatibility model. diff --git a/docs/docs.json b/docs/docs.json index b6530a0f828..ff8abe3e8ca 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1182,6 +1182,7 @@ "group": "Plugins", "pages": [ "tools/plugin", + "plugins/manage-plugins", "plugins/community", "plugins/plugin-inventory", "plugins/reference", diff --git a/docs/plugins/manage-plugins.md b/docs/plugins/manage-plugins.md new file mode 100644 index 00000000000..822178974dc --- /dev/null +++ b/docs/plugins/manage-plugins.md @@ -0,0 +1,180 @@ +--- +summary: "Quick examples for installing, listing, uninstalling, updating, and publishing OpenClaw plugins" +read_when: + - You want quick plugin install, list, update, or uninstall examples + - You want to choose between ClawHub and npm plugin distribution + - You are publishing a plugin package +title: "Manage plugins" +sidebarTitle: "Manage plugins" +--- + +Most plugin workflows are a few commands: search, install, restart the Gateway, +verify, and uninstall when you no longer need the plugin. + +## List plugins + +```bash +openclaw plugins list +openclaw plugins list --enabled +openclaw plugins list --verbose +openclaw plugins list --json +``` + +Use `--json` for scripts. It includes registry diagnostics and each plugin's +static `dependencyStatus` when the plugin package declares `dependencies` or +`optionalDependencies`. + +```bash +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 process imported the plugin runtime. + +## Install plugins + +```bash +# Search ClawHub for plugin packages. +openclaw plugins search "calendar" + +# Bare package specs try ClawHub first, then npm fallback. +openclaw plugins install + +# Force one source. +openclaw plugins install clawhub: +openclaw plugins install npm: + +# Install a specific version or dist-tag. +openclaw plugins install clawhub:@1.2.3 +openclaw plugins install clawhub:@beta +openclaw plugins install npm:@scope/openclaw-plugin@1.2.3 +openclaw plugins install npm:@openclaw/codex@beta + +# 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 +``` + +After installing plugin code, restart the Gateway that serves your channels: + +```bash +openclaw gateway restart +openclaw plugins inspect --runtime --json +``` + +Use `inspect --runtime` when you need proof that the plugin registered runtime +surfaces such as tools, hooks, services, Gateway methods, or plugin-owned CLI +commands. + +## Update plugins + +```bash +openclaw plugins update +openclaw plugins update +openclaw plugins update --all +``` + +If a plugin was installed from an npm dist-tag such as `@beta`, later +`update ` calls reuse that recorded tag. Passing an explicit npm spec +switches the tracked install to that spec for future updates. + +```bash +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. + +## Uninstall plugins + +```bash +openclaw plugins uninstall --dry-run +openclaw plugins uninstall +openclaw plugins uninstall --keep-files +openclaw gateway restart +``` + +Uninstall removes the plugin's config entry, plugin index record, allow/deny list +entries, and linked load paths when applicable. Managed install directories are +removed unless you pass `--keep-files`. + +## Publish plugins + +You can publish external plugins to [ClawHub](https://clawhub.ai), npmjs.com, or +both. + +### Publish to ClawHub + +ClawHub is the primary public discovery surface for OpenClaw plugins. It gives +users searchable metadata, version history, and registry scan results before +install. + +```bash +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 +``` + +Users install from ClawHub with: + +```bash +openclaw plugins install clawhub: +openclaw plugins install +``` + +The bare form still checks ClawHub first. + +### Publish to npmjs.com + +Native npm plugins must include a plugin manifest and `package.json` OpenClaw +entrypoint metadata. + +```json package.json +{ + "name": "@acme/openclaw-plugin", + "version": "1.0.0", + "type": "module", + "openclaw": { + "extensions": ["./dist/index.js"] + } +} +``` + +```bash +npm publish --access public +``` + +Users install npm-only with: + +```bash +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 +``` + +If the same package is also available on ClawHub, `npm:` skips ClawHub lookup and +forces npm resolution. + +## Source choice + +- **ClawHub**: use when you want OpenClaw-native discovery, scan summaries, + versions, and install hints. +- **npmjs.com**: use when you already ship JavaScript packages or need npm + dist-tags/private registry workflows. +- **Git**: use when you want to install directly from a branch, tag, or commit. +- **Local path**: use when you are developing or testing a plugin on the same + machine. + +## Related + +- [Plugins](/tools/plugin) - overview and troubleshooting +- [`openclaw plugins`](/cli/plugins) - full CLI reference +- [ClawHub](/tools/clawhub) - publish and registry operations +- [Building plugins](/plugins/building-plugins) - create a plugin package +- [Plugin manifest](/plugins/manifest) - manifest and package metadata diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index 48f5e4c2d60..78551be2e29 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -18,6 +18,9 @@ temporary set of OpenClaw-owned plugin packages while that migration finishes. ## Quick start +For copy-paste install, list, uninstall, update, and publishing examples, see +[Manage plugins](/plugins/manage-plugins). + ```bash