OpenClaw moves fast. A small npm publish can land a new tool API, rename an internal table, or deprecate a flag you've been relying on since 0.9. If you type npm i -g openclaw@latest on production without preparation you'll probably break at least one of your agents. This guide documents the workflow I've used since 0.12.4 (mid-2023) to update OpenClaw to the latest version safely.

1. Why updating OpenClaw requires a plan

OpenClaw isn't a thin client; it's an event router, a browser automation layer, a memory store, a cron scheduler, and—in most setups—a handful of shell scripts you've duct-taped around it. Every update touches at least one of those surfaces. Since v1.0 the team promises semantic versioning, but minor releases (1.x) still ship breaking changes when a security patch or upstream dependency forces their hand. Translation: you need a repeatable upgrade path, backups, and rollback.

2. Snapshot your memory and config before touching anything

2.1 Export persistent memory

The default memory store lives in ~/.openclaw/memory.sqlite. Starting with 1.3.0 you can export it as JSON:

openclaw memory dump --output ~/backups/openclaw-memory-$(date +%F).json

If you're on <1.3.0 grab the SQLite file directly:

cp ~/.openclaw/memory.sqlite ~/backups/memory-$(date +%F).sqlite

2.2 Back up the runtime config

All agent definitions live in ~/.openclaw/agents/. I commit that folder into a private Git repo:

cd ~/.openclaw && git add agents && git commit -m "pre-upgrade backup $(date +%F)"

If you consider that overkill, at least create a tarball:

tar czf ~/backups/openclaw-agents-$(date +%F).tgz -C ~/.openclaw agents

2.3 Snapshot your database if you switched drivers

Some installations point OPENCLAW_DB_URL to Postgres or MySQL. Use your usual tooling (pg_dump, mysqldump, psql \copy) to grab a snapshot. Schema migrations are the #1 cause of breakage in major upgrades.

3. Read the release notes like your cluster depends on it

Release notes live on GitHub under github.com/openclaw/openclaw/releases. I skim until I hit a heading named BREAKING. If that string isn't in the notes I still search the diff for remove and deprecated. Two minutes here saves an hour later.

  • Check minimum Node requirement. As of 1.4.0 OpenClaw needs Node 22. If you're on Debian stable you're probably stuck on 20 and need nvm install 22 first.
  • Look for migrations. Anything touching memory tables triggers a new openclaw doctor migrate step.
  • Scan integration APIs. If Telegram changed its webhook format you'll need to tweak the agent config.

4. Update path A: npm / npx installations

4.1 Dry-run in a throwaway directory

Create an isolated folder, install the new version, and fire up a sample agent:

mkdir /tmp/oc-upgrade-test && cd /tmp/oc-upgrade-test npm init -y npm install openclaw@latest npx openclaw quickstart --name smoke

If openclaw quickstart finishes and you can chat with the dummy agent via web UI, you're likely safe.

4.2 Upgrade globally or per project

Most folks install OpenClaw globally because the daemon finds plugins in $PATH. To update:

npm i -g openclaw@latest

If you pin a specific version in package.json (CI/CD workflows) bump it manually:

npm install openclaw@1.4.2 --save-exact

4.3 Verify the binary version

openclaw --version # expect 1.4.2

5. Update path B: git clone / source installations

Some production setups clone main or a tagged release, build with pnpm, and deploy via systemd. The workflow:

  1. Commit local changes (you really shouldn't hack core but we all do).
  2. Switch to the tag you want, e.g. git checkout v1.4.2.
  3. Reinstall dependencies: pnpm install --frozen-lockfile.
  4. Rebuild: pnpm run build.
  5. Restart the service: systemctl restart openclaw.

If you track main add git pull --ff-only and accept that you're basically on nightly.

6. Run the migration helper: openclaw doctor migrate

Since 1.2.0 the CLI ships a pseudo-ORM (Drizzle) with auto-generated SQL migrations. After upgrading, run:

openclaw doctor migrate

You'll see output similar to:

🔍 Checking schema... current=1 target=3 📄 Applying 2 migrations ... 002_add_agent_scope.sql ✔️ Migrations applied successfully

If you hit a foreign key error cancel immediately and rollback (see section 8). The docs say migrations are idempotent but I've bricked a test instance twice.

7. Smoke-test the upgraded agent

I keep two scripts for this.

7.1 Health check script

#!/usr/bin/env bash set -euo pipefail curl -sf http://localhost:5920/health | jq .ok | grep true

The gateway exports /health since 1.3.1. Run the script; non-zero exit means rollback.

7.2 Integration ping

Send a “ping” message from Slack and assert the agent replies within 2s. I automate using Slack's Web API:

# send curl -s -H "Authorization: Bearer $SLACK_TOKEN" \ -F channel=C123456 \ -F text="upgrade ping $(date +%s)" \ https://slack.com/api/chat.postMessage # receive (poll once) resp=$(curl -s -H "Authorization: Bearer $SLACK_TOKEN" "https://slack.com/api/conversations.history?channel=C123456&limit=1") jq -e '.messages[0].text | test("pong")' <<< "$resp"

8. Roll back fast when things go sideways

8.1 npm rollback

npm i -g openclaw@1.3.5 # last known good

The CLI keeps no internal state beyond ~/.openclaw, so downgrading the binary usually works. If you ran migrations that altered schema, restore your backup SQLite file:

systemctl stop openclaw cmp ~/backups/memory-2024-04-15.sqlite ~/.openclaw/memory.sqlite systemctl start openclaw

8.2 git rollback

cd /opt/openclaw git checkout v1.3.5 pnpm install --frozen-lockfile pnpm run build systemctl restart openclaw

If databases changed you're stuck. Re-import the snapshot you took in section 2.

8.3 Confirm rollback health

Run the same health check from section 7. If everything passes, file an issue on GitHub with the label regression. The maintainers triage fast when breakages come with logs.

9. Automating safe OpenClaw updates

After the third manual upgrade I scripted the flow in GitHub Actions. Sketch:

name: openclaw-upgrade on: schedule: - cron: "0 3 * * 1" # every Monday 03:00 UTC jobs: test-upgrade: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install Node 22 uses: actions/setup-node@v4 with: node-version: 22 - run: npm install -g openclaw@latest - run: openclaw doctor migrate --dry-run - run: ./ci/smoke.sh

If the smoke script fails the workflow stops. I get a Slack DM via actions/slack and hold off production updates. Works 9/10 times.

10. Practical takeaway

Updating OpenClaw safely boils down to three habits: treat your memory store like a database, read the release notes with suspicion, and practice rollback until it's boring. Automate what you can, but keep a manual playbook for the 3 a.m. outage. Your agents—and your future self—will thank you.