openclaw-backup-restore

intent

snapshot and migrate your complete openclaw setup (config, agents, flows, skills, credentials, memory, workspace) as a single portable .tar.gz archive. use this when you need to backup your entire openclaw home directory for disaster recovery, migrate to a new machine, or version your setup. on restore, any existing ~/.openclaw gets timestamped and preserved before replacement, so your previous state is never lost.

inputs

environment variables and flags:

• OPENCLAW_HOME: path to openclaw directory. defaults to ~/.openclaw. can be overridden with --home flag.
• BACKUP_DIR: output directory for archives. defaults to ~/openclaw-backups. can be overridden with --output flag.
• BACKUP_GPG_RECIPIENT: email or GPG key ID for encryption. triggers encryption if set. can be overridden with --encrypt <recipient> flag.
• GPG_PASSPHRASE: optional passphrase if using GPG encryption (for non-interactive mode).

external tools:

• bash (v4+)
• tar
• gzip
• gpg (optional, for encrypted backups)

archive files:

• backup archive path (filename): openclaw-backup-YYYY-MM-DD_HHMMSS.tar.gz or .tar.gz.gpg if encrypted.

preconditions:

• openclaw installation must exist at OPENCLAW_HOME (for backup).
• backup archive must exist and be readable (for restore or verify).
• user must have write permissions to BACKUP_DIR (for backup) or to parent of OPENCLAW_HOME (for restore).
• sufficient disk space for archive (rough estimate: size of ~/.openclaw directory).

procedure

backup workflow

1. resolve directories: read OPENCLAW_HOME env var or use default ~/.openclaw. read BACKUP_DIR env var or use default ~/openclaw-backups. create BACKUP_DIR if it does not exist.

2. check openclaw exists: verify OPENCLAW_HOME is a readable directory. if not, exit with error "openclaw home not found at $OPENCLAW_HOME".

3. warn if openclaw running: attempt to detect running openclaw process (e.g., ps aux | grep openclaw). if found, print warning "openclaw appears to be running. database state may be dirty. consider stopping it before backup." do not block.

4. check sensitive file disclosure: if identity/device-auth.json exists in OPENCLAW_HOME, inform user "backup includes identity/device-auth.json which contains auth tokens. keep backups secure."

5. generate timestamp: create timestamp in format YYYY-MM-DD_HHMMSS (e.g., 2026-05-24_120000). use this for archive filename.

6. create archive: run tar czf $BACKUP_DIR/openclaw-backup-$TIMESTAMP.tar.gz -C ~ .openclaw/ to archive entire ~/.openclaw directory. input: OPENCLAW_HOME directory. output: $BACKUP_DIR/openclaw-backup-$TIMESTAMP.tar.gz.

7. optionally encrypt: if --encrypt flag or BACKUP_GPG_RECIPIENT env var is set, encrypt archive with gpg: gpg --encrypt --recipient $RECIPIENT $ARCHIVE.tar.gz. output: $ARCHIVE.tar.gz.gpg. delete unencrypted .tar.gz after encryption succeeds.

8. report results: print archive filename, full path, file size, and file count (use tar tzf to count entries). example: "backup complete: openclaw-backup-2026-05-24_120000.tar.gz (245 MB, 1243 files)".

restore workflow

1. validate archive path: accept archive filename or full path as input. verify file exists and is readable. if not found, exit with error "backup archive not found: $ARCHIVE".

2. check gzip integrity: run gzip -t $ARCHIVE (or gzip -t <(gpg --decrypt $ARCHIVE.gpg) if .gpg extension). if gzip test fails, exit with error "archive is corrupted".

3. check path traversal: list archive contents with tar tzf $ARCHIVE (or via gpg decrypt pipe). scan for paths containing .. or leading /. if found, exit with error "archive contains suspicious path traversal".

4. resolve target directory: read --home flag or OPENCLAW_HOME env var. default to ~/.openclaw. this is the target restore location.

5. warn if target exists: if target directory exists and is non-empty, print warning "~/.openclaw already exists. it will be backed up as ~/.openclaw-backup-$TIMESTAMP before restore." if user does not pass --force flag, prompt "continue? (y/n)". exit if user declines.

6. preserve existing state: if target directory exists, rename it to ~/.openclaw-backup-$TIMESTAMP where timestamp is current time. this preserves the previous state.

7. optionally decrypt: if archive has .gpg extension, decrypt with gpg --decrypt $ARCHIVE.gpg > $ARCHIVE.tar.gz (or use --output flag). use GPG_PASSPHRASE env var if available for non-interactive mode.

8. extract archive: run tar xzf $ARCHIVE.tar.gz -C ~ to extract to home directory. this creates or overwrites ~/.openclaw/. input: archive file. output: ~/.openclaw/ directory with all contents.

