From 3effdf98f702c3ef4a7edd1e482835197f9dcd37 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Mon, 16 Mar 2026 02:02:39 -0700 Subject: [PATCH] Docs: add Claude marketplace plugin install guidance --- docs/cli/index.md | 3 ++- docs/cli/plugins.md | 33 +++++++++++++++++++++++++++++++-- docs/plugins/bundles.md | 7 +++++++ docs/tools/plugin.md | 16 ++++++++++++++++ 4 files changed, 56 insertions(+), 3 deletions(-) diff --git a/docs/cli/index.md b/docs/cli/index.md index ded970cde9d..9c4b58d1c35 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -284,7 +284,8 @@ Manage extensions and their config: - `openclaw plugins list` — discover plugins (use `--json` for machine output). - `openclaw plugins info ` — show details for a plugin. -- `openclaw plugins install ` — install a plugin (or add a plugin path to `plugins.load.paths`). +- `openclaw plugins install ` — install a plugin (or add a plugin path to `plugins.load.paths`). +- `openclaw plugins marketplace list ` — list marketplace entries before install. - `openclaw plugins enable ` / `disable ` — toggle `plugins.entries..enabled`. - `openclaw plugins doctor` — report plugin load errors. diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md index 4d9d1e8e80d..b867420551f 100644 --- a/docs/cli/plugins.md +++ b/docs/cli/plugins.md @@ -1,5 +1,5 @@ --- -summary: "CLI reference for `openclaw plugins` (list, install, uninstall, enable/disable, doctor)" +summary: "CLI reference for `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)" read_when: - You want to install or manage Gateway plugins or compatible bundles - You want to debug plugin load failures @@ -28,6 +28,7 @@ openclaw plugins uninstall openclaw plugins doctor openclaw plugins update openclaw plugins update --all +openclaw plugins marketplace list ``` Bundled plugins ship with OpenClaw but start disabled. Use `plugins enable` to @@ -46,6 +47,8 @@ capabilities. ```bash openclaw plugins install openclaw plugins install --pin +openclaw plugins install @ +openclaw plugins install --marketplace ``` Security note: treat plugin installs like running code. Prefer pinned versions. @@ -65,6 +68,31 @@ name, use an explicit scoped spec (for example `@scope/diffs`). Supported archives: `.zip`, `.tgz`, `.tar.gz`, `.tar`. +Claude marketplace installs are also supported. + +Use `plugin@marketplace` shorthand when the marketplace name exists in Claude's +local registry cache at `~/.claude/plugins/known_marketplaces.json`: + +```bash +openclaw plugins marketplace list claude-plugins-official +openclaw plugins install superpowers@claude-plugins-official +``` + +Use `--marketplace` when you want to pass the marketplace source explicitly: + +```bash +openclaw plugins install superpowers --marketplace claude-plugins-official +openclaw plugins install superpowers --marketplace anthropics/claude-plugins-official +openclaw plugins install superpowers --marketplace ./my-marketplace +``` + +Marketplace sources can be: + +- a Claude known-marketplace name from `~/.claude/plugins/known_marketplaces.json` +- a local marketplace root or `marketplace.json` path +- a GitHub repo shorthand such as `owner/repo` +- a git URL + For local paths and archives, OpenClaw auto-detects: - native OpenClaw plugins (`openclaw.plugin.json`) @@ -114,7 +142,8 @@ openclaw plugins update --all openclaw plugins update --dry-run ``` -Updates only apply to plugins installed from npm (tracked in `plugins.installs`). +Updates apply to tracked installs in `plugins.installs`, currently npm and +marketplace installs. When a stored integrity hash exists and the fetched artifact hash changes, OpenClaw prints a warning and asks for confirmation before proceeding. Use diff --git a/docs/plugins/bundles.md b/docs/plugins/bundles.md index b5f92f8f5ee..c652ff997f0 100644 --- a/docs/plugins/bundles.md +++ b/docs/plugins/bundles.md @@ -259,12 +259,19 @@ openclaw plugins install ./my-codex-bundle openclaw plugins install ./my-claude-bundle openclaw plugins install ./my-cursor-bundle openclaw plugins install ./my-bundle.tgz +openclaw plugins marketplace list claude-plugins-official +openclaw plugins install superpowers@claude-plugins-official openclaw plugins info my-bundle ``` If the directory is a native OpenClaw plugin/package, the native install path still wins. +For Claude marketplace names, OpenClaw reads the local Claude known-marketplace +registry at `~/.claude/plugins/known_marketplaces.json`. Marketplace entries +can resolve to bundle-compatible directories/archives or to native plugin +sources; after resolution, the normal install rules still apply. + ## Troubleshooting ### Bundle is detected but capabilities do not run diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index 246724719ff..af29b5eb8ac 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -57,6 +57,18 @@ openclaw plugins install ./my-bundle openclaw plugins install ./my-bundle.tgz ``` +For Claude marketplace installs, list the marketplace first, then install by +marketplace entry name: + +```bash +openclaw plugins marketplace list claude-plugins-official +openclaw plugins install superpowers@claude-plugins-official +``` + +OpenClaw resolves known Claude marketplace names from +`~/.claude/plugins/known_marketplaces.json`. You can also pass an explicit +marketplace source with `--marketplace`. + ## Architecture OpenClaw's plugin system has four layers: @@ -94,6 +106,10 @@ OpenClaw also recognizes two compatible external bundle layouts: component layout without a manifest - Cursor-style bundles: `.cursor-plugin/plugin.json` +Claude marketplace entries can point at any of these compatible bundles, or at +native OpenClaw plugin sources. OpenClaw resolves the marketplace entry first, +then runs the normal install path for the resolved source. + They are shown in the plugin list as `format=bundle`, with a subtype of `codex` or `claude` in verbose/info output.