Safe Backup

Backup OpenClaw state directory and workspace with security best practices.

⚠️ Security Warnings

• Backup may contain sensitive data - review before sharing
• If uploading to GitHub - use a private repository and consider encryption
• auth-profiles.json is EXCLUDED - after restore, you must re-authenticate
• This script does NOT automatically push to any remote

Quick Start

1. Run Backup

~/.openclaw/skills/safe-backup/scripts/backup.sh

2. Check Output

Backup file: /tmp/safe-backup-20260223.tar.gz  (Linux)
Backup file: /var/folders/xx/.../safe-backup-20260223.tar.gz  (macOS)
Backup file: C:\Users\xxx\AppData\Local\Temp\safe-backup-20260223.tar.gz  (Windows)

3. Store Securely

See "Storage Options" below.

Cross-Platform Migration

Platform Support

| Platform | Status | Requirements |

|----------|--------|--------------|

| Linux | ✅ Fully supported | Native bash |

| macOS | ✅ Fully supported | Native bash |

| Windows (Git Bash) | ✅ Supported | Git for Windows |

| Windows (WSL) | ✅ Supported | WSL Ubuntu/Debian |

| Windows (Native CMD) | ❌ Not supported | Requires bash |

Important Notes for Migration

1. Temporary Directory Auto-Detection

The script automatically detects the appropriate temp directory for each platform:

| Platform | Temp Directory | Environment Variable |

|----------|----------------|---------------------|

| Linux | /tmp | - |

| macOS | /var/folders/xx/... | $TMPDIR |

| Windows (Git Bash) | C:\Users\xxx\AppData\Local\Temp | $TEMP / $TMP |

2. rsync Dependency

The script uses rsync for efficient file copying:

• Linux/macOS: ✅ Built-in
• Windows: ⚠️ Git Bash includes rsync

If rsync is not available, the script will fail. For Windows without Git Bash, you need to install rsync separately (e.g., via MSYS2 or Cygwin).

3. Path Separators

The script uses Unix-style forward slashes (/). This works in:

• Linux ✅
• macOS ✅
• Git Bash ✅
• WSL ✅

Native Windows CMD uses backslashes (\) and won't work without modifications.

4. Home Directory Detection

The script uses $HOME environment variable:

• Linux: /home/username
• macOS: /Users/username
• Windows (Git Bash): C:\Users\username

This works correctly in all supported platforms.

Migration Checklist

When migrating from one platform to another:

• [ ] Run backup on source machine
• [ ] Transfer backup file securely (USB, encrypted cloud, etc.)
• [ ] Install Git Bash (Windows) or ensure bash is available
• [ ] Install OpenClaw on target machine
• [ ] Run restore script
• [ ] Re-authenticate all services (credentials are not backed up)

Platform-Specific Notes

Windows (Git Bash)

# Run from Git Bash, NOT CMD or PowerShell
~/.openclaw/skills/safe-backup/scripts/backup.sh

If you get "rsync not found", install Git for Windows with all optional Unix tools.

macOS

# Native bash is available
~/.openclaw/skills/safe-backup/scripts/backup.sh

Temp directory will be in $TMPDIR (e.g., /var/folders/xx/...).

Linux

# Native bash is available
~/.openclaw/skills/safe-backup/scripts/backup.sh

Temp directory will be /tmp.

What Gets Backed Up

✅ Included (Safe to Backup)

| Directory | Contents |

|-----------|----------|

| ~/.openclaw/ | OpenClaw configuration |

| ~/.openclaw/workspace/ | Agent workspace files |

| agents/ | Agent definitions |

| skills/ | Installed skills |

| memory/ | Memory files |

| hooks/ | Custom hooks |

❌ Excluded (Sensitive - Not Backed Up)

| Pattern | Reason |

|---------|--------|

| *.log | Log files |

| .log. | Log rotation files |

| sessions.json | Session data |

| logs/ | Log directory |

| auth-profiles.json | API tokens & credentials |

| .env | Environment variables |

| .pem, .key | TLS/SSH keys |

| credentials.json | Stored credentials |

| api-keys.json | API keys |

| sessions/ | Runtime sessions |

| browser/ | Browser cache |

| canvas/ | Canvas cache |

| media/ | Temporary media files |

| backups/ | Backup directory itself |

| delivery-queue/ | Runtime queue |

| devices/ | Device cache |

| subagents/ | Runtime subagents |

| completions/ | Auto-completion cache |

| *.bak | Backup files |

| *.save | Save files |

| update-check.json | Update check cache |

Complete Workflow

Use Cases

| Scenario | Recommended Solution | Description |

|----------|---------------------|-------------|

| Regular Backup | Local encrypted storage | Weekly backup, store in encrypted local directory |

| Migrate to New Machine | Local tarball + USB | Transfer between machines, avoid network transmission |

| Cloud Disaster Recovery | Private GitHub repo | Private repo + encryption, for offsite backup |

| Server Environment | rsync to backup server | Automated periodic sync, suitable for production |

