Soul Transfer (夺舍)

---

name: soul-transfer

description: "Backup and restore an OpenClaw agent's full workspace (memory, config, credentials, skills, cron jobs) to/from a Git repository. Use when: migrating to a new instance, disaster recovery, setting up a fresh machine, the user says 'backup', 'restore', 'migrate', 'transfer', '夺舍', '还魂', or 'soul transfer'. Also use for periodic backup setup and backup verification."

---

# Soul Transfer (夺舍)

Agent workspace migration between OpenClaw instances via Git.

Concepts

Backup Procedure

1. Ensure Git remote is configured

cd $WORKSPACE
git remote get-url origin || git remote add origin https://<token>@github.com/<owner>/<repo>.git

2. Export current OpenClaw config

Save a copy of the live config for future restoration. This file contains channel tokens, API keys, and guild settings that are NOT in the workspace markdown files.

Use `gateway config.get` tool → extract the `parsed` object → write to a JSON file in the workspace (e.g. `openclaw-config-backup.json`).

This step is critical — without this file, channel connections cannot be restored on a new instance.

3. Commit and push

git add -A
git commit -m "backup: $(date +%Y-%m-%d_%H%M)"
git push origin master

4. Verify backup

git log --oneline -1
git diff --stat HEAD~1

Backup cron (automated)

Set up a recurring cron job for automatic backups. See references/cron-templates.md for ready-to-use definitions.

Restore Procedure (夺舍 Checklist)

Execute these steps in order. Do not skip step 5 — it is the most commonly forgotten step.

Step 1: Clone the backup repo

git clone https://<token>@github.com/<owner>/<repo>.git /tmp/soul-backup

Step 2: Audit contents

Before restoring, review what's in the repo:

find /tmp/soul-backup -type f | wc -l
cat /tmp/soul-backup/IDENTITY.md

Identify sensitive files that should NOT be copied to markdown: standalone credential files (API tokens, key files, etc.)

Step 3: Restore workspace files

Copy core files from the backup into `$WORKSPACE`:

Step 4: Scrub hardcoded credentials from markdown files

# Scan for credential patterns
grep -rl 'ghp_\|AKIA[0-9A-Z]\|sk-[a-zA-Z0-9]' $WORKSPACE/ \
  --include='*.md' 2>/dev/null

Replace found credentials with `[REDACTED]` in markdown and log files.

Do NOT scrub the config backup JSON — it contains credentials needed for step 5.

Step 5: Restore OpenClaw config (⚠️ CRITICAL — do not skip)

This is the step that connects channels, API keys, and runtime settings. Without it, all channels remain disconnected.

Read the config backup JSON from the workspace. Extract:

Apply via `gateway config.patch`:

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "<from config backup>",
      "groupPolicy": "allowlist",
      "guilds": { "..." },
      "dm": { "..." },
      "actions": { "..." }
    }
  },
  "tools": {
    "web": { "search": { "apiKey": "<from config backup>" } },
    "exec": { "security": "full" }
  }
}

After patching, OpenClaw restarts automatically. Verify with `openclaw status` — channels should show connected.

Use `config.schema.lookup` to check field names if the OpenClaw version differs from the backup.

Step 6: Rebuild cron jobs

Cron jobs are runtime state, NOT stored in git. Rebuild from documented list or references/cron-templates.md.

Use `cron add` for each job. Only restore jobs that are still needed.

Step 7: Verify and clean up

# Verify channel connectivity
openclaw status

# Delete temp clone
rm -rf /tmp/soul-backup

# Delete BOOTSTRAP.md if present (no longer a fresh instance)
rm -f $WORKSPACE/BOOTSTRAP.md

# Commit restored state
cd $WORKSPACE
git add -A && git commit -m "夺舍完成: $(date +%Y-%m-%d_%H%M)"

Step 8: Log the event

Record the transfer in today's daily log with timestamp, file count, and any issues encountered.

Common Pitfalls

1. **Skipping config restore** — Workspace files restore memory but NOT channel connections. The config backup JSON → `config.patch` is mandatory.

2. **Over-scrubbing credentials** — Don't scrub the config backup JSON; it's needed for config.patch. Only scrub credentials embedded in markdown/log files.

3. **Forgetting cron rebuild** — Cron is runtime state, not in git.

4. **Old vs new config schema** — Use `config.schema.lookup` to verify field names before patching. OpenClaw versions may rename fields.

5. **Git remote not configured** — New instance has no remote; configure before first backup push.

Backup Health Check

Run periodically to verify backup integrity:

cd $WORKSPACE
# Check remote is configured
git remote -v
# Check last push time
git log --oneline -1
# Check for uncommitted changes
git status --short
# Verify config backup exists and has channel tokens
grep -c '"token"' openclaw-config-backup.json 2>/dev/null || echo "⚠️ No config backup found"