Backup and restore all agent files and configurations to fully migrate this agent with automatic path mapping and integrity verification.
---
name: soul-transfer
version: 1.0.2
description: "Soul Transfer" - Locally packaged complete agent backup and restore. Analyzes ALL files, creates a portable ZIP archive, and fully restores to any environment. 100% local - no cloud dependency.
---
# 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
| 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
```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
| 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
```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)
```
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
| 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)
```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).
don't have the plugin yet? install it then click "run inline in claude" again.