diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index 43bb313dc..4d7f76b7e 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
{
"repository": "openclaw/openclaw",
- "sha": "cf21bcf9bfffefea3dfb1bd4571d4942ad467913",
- "syncedAt": "2026-05-02T19:01:29.311Z"
+ "sha": "66db1899625f7a46e171717bbf88b0759b62dc84",
+ "syncedAt": "2026-05-02T19:07:11.451Z"
}
diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json
index 31358840c..7f796a7b7 100644
--- a/docs/.i18n/glossary.zh-CN.json
+++ b/docs/.i18n/glossary.zh-CN.json
@@ -3,6 +3,10 @@
"source": "OpenClaw",
"target": "OpenClaw"
},
+ {
+ "source": "ClawHub",
+ "target": "ClawHub"
+ },
{
"source": "OpenAI",
"target": "OpenAI"
@@ -471,6 +475,14 @@
"source": "Plugins",
"target": "插件"
},
+ {
+ "source": "Manage plugins",
+ "target": "管理插件"
+ },
+ {
+ "source": "Plugin manifest",
+ "target": "插件清单"
+ },
{
"source": "Building plugins",
"target": "构建插件"
diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md
index db97a9a06..028d0eb1e 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 0d96dac43..1cd66eb68 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1197,6 +1197,7 @@
"group": "Plugins",
"pages": [
"tools/plugin",
+ "plugins/manage-plugins",
"plugins/community",
"plugins/plugin-inventory",
"plugins/reference",
@@ -2679,6 +2680,7 @@
"group": "Plugins",
"pages": [
"zh-TW/tools/plugin",
+ "zh-TW/plugins/manage-plugins",
"zh-TW/plugins/community",
"zh-TW/plugins/plugin-inventory",
"zh-TW/plugins/reference",
@@ -3546,6 +3548,7 @@
"group": "Plugins",
"pages": [
"ja-JP/tools/plugin",
+ "ja-JP/plugins/manage-plugins",
"ja-JP/plugins/community",
"ja-JP/plugins/plugin-inventory",
"ja-JP/plugins/reference",
@@ -4413,6 +4416,7 @@
"group": "Plugins",
"pages": [
"es/tools/plugin",
+ "es/plugins/manage-plugins",
"es/plugins/community",
"es/plugins/plugin-inventory",
"es/plugins/reference",
@@ -5280,6 +5284,7 @@
"group": "Plugins",
"pages": [
"pt-BR/tools/plugin",
+ "pt-BR/plugins/manage-plugins",
"pt-BR/plugins/community",
"pt-BR/plugins/plugin-inventory",
"pt-BR/plugins/reference",
@@ -6147,6 +6152,7 @@
"group": "Plugins",
"pages": [
"ko/tools/plugin",
+ "ko/plugins/manage-plugins",
"ko/plugins/community",
"ko/plugins/plugin-inventory",
"ko/plugins/reference",
@@ -7014,6 +7020,7 @@
"group": "Plugins",
"pages": [
"de/tools/plugin",
+ "de/plugins/manage-plugins",
"de/plugins/community",
"de/plugins/plugin-inventory",
"de/plugins/reference",
@@ -7881,6 +7888,7 @@
"group": "Plugins",
"pages": [
"fr/tools/plugin",
+ "fr/plugins/manage-plugins",
"fr/plugins/community",
"fr/plugins/plugin-inventory",
"fr/plugins/reference",
@@ -8748,6 +8756,7 @@
"group": "Plugins",
"pages": [
"ar/tools/plugin",
+ "ar/plugins/manage-plugins",
"ar/plugins/community",
"ar/plugins/plugin-inventory",
"ar/plugins/reference",
@@ -9615,6 +9624,7 @@
"group": "Plugins",
"pages": [
"it/tools/plugin",
+ "it/plugins/manage-plugins",
"it/plugins/community",
"it/plugins/plugin-inventory",
"it/plugins/reference",
@@ -10482,6 +10492,7 @@
"group": "Plugins",
"pages": [
"vi/tools/plugin",
+ "vi/plugins/manage-plugins",
"vi/plugins/community",
"vi/plugins/plugin-inventory",
"vi/plugins/reference",
@@ -11349,6 +11360,7 @@
"group": "Plugins",
"pages": [
"nl/tools/plugin",
+ "nl/plugins/manage-plugins",
"nl/plugins/community",
"nl/plugins/plugin-inventory",
"nl/plugins/reference",
@@ -12216,6 +12228,7 @@
"group": "Plugins",
"pages": [
"tr/tools/plugin",
+ "tr/plugins/manage-plugins",
"tr/plugins/community",
"tr/plugins/plugin-inventory",
"tr/plugins/reference",
@@ -13083,6 +13096,7 @@
"group": "Plugins",
"pages": [
"uk/tools/plugin",
+ "uk/plugins/manage-plugins",
"uk/plugins/community",
"uk/plugins/plugin-inventory",
"uk/plugins/reference",
@@ -13950,6 +13964,7 @@
"group": "Plugins",
"pages": [
"id/tools/plugin",
+ "id/plugins/manage-plugins",
"id/plugins/community",
"id/plugins/plugin-inventory",
"id/plugins/reference",
@@ -14817,6 +14832,7 @@
"group": "Plugins",
"pages": [
"pl/tools/plugin",
+ "pl/plugins/manage-plugins",
"pl/plugins/community",
"pl/plugins/plugin-inventory",
"pl/plugins/reference",
diff --git a/docs/plugins/manage-plugins.md b/docs/plugins/manage-plugins.md
new file mode 100644
index 000000000..822178974
--- /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 48f5e4c2d..78551be2e 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