SOUL Backup Skill

Backup and restore OpenClaw workspace SOUL files (SOUL.md, USER.md, AGENTS.md, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md) with versioning, validation, and rollback capabilities.

Purpose

Protect critical workspace configuration files from accidental deletion, corruption, or misconfiguration. Enable quick recovery and version history tracking.

What Gets Backed Up

Core SOUL files from workspace root:

• - SOUL.md — agent personality and mission
• INLINECODE1 — user profile and preferences
• INLINECODE2 — agent instructions and workflows
• INLINECODE3 — agent identity configuration
• INLINECODE4 — local tool configuration
• INLINECODE5 — periodic task configuration
• INLINECODE6 — initialization instructions

Config backup policy:

• - openclaw.json is included via a sanitized copy: INLINECODE8
• Sensitive fields are redacted (token, key, secret, password, etc.)
• Restore recovers non-sensitive structure; secrets can be auto-restored in newer workflow or manually refilled if needed

Usage

Backup Current SOUL Files

CODEBLOCK0

List Backups

CODEBLOCK1

Restore from Backup

CODEBLOCK2

Validate Backup Integrity

CODEBLOCK3

Backup Structure

CODEBLOCK4

Manifest Format

Each backup includes a manifest.json:

CODEBLOCK5

Recovery Workflow

Standard Recovery

1. 1. List available backups: INLINECODE14
2. Preview restore: INLINECODE15
3. Apply restore: INLINECODE16
4. Verify: Check workspace files manually

Emergency Recovery

If workspace is corrupted and scripts won't run:

CODEBLOCK6

Rollback After Bad Restore

Every restore creates an automatic pre-restore backup:

CODEBLOCK7

Automation

Cron Schedule (Recommended)

Add to OpenClaw heartbeat or system cron:

CODEBLOCK8

Pre-Deployment Hook

CODEBLOCK9

Validation Checks

The validate script checks:

• - Manifest integrity (valid JSON, required fields)
• File existence (all files listed in manifest exist)
• Hash verification (SHA-256 checksums match)
• Workspace path consistency
• Timestamp format validity

Failure Scenarios & Recovery

Scenario 1: Accidental SOUL.md Deletion

CODEBLOCK10

Scenario 2: Bad Configuration Change

CODEBLOCK11

Scenario 3: Corrupted Backup

CODEBLOCK12

Scenario 4: Complete Workspace Loss

CODEBLOCK13

Best Practices

1. 1. Backup before major changes: Always create a named backup before refactoring SOUL files
2. Validate regularly: Run validate.mjs weekly to catch corruption early
3. Keep 30 days of backups: Prune old backups monthly
4. Test restore process: Practice recovery quarterly
5. Document custom changes: Use --desc flag to explain why backup was created
6. Version control: Consider committing backup directory to git for off-machine redundancy

Security Notes

• - Backups contain sensitive configuration (API keys in TOOLS.md, user info in USER.md)
• Store backup directory with same permissions as workspace
• Do not commit backups to public repositories
• Consider encrypting backup directory if workspace contains secrets

Dependencies

• - Node.js 18+
• No external npm packages (uses built-in crypto, fs, path)

Troubleshooting

"Backup directory not found"

• - Run mkdir -p backups in skill directory

"Permission denied"

• - Check workspace directory permissions: INLINECODE20
• Ensure backup script has execute permissions: INLINECODE21

"Hash mismatch during validation"

• - File was modified after backup creation
• Backup may be corrupted — use previous backup

"Restore failed: file conflicts"

• - Use --force flag to overwrite existing files
• Or manually move conflicting files before restore

Future Enhancements

• - [ ] Compression (gzip backups to save space)
• [ ] Remote backup sync (S3, Dropbox, rsync)
• [ ] Differential backups (only changed files)
• [ ] Backup retention policy (auto-prune old backups)
• [ ] Encrypted backups (GPG encryption)
• [ ] Web UI for backup management
• [ ] Slack/Telegram notifications on backup/restore