Tools
Update
By OpenClaw update driver for pnpm/npm drift, plugin cleanup, service regeneration, and post-update health checks
Install
OpenClaw plugin install metadataREADME
# OpenClaw Update
`openclaw-up` is an opinionated update driver for OpenClaw installations that use pnpm global packages, managed user plugins, and systemd user services.
It was built after repeated update failures where package-manager state, plugin install metadata, and regenerated service units drifted apart. The script coordinates those pieces into one auditable update flow with snapshots, health checks, logs, and recovery hooks.
## Problem Statement
OpenClaw updates are not always a single-package operation on long-lived hosts.
On a long-lived OpenClaw instance, the runtime can have three moving parts that drift independently:
- OpenClaw core installed through pnpm global packages.
- User plugin dependencies under `~/.openclaw/npm`.
- systemd user service units whose `ExecStart` paths can point at pnpm store paths from the previous OpenClaw version.
This produced a few practical failure modes:
- `openclaw --version` could disagree with the version recorded by pnpm if an old shim or service unit still referenced an older store path.
- Services could restart successfully while still running an older OpenClaw build.
- Plugin install metadata could report version drift after npm/pnpm package updates.
- Failed or deprecated plugin installs, especially old Brave plugin remnants quarantined under `node_modules/.ignored`, could poison later plugin scans.
- Gateway and node could race each other during plugin staging, causing flaky startup and missing runtime tools.
- A manual update run could look successful but leave Telegram, WhatsApp, the agent harness, or memory search broken.
The core lesson: OpenClaw updates need to refresh the package tree, plugin metadata, service units, runtime processes, and post-update health state as one transaction-like operation.
## Solution Architecture
`bin/openclaw-up` performs the update in ordered stages:
1. Capture a pre-flight snapshot under `~/.openclaw/up-snapshots`.
2. Resolve the latest OpenClaw version and install it via `pnpm add -g --allow-build=openclaw`.
3. Verify the pnpm global version matches what `openclaw --version` actually invokes.
4. Clean quarantined plugin leftovers from `~/.openclaw/npm/node_modules/.ignored`.
5. Update user plugin dependencies under `~/.openclaw/npm`.
6. Refresh OpenClaw plugin install metadata with `openclaw plugins update --all`.
7. Stop gateway and node services.
8. Reinstall gateway and node service units so generated systemd files point at the current pnpm store path.
9. Start services in order: Bitwarden unlock helper, gateway, then node.
10. Verify health using `openclaw status --all` as the primary contract.
11. Check for harness registration errors in the gateway journal.
12. Run the OpenClaw instance memory sanity check when present.
13. Capture post-update status, audit output, plugin doctor output, config diff, and summary metadata.
14. Prune old local update snapshots.
The script deliberately keeps the old recovery hook (`~/.local/bin/openclaw-recover.sh`) as a last resort, but treats normal status-based verification as the primary path.
## Usage
```bash
bin/openclaw-up
```
Useful modes:
```bash
bin/openclaw-up --dry-run
bin/openclaw-up --check
bin/openclaw-up --skip-recovery
bin/openclaw-up --skip-plugin-update
bin/openclaw-up --no-restart
bin/openclaw-up --json-summary
```
Recommended production runbook:
1. Confirm the current baseline is healthy:
```bash
openclaw status --all
bin/openclaw-up --check
```
2. Take a hypervisor snapshot or equivalent host-level rollback point.
3. Run:
```bash
bin/openclaw-up
```
4. Confirm:
```bash
openclaw status --all
```
5. Send a real test message through the configured chat channel.
6. Keep the hypervisor snapshot for about 24 hours before deleting it.
## Health Contract
The script considers an update healthy when:
- gateway is reachable;
- gateway service is running;
- node service is running;
- Telegram is OK;
- WhatsApp is OK;
- channel credentials are available in the gateway runtime;
- at least one agent is active;
- gateway and node service descriptions match the current OpenClaw version;
- no harness registration errors appear in the restart window;
- `openclaw plugins doctor` reports no plugin issues;
- OpenClaw instance memory sanity passes when the local checker exists.
## Maintenance Guidelines
Review this script after each OpenClaw release that changes CLI commands, service installation, plugin staging, or status output.
When reviewing:
- Update `TESTED_AGAINST` only after a real update or `--check` pass succeeds on that OpenClaw version.
- Prefer `openclaw status --all` and `openclaw plugins doctor` over brittle journal greps.
- Keep dry-run side-effect free.
- Keep service restart order conservative: unlock helper, gateway, then node.
- Preserve the pnpm shim/version check; it catches stale global shims and stale systemd paths.
- Treat Brave plugin remnants under `.ignored` as disposable cleanup state, not a source of truth.
- Do not remove recovery support until repeated releases prove the plugin staging race is gone.
- Keep the memory sanity hook optional, because it is instance-specific.
- Avoid embedding secrets, hostnames that should not be public, or private config dumps in logs committed to this repo.
## Compatibility
Current tested OpenClaw version:
```text
2026.5.27
```
Current target platform:
```text
Linux systemd user services
pnpm global OpenClaw install
OpenClaw managed plugin tree at ~/.openclaw/npm
```
The script is intentionally Unix/Linux-oriented. macOS launchd or Windows task support would need separate service handling.
## License
MIT
tools
Comments
Sign in to leave a comment