SOUL Backup Skill

Backup and restore OpenClaw workspace SOUL files with versioning, validation, and sanitized openclaw.json handling.

Security Scan

The skill appears to implement the advertised local backup/restore features, but there are a few mismatches between the documentation/registry metadata and the actual runtime requirements (notably Node.js is required but 'required binaries' lists none), so review before installing.

Purpose & Capability

The skill's name, description, and SKILL.md all describe a local backup/restore tool for SOUL files and that matches the included scripts and docs. However the registry metadata claims 'Required binaries: none' while all runtime examples and the included .mjs scripts require Node (node command). That is an inconsistency: Node.js is a legitimate required runtime for this skill and should be declared.

Instruction Scope

The SKILL.md instructions stay within the stated purpose: create/back up SOUL files, list/validate/restore them, sanitize openclaw.json, and use cron/hooks for automation. The instructions explicitly operate on workspace files and manifest.json and do not instruct the agent to read unrelated system data or to ship data to external endpoints. They do reference cloning or using a repository URL and manual cp for emergency recovery (expected for a backup tool).

Install Mechanism

There is no install spec (instruction-only at registry level), which reduces install-time risk. However, the package contains multiple executable scripts (.mjs) and a package.json; installing means cloning/placing these files in a workspace and running them with node — nothing is automatically installed by the skill. This is consistent but should be explicitly documented as requiring Node.js on PATH (the metadata omitted that).

Credentials

The skill does not request any environment variables or external credentials and the documented behavior (sanitizing openclaw.json and redacting token/key/password fields) is consistent with that. There is no indication the scripts attempt to access unrelated credentials or other services. The sanitize behavior should still be reviewed in the code to ensure it does not accidentally log or transmit redacted values.

Persistence & Privilege

The skill does not request always:true and is not requesting elevated or persistent platform privileges. It operates on files in the workspace and creates local backups; its described pre-restore backups and retention/prune plans are scoped to its own backup directory. It does not claim to modify other skills or system-wide agent settings.

What to consider before installing

