docs: explain blocked plugin ownership repair

docs/.i18n/glossary.zh-CN.json

@@ -583,6 +583,14 @@
     "source": "Manage plugins",
     "target": "管理插件"
   },
+  {
+    "source": "Plugin path ownership",
+    "target": "插件路径所有权"
+  },
+  {
+    "source": "Docker permissions",
+    "target": "Docker 权限"
+  },
   {
     "source": "Plugin manifest",
     "target": "插件清单"

docs/help/troubleshooting.md

@@ -80,6 +80,40 @@ Example:
 
 Reference: [Plugin architecture](/plugins/architecture)
 
+## Plugin present but blocked by suspicious ownership
+
+If `openclaw doctor`, setup, or startup warnings show:
+
+```text
+blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)
+plugin present but blocked
+```
+
+the plugin files are owned by a different Unix user than the process loading
+them. Do not remove the plugin config. Fix the file ownership or run OpenClaw as
+the same user that owns the state directory.
+
+Docker installs normally run as `node` (uid `1000`). For the default Docker
+setup, repair the host bind mounts:
+
+```bash
+sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
+openclaw doctor --fix
+```
+
+If you intentionally run OpenClaw as root, repair the managed plugin root to
+root ownership instead:
+
+```bash
+sudo chown -R root:root /path/to/openclaw-config/npm
+openclaw doctor --fix
+```
+
+Deeper docs:
+
+- [Plugin path ownership](/tools/plugin#blocked-plugin-path-ownership)
+- [Docker permissions](/install/docker#permissions-and-eacces)
+
 ## Decision tree
 
 ```mermaid

docs/install/docker.md

@@ -343,6 +343,14 @@ See [ClawDock](/install/clawdock) for the full helper guide.
     sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
     ```
 
+    The same mismatch can show up as a plugin warning such as
+    `blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)`
+    followed by `plugin present but blocked`. That means the process uid and the
+    mounted plugin directory owner disagree. Prefer running the container as the
+    default uid 1000 and fixing the bind mount ownership. Only chown
+    `/path/to/openclaw-config/npm` to `root:root` if you intentionally run
+    OpenClaw as root long term.
+
   </Accordion>
 
   <Accordion title="Faster rebuilds">

docs/tools/plugin.md

@@ -127,6 +127,34 @@ visible plugin without importing runtime code or repairing dependencies.
 See [Plugin dependency resolution](/plugins/dependency-resolution) for the
 install-time lifecycle.
 
+### Blocked plugin path ownership
+
+If plugin diagnostics say
+`blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)`
+and config validation follows with `plugin present but blocked`, OpenClaw found
+plugin files owned by a different Unix user than the process that is loading
+them. Keep the plugin config in place; fix the filesystem ownership or run
+OpenClaw as the same user that owns the state directory.
+
+For Docker installs, the official image runs as `node` (uid `1000`), so the
+host bind-mounted OpenClaw config and workspace directories should normally be
+owned by uid `1000`:
+
+```bash
+sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
+```
+
+If you intentionally run OpenClaw as root, repair the managed plugin root to
+root ownership instead:
+
+```bash
+sudo chown -R root:root /path/to/openclaw-config/npm
+```
+
+After fixing ownership, rerun `openclaw doctor --fix` or
+`openclaw plugins registry --refresh` so the persisted plugin registry matches
+the repaired files.
+
 For npm installs, mutable selectors such as `latest` or a dist-tag are resolved
 before installation and then pinned to the exact verified version in OpenClaw's
 managed npm root. After npm finishes, OpenClaw verifies the installed