ClawHub

openclaw-backup-restore

Data & APIs

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

Install

openclaw skills install claw-home-dir-backup-restore

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

ScriptPurpose
scripts/backup.shCreate a backup archive
scripts/restore.shRestore from a backup archive

Usage examples

# 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 you@example.com

# 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.
More in Data & APIs