Soul Transfer

Backup and restore all agent files and configurations to fully migrate this agent with automatic path mapping and integrity verification.

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

Type	Files/Directories
Identity	SOUL.md, IDENTITY.md, USER.md, AGENTS.md, HEARTBEAT.md, TOOLS.md
Memory	memory//*, self-improving//, proactive/**/
Skills	skills/**/*
Config	openclaw.json, config.yaml, .env
Credentials	credentials//*, tokens//*
Plugins	extensions//*, plugins//*
Agents	agents/**/*
Sessions	sessions/**/*
Channels	telegram//*, discord//, weixin/**/, whatsapp/**/*
Cron	cron//*, scheduled//*
Database	*/.db, **/.sqlite, /*.sqlite3, qmd//
Logs	(excluded by default)
Cache	(excluded - regenerated automatically)

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

Environment	State Dir	Workspace Dir
Linux	~/.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)

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

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

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

# 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

Feature	Description
ZIP Verification	unzip -t validates archive integrity
SHA256 Checksums	Every file has checksum for tamper detection
Safety Backup	Current state backed up before any overwrite
Rollback	Can restore from safety backup if anything fails
Path Mapping	Automatic translation between environments
Dry Run	Preview what will happen without making changes
Exclusion Lists	Cache, logs, node_modules excluded by default

Security Features

Feature	Description
100% Local	No network requests, no cloud upload
Integrity Check	SHA256 checksums detect corruption/tampering
Credential Safety	All credentials included (encrypted if stored)
No Third-Party	Only uses standard tools: zip, tar, sha256sum

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

Type	Reason
*.log	Regenerated 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)

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