If the rough week taught the OpenClaw community anything, it's that upgrade paths can hurt in ways that generic smoke tests don't catch. Clawback is a new open-source tool built specifically around that lesson.
It's an upgrade safety harness for OpenClaw installs. Before you run openclaw update, Clawback captures a baseline of your current install, rehearses the target version inside a sanitized container, compares behavior, and hands you a rollback plan — all before anything on your live host changes.
The Origin Story
The README is refreshingly honest about why this tool exists:
Clawback started after a real OpenClaw upgrade path hurt more than it should have. A working install moved from 2026.4.26 toward 2026.4.29, hit upgrade issues, then even 2026.4.26 stopped being a good recovery point. The setup eventually had to be manually rolled back to 2026.4.23.
That's the rough week in miniature. And it exposes the core problem: every OpenClaw install is different. Agents, channels, gateway auth, task history, workspace paths, systemd state, device links — all of it matters. A version that clears a generic smoke test can still wreck a specific personal setup.
Clawback gives you a repeatable way to find out before it's your live system on the line.
How It Works
The main flow is npm run suite:pre before upgrading and npm run suite:post after.
Pre-upgrade does three things: exports a sanitized fixture of your current install, captures a local baseline, and then runs the target version in a Docker or Podman container against that same-harness baseline. The container run compares gateway identity, scopes, command behavior, configured channels, and baseline drift. Hard errors block the upgrade. Warnings go to the report for your review.
If the container rehearsal passes, Clawback prints guarded update commands for you to review before running. The updater refuses to touch the host unless the container report matches the requested target and has zero hard errors.
Post-upgrade waits up to 120 seconds for the gateway to settle, then compares live health, channels, agents, and baseline drift against your pre-upgrade snapshot. If it reports errors, you have a rollback plan on hand.
One detail worth appreciating: the checks overlap on purpose. There's a local baseline (what's true on your host right now), a container baseline for the current OpenClaw version, and a container rehearsal for the target version — all compared against each other. That layering catches regressions the target introduces relative to a known-good containerized baseline, not just relative to abstract expectations.
Getting Started
Clawback is at v0.3.5 and Linux/POSIX-first (container rehearsal requires Docker or Podman):
git clone --depth 1 --branch v0.3.5 https://github.com/haishmg/Clawback.git clawback
cd clawback
npm install --ignore-scripts
node bin/clawback.js --help
To rehearse a specific OpenClaw version:
npm run suite:pre -- --target 2026.5.6
Review the reports, then apply if clean:
npm run upgrade:apply -- --target 2026.5.6 --report reports/container-rehearsal/run/report.json --yes
npm run suite:post
If post-upgrade validation fails, roll back:
npm run upgrade:rollback -- --plan reports/updates/<run>/rollback.json --yes
npm run suite:post
What It Checks
Clawback validates CLI availability, runtime/update metadata, gateway reachability, service state, configured channels, agents, workspace and session paths, cron/task commands, config validation, baseline drift, and host resource pressure.
Exit code 0 means no hard errors. Exit code 1 means errors were found. Exit code 2 means the guard itself failed (invalid arguments, etc.).
Each run writes three output files: report.json (machine-readable, secrets redacted), summary.md (human-readable findings and next steps), and report.html (an interactive dashboard with severity filters, search, expandable details, and timing bars).
The ClawHub Plugin
There's also a ClawHub plugin in the repo (packages/clawback-openclaw-plugin) that you can install locally:
openclaw plugins install packages/clawback-openclaw-plugin --link
openclaw plugins enable clawback
openclaw clawback commands --target 2026.5.6
The README notes it's pending publication to ClawHub — once that lands, install will be as simple as openclaw plugins install clawhub:clawback.
Caveats
Container rehearsal is a compatibility smoke test, not a full live-host clone. It doesn't exercise live channel auth, external workspace directories, task history, media, memory, or runtime caches. It won't send test messages to your chat channels. What it will catch is whether the target version can start cleanly, find your channels, respect your agents, and not drift on baseline behaviors — which is exactly what the rough week was breaking.
If you've been upgrading OpenClaw by crossing your fingers and running npm update, Clawback is worth adding to your workflow.
Source: github.com/haishmg/Clawback | HN discussion