Soul Transfer - Locally Packaged Complete Agent Migration

Concept

"Change the body, keep the soul completely intact."

This skill performs 100% local backup and restore for any OpenClaw agent. No cloud services, no third-party dependencies - everything stays on your machine.

Core Principles

1. Local Only — All operations happen locally. No data leaves your machine.
2. Complete — Every file that makes the agent "itself" is included.
3. Portable — ZIP format for maximum compatibility across systems.
4. Safe — Verification, safety backups, and rollback support.

Phase 1: Analyze (Discovery)

Before backup, the skill analyzes exactly what files exist:

# 1. Find OpenClaw state directory
# 2. Find workspace directory
# 3. Scan ALL subdirectories recursively

Files to Detect

Environment Detection

# Detect OS type
detect_linux() { uname == "Linux" && ! grep -q Microsoft /proc/version; }
detect_macos() { uname == "Darwin"; }
detect_windows() { uname == *"MINGW"* || uname == *"CYGWIN"*; }
detect_docker() { grep -q docker /proc/1/cgroup 2>/dev/null; }

Path Mapping Table

Phase 2: Backup (Create ZIP)

1. Ask user: "Where should I save the backup?"
   - Accept: directory path or full filename.zip
   
2. Analyze current environment
   - Scan all OpenClaw directories
   - Build complete file manifest with SHA256 checksums
   
3. Create ZIP archive:
   zip -r \x3Coutput.zip> \x3Cfiles> -x "*.log" "*/cache/*" "*/node_modules/*"
   
4. Generate backup manifest:
   - File list with checksums
   - Environment info (OS, OpenClaw version, timestamp)
   - Original paths mapping
   
5. Verify ZIP integrity:
   zip -T \x3Coutput.zip>
   
6. Report:
   - Backup location
   - Total size
   - File count
   - Checksums

Backup Command

# Create backup with verification
BACKUP_DIR="${1:-~/backups}"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/agent-backup-$TIMESTAMP.zip"

mkdir -p "$BACKUP_DIR"

# Find all OpenClaw files and package them
zip -r "$BACKUP_FILE" \
    ~/.openclaw/ \
    ~/workspace/ \
    -x "*.log" \
    -x "*/cache/*" \
    -x "*/node_modules/*" \
    -x "*/.git/*" \
    -x "*/completions/*"

# Generate manifest
cat > "$BACKUP_DIR/manifest-$TIMESTAMP.json" \x3C\x3C EOF
{
  "version": "1.0.2",
  "timestamp": "$TIMESTAMP",
  "files": [],
  "checksums": {},
  "environment": "$(uname -a)"
}
EOF

zip -m "$BACKUP_FILE" "$BACKUP_DIR/manifest-$TIMESTAMP.json"

Phase 3: Restore (Complete Recovery)

1. Locate backup ZIP
   - Ask user if not provided
   
2. Verify ZIP integrity:
   unzip -t \x3Cbackup.zip>
   
3. Analyze new environment:
   - Detect OS type
   - Find OpenClaw installation
   - Determine correct paths
   
4. Safety check:
   - Ask user: "This will replace current configuration. Continue?"
   - Create safety backup: ~/.soul-transfer-backup-\x3Ctimestamp>
   
5. Stop gateway (user confirmation required)

6. Extract ZIP:
   unzip -o \x3Cbackup.zip> -d ~
   
7. Path translation (if different environment):
   - Read manifest
   - Map old paths to new paths
   - Update openclaw.json if needed
   
8. Reinstall dependencies:
   cd \x3Cworkspace>
   npm install --silent
   
9. Restart gateway

10. Verify soul transfer:
    Ask agent questions to confirm identity

Restore Command

# Verify ZIP integrity
unzip -t \x3Cbackup.zip>
if [ $? -ne 0 ]; then
    echo "ERROR: Backup file is corrupted"
    exit 1
fi

# Create safety backup
SAFETY_DIR=~/.soul-transfer-backup-$(date +%Y%m%d_%H%M%S)
mkdir -p "$SAFETY_DIR"
cp -r ~/.openclaw "$SAFETY_DIR/" 2>/dev/null
cp -r ~/workspace "$SAFETY_DIR/" 2>/dev/null

# Extract backup
unzip -o \x3Cbackup.zip> -d ~

# Update permissions
chmod -R 755 ~/.openclaw/
chmod -R 755 ~/workspace/

# Reinstall npm packages
cd ~/workspace && npm install --silent 2>/dev/null

Safety Features

Security Features

What Gets Backed Up

Agent "Soul" = Everything that makes this agent ITSELF:

├── Identity
│   ├── SOUL.md
│   ├── IDENTITY.md
│   ├── USER.md
│   ├── AGENTS.md
│   ├── HEARTBEAT.md
│   └── TOOLS.md
│
├── Memory
│   ├── memory/
│   │   ├── user/
│   │   ├── monthlydailylog/
│   │   ├── projects/
│   │   └── setup.md
│   ├── self-improving/
│   │   ├── memory.md
│   │   ├── corrections.md
│   │   ├── index.md
│   │   └── ...
│   └── proactive/
│       ├── memory.md
│       ├── session-state.md
│       └── ...
│
├── Skills
│   └── skills/
│
├── Configuration
│   ├── .openclaw/
│   │   ├── openclaw.json
│   │   ├── credentials/
│   │   ├── extensions/
│   │   ├── agents/
│   │   ├── sessions/
│   │   └── ...
│   └── .env
│
├── Database
│   └── db/
│
└── Channels
    └── (WeChat, Telegram, Discord sessions)

What Gets Excluded

Usage Examples

Create Backup (interactive)

> backup
User: Where should I save the backup?
User: /mnt/backup/agent.zip
Creating backup...
Backup created: /mnt/backup/agent.zip (1.2 GB)
Verification: OK

Create Backup (command)

soul-transfer backup --destination /mnt/backup/my-agent.zip

Restore

soul-transfer restore --source /mnt/backup/my-agent.zip

Verify Only

soul-transfer verify --source /mnt/backup/my-agent.zip

Dry Run

soul-transfer restore --dry-run --source /mnt/backup/my-agent.zip

Verification Questions

After restore, confirm "soul" is intact:

1. "Do you know who you are?"
2. "What is your owner's name?"
3. "What were we working on last?"
4. "What is your communication style?"

Correct answers = successful soul transfer.

Important Notes

• API Keys — Stored in backup, work immediately in new environment
• Skills — Require npm install after restore
• Gateway Restart — Required after restore
• Channel Re-auth — Some channels may need re-login (WeChat, Telegram)
• QMD Index — Rebuilds automatically on first search

Design Goals

1. Universal — Works on any OS with standard tools (zip, bash)
2. Complete — Every agent file is identified and backed up
3. Safe — Multiple safety checks and rollback capability
4. Local — Zero network dependency, complete privacy
5. Portable — ZIP format works everywhere

Technical Requirements

• zip command (standard on most systems)
• sha256sum or shasum (for checksums)
• bash or compatible shell
• Standard Unix tools (cp, mv, chmod, mkdir)

All requirements are available by default on Linux, macOS, and Windows Subsystem for Linux (WSL).