openclaw-backup

What this skill does

# OpenClaw Backup Skill

Automated encrypted backup and restore for OpenClaw Agent workspace files using Claude Code.

## Overview

This skill provides three core functions:

1. **Upload Backup** - Encrypt and upload workspace files to soul-upload.com with auto-generated password
2. **Download Backup** - Download and decrypt backups from soul-upload.com using stored password
3. **Delete Backup** - Delete backups from remote storage

All backups use **AES-256-CBC encryption** (via openssl) with **auto-generated random passwords**. Each backup gets a unique password that is stored in the recovery file.

## System Requirements

Before executing backup operations, ensure the following tools are installed:

- **Python 3.7+** (script runtime environment)
- **requests library** (`pip install requests`)
- **tar** (file archiving)
- **openssl** (encryption/decryption)
- **curl** (HTTP requests, system built-in)

## Default Backup Files

If the user doesn't specify files, the following OpenClaw workspace files are backed up by default:

- `SOUL.md` - Agent core identity and goals
- `MEMORY.md` - Agent memory and context
- `IDENTITY.md` - Agent identity definition
- `AGENTS.md` - Agent configuration
- `TOOLS.md` - Tool configuration

## Workflow 1: Upload Backup

### Trigger Scenarios

Execute when the user requests to backup workspace files:

- "Back up my workspace files"
- "Upload SOUL.md to soul-upload"
- "Create an encrypted backup of my agent files"
- "Backup SOUL.md and MEMORY.md"

### Execution Steps

1. **Collect File List**
   - If user specified files, use the user-specified files
   - Otherwise, use default list: `SOUL.md MEMORY.md IDENTITY.md AGENTS.md TOOLS.md`
   - Use Read tool to verify files exist

2. **Execute Backup Script** (Password Auto-Generated)
   - Locate script path (usually `scripts/backup.py` in Skill directory)
   - Execute command WITHOUT --password argument (script will auto-generate):
     ```bash
     python3 scripts/backup.py upload \
       --files "SOUL.md MEMORY.md IDENTITY.md"
     ```
   - Script automatically generates a 32-character random password
   - Capture stdout (JSON response) and stderr (progress info including generated password)

3. **Process Response**
   - On success, script outputs JSON:
     ```json
     {
       "backupId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
       "downloadUrl": "https://soul-upload.com/backup/...",
       "sizeBytes": 12345,
       "sha256": "abc123...",
       "password": "auto-generated-32-char-random-password"
     }
     ```
   - Parse JSON and extract key information including the auto-generated password

4. **Save Recovery Information**
   - Use Write tool to create/update `.openclaw-backup-recovery.txt`
   - **CRITICAL**: Include the auto-generated password in the recovery file
   - Format:
     ```
     Backup ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
     Password: auto-generated-32-char-random-password
     Download URL: https://soul-upload.com/backup/...
     Created: 2024-01-15 10:30:00 UTC
     Size: 12.05 KB
     SHA256: abc123...
     Files: SOUL.md, MEMORY.md, IDENTITY.md
     ---
     ```
   - Append to end of file (preserve history)

5. **Display Success Message**
   - Inform user backup is complete
   - Show Backup ID and file size
   - **IMPORTANT**: Inform user that password was auto-generated and saved to `.openclaw-backup-recovery.txt`
   - Warn user: Recovery file is CRITICAL - without it, backup cannot be restored

### Error Handling

| Error Scenario | Detection | User Guidance |
|----------------|-----------|---------------|
| Files not found | Script returns error: "Files not found: ..." | List missing files, ask if user wants to continue backing up other files |
| Files too large | Script returns error: "Backup size ... exceeds limit ..." | Show actual size, suggest removing large files or splitting backup |
| Network error | Script returns error: "Network error: ..." | Suggest checking network connection, ask if retry is wanted |
| 413 Too Large | Script returns error: "File too large (413 Payload Too Large)" | Indicate 20MB limit exceeded, suggest reducing backup size |
| Encryption failed | Script returns error: "openssl encryption failed: ..." | Check if openssl is properly installed |

### Example Conversation

```
User: Back up my SOUL.md and MEMORY.md
Claude: I'll backup these files with auto-generated encryption.
       [Executes backup script]
       Backup complete!
       - Backup ID: 3f8a2b1c-...
       - Size: 45.2 KB
       - Password: Auto-generated (32 chars)
       - Recovery info saved to .openclaw-backup-recovery.txt

       IMPORTANT: Keep .openclaw-backup-recovery.txt safe!
       It contains the password needed to restore this backup.
```

## Workflow 2: Download Backup

### Trigger Scenarios

Execute when user requests to restore backup:

- "Restore my backup"
- "Download my last backup"
- "Recover backup [backup-id]"
- "Restore from [download-url]"

### Execution Steps

1. **Get Backup ID and Password**
   - Check if user provided Backup ID or Download URL
   - If not provided, use Read tool to read `.openclaw-backup-recovery.txt`
   - Extract latest Backup ID AND password from file
   - If file doesn't exist or is empty, cannot proceed (password unknown)

2. **Determine Output Directory**
   - Default: Current working directory (`.`)
   - If user specified a directory, use user-specified directory
   - Warn user: Existing files may be overwritten

3. **Execute Restore Script**
   - Execute command with password from recovery file:
     ```bash
     python3 scripts/backup.py download \
       --backup-id "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
       --password "password-from-recovery-file" \
       --output-dir "."
     ```
   - Capture stdout (JSON response) and stderr (progress info)

4. **Process Response**
   - On success, script outputs JSON:
     ```json
     {
       "success": true,
       "extractedFiles": ["SOUL.md", "MEMORY.md", "IDENTITY.md"],
       "outputDir": "/path/to/output"
     }
     ```
   - Parse extracted file list

5. **Verify Restoration Result**
   - Use Read tool to read first few lines of restored files
   - Show file preview for user to confirm content is correct
   - Remind user to check complete content

6. **Display Success Message**
   - List restored files
   - Show output directory
   - Suggest user verify file content

### Error Handling

| Error Scenario | Detection | User Guidance |
|----------------|-----------|---------------|
| Backup ID doesn't exist | Script returns error: "Backup not found: ..." | Check if Backup ID is correct, may have been deleted |
| Recovery file missing | `.openclaw-backup-recovery.txt` not found | Cannot restore - password is unknown without recovery file |
| Wrong password | Script returns error: "Decryption failed - wrong password ..." | Recovery file may be corrupted or from different backup |
| Network error | Script returns error: "Network error: ..." | Suggest checking network connection, ask if retry is wanted |
| Extraction failed | Script returns error: "tar extraction failed: ..." | File may be corrupted, try downloading again |

### Example Conversation

```
User: Restore my last backup
Claude: I found the most recent backup in .openclaw-backup-recovery.txt
       - Backup ID: 3f8a2b1c-...
       - Created: 2024-01-15 10:30:00 UTC
       Downloading and decrypting backup...
       Restoration complete! Extracted the following files:
       - SOUL.md
       - MEMORY.md
       - IDENTITY.md
       Files saved to current directory, please verify content is correct.
```

## Workflow 3: Delete Backup

### Trigger Scenarios

Execute when user requests to delete remote backup:

- "Delete my backup"
- "Remove backup [backup-id]"
- "Delete the backup from soul-upload"

### Execution Steps

1. **Get Backup ID**
   - Check if user provided Backup ID
   - If not provided, use Read tool to read `.openclaw-backup-recovery.txt`
   - Show available backup list fo