soul-transfer
# 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
```bash
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
```bash
git add -A
git commit -m "backup: $(date +%Y-%m-%d_%H%M)"
git push origin master
```
### 4. Verify backup
```bash
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
```bash
git clone https://<token>@github.com/<owner>/<repo>.git /tmp/soul-backup
```
### Step 2: Audit contents
Before restoring, review what's in the repo:
```bash
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
```bash
# 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`:
```json
{
"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
```bash
# 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:
```bash
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"
```
标签
skill
ai
