OpenClaw Update Procedure: Snapshot First, Then Upgrade

A practical update procedure for OpenClaw on my homelab: take the snapshot first, understand the release, upgrade, then verify the running gateway before calling it done.

OpenClaw is not a side package on this host. In my setup it runs Samantha, handles Telegram, launches tools, keeps sessions alive, loads plugins, and sits in the middle of my day-to-day operations.

The update command itself is simple. The service around it matters more. If the gateway does not restart cleanly, I do not just lose a CLI. I lose the assistant runtime, channel access, tool execution, and the context attached to active sessions.

This is the update routine I want to follow on the main OpenClaw VM. It is intentionally simple: create a rollback point, check the current state, read the release notes, upgrade, restart, and verify the system that is actually running.

The one non-negotiable rule

Before asking the assistant to update OpenClaw, take a Proxmox snapshot of the VM.

Not after reading half of the changelog. Not after the install has started. Before touching the package.

Most OpenClaw updates should be uneventful, and that is exactly why the process should stay boring. A snapshot gives me a clean rollback path if the gateway, config, plugins, or runtime state do not come back as expected.

Step 0: take the Proxmox snapshot

From the Proxmox UI:

1. Open the VM running OpenClaw.
2. Go to Snapshots.
3. Create a snapshot with an explicit name.

pre-openclaw-update-2026-05-04

Add a short description with the target version when you know it:

Before OpenClaw update to 2026.5.3-1

CLI equivalent:

qm snapshot <vmid> pre-openclaw-update-YYYY-MM-DD \
  --description "Before OpenClaw update"

If QEMU guest agent or filesystem quiescing is available, use it. If not, a normal VM snapshot is still far better than relying on memory after something has already changed.

Step 1: check the current state

Before updating, capture the state of the host and gateway:

openclaw --version
openclaw status
openclaw doctor --non-interactive

I want to know three things before the upgrade:

• which version is currently installed;
• whether the gateway is healthy before I touch it;
• whether doctor already sees config, plugin, session, or migration issues.

If OpenClaw is already unhealthy, I do not treat the update as the fix. First I understand the current failure. Otherwise the upgrade just adds another variable.

Step 2: read the changelog like an operator

Before installing anything, I ask the assistant to read the release notes and answer three specific questions:

1. What are the breaking changes?
2. Do we need to adapt anything in this setup?
3. Which new features are actually useful here?

The point is not to summarize every line. I care about operational impact:

• config keys that changed or became stricter;
• plugins that moved, were externalized, or need migration;
• new defaults affecting tools, channels, sandboxing, memory, or exec permissions;
• features worth enabling because they fit the homelab;
• doctor warnings that may matter more after the new version.

For the 2026.5.3-1 update, the useful summary was:

• no declared breaking change for this setup;
• stricter config behavior: invalid config now fails closed, and doctor --fix owns repair and migration;
• legacy sandbox registry cleanup to run with doctor --fix;
• new native file-transfer plugin, interesting later for safer node file operations;
• gateway startup and performance improvements, relevant on a host that had occasional event loop warnings;
• new /steer and /side commands, useful for long-running sessions and side questions.

If the answer to “do we need to adapt anything?” is yes, I either adapt first or write down the change clearly. I do not want to discover it after the gateway restart.

Step 3: check the target version

See what npm considers latest:

npm view openclaw version

Then compare it with the local CLI:

openclaw --version

This gives a clean before and after. It also makes the final verification less ambiguous.

Step 4: update the package

On this host, OpenClaw is installed globally via npm:

npm install -g openclaw@latest

Then verify the CLI:

openclaw --version

This confirms the package on disk. It does not prove the running gateway has switched to the new code yet.

Step 5: restart the gateway

Use OpenClaw’s gateway lifecycle command:

openclaw gateway restart

Then wait a few seconds and check:

openclaw gateway status

During restart, the old process may need a moment to drain active work. That is fine. What matters is the final service state.

Step 6: verify the running gateway, not just the CLI

This is the check that actually matters:

openclaw status

The healthy result should show:

• Update: up to date;
• Gateway: reachable;
• Gateway app: the new version;
• Gateway self: the new version;
• Gateway service: systemd installed, enabled, running;
• Channels: Telegram OK;
• Plugins: no errors.

After the 2026.5.3-1 update, the good state looked like this:

OpenClaw 2026.5.3-1
Gateway reachable
Gateway app 2026.5.3-1
Gateway service running
Telegram OK

That is the difference between “npm completed” and “the system is actually back online”.

If the gateway looks stuck

If the CLI reports the new version but openclaw status still shows the old gateway app version, inspect the running service:

ss -ltnp 'sport = :18789'
ps -eo pid,ppid,stat,lstart,cmd | grep -E 'openclaw.*gateway|dist/index.js gateway' | grep -v grep
systemctl --user status openclaw-gateway.service --no-pager -l
journalctl --user -u openclaw-gateway.service -n 120 --no-pager

If needed:

systemctl --user restart openclaw-gateway.service

Then re-run:

openclaw status

Step 7: run doctor after the update

Once the gateway is reachable:

openclaw doctor --non-interactive

If doctor reports safe migrations or cleanup:

openclaw doctor --fix

Recent OpenClaw versions are stricter about configuration. Invalid config now fails closed instead of being silently adjusted during startup. I prefer that behavior. It makes problems visible at the right time.

For me, doctor is part of the update procedure, not a separate maintenance task.

Step 8: smoke test what matters

For this environment, “the service is running” is not enough. I want a small functional test:

• send and receive a Telegram message;
• run a simple tool command through Samantha;
• check that sessions still load;
• check memory search if enabled;
• run heartbeat or cost tracking if configured;
• check node or browser integrations if they matter for the current setup.

For example:

python3 /home/pi/.openclaw/workspace/tools/cost-tracker.py

And Telegram health should show as OK in:

openclaw status

Where automation could go next

This procedure is still deliberately human-gated. I take the snapshot, I ask for the update, and I keep the rollback decision under control.

But technically, the automation could be pushed further. With the right Proxmox access, OpenClaw could let Samantha create the VM snapshot herself, record the current state, read the release notes, run the package update, restart the gateway, execute doctor, smoke test Telegram and tools, then report the final result.

That would turn the whole update into an assisted maintenance workflow instead of a manual checklist. The important part is not removing human oversight completely. It is making each step explicit, logged, reversible, and safe enough that the assistant can execute it without improvising.

The final checklist

• Proxmox snapshot exists.
• Current version recorded.
• openclaw status healthy before update.
• openclaw doctor --non-interactive checked.
• Release notes reviewed.
• Required adaptations identified.
• Package updated.
• Gateway restarted.
• Gateway app version matches CLI version.
• Telegram OK.
• Doctor clean, or warnings understood.
• Basic assistant and tool smoke test passed.

When all of that is green, the update is done.

Updated and verified.