openclaw-backup-restore

Backup or restore your entire OpenClaw setup including config, agents, skills, credentials, and workspace as a timestamped portable .tar.gz archive.

OpenClaw Backup & Restore Skill

Snapshot and migrate your complete OpenClaw setup — config, agents, flows, skills, credentials, memory, and workspace — as a single portable archive.

What this skill does

• Backup: Archives the entire ~/.openclaw/ directory into a timestamped .tar.gz (or .tar.gz.gpg if encrypted) — no files excluded.
• Restore: Extracts an archive back into ~/.openclaw/, preserving directory structure and permissions, so OpenClaw works immediately after extraction.
• List: Shows available backup archives in the configured output directory.
• Verify: Validates a backup archive's integrity before restore.

Use this skill when the user says:

• "backup my openclaw setup"
• "migrate openclaw to my new machine"
• "snapshot my openclaw config"
• "restore openclaw from backup"
• "what backups do I have?"

What is backed up

The entire ~/.openclaw directory — every file and subdirectory — is included in the archive. No exclusions. The restored machine gets an exact copy of the original, and OpenClaw works immediately without any missing configuration, credentials, skills, or state.

See references/paths.md for details on sensitive paths and restore-time permissions.

Workflow

Backup

1. Resolve the OpenClaw home directory (OPENCLAW_HOME, defaults to ~/.openclaw).
2. Resolve the output directory (BACKUP_DIR, defaults to ~/openclaw-backups).
3. Archive the full ~/.openclaw directory into a timestamped .tar.gz.
4. Optionally encrypt with GPG: --encrypt flag or BACKUP_GPG_RECIPIENT env var.
5. Print the archive path and size.

Restore

1. Validate the archive (non-empty, valid gzip, no path traversal).
2. Warn if ~/.openclaw already exists and prompt for confirmation (or use --force).
3. Optionally decrypt if .gpg extension detected.
4. Extract to ~/.openclaw/ with --strip-components=0.
5. Fix permissions on sensitive files (credentials/, secrets/, identity/).
6. Print a summary of restored paths.

List

Print all .tar.gz and .tar.gz.gpg files in BACKUP_DIR with size and date.

Verify

Run gzip -t on the archive and list its top-level contents without extracting.

Scripts

Script	Purpose
scripts/backup.sh	Create a backup archive
scripts/restore.sh	Restore from a backup archive

Usage examples

bash

# Create a backup in ~/openclaw-backups/
bash scripts/backup.sh

# Backup to a custom directory
bash scripts/backup.sh --output /Volumes/USB/backups

# Backup with GPG encryption
bash scripts/backup.sh --encrypt [e-mail]

# List available backups
bash scripts/backup.sh --list

# Verify a backup without restoring
bash scripts/restore.sh --verify openclaw-backup-2026-05-24_120000.tar.gz

# Restore (will prompt before overwriting)
bash scripts/restore.sh openclaw-backup-2026-05-24_120000.tar.gz

# Restore without confirmation prompt
bash scripts/restore.sh --force openclaw-backup-2026-05-24_120000.tar.gz

# Restore to a custom openclaw home
bash scripts/restore.sh --home /opt/openclaw openclaw-backup-2026-05-24_120000.tar.gz

Migration workflow (old machine → new machine)

1. On the old machine: run bash scripts/backup.sh — copy the .tar.gz to the new machine.
2. On the new machine: install OpenClaw binary, then run bash scripts/restore.sh <archive>.
3. OpenClaw will start with your full config, agents, skills, credentials, and workspace intact.

Security notes

• credentials/ and secrets/ contain sensitive API keys. Keep backups in a secure location.
• Use --encrypt with a GPG key for backups stored in cloud storage or on shared drives.
• The restore script sets chmod 700 on sensitive directories automatically.

Guardrails

• Never extract archives with path components that escape ~/.openclaw/ (path traversal check).
• Always show the archive size and file count after backup so the user can sanity-check completeness.
• If OpenClaw is running during backup, warn the user — SQLite databases may be in a dirty state.
• Do not backup identity/device-auth.json without informing the user it contains auth tokens.