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"