openclaw-backup（OpenClaw 备份）

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

1. 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): 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)

1. Process Response

- On success, script outputs 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

1. 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)

1. 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

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)

1. Determine Output Directory

- Default: Current working directory (.) - If user specified a directory, use user-specified directory - Warn user: Existing files may be overwritten

1. Execute Restore Script

- Execute command with password from recovery file: 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)

1. Process Response

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

1. 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

1. Display Success Message

- List restored files - Show output directory - Suggest user verify file content

Error Handling

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 for user to select - If file doesn't exist or is empty, ask user to provide Backup ID

1. Request Confirmation

- Warning: This operation is irreversible, backup will be permanently deleted - Show Backup ID to delete and creation time - Ask user to confirm deletion

1. Execute Delete Script

- After user confirms, execute command: python3 scripts/backup.py delete \ --backup-id "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" - Capture stdout (JSON response) and stderr (progress info)

1. Process Response

- On success, script outputs JSON: {"success": true, "backupId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}

1. Update Recovery Info File

- Use Read tool to read .openclaw-backup-recovery.txt - Remove deleted backup record (including its password) - Use Write tool to save updated file - If file becomes empty, can delete the file

1. Display Success Message

- Confirm backup was deleted - Show deleted Backup ID - Remind user: If backup is needed again, must create new one with new password

Error Handling

Example Conversation

User: Delete my backup
Claude: I found the following backups in .openclaw-backup-recovery.txt:
       1. Backup ID: 3f8a2b1c-... (2024-01-15 10:30:00)
       2. Backup ID: 7b2c9d4e-... (2024-01-14 08:20:00)
       Which backup would you like to delete? (1 or 2)
User: 1
Claude: Warning: This will permanently delete backup 3f8a2b1c-...
       This action cannot be undone. Confirm deletion? (yes/no)
User: yes
Claude: Backup deleted.
       - Backup ID: 3f8a2b1c-...
       To backup again, create a new backup with a new auto-generated password.

Security Notes

Password Policy (NEW)

• Auto-Generated Passwords: Each backup gets a unique 32-character random password
• Never Reuse Passwords: Per soul-upload.com policy, do NOT reuse passwords across backups
• Password Storage: Password is stored in .openclaw-backup-recovery.txt (necessary for decryption)
• User Responsibility: Users must keep recovery file safe - without it, backup cannot be restored

Recovery File Security

• File Location: .openclaw-backup-recovery.txt (workspace root directory)
• Content: Backup ID, Password (CRITICAL), Download URL, timestamp, SHA256
• CRITICAL: Recovery file is the ONLY place password is stored
• Recommendation:

- Add to .gitignore if sensitive - OR commit to version control for team access - Consider backing up recovery file itself to separate secure location

Encryption Algorithm

• Algorithm: AES-256-CBC (symmetric encryption)
• Salting: openssl automatically adds salt for enhanced security
• Compatibility: Consistent with soul-upload.com official documentation

Temporary File Cleanup

• Script uses try-finally to ensure temporary files are cleaned up
• Avoids leaving unencrypted sensitive data on disk

File Size Limits

• Maximum Backup Size: 20 MB (compressed and encrypted)
• Check Timing: Automatically checked before upload
• Limit Exceeded Handling: Show actual size, suggest user:

- Remove large files (like logs, caches) - Split backup (backup different files in batches)

API Reference

soul-upload.com Backup API:

Common Status Codes:

• 200 - Success
• 404 - Backup not found
• 413 - File too large (exceeds 20MB)
• 415 - Unsupported file type
• 500 - Server error

Troubleshooting

Missing Dependencies

Problem: Script error "Missing required tools: tar, openssl"

Solution:

• macOS: brew install openssl (tar built-in)
• Ubuntu/Debian: sudo apt-get install tar openssl
• Verify installation: tar --version and openssl version

Python requests Library Missing

Problem: Script error "Error: 'requests' library not found"

Solution:

pip install requests
# or
pip3 install requests

Recovery File Lost

Problem: Cannot restore backup - recovery file missing

Solution:

• Recovery file is CRITICAL - contains the only copy of the password
• Without recovery file, backup CANNOT be restored
• Recommend backing up recovery file to separate secure location
• If lost, backup is permanently inaccessible

Network Timeout

Problem: Timeout during upload/download

Solution:

• Check network connection
• Reduce backup file size (remove unnecessary files)
• Script default timeout is 5 minutes, usually sufficient

File Already Exists

Problem: Overwriting existing files during restore

Solution:

• Backup existing files before restore
• Specify different output directory
• Manually move existing files to other location

Usage Examples

Example 1: Backup All Default Files

User: Back up my workspace files
Claude: [Execute upload workflow using default file list]
       [Auto-generate password and save to recovery file]

Example 2: Backup Specific Files

User: Back up only SOUL.md and MEMORY.md
Claude: [Execute upload workflow, backup only specified files]
       [Auto-generate password and save to recovery file]

Example 3: Restore Latest Backup

User: Restore my last backup
Claude: [Read latest Backup ID and password from .openclaw-backup-recovery.txt]
       [Execute download workflow]

Example 4: Restore Specific Backup

User: Restore backup 3f8a2b1c-1234-5678-90ab-cdef12345678
Claude: [Read password for this Backup ID from recovery file]
       [Execute download workflow]

Example 5: Delete Old Backups

User: Delete my old backups
Claude: [Show available backup list from recovery file]
       [User selects backup to delete]
       [Execute delete workflow]
       [Remove entry from recovery file]

Best Practices

1. Regular Backups: Recommend weekly backups or after important changes
2. Recovery File Management: Keep .openclaw-backup-recovery.txt safe and backed up separately
3. Verify Restoration: Regularly test backup restoration process to ensure backups are usable
4. Clean Old Backups: Regularly delete unneeded old backups to save storage space
5. Multiple Copies: Consider keeping recovery file in multiple secure locations

Script Path

Script file is located in Skill directory at scripts/backup.py.

When executing Bash commands, ensure correct relative or absolute path is used. Usually:

• If currently in Skill directory: python3 scripts/backup.py...
• If in other directory: Use absolute path or cd to Skill directory first

Reference Documentation

• soul-upload.com Backup Guide
• soul-upload.com Restore Guide
• OpenClaw Agent Documentation

Version: 2.0.0 Author: Claude Code License: MIT Password Policy: Auto-generated unique password per backup (NEW in v2.0.0)