OpenClaw Part 5: Backup, Restore & Maintenance

You've spent four tutorials building an AI monitoring pipeline — agent personality, SSH security, diagnostic scripts, Matrix integration, model tuning. If the SSD dies tomorrow, how much of that can you get back?

This tutorial answers that question. OpenClaw has a built-in backup command that captures your agent's entire state. We'll create a backup, verify it, wipe everything, and restore from scratch — proving it actually works.

Prerequisites

• Completed Parts 1-4 (full pipeline working)
• SSH access to the OpenClaw machine
• Somewhere to store the backup off-machine (NAS, USB, another server)

What the Backup Covers

The built-in openclaw backup create captures the entire ~/.openclaw/ directory tree:

~/.openclaw/
├── openclaw.json          config (model, gateway, channels, hooks)
├── .env                   secrets and API keys
├── exec-approvals.json    tool permissions
├── workspace/             personality (IDENTITY.md, USER.md), memory, scripts
├── credentials/           Matrix tokens, OAuth
├── agents/                session history
├── plugins/               installed plugins
├── cron/                  scheduled tasks (morning brief, etc.)
├── canvas/                dashboard data
└── (memory, subagents, devices, identity, logs)

The archive also includes a manifest.json that records the resolved source paths and archive layout — useful for understanding what went where during restore.

What the Backup Does NOT Cover

These are system-level files that live outside ~/.openclaw/:

These are all documented in earlier parts of the series. If you need to rebuild from scratch, follow the relevant steps from Parts 1-2. The SSH key on the Proxmox side (authorized_keys) survives independently — you just need to regenerate the private key and update it.

Part 1: Creating the Backup

Step 1: Create the Backup Directory and Run the Backup

mkdir -p ~/backups

openclaw backup create --output ~/backups --verify

The --verify flag validates the archive immediately after creation. You'll get a timestamped .tar.gz in ~/backups/.

Step 2: Check the Archive

ls -lh ~/backups/

Step 3: Inspect the Contents

See what's inside the archive:

tar -tzf ~/backups/*openclaw-backup*.tar.gz | head -20

Note the path structure — the archive uses nested directories like <timestamp>-openclaw-backup/payload/posix/home/username/.openclaw/.... This matters during restore.

Step 4: Verify Independently

You can verify any archive at any time:

openclaw backup verify ~/backups/*openclaw-backup*.tar.gz

Step 5: Copy Off-Machine

The backup is useless if it dies with the machine:

scp ~/backups/*openclaw-backup*.tar.gz user@your-nas:/path/to/backups/

Part 2: Proving the Restore

A backup you haven't tested is a backup you don't have.

Step 6: Record the Current State

Before destroying anything, snapshot what "working" looks like:

echo "OpenClaw version: $(openclaw --version 2>&1)"

echo "Workspace files:" && ls ~/.openclaw/workspace/

openclaw cron list

ssh proxmox diagnostics-index 2>&1 | head -3

Save this output — it's what you're restoring to.

Step 7: Wipe Everything

Stop the gateway:

systemctl --user stop openclaw-gateway

Delete the entire OpenClaw state:

rm -rf ~/.openclaw

Verify it's gone:

ls ~/.openclaw/ 2>&1 || echo "State wiped"

Everything is gone. Config, personality, memory, credentials, cron jobs — all deleted.

Step 8: Restore from Backup

Extract the backup archive to a staging directory:

mkdir -p /tmp/openclaw-restore

tar -xzf ~/backups/*openclaw-backup*.tar.gz -C /tmp/openclaw-restore

Check the manifest to understand the layout:

cat /tmp/openclaw-restore/*/manifest.json | python3 -m json.tool

Copy the payload to your home directory. The archive mirrors the original absolute path under payload/posix/:

ARCHIVE_DIR=$(ls -d /tmp/openclaw-restore/*openclaw-backup*)
cp -a "$ARCHIVE_DIR/payload/posix/home/"*"/.openclaw" ~/

Step 9: Verify the Restore

Start the gateway:

systemctl --user start openclaw-gateway

Wait a few seconds for it to initialize:

sleep 5

Run the same checks from Step 6:

echo "OpenClaw version: $(openclaw --version 2>&1)"

echo "Workspace files:" && ls ~/.openclaw/workspace/

openclaw cron list

Compare to Step 6. Config, workspace files, cron jobs, and credentials should all be back.

Step 10: End-to-End Pipeline Test

The ultimate proof. Stop nginx and let the full pipeline run:

pct exec 150 -- systemctl stop nginx

If the investigation report lands in your Matrix Investigations room, the restore is complete. Everything works — config, credentials, Matrix tokens, webhook handling, SSH access, diagnostic scripts.

After verifying:

pct exec 150 -- systemctl start nginx

Clean up the staging directory:

rm -rf /tmp/openclaw-restore

Useful Backup Options

Config only — skip workspace, credentials, and everything else. Just the config file:

openclaw backup create --only-config --output ~/backups

Good for quick snapshots before changing settings.

Skip workspace — if your workspace has large files and you only need config + credentials:

openclaw backup create --no-include-workspace --output ~/backups

Dry run — see what would be backed up without creating the archive:

openclaw backup create --dry-run

Maintenance Reference

Updating OpenClaw

Always back up first:

openclaw backup create --output ~/backups --verify

Then update and run the post-update migration:

openclaw update

openclaw doctor

systemctl --user restart openclaw-gateway

Rotating SSH Keys

Generate a new key:

ssh-keygen -t ed25519 -C "openclaw-agent -- rotated" \
  -f ~/.ssh/id_ed25519_proxmox_monitor -N ""

Update the authorized_keys entry on Proxmox with the new public key (keep the restrict,command=,from= prefix from Part 2). Then test:

ssh proxmox diagnostics-index

Model Cleanup

After the Part 4 shootout, remove unused models to free disk:

ollama rm qwen3.5:9b

ollama rm gpt-oss:20b

ollama rm qwen3.5:27b-q8_0

ollama rm qwen3.5:122b-a10b

Keep whatever you're running in production. Models aren't in the backup (they're 173GB+) — faster to ollama pull than to back up and restore.

Summary

OpenClaw's built-in backup captures the full agent state — config, credentials, workspace, cron jobs, session history, exec approvals. One command to create, one command to verify. Restoration is manual cp from the extracted archive since there's no restore subcommand yet.

What it doesn't cover: SSH keys, systemd services, and GPU config. These are system-level files documented in Parts 1-2. If you're starting from a dead machine, follow Parts 1-2 for the system setup, then restore the OpenClaw backup on top.

The key takeaway: back up before every update, copy the archive off-machine, and test the restore at least once. A backup you haven't tested is a backup you don't have.

In Part 6, we add Caddy and Pi-hole for HTTPS — fixing the Element Web service worker warnings and making the whole setup production-ready.