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:

bash

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

Files to Detect#

TypeFiles/DirectoriesIdentitySOUL.md, IDENTITY.md, USER.md, AGENTS.md, HEARTBEAT.md, TOOLS.mdMemorymemory/ /*, self-improving// _, proactive/**/_Skillsskills/**/*Configopenclaw.json, config.yaml, .envCredentialscredentials/ /*, tokens//*Pluginsextensions/ /*, plugins//*Agentsagents/**/*Sessionssessions/**/*Channelstelegram/ /*, discord// , weixin/**/, whatsapp/**/*Croncron/ /*, scheduled//*Database* _/.db, **/.sqlite, /*.sqlite3, qmd//_Logs(excluded by default)Cache(excluded - regenerated automatically)

Environment Detection#

bash

# 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#

EnvironmentState DirWorkspace DirLinux~/.openclaw//workspace/macOS/.openclaw//workspace/Docker/home/app/.openclaw//workspace/飞牛 NAS/trim.openclaw/data/home/.openclaw/~/trim.openclaw/data/workspace/Windows%USERPROFILE%/.openclaw/%USERPROFILE%/workspace/

Phase 2: Backup (Create ZIP)#

text

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 <output.zip> <files> -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 <output.zip>

6. Report:
   - Backup location
   - Total size
   - File count
   - Checksums

Backup Command#

bash

# 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" << 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)#

text

1. Locate backup ZIP
   - Ask user if not provided

2. Verify ZIP integrity:
   unzip -t <backup.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-<timestamp>

5. Stop gateway (user confirmation required)

6. Extract ZIP:
   unzip -o <backup.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 <workspace>
   npm install --silent

9. Restart gateway

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

Restore Command#

bash

# Verify ZIP integrity
unzip -t <backup.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 <backup.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#

FeatureDescriptionZIP Verificationunzip -t validates archive integritySHA256 ChecksumsEvery file has checksum for tamper detectionSafety BackupCurrent state backed up before any overwriteRollbackCan restore from safety backup if anything failsPath MappingAutomatic translation between environmentsDry RunPreview what will happen without making changesExclusion ListsCache, logs, node_modules excluded by default

Security Features#

FeatureDescription100% LocalNo network requests, no cloud uploadIntegrity CheckSHA256 checksums detect corruption/tamperingCredential SafetyAll credentials included (encrypted if stored)No Third-PartyOnly uses standard tools: zip, tar, sha256sum

What Gets Backed Up#

text

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#

TypeReason*.logRegenerated automatically*/cache/*Regenerated automatically*/node_modules/*Reinstalled via npm install*/.git/*Version control, not part of agent*/completions/*API cache, regenerated

Usage Examples#

Create Backup (interactive)#

text

> 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)#

bash

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

Restore#

bash

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

Verify Only#

bash

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

Dry Run#

bash

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