9. fix permissions: set chmod 700 on sensitive subdirectories: credentials/, secrets/, identity/, memory/. set chmod 600 on any .json files in those directories. example: find ~/.openclaw/credentials -type d -exec chmod 700 {} \;.

10. verify extraction: run test -d ~/.openclaw && echo "restore successful". count restored files with find ~/.openclaw -type f | wc -l.

11. report results: print summary "restore complete: $FILECOUNT files extracted to ~/.openclaw". if old state was preserved, print "previous state backed up to ~/.openclaw-backup-$TIMESTAMP".

list workflow

1. resolve backup directory: read BACKUP_DIR env var or default to ~/openclaw-backups.

2. check directory exists: if BACKUP_DIR does not exist, print "no backups found" and exit.

3. list archives: run ls -lh $BACKUP_DIR/*.tar.gz $BACKUP_DIR/*.tar.gz.gpg 2>/dev/null | awk '{print $9, $5, $6, $7, $8}' to list all backup files with size and date.

4. handle empty results: if no archives found, print "no backups found in $BACKUP_DIR".

5. report results: print table with columns: filename, size, date. example output:

   openclaw-backup-2026-05-24_120000.tar.gz       245 MB   May 24 12:00
   openclaw-backup-2026-05-25_150000.tar.gz.gpg   248 MB   May 25 15:00
   

verify workflow

1. accept archive path: take archive filename or full path as input.

2. validate file: check file exists and is readable (same as restore step 1).

3. test gzip integrity: run gzip -t $ARCHIVE (or decrypt first if .gpg). print "archive integrity: OK" or "archive integrity: FAILED".

4. list top-level contents: run tar tzf $ARCHIVE | head -20 to show first 20 entries. print "archive contains:" followed by list.

5. count files: run tar tzf $ARCHIVE | wc -l to count total entries. print "total entries: $COUNT".

6. report results: print summary including integrity status, file count, and sample of top-level paths.

decision points

• if openclaw is running during backup: warn user that database state may be dirty (sqlite journals may be in-flight), but do not block backup. user can choose to stop openclaw first.

• if --encrypt flag or BACKUP_GPG_RECIPIENT is set: encrypt archive with gpg. if gpg is not installed, exit with error "gpg not found. install with brew install gnupg or use unencrypted backup".

• if restore target (~/.openclaw) already exists: check --force flag. if --force not set, prompt user for confirmation. if confirmed, preserve existing state by renaming to ~/.openclaw-backup-$TIMESTAMP. if not confirmed, exit without restoring.

• if archive is .tar.gz.gpg: auto-detect gpg encryption from file extension. if GPG_PASSPHRASE env var is set, use it for non-interactive decryption. if not set and gpg requires passphrase, prompt user interactively.

• if archive fails gzip integrity test: exit immediately with error. do not attempt to extract corrupted archive.

• if path traversal detected in archive: exit immediately with error. do not extract.

• if BACKUP_DIR does not exist and user runs backup: create BACKUP_DIR automatically.

• if BACKUP_DIR does not exist and user runs list: print "no backups found" instead of creating directory.

output contract

backup success:

• file created at $BACKUP_DIR/openclaw-backup-$TIMESTAMP.tar.gz (or .tar.gz.gpg if encrypted).
• file is readable and passes gzip -t integrity test.
• file size reported in bytes and human-readable format (e.g., "245 MB").
• file count reported (number of files and directories archived).
• timestamp is valid format YYYY-MM-DD_HHMMSS.

restore success:

• ~/.openclaw/ directory exists with full directory structure intact.
• all subdirectories (agents/, flows/, skills/, credentials/, secrets/, identity/, etc.) are present.
• credentials/, secrets/, identity/ directories have chmod 700 permissions.
• file permissions preserved from original backup (tar handles this by default).
• if old state was preserved, ~/.openclaw-backup-$TIMESTAMP directory exists.
• stdout reports file count extracted and target location.

list success:

• stdout prints table of all .tar.gz and .tar.gz.gpg files in BACKUP_DIR.
• each row includes filename, file size (human-readable), and modification date.
• if no backups exist, stdout prints "no backups found in $BACKUP_DIR".

verify success:

• stdout prints gzip integrity status ("OK" or "FAILED").
• stdout prints list of top-level archive paths (first 20 entries).
• stdout prints total file count in archive.

outcome signal

• backup: user receives confirmation message with archive filename, size, and file count. archive file is immediately usable for restore or transfer to another machine.

• restore: openclaw starts with full config, agents, skills, credentials, and workspace intact. user can verify by checking ~/.openclaw/ directory exists and contains expected subdirectories. if old state was backed up, user sees message with timestamp and can recover if needed.

• list: user sees table of available backups and can choose which to restore.

• verify: user confirms archive integrity before attempting restore, reducing risk of corrupted restore.

• error cases: script exits with non-zero exit code and prints error message to stderr. user can diagnose issue and retry.

credits: skill authored by vbrunotech (clawhub).