vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 13:40:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: explain blocked plugin ownership repair

Browse Source
This commit is contained in:
Peter Steinberger
2026-05-06 04:43:31 +01:00
parent b971ebaaab
commit cbc228f0f6
4 changed files with 78 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/tools/plugin.md
View File

@@ -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