From 4bd6837aceb19b6ee3d5a8b3bd710f6f232af548 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Wed, 6 May 2026 03:47:25 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@cbc228f0f683189a325773e41cb7b284a88f9c42 --- .openclaw-sync/source.json | 4 ++-- docs/.i18n/glossary.zh-CN.json | 8 ++++++++ docs/help/troubleshooting.md | 34 ++++++++++++++++++++++++++++++++++ docs/install/docker.md | 8 ++++++++ docs/tools/plugin.md | 28 ++++++++++++++++++++++++++++ docs/uk/tools/skills.md | 1 + docs/zh-CN/tools/skills.md | 1 + 7 files changed, 82 insertions(+), 2 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index eb80d78f9..74fb4d42c 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "f4a63940cc6d82bbe650f97a2b339b17eeae950e", - "syncedAt": "2026-05-06T03:36:50.788Z" + "sha": "cbc228f0f683189a325773e41cb7b284a88f9c42", + "syncedAt": "2026-05-06T03:45:21.830Z" } diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index 05284fc38..98af41ede 100644 --- a/docs/.i18n/glossary.zh-CN.json +++ b/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": "插件清单" diff --git a/docs/help/troubleshooting.md b/docs/help/troubleshooting.md index 1781865e8..fb50dd24e 100644 --- a/docs/help/troubleshooting.md +++ b/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 diff --git a/docs/install/docker.md b/docs/install/docker.md index 07f65e125..5f7f62b1b 100644 --- a/docs/install/docker.md +++ b/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. + diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index 50e253370..2876b1865 100644 --- a/docs/tools/plugin.md +++ b/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 diff --git a/docs/uk/tools/skills.md b/docs/uk/tools/skills.md index 6dc7d3bc1..b58e3bac1 100644 --- a/docs/uk/tools/skills.md +++ b/docs/uk/tools/skills.md @@ -74,6 +74,7 @@ OpenClaw завантажує навички з цих джерел, **від н - Задайте `agents.list[].skills: []`, щоб навичок не було. - Непорожній список `agents.list[].skills` є **остаточним** набором для цього агента - він не обʼєднується зі значеннями за замовчуванням. - Ефективний список дозволів застосовується до побудови промптів, виявлення slash-команд навичок, синхронізації sandbox і знімків навичок. + diff --git a/docs/zh-CN/tools/skills.md b/docs/zh-CN/tools/skills.md index 3c817d5ea..de85ee64c 100644 --- a/docs/zh-CN/tools/skills.md +++ b/docs/zh-CN/tools/skills.md @@ -74,6 +74,7 @@ Codex CLI 原生的 `$CODEX_HOME/skills` 目录不属于这些 OpenClaw 技能 - 设置 `agents.list[].skills: []` 表示没有技能。 - 非空的 `agents.list[].skills` 列表是该智能体的**最终**集合——它不会与默认值合并。 - 有效允许列表会应用于提示构建、技能斜杠命令发现、沙箱同步和技能快照。 +