Backup & Restore

ClawBook includes automated backups to protect your data. This guide covers backup configuration, manual backups, and restoration procedures.

Backup Overview

What's Backed Up

Component	Included	Size (typical)
Conversations	✅	50-500 MB
Configuration	✅	< 1 MB
User data	✅	10-50 MB
Integration sessions	✅	< 5 MB
System logs	❌	Not backed up
Temporary files	❌	Not backed up

Backup Tiers by Plan

Plan	Frequency	Retention	Storage
Standard	Weekly	2 backups	10 GB
Pro	Daily	7 backups	50 GB
Elite	Daily	30 backups	200 GB

Automated Backups

Backups run automatically based on your plan:

Viewing Backup Status

1. Go to Settings → Backups
2. See list of available backups:

Backup History
--------------
2026-01-30 03:00 UTC | 245 MB | ✅ Completed
2026-01-29 03:00 UTC | 243 MB | ✅ Completed
2026-01-28 03:00 UTC | 241 MB | ✅ Completed

Backup Schedule

Default backup time is 03:00 UTC. To change:

1. Settings → Backups → Schedule
2. Select preferred time (in your timezone)
3. Click Save

Backup Schedule:
  Time: 03:00 UTC
  Days: Daily (Pro/Elite) or Sunday (Standard)
  Retention: Based on plan

Manual Backups

Create on-demand backups before major changes:

Via Dashboard

1. Go to Settings → Backups
2. Click Create Backup Now
3. Enter description: "Before WhatsApp reconnect"
4. Click Start Backup

Via Command Line

# Create backup
clawbook-backup create --description "Pre-upgrade backup"

# List backups
clawbook-backup list

# Output:
# ID         Date                 Size    Description
# bk-001     2026-01-30 15:30    245 MB  Pre-upgrade backup
# bk-auto-29 2026-01-29 03:00    243 MB  Automated backup

Backup Contents

Full Backup Structure

backup-2026-01-30.tar.gz
├── database/
│   ├── conversations.sql
│   ├── users.sql
│   └── settings.sql
├── config/
│   ├── config.yaml
│   ├── integrations.yaml
│   └── prompts.yaml
├── sessions/
│   ├── whatsapp/
│   ├── telegram/
│   └── discord/
└── metadata.json

Metadata File

{
  "backup_id": "bk-001",
  "created_at": "2026-01-30T15:30:00Z",
  "version": "1.5.0",
  "size_bytes": 256901120,
  "components": ["database", "config", "sessions"],
  "checksum": "sha256:abc123..."
}

Restoring from Backup

Via Dashboard

1. Go to Settings → Backups
2. Find the backup you want to restore
3. Click ⋮ → Restore
4. Confirm by typing "RESTORE"
5. Wait for restoration (2-5 minutes)

warning

Restoration will overwrite current data. Create a backup first if needed.

Via Command Line

# List available backups
clawbook-backup list

# Restore specific backup
clawbook-backup restore bk-001

# Restore with confirmation skip (use carefully)
clawbook-backup restore bk-001 --yes

# Restore only specific components
clawbook-backup restore bk-001 --only database,config

Partial Restoration

Restore only what you need:

# Restore only conversations
clawbook-backup restore bk-001 --only database

# Restore only configuration
clawbook-backup restore bk-001 --only config

# Restore only WhatsApp session
clawbook-backup restore bk-001 --only sessions/whatsapp

Downloading Backups

Save backups locally for extra safety:

Via Dashboard

1. Settings → Backups
2. Click ⋮ → Download
3. Save the .tar.gz file

Via Command Line

# Download to current directory
clawbook-backup download bk-001

# Download to specific location
clawbook-backup download bk-001 --output /path/to/backup.tar.gz

# Via SCP
scp root@YOUR_VPS_IP:/var/backups/clawbook/bk-001.tar.gz ./

Uploading Backups

Restore from a downloaded backup:

Via Dashboard

1. Settings → Backups
2. Click Upload Backup
3. Select your .tar.gz file
4. Wait for upload and verification
5. Click Restore when ready

Via Command Line

# Upload backup file
clawbook-backup upload /path/to/backup.tar.gz

# Verify backup integrity
clawbook-backup verify bk-uploaded-001

# Restore uploaded backup
clawbook-backup restore bk-uploaded-001

External Backup Storage

Amazon S3

# /etc/openclaw/backup.yaml
external_storage:
  provider: s3
  bucket: my-clawbook-backups
  region: us-east-1
  access_key: AKIA...
  secret_key: xxxxx
  path_prefix: backups/
  upload_after_backup: true

Google Cloud Storage

external_storage:
  provider: gcs
  bucket: my-clawbook-backups
  project: my-project-id
  credentials_file: /etc/openclaw/gcs-key.json

Custom S3-Compatible

external_storage:
  provider: s3
  endpoint: https://s3.example.com
  bucket: backups
  access_key: xxx
  secret_key: xxx

Backup Encryption

Backups are encrypted by default:

encryption:
  enabled: true
  algorithm: AES-256-GCM
  key_source: derived  # From master password

Custom Encryption Key

# Set custom encryption key
clawbook-backup set-key

# Enter your encryption passphrase (remember this!)

danger

If you lose your encryption key, backups cannot be restored!

Disaster Recovery

Complete VPS Loss

If your VPS is completely lost:

1. Provision new ClawBook VPS
2. Install fresh ClawBook
3. Upload backup file
4. Restore from backup
5. Reconnect integrations (WhatsApp QR, etc.)

Recovery Time Objectives

Scenario	Recovery Time
Restore from dashboard	2-5 minutes
Restore from downloaded backup	10-15 minutes
Full VPS rebuild + restore	30-60 minutes

Backup Verification

Ensure backups are working:

# Verify backup integrity
clawbook-backup verify bk-001

# Output:
# ✅ Checksum valid
# ✅ All components present
# ✅ Database integrity OK
# ✅ Backup is restorable

Automated Verification

# /etc/openclaw/backup.yaml
verification:
  enabled: true
  frequency: weekly
  notify_on_failure: true
  notification_email: admin@example.com

Backup Notifications

Get notified about backup status:

1. Settings → Notifications → Backups
2. Enable:
   • ✅ Backup completed
   • ✅ Backup failed
   • ✅ Storage quota warning

notifications:
  backup_completed: email
  backup_failed: email, slack
  storage_warning_threshold: 80%

Troubleshooting

Backup Failed

Check logs:

tail -f /var/log/openclaw/backup.log

Common causes:

• Disk full
• Database locked
• Permission issues

Restore Failed

# Check restoration log
cat /var/log/openclaw/restore.log

# Try with verbose output
clawbook-backup restore bk-001 --verbose

Corrupted Backup

# Verify backup
clawbook-backup verify bk-001

# If corrupted, try previous backup
clawbook-backup restore bk-002

Best Practices

1. Test restores regularly - Don't wait for a disaster
2. Download backups offsite - Keep local copies
3. Use external storage - S3, GCS, etc.
4. Document your setup - So you can rebuild if needed
5. Monitor backup health - Enable notifications

Next Steps

• Upgrade/Downgrade - Change your plan
• Security Best Practices - Protect your data
• Troubleshooting - Get help