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.