fix(plugins): support root-owned bundled runtime deps

docs/cli/doctor.md

@@ -42,6 +42,7 @@ Notes:
 - `--fix` (alias for `--repair`) writes a backup to `~/.openclaw/openclaw.json.bak` and drops unknown config keys, listing each removal.
 - State integrity checks now detect orphan transcript files in the sessions directory and can archive them as `.deleted.<timestamp>` to reclaim space safely.
 - Doctor also scans `~/.openclaw/cron/jobs.json` (or `cron.store`) for legacy cron job shapes and can rewrite them in place before the scheduler has to auto-normalize them at runtime.
+- Doctor repairs missing bundled plugin runtime dependencies without requiring write access to the installed OpenClaw package. For root-owned npm installs or hardened systemd units, set `OPENCLAW_PLUGIN_STAGE_DIR` to a writable directory such as `/var/lib/openclaw/plugin-runtime-deps`.
 - Doctor auto-migrates legacy flat Talk config (`talk.voiceId`, `talk.modelId`, and friends) into `talk.provider` + `talk.providers.<provider>`.
 - Repeat `doctor --fix` runs no longer report/apply Talk normalization when the only difference is object key order.
 - Doctor includes a memory-search readiness check and can recommend `openclaw configure --section model` when embedding credentials are missing.

docs/install/updating.md

@@ -54,6 +54,25 @@ pnpm add -g openclaw@latest
 bun add -g openclaw@latest
 ```
 
+### Root-owned global npm installs
+
+Some Linux npm setups install global packages under root-owned directories such as
+`/usr/lib/node_modules/openclaw`. OpenClaw supports that layout: the installed
+package is treated as read-only at runtime, and bundled plugin runtime
+dependencies are staged into a writable runtime directory instead of mutating the
+package tree.
+
+For hardened systemd units, set a writable stage directory that is included in
+`ReadWritePaths`:
+
+```ini
+Environment=OPENCLAW_PLUGIN_STAGE_DIR=/var/lib/openclaw/plugin-runtime-deps
+ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
+```
+
+If `OPENCLAW_PLUGIN_STAGE_DIR` is not set, OpenClaw uses `$STATE_DIRECTORY` when
+systemd provides it, then falls back to `~/.openclaw/plugin-runtime-deps`.
+
 ## Auto-updater
 
 The auto-updater is off by default. Enable it in `~/.openclaw/openclaw.json`: