Snapshot — OpenClaw Backup & Restore

Encrypted backup and restore for the ~/.openclaw agent folder.
Backups are GPG-encrypted, chunked for GitHub's 100MB file limit, and pushed to a private repo.

How it works

• - backup — tar.gz → GPG encrypt → split into ≤95MB chunks → push to GitHub
• restore — clone repo → pick version → reassemble chunks → verify checksum → decrypt → extract
• setup — install GPG, clone/init the GitHub transport repo

Each backup version lives in its own folder with a manifest:
CODEBLOCK0

Last 10 backups are kept; older ones are auto-deleted.

Prerequisites

Before running any command, verify:

1. 1. GPG is installed. If not: INLINECODE1
2. Credentials are configured (see below)
3. Setup has been run at least once on this workspace: INLINECODE2

Providing credentials

The scripts need these values: BACKUP_PASSWORD, GITHUB_PAT, GITHUB_USERNAME, and optionally REPO_NAME (defaults to openclaw-transport).

Provide them via any of these methods (checked in this order):

1. 1. OpenClaw's env file (recommended): Add to ~/.openclaw/.env:

   BACKUP_PASSWORD=your-strong-password
   GITHUB_PAT=ghp_xxxxxxxxxxxxxxxxxxxx
   GITHUB_USERNAME=YourGitHubUsername
   REPO_NAME=openclaw-transport
   

1. 2. Skill-local env file: Copy env-example.txt to .env in this skill's directory and fill in values. Useful for standalone usage outside OpenClaw.

1. 3. Shell environment: Export the variables in your shell profile.

Commands

All scripts live in the scripts/ subdirectory of this skill.

Take a backup

python3 <skill-path>/scripts/backup.py

Restore a backup

Run setup (first time or new workspace)

python3 <skill-path>/scripts/setup.py

Typical workflows

Always run setup.py before backup or restore. It's idempotent (safe to run every time) and ensures GPG is installed, the transport repo exists, and the local repo is synced with GitHub. This prevents issues like missing repos, stale local state, or remotely deleted backups not being reflected locally.

"Back up my agent"

1. 1. Run INLINECODE13
2. Run INLINECODE14
3. Report the timestamp and size to the user

"Restore my agent" or "Load the latest backup"

1. 1. Run INLINECODE15
2. Run INLINECODE16
3. Tell the user it's done and suggest restarting: INLINECODE17

"Show me available backups"

1. 1. Run INLINECODE18
2. Run INLINECODE19
3. Present the version list to the user

"Set up backups on this new workspace"

1. 1. Confirm the user has a .env file with credentials (help them create one from env-example.txt if not)
2. Run INLINECODE22

"Restore a specific version"

1. 1. Run INLINECODE23
2. Run python3 <skill-path>/scripts/restore.py --list to show available versions
3. Ask the user which timestamp they want
4. Run INLINECODE25

Important notes

• - All .env files are excluded from backups — both ~/.openclaw/.env (OpenClaw root secrets) and the skill's own .env. Credentials never end up in encrypted archives.
• The transport repo (~/openclaw-transport/) lives outside .openclaw and is not backed up.
• The skill scripts themselves are backed up as part of .openclaw.
• WhatsApp sessions are excluded (workspace-specific). User must reconnect after restore.
• After restoring, the user should restart their agent: INLINECODE32