Soul Transfer

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

• Soul = workspace files (memory, identity, skills, frameworks)
• Body = OpenClaw instance (runtime, config, cron jobs)
• Backup repo = Git repository holding the soul
• Transfer = clone soul into new body, restore config, rebuild runtime state
• $WORKSPACE = the agent's workspace directory (resolve via repo path in system prompt, or ~/.openclaw/workspace as fallback)
• openclaw-config-backup.json = exported OpenClaw config snapshot (channel tokens, API keys, runtime settings). Name it whatever you like — just keep it in the workspace and committed to the backup repo.

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:

• Identity files: IDENTITY.md, USER.md, SOUL.md
• Memory files: MEMORY.md, AGENTS.md, HEARTBEAT.md, NOW.md, SESSION-STATE.md
• State files: heartbeat-state.json
• Daily logs: memory/*.md (all of them)
• Skills: skills/ directory
• Framework files: any .md or .json strategy/framework files
• Config backup: the exported OpenClaw config JSON file

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:

• Channel tokens (Discord bot token, Telegram token, etc.)
• Channel settings (guilds, allowlists, DM policies, actions)
• API keys (web search, etc.)
• Tool settings (exec security level)
• Environment variables

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"