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

docs(updating): group advanced npm topics in AccordionGroup

Browse Source
This commit is contained in:
Vincent Koc
2026-04-26 21:28:48 -07:00
parent 8cd68487d9
commit ebbc7dcfeb
1 changed files with 28 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
docs/install/updating.md
View File

@@ -101,52 +101,33 @@ pnpm add -g openclaw@latest
bun add -g openclaw@latest
```
### Global npm installs and runtime dependencies
### Advanced npm install topics
OpenClaw treats packaged global installs as read-only at runtime, even when the
global package directory is writable by the current user. Bundled plugin runtime
dependencies are staged into a writable runtime directory instead of mutating the
package tree. This keeps `openclaw update` from racing with a running gateway or
local agent that is repairing plugin dependencies during the same install.
<AccordionGroup>
<Accordion title="Read-only package tree">
OpenClaw treats packaged global installs as read-only at runtime, even when the global package directory is writable by the current user. Bundled plugin runtime dependencies are staged into a writable runtime directory instead of mutating the package tree. This keeps `openclaw update` from racing with a running gateway or local agent that is repairing plugin dependencies during the same install.
Some Linux npm setups install global packages under root-owned directories such
as `/usr/lib/node_modules/openclaw`. OpenClaw supports that layout through the
same external staging path.
Some Linux npm setups install global packages under root-owned directories such as `/usr/lib/node_modules/openclaw`. OpenClaw supports that layout through the same external staging path.
</Accordion>
<Accordion title="Hardened systemd units">
Set a writable stage directory that is included in `ReadWritePaths`:
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
```
```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`. The repair step treats that stage as an OpenClaw-owned local package root and ignores user npm prefix and global settings, so global-install npm config does not redirect bundled plugin dependencies into `~/node_modules` or the global package tree.
</Accordion>
<Accordion title="Disk-space preflight">
Before package updates and bundled runtime-dependency repairs, OpenClaw tries a best-effort disk-space check for the target volume. Low space produces a warning with the checked path, but does not block the update because filesystem quotas, snapshots, and network volumes can change after the check. The actual npm install, copy, and post-install verification remain authoritative.
</Accordion>
<Accordion title="Bundled plugin runtime dependencies">
Packaged installs keep bundled plugin runtime dependencies out of the read-only package tree. On startup and during `openclaw doctor --fix`, OpenClaw repairs runtime dependencies only for bundled plugins that are active in config, active through legacy channel config, or enabled by their bundled manifest default. Persisted channel auth state alone does not trigger Gateway startup runtime-dependency repair.
If `OPENCLAW_PLUGIN_STAGE_DIR` is not set, OpenClaw uses `$STATE_DIRECTORY` when
systemd provides it, then falls back to `~/.openclaw/plugin-runtime-deps`.
The repair step treats that stage as an OpenClaw-owned local package root and
ignores user npm prefix/global settings, so global-install npm config does not
redirect bundled plugin dependencies into `~/node_modules` or the global package
tree.
Before package updates and bundled runtime-dependency repairs, OpenClaw tries a
best-effort disk-space check for the target volume. Low space produces a warning
with the checked path, but does not block the update because filesystem quotas,
snapshots, and network volumes can change after the check. The actual npm
install, copy, and post-install verification remain authoritative.
### Bundled plugin runtime dependencies
Packaged installs keep bundled plugin runtime dependencies out of the read-only
package tree. On startup and during `openclaw doctor --fix`, OpenClaw repairs
runtime dependencies only for bundled plugins that are active in config, active
through legacy channel config, or enabled by their bundled manifest default.
Persisted channel auth state alone does not trigger Gateway startup
runtime-dependency repair.
Explicit disablement wins. A disabled plugin or channel does not get its
runtime dependencies repaired just because it exists in the package. External
plugins and custom load paths still use `openclaw plugins install` or
`openclaw plugins update`.
Explicit disablement wins. A disabled plugin or channel does not get its runtime dependencies repaired just because it exists in the package. External plugins and custom load paths still use `openclaw plugins install` or `openclaw plugins update`.
</Accordion>
</AccordionGroup>
## Auto-updater
@@ -210,7 +191,9 @@ openclaw doctor
openclaw gateway restart
```
Tip: `npm view openclaw version` shows the current published version.
<Tip>
`npm view openclaw version` shows the current published version.
</Tip>
### Pin a commit (source)
@@ -232,6 +215,6 @@ To return to latest: `git checkout main && git pull`.
## Related
- [Install Overview](/install) — all installation methods
- [Doctor](/gateway/doctor) — health checks after updates
- [Migrating](/install/migrating) — major version migration guides
- [Install overview](/install): all installation methods.
- [Doctor](/gateway/doctor): health checks after updates.
- [Migrating](/install/migrating): major version migration guides.