OpenClaw Backup and Restore: The Complete Operational Guide

An OpenClaw backup is one tar archive of your install directory (minus node_modules) plus your nginx config, shipped off the VPS daily by cron. That single archive captures your configuration, channel credentials, plugins, and conversation memory - everything needed to rebuild the instance on a fresh server in about 15 minutes. This guide covers the script, the automation, and the restore runbook.

Most people set up OpenClaw once, connect their channels, and never think about what happens when the VPS dies. Then it dies - a failed disk, a botched upgrade, a provider outage - and months of conversation memory and hours of channel verification work vanish. The fix takes 20 minutes to set up. Here it is.

What Actually Needs Backing Up?

The good news: OpenClaw keeps its state in one place. If you followed our VPS install guide, everything lives under /opt/openclaw:

• Configuration - config/openclaw.yaml holds your AI provider API keys, channel credentials (WhatsApp access tokens, Telegram bot tokens, webhook verify tokens), port settings, and agent configs. This is the single most important file on the server.
• Plugins and custom tools - the plugins/ directory, including any custom JavaScript tools you wrote under plugins/custom/. Community plugins installed via npm are re-fetched by npm install, but your own code is not.
• Conversation memory - if you run the memory plugin, its local vector store (SQLite-based) lives on the same VPS inside your OpenClaw directory. This is your assistant’s accumulated context - the thing you genuinely cannot recreate.

Outside the OpenClaw directory, two things are worth grabbing so a restore does not mean redoing server setup:

• nginx site config - /etc/nginx/sites-available/openclaw
• SSL certificates - /etc/letsencrypt (optional; Certbot can reissue them in a minute, but backing them up avoids rate-limit surprises during a stressful restore)

What you can skip: node_modules (rebuilt from the lockfile by npm install), PM2 itself (a one-line global install), and the OS. Anything reproducible from a command is not worth archiving.

One warning before we script this: because config/openclaw.yaml contains live API keys and channel tokens, your backup archive is a secret. Store it accordingly - encrypted at rest, never in a public bucket.

Step 1: Write the Backup Script

Create /opt/backup-openclaw.sh:

#!/usr/bin/env bash
set -euo pipefail

BACKUP_DIR="/var/backups/openclaw"
STAMP=$(date +%Y%m%d-%H%M)
ARCHIVE="$BACKUP_DIR/openclaw-$STAMP.tar.gz"

mkdir -p "$BACKUP_DIR"

tar -czf "$ARCHIVE" \
  --exclude="node_modules" \
  -C /opt openclaw \
  -C /etc/nginx/sites-available openclaw

# keep 14 days of history, prune the rest
find "$BACKUP_DIR" -name "openclaw-*.tar.gz" -mtime +14 -delete

echo "Backup written: $ARCHIVE ($(du -h "$ARCHIVE" | cut -f1))"

Make it executable and run it once:

chmod +x /opt/backup-openclaw.sh
sudo /opt/backup-openclaw.sh

With node_modules excluded, a typical archive is a few megabytes - small enough to keep weeks of daily history without thinking about disk space.

Step 2: Automate It with Cron

A backup you have to remember to run is a backup that stops happening in week three. Add a cron entry:

sudo crontab -e

# Daily OpenClaw backup at 04:15 server time
15 4 * * * /opt/backup-openclaw.sh >> /var/log/openclaw-backup.log 2>&1

Daily is the right default. Your worst case becomes 24 hours of lost conversation memory - annoying, not catastrophic. If your instance runs business workflows, bump it to every 6 hours (15 */6 * * *).

Check /var/log/openclaw-backup.log after the first scheduled run. A cron job that silently fails is worse than no cron job, because you believe you are covered.

Step 3: Get Backups Off the VPS

This is the step most people skip, and it is the one that matters. A backup sitting on the same disk as the data it protects dies with that disk. Two solid options:

Object storage with rclone (Backblaze B2, Cloudflare R2, or S3). At OpenClaw archive sizes this costs pennies per month:

sudo apt-get install -y rclone
rclone config   # one-time interactive setup for your provider

Then append one line to the backup script:

rclone copy "$ARCHIVE" remote:openclaw-backups/

rsync to another host you already control (a home server, another VPS):

rsync -az /var/backups/openclaw/ backup-user@other-host:/backups/openclaw/

Either way, verify the remote copy exists after the first automated run. Trust the pipeline only after you have seen it work once.

How Do I Restore OpenClaw from a Backup?

Here is the runbook, in order. On a fresh Ubuntu 24.04 server (or the same one after a rebuild):

1. Install the runtime. OpenClaw requires Node.js 24:

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs nginx certbot python3-certbot-nginx
sudo npm install -g pm2

2. Clone OpenClaw and lay your state over it:

cd /opt
sudo git clone https://github.com/openclaw/openclaw.git
sudo tar -xzf /path/to/openclaw-YYYYMMDD-HHMM.tar.gz -C /opt
sudo chown -R $USER:$USER /opt/openclaw
cd /opt/openclaw
npm install

Extracting the archive restores your config/openclaw.yaml, plugins/, and memory store on top of the fresh clone. npm install rebuilds node_modules.

3. Restore nginx and SSL. Copy the archived nginx config back to /etc/nginx/sites-available/openclaw, symlink it into sites-enabled, then issue a certificate for your domain:

sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d ai.yourdomain.com

4. Start OpenClaw and persist it:

pm2 start npm --name "openclaw" -- start
pm2 startup
pm2 save
pm2 status   # expect: openclaw | online

Send a test message on your simplest channel (Telegram is ideal) and confirm a reply. If the instance starts but channels misbehave, our troubleshooting guide covers the usual suspects.

Test the Restore Before You Need It

An untested backup is a hope, not a plan. Once - just once - spin up the cheapest throwaway VPS your provider offers, run the runbook above against your latest archive, and confirm OpenClaw comes online with your config and memory intact. Then destroy the server. The rehearsal costs under an hour and answers the only question that matters: can you actually get your assistant back?

While you are at it, note how long the restore took. That number is your real recovery time, and it is much nicer to learn it on a calm afternoon than during an outage.

Migrating OpenClaw to a New VPS

Migration is just a restore with a DNS change, plus a few gotchas:

1. Run a fresh backup on the old VPS immediately before migrating, so you carry the latest conversation memory.
2. Restore onto the new VPS using the runbook above, but keep the old instance running.
3. Lower your DNS TTL ahead of time (300 seconds is fine), then point your domain at the new IP.
4. Re-verify webhook channels. This is the step that bites people. WhatsApp delivers messages to your HTTPS callback URL, and Meta re-checks it - the new instance must be online and reachable at the domain before webhook delivery resumes. If verification fails after the switch, re-save the webhook in the Meta Developer Console per our WhatsApp setup guide. Polling-based channels like Telegram follow automatically with no re-verification.
5. Watch both servers briefly. Until DNS propagates, some webhook traffic may still hit the old IP. Keep the old instance alive until the new one is answering messages, then shut it down.

Done carefully, total downtime is a few minutes of DNS propagation - and because you rehearsed the restore, none of it is guesswork.

The 20-Minute Insurance Policy

Script, cron entry, rclone remote, one rehearsed restore. That is the entire discipline, and it converts “the VPS died” from a data-loss event into a mild inconvenience. Set it up today, before the disk decides for you. And if you would rather have someone else own the whole lifecycle - backups, monitoring, and the restore path - that is exactly what our maintenance plans exist for.