How to Back Up and Restore Your OpenClaw Setup (v2026.3.8+)

Why Your OpenClaw State Is Worth Backing Up

OpenClaw stores more than just a config file. A full installation accumulates: your gateway configuration (openclaw.json), agent instruction files (AGENTS.md, MEMORY.md), conversation session history, cron job definitions, installed skill metadata, credentials and token files, and plugin state. If you're running a production deployment, this data represents weeks or months of tuning, iteration, and real usage.

Before v2026.3.8, creating a reliable backup meant knowing the file layout under ~/.openclaw/ and manually archiving the right directories — easy to get wrong, easy to forget subdirectories, and no built-in way to verify the result was actually usable.

The New Commands: openclaw backup

OpenClaw v2026.3.8 ships two new CLI commands that make this reliable:

• openclaw backup create — creates a timestamped archive of your OpenClaw state
• openclaw backup verify — validates an existing archive for integrity and completeness

Creating a Backup

The basic command:

openclaw backup create

This creates a .tar.gz archive named with an ISO timestamp for easy sorting — for example, openclaw-backup-2026-03-17T14-32-00.tar.gz. The archive includes:

• Your full ~/.openclaw/ directory structure
• Gateway configuration files
• Agent workspaces and memory files
• Session history
• Cron job definitions
• Installed plugin metadata
• A manifest file recording what was included and the OpenClaw version at backup time

Config-Only Backup

For a smaller archive that only captures your configuration — not session history or memory files — use:

openclaw backup create --only-config

This produces a much smaller archive: just the files you'd need to recreate your setup on a new machine or restore after a fresh install. Useful for committing to a private git repo, attaching to a support request, or quick snapshots before config changes.

Excluding the Workspace

If you have large workspace files (documents, downloaded content, large memory stores), skip them:

openclaw backup create --no-include-workspace

Verifying a Backup

Before you ever need to use a backup in a crisis, it's worth verifying it while everything is calm:

openclaw backup verify openclaw-backup-2026-03-17T14-32-00.tar.gz

Verification checks:

• Archive integrity (not corrupted or truncated)
• Manifest presence and version metadata
• Payload completeness against the manifest
• Presence of key files (config, credentials)

A passing verify gives you confidence the archive is actually usable — not just a file that exists but can't be extracted.

When to Create Backups

OpenClaw now automatically prompts you to create a backup before destructive operations like openclaw doctor --fix or major config rewrites. But for production deployments, these manual triggers matter too:

• Before every OpenClaw update — particularly for major version bumps or releases with breaking changes in the changelog
• Before changing your AI model provider — model switches can affect session history compatibility
• Before adding or removing channels — channel reconfiguration changes how sessions are routed and stored
• Before plugin updates — plugin state changes can be difficult to roll back without a clean backup
• Before moving to a new server — a verified backup is what makes a VPS migration reliable
• On a regular schedule — weekly or daily automated backups for any deployment you rely on

Automating Backups with a Cron Job

For production, the cleanest approach is automated backups on a schedule. Add this to your system crontab:

# Daily backup at 2am, keep 7 days
0 2 * * * openclaw backup create --only-config -o /backups/openclaw/ && find /backups/openclaw/ -name "*.tar.gz" -mtime +7 -delete

Pair this with offsite storage — S3, Backblaze B2, or SFTP to a separate server — and you have a production-grade backup strategy that requires zero manual intervention.

Restoring from a Backup

Restoration is currently a manual process. The recommended procedure:

1. Stop the gateway: openclaw gateway stop
2. Preserve the current state: mv ~/.openclaw ~/.openclaw.old
3. Extract the archive: tar -xzf openclaw-backup-2026-03-17T14-32-00.tar.gz -C ~/
4. Start the gateway: openclaw gateway start
5. Verify it's healthy: openclaw gateway status --deep
6. Once confirmed working: rm -rf ~/.openclaw.old

Keeping the .old directory around until you've verified the restore means you always have a fallback if something doesn't look right.

What Backups Don't Cover

Backup and restore is a recovery tool, not a security tool. If you've had a security incident — credentials exposed, unauthorized access — restoring a backup restores the compromised state. In that scenario, you need a security audit alongside the restore, not just a file replacement. Backups protect against data loss and failed updates; they don't protect against security compromises.