Phase 1: Backup

# Step 1: Run backup
~/.openclaw/skills/safe-backup/scripts/backup.sh

# Step 2: Find output path (check the last line of output)
# The script will display: "Backup file: /path/to/safe-backup-YYYYMMDD.tar.gz"

# Step 3: Verify backup contents
tar -tzf "$(ls -t /tmp/safe-backup-*.tar.gz | head -1)" | head -20

# Or use the exact path shown in output:
# tar -tzf /tmp/safe-backup-20260223.tar.gz | head -20

Phase 2: Storage

Choose one:

Option A: Local Encrypted Storage (Recommended)

# Find the latest backup file
BACKUP_FILE=$(ls -t /tmp/safe-backup-*.tar.gz | head -1)

# Create encrypted archive
openssl enc -aes-256-cbc -salt -in "$BACKUP_FILE" -out ~/backups/safe-backup-$(date +%Y%m%d).tar.gz.enc

# Enter a strong password when prompted

# Delete unencrypted backup
rm "$BACKUP_FILE"

Option B: Private GitHub Repository

# One-time setup: Create private repo on GitHub

# Find the latest backup file
BACKUP_FILE=$(ls -t /tmp/safe-backup-*.tar.gz | head -1)

# Clone your private repo
git clone https://github.com/YOUR_USERNAME/safe-backup.git ~/safe-backup

# Extract backup
mkdir -p ~/safe-backup/$(date +%Y-%m-%d)
tar -xzf "$BACKUP_FILE" -C ~/safe-backup/$(date +%Y-%m-%d)/

# Commit and push
cd ~/safe-backup
git add .
git commit -m "Backup $(date +%Y-%m-%d)"
git push origin main

# Delete local copy
rm -rf ~/safe-backup
rm "$BACKUP_FILE"

Option C: rsync to Remote Server

# Example: sync to remote server
rsync -avz --delete \
  --exclude='*.log' \
  --exclude='sessions.json' \
  ~/.openclaw/ user@backup-server:/path/to/backups/

Phase 3: Restore

Step 1: Locate Backup

# If encrypted
openssl enc -aes-256-cbc -d -in ~/backups/safe-backup-20260223.tar.gz.enc -out /tmp/safe-backup.tar.gz

# If plain tarball, find the file
# Check your backup location (USB, cloud download, etc.)
cp /path/to/your/backup/safe-backup-20260223.tar.gz /tmp/

Step 2: Stop Gateway

systemctl --user stop openclaw-gateway

Step 3: Restore Files

# Determine temp directory based on platform
if [[ -n "$TMPDIR" ]]; then
    TEMP_DIR="$TMPDIR"
elif [[ -n "$TEMP" ]]; then
    TEMP_DIR="$TEMP"
elif [[ -n "$TMP" ]]; then
    TEMP_DIR="$TMP"
else
    TEMP_DIR="/tmp"
fi

# Extract to temporary location
mkdir -p "$TEMP_DIR/restore"
tar -xzf "$TEMP_DIR/safe-backup.tar.gz" -C "$TEMP_DIR/restore"

# Restore state directory
cp -r "$TEMP_DIR/restore/state/"* ~/.openclaw/

# Restore workspace (if needed)
cp -r "$TEMP_DIR/restore/workspace/"* ~/.openclaw/workspace/

Step 4: Re-authenticate

Because auth-profiles.json was excluded, you must re-configure:

# Edit config to add authentication
openclaw config edit

# Or manually create auth-profiles.json
nano ~/.openclaw/agents/main/agent/auth-profiles.json

Required re-configuration:

• Telegram bot token
• Discord bot token
• Feishu credentials
• Any other API keys

Step 5: Restart Gateway

systemctl --user start openclaw-gateway

# Verify
openclaw status

Environment Variables

| Variable | Default | Description |

|----------|---------|-------------|

| OPENCLAW_STATE_DIR | $HOME/.openclaw | OpenClaw state directory |

| OPENCLAW_WORKSPACE_DIR | $HOME/.openclaw/workspace | Workspace directory |

Example:

OPENCLAW_STATE_DIR=/data/openclaw ~/.openclaw/skills/safe-backup/scripts/backup.sh

Troubleshooting

"State directory not found"

# Check if OpenClaw is installed
ls -la ~/.openclaw

"Permission denied"

# Run with appropriate permissions
chmod +x ~/.openclaw/skills/safe-backup/scripts/backup.sh

"rsync not found" (Windows)

# Install Git for Windows with Unix tools, or use WSL
# Alternatively, install rsync via MSYS2:
# pacman -S rsync

Restore Fails

# Check backup integrity
tar -tzf /path/to/your/backup.tar.gz

# If encrypted, verify password
openssl enc -aes-256-cbc -d -in backup.enc -o /dev/null

Best Practices

1. Backup regularly - at least weekly
2. Test restore - periodically verify backups work
3. Store offsite - keep backup in different location
4. Encrypt - never store unencrypted backups in cloud
5. Document - keep notes on what was re-configured after restore