Deployment Upgrade Runbook

Production-style upgrade checklist and rollback plan

Page scope (operations runbook niche): This page is for operator workflows (preflight, rollout, smoke tests, rollback). For config migration details use Upgrading / Migrating. For release history use Releases.

Pre-upgrade gate

  1. Create a backup: openclaw backup create.
  2. Capture current version and health: openclaw --version, openclaw doctor.
  3. Verify maintenance window and owner comms (channel impact, rollback owner).
  4. Confirm host resources (disk, memory, network) and dependency versions.

Upgrade execution

Execution sequence
openclaw update
openclaw doctor --fix
openclaw gateway restart
openclaw doctor

If migration-related warnings appear, continue with Upgrading / Migrating and provider-specific guides.

Post-upgrade smoke tests

  • Gateway health: service starts cleanly, no auth/pairing regressions.
  • Tool path: run one safe tool call and verify expected response.
  • Channel path: send one test message and confirm delivery + reply.
  • Provider path: test at least one model/provider call relevant to your production flow.

v2026.5.18+ additional checks

If you upgraded to v2026.5.18 or newer, add these checks to the smoke list:

  • Node runtime: node -v shows 22.19+ before openclaw update completes.
  • Restart latency: openclaw gateway restart reaches ready without prolonged sidecar stalls (compare to pre-upgrade if you log restart traces).
  • Mac app (if used): open Settings panes (permissions, voice, skills, cron); confirm menu bar app version matches Gateway.
  • Browser automation (if used): one snapshot with a pending dialog; answer with browser dialog --dialog-id if your flow depends on modals.
  • Android Talk Mode (if used): paired node on 5.18+; one short realtime voice turn with transcript on device (Android guide).
  • Plugins (if used): openclaw plugins validate on any custom tool plugins; spot-check openclaw plugins build in CI if you ship plugins.

Migration checklist: Upgrading → v2026.5.18 · Release highlights: Releases → v2026.5.18

Rollback plan

  1. Stop active automation if behavior is unstable.
  2. Restore known-good backup/config.
  3. Restart gateway and re-run smoke tests.
  4. Document incident scope and root cause before retrying upgrade.

Docker and managed hosts

On Docker, pin image tags before upgrade and keep the previous tag for rollback. Managed vendors may auto-update—ask whether you can defer upgrades during incidents. Always export config (openclaw backup create) before vendor-side maintenance windows.

Communication template

Before upgrading, notify channel users: expected downtime (usually gateway restart only), whether pairing must be re-approved, and who to ping if replies stop. After smoke tests pass, send an all-clear with the new openclaw --version string for support tickets.

Related