This skill mostly matches its description (local backup/restore of SOUL files), but before installing or running it: 1) Ensure Node.js is installed and available as `node` (the registry metadata omitted this requirement). 2) Inspect the scripts (scripts/*.mjs) yourself to verify there are no unexpected network calls or logging of secrets — the SKILL.md says openclaw.json is sanitized, but you should confirm the sanitize routine only redacts and does not transmit or persist sensitive values in logs. 3) Run the scripts from a test workspace first (or with dry-run flags) to confirm behavior and that paths conform to your environment. 4) Do not run as root and avoid committing backups to public repositories — keep backups stored off-machine if you need protection against machine loss. 5) Because the package contains executable scripts but no install step, you are responsible for placing them in the correct workspace path; verify .gitignore excludes backups/ and consider encrypting/moving sensitive backups to an off-machine location. If you want higher assurance, ask the publisher for an explicit statement of Node versions supported, and request a short audit of the sanitize/restore code paths to confirm no exfiltration or unexpected network activity.

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
• USER.md — user profile and preferences
• AGENTS.md — agent instructions and workflows
• IDENTITY.md — agent identity configuration
• TOOLS.md — local tool configuration
• HEARTBEAT.md — periodic task configuration
• BOOTSTRAP.md — initialization instructions

Config backup policy:

• openclaw.json is included via a sanitized copy: openclaw.sanitized.json
• 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

# Create timestamped backup
node scripts/backup.mjs

# Create named backup
node scripts/backup.mjs --name "pre-migration"

# Backup with description
node scripts/backup.mjs --desc "Before major refactor"

List Backups

# List all backups
node scripts/list.mjs

# Show detailed info
node scripts/list.mjs --verbose

Restore from Backup

# Restore latest backup
node scripts/restore.mjs

# Restore specific backup by timestamp
node scripts/restore.mjs --timestamp 2026-03-05T00-51-30

# Restore specific backup by name
node scripts/restore.mjs --name "pre-migration"

# Dry run (preview without applying)
node scripts/restore.mjs --dry-run

Validate Backup Integrity

# Validate all backups
node scripts/validate.mjs

# Validate specific backup
node scripts/validate.mjs --timestamp 2026-03-05T00-51-30

Backup Structure

backups/
├── 2026-03-05T00-51-30/
│   ├── manifest.json          # Backup metadata
│   ├── SOUL.md
│   ├── USER.md
│   ├── AGENTS.md
│   ├── IDENTITY.md
│   ├── TOOLS.md
│   ├── HEARTBEAT.md
│   └── BOOTSTRAP.md
├── 2026-03-05T01-15-42/
│   └── ...
└── named/
    ├── pre-migration/
    │   └── ...
    └── stable-v1/
        └── ...

Manifest Format

Each backup includes a manifest.json:

{
  "timestamp": "2026-03-05T00:51:30.123Z",
  "name": "pre-migration",
  "description": "Before major refactor",
  "workspace": "/Users/m1/.openclaw/workspace-hunter",
  "files": {
    "SOUL.md": {
      "size": 1234,
      "hash": "sha256:abc123...",
      "exists": true
    },
    "USER.md": {
      "size": 567,
      "hash": "sha256:def456...",
      "exists": true
    }
  },
  "created_by": "hunter",
  "openclaw_version": "1.0.0"
}

Recovery Workflow

Standard Recovery

1. List available backups: node scripts/list.mjs
2. Preview restore: node scripts/restore.mjs --timestamp <ts> --dry-run
3. Apply restore: node scripts/restore.mjs --timestamp <ts>
4. Verify: Check workspace files manually

Emergency Recovery

If workspace is corrupted and scripts won't run:

# Manual restore from backup directory
cd /Users/m1/.openclaw/workspace-hunter
cp -r soul-backup-skill/backups/LATEST_TIMESTAMP/* .

Rollback After Bad Restore

Every restore creates an automatic pre-restore backup:

# Restore creates: backups/pre-restore-2026-03-05T01-20-00/
# To rollback:
node scripts/restore.mjs --timestamp pre-restore-2026-03-05T01-20-00

Automation

Cron Schedule (Recommended)

Add to OpenClaw heartbeat or system cron:

# Daily backup at 2 AM
0 2 * * * cd /Users/m1/.openclaw/workspace-hunter/soul-backup-skill && node scripts/backup.mjs --name "daily-$(date +\%Y-\%m-\%d)"

# Weekly backup on Sunday
0 3 * * 0 cd /Users/m1/.openclaw/workspace-hunter/soul-backup-skill && node scripts/backup.mjs --name "weekly-$(date +\%Y-W\%V)"

Pre-Deployment Hook

# Before deploying changes
cd /Users/m1/.openclaw/workspace-hunter/soul-backup-skill
node scripts/backup.mjs --name "pre-deploy-$(git rev-parse --short HEAD)"

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

# Immediate recovery
node scripts/restore.mjs --file SOUL.md

# Or full restore
node scripts/restore.mjs

Scenario 2: Bad Configuration Change

# Preview what will be restored
node scripts/restore.mjs --dry-run

# Restore previous version
node scripts/restore.mjs --timestamp <previous-backup>

Scenario 3: Corrupted Backup

# Validate all backups
node scripts/validate.mjs

# Find last good backup
node scripts/list.mjs --verbose

# Restore from last good backup
node scripts/restore.mjs --timestamp <last-good>

Scenario 4: Complete Workspace Loss

# Recreate workspace directory
mkdir -p /Users/m1/.openclaw/workspace-hunter

# Clone backup skill
cd /Users/m1/.openclaw/workspace-hunter
git clone <backup-repo-url> soul-backup-skill

# Restore latest backup
cd soul-backup-skill
node scripts/restore.mjs

Best Practices

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: ls -la ..
• Ensure backup script has execute permissions: chmod +x scripts/*.mjs

"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