Soul Transfer

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

Security Scan

The skill's backup/restore steps are broadly coherent for agent migration, but there are important inconsistencies and sensitive operations (credential copying, service stop/kill, and implied network activity) that the user should review before running.

Purpose & Capability

The name and description claim a complete local backup/restore of an agent and the instructions do indeed scan and package the OpenClaw state, workspace, credentials, and plugins — which is consistent with the stated purpose. However the doc also references reinstalling npm packages and uses commands (npm install) that imply network access, which contradicts the '100% local / no third-party' claim.

Instruction Scope

The SKILL.md instructs recursively scanning and copying highly sensitive locations (credentials/**/*, tokens/**/*, ~/.openclaw/, ~/workspace/) and stopping/killing gateway processes. Those operations are expected for a full migration tool, but the instructions are broad and will include secrets by design. The doc asserts 'no network requests' yet calls for 'npm install' and other operations that typically fetch packages from the network unless explicit offline measures are taken. There is also no explicit, reliable encryption step for exported credentials despite stating 'credentials included (encrypted if stored)'.

Install Mechanism

No install spec and no code files are included; this is an instruction-only skill. That minimizes filesystem write risk from the skill package itself. The runtime commands will, however, perform file operations when executed by the user/agent.

Credentials

The skill requests no environment variables or external credentials, which is proportionate. That said, it explicitly reads and packages local credential stores and tokens (files under credentials, tokens, channel dirs). Accessing those files is necessary for a 'complete' migration, but it is high-sensitivity access — the user should expect exported archives to contain secrets unless they are separately encrypted.

Persistence & Privilege

The skill does not request always:true or other elevated/persistent privileges. It does instruct the agent to stop/restart services and modify config in-place, which are normal for a restore operation but require user confirmation and appropriate local permissions.

Scan Findings in Context

[no-findings] expected: The regex-based scanner found no code files to analyze. This is expected because the skill is instruction-only (SKILL.md + reference doc). The real security surface is the runtime commands described in SKILL.md.

What to consider before installing

This skill appears to do what it says (complete local backup and restore) but it will copy your agent's secrets and stop/modify running services. Before using it: - Understand that backups will include credentials/tokens unless you separately encrypt or exclude them; treat the resulting ZIP as highly sensitive. - The docs claim '100% local' but call for 'npm install' (a network operation) — if you truly need an offline restore, prepare offline dependency caches or skip automatic npm install. - Test the workflow in a disposable environment first (not your production agent) so you can verify the safety backup/rollback behavior. - Review and, if needed, modify the exclusion lists (e.g., exclude credentials or channel tokens if you don't want them packaged) and ensure any extracted backups are stored securely. - Avoid running as root; ensure you have backups and explicit confirmations for stop/kill operations the script suggests. If you plan to trust this skill for production migration, ask the publisher for clarifications about offline dependency handling, explicit encryption of credential files, and any additional safeguards during restore. If you cannot verify those answers, proceed cautiously or perform the migration manually.

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