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

1. Backup before changes - Always create a backup before modifying configuration
2. Regular backups - Set up automated daily/weekly backups
3. Test restores - Periodically test that backups can be restored
4. Keep multiple versions - Don't delete old backups immediately
5. Off-site backups - Copy important backups to another machine or cloud storage
6. 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