OpenClaw Backup

Complete backup and restore solution for OpenClaw configuration and data.

Quick Start

Create a backup

python3 scripts/backup.py

Creates a timestamped backup in ~/.openclaw/backups/

Push to GitHub (recommended)

cd ~/.openclaw/backups
git add *.tar.gz
git commit -m "备份：$(date +%Y-%m-%d)"
git push

List backups

python3 scripts/list_backups.py

Restore from backup

python3 scripts/restore.py <backup-file>

What Gets Backed Up

Configuration:

✅ openclaw.json - Main configuration file
✅ Agent configurations (auth profiles, settings)

Workspace:

✅ AGENTS.md, SOUL.md, USER.md, IDENTITY.md
✅ MEMORY.md, TOOLS.md, HEARTBEAT.md
✅ memory/ directory - All memory files

Skills:

✅ Custom skills (openclaw-config, skill-publisher, openclaw-backup)
❌ System skills (not backed up, can be reinstalled)

Metadata:

✅ Backup timestamp and version info
✅ Contents manifest

Usage

Create a backup with custom name

python3 scripts/backup.py --name "before-update"

Output: openclaw-backup-before-update-20260301-153000.tar.gz

Create backup in custom directory

python3 scripts/backup.py --output-dir ~/my-backups

List backups with details

python3 scripts/list_backups.py

Shows:

Backup name and size
Creation date
Contents (config, agents, workspace, skills)
Full path

Restore from backup

python3 scripts/restore.py ~/.openclaw/backups/openclaw-backup-20260301-153000.tar.gz

Safety features:

Confirms before overwriting
Creates backup of current config (openclaw.json.before-restore)
Shows what will be restored

GitHub Integration

Setup (one-time)

Create a private GitHub repository for backups:

cd ~/.openclaw/backups
git init
gh repo create openclaw-backups --private --description "OpenClaw 配置备份（私密）" --source=. --remote=origin --push

Backup workflow with GitHub

# 1. Create backup
python3 scripts/backup.py --name "before-update"

# 2. Push to GitHub
cd ~/.openclaw/backups
git add *.tar.gz
git commit -m "备份：$(date +%Y-%m-%d) - before-update"
git push

Restore from GitHub

# 1. Pull latest backups
cd ~/.openclaw/backups
git pull

# 2. Restore
python3 scripts/restore.py ~/.openclaw/backups/<backup-file>.tar.gz

Common Workflows

Before making major changes

# Create a backup
python3 scripts/backup.py --name "before-agent-changes"

# Push to GitHub (recommended)
cd ~/.openclaw/backups && git add *.tar.gz && git commit -m "Before agent changes" && git push

# Make your changes
# ...

# If something goes wrong, restore
python3 scripts/restore.py ~/.openclaw/backups/openclaw-backup-before-agent-changes-*.tar.gz

Regular backups

# Daily backup
python3 scripts/backup.py --name "daily-$(date +%A)"

# Weekly backup
python3 scripts/backup.py --name "weekly-$(date +%U)"

Migrate to new machine

# On old machine
python3 scripts/backup.py --name "migration"

# Copy backup file to new machine
scp ~/.openclaw/backups/openclaw-backup-migration-*.tar.gz newmachine:~/

# On new machine
python3 scripts/restore.py ~/openclaw-backup-migration-*.tar.gz
openclaw gateway restart

Backup Structure

openclaw-backup-20260301-153000.tar.gz
└── openclaw-backup-20260301-153000/
    ├── backup-metadata.json
    ├── openclaw.json
    ├── agents/
    │   ├── main/
    │   │   └── agent/
    │   └── project-manager/
    │       └── agent/
    ├── workspace/
    │   ├── AGENTS.md
    │   ├── SOUL.md
    │   ├── USER.md
    │   ├── MEMORY.md
    │   └── memory/
    └── skills/
        ├── openclaw-config/
        ├── skill-publisher/
        └── openclaw-backup/

What's NOT Backed Up

Sessions:

Session history (.jsonl files)
Session state (sessions.json)
Reason: Can be large, usually not needed for restore

Credentials:

Sensitive authentication data
Reason: Security - should be reconfigured manually

System Skills:

Built-in skills from OpenClaw installation
Reason: Can be reinstalled, reduces backup size

Logs:

Gateway logs
Reason: Not needed for configuration restore

Automation

Cron job for daily backups

# Add to crontab
0 2 * * * cd ~/.openclaw/workspace/skills/openclaw-backup && python3 scripts/backup.py --name "auto-daily" >> ~/.openclaw/backup.log 2>&1

Cleanup old backups

# Keep only last 7 backups
cd ~/.openclaw/backups
ls -t openclaw-backup-*.tar.gz | tail -n +8 | xargs rm -f

Troubleshooting

Backup fails:

Check disk space: df -h ~/.openclaw
Check permissions: ls -la ~/.openclaw
Check if OpenClaw is running: openclaw gateway status

Restore fails:

Verify backup file exists and is not corrupted
Check if you have write permissions
Stop OpenClaw before restoring: openclaw gateway stop

Backup too large:

Sessions are not backed up by default
Consider excluding large files manually
Compress old backups: gzip -9 old-backup.tar

Best Practices

Backup before changes - Always create a backup before modifying configuration
Regular backups - Set up automated daily/weekly backups
Test restores - Periodically test that backups can be restored
Keep multiple versions - Don't delete old backups immediately
Off-site backups - Copy important backups to another machine or cloud storage
Document changes - Use descriptive backup names

Security Notes

Backups may contain sensitive information (bot tokens, API keys)
Store backups securely
Don't share backups publicly
Consider encrypting backups for sensitive deployments

Reference

Backup location: ~/.openclaw/backups/
Backup format: .tar.gz (compressed tar archive)
Naming: openclaw-backup-[name-]YYYYMMDD-HHMMSS.tar.gz