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
CODEBLOCK0
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
CODEBLOCK1
4. Verify backup
CODEBLOCK2
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
CODEBLOCK3
Step 2: Audit contents
Before restoring, review what's in the repo:
CODEBLOCK4
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, INLINECODE9 - Memory files:
MEMORY.md, AGENTS.md, HEARTBEAT.md, NOW.md, INLINECODE14 - State files: INLINECODE15
- 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
CODEBLOCK5
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:
CODEBLOCK6
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
CODEBLOCK7
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. - Over-scrubbing credentials — Don't scrub the config backup JSON; it's needed for config.patch. Only scrub credentials embedded in markdown/log files.
- Forgetting cron rebuild — Cron is runtime state, not in git.
- Old vs new config schema — Use
config.schema.lookup to verify field names before patching. OpenClaw versions may rename fields. - Git remote not configured — New instance has no remote; configure before first backup push.
Backup Health Check
Run periodically to verify backup integrity:
CODEBLOCK8
Soul Transfer (夺舍)
通过 Git 在 OpenClaw 实例之间迁移工作空间。
概念
- - 灵魂 = 工作空间文件（记忆、身份、技能、框架）
- 身体 = OpenClaw 实例（运行时、配置、定时任务）
- 备份仓库 = 存放灵魂的 Git 仓库
- 转移 = 将灵魂克隆到新身体，恢复配置，重建运行时状态
- $WORKSPACE = 代理的工作空间目录（通过系统提示中的仓库路径解析，或回退到 ~/.openclaw/workspace）
- openclaw-config-backup.json = 导出的 OpenClaw 配置快照（频道令牌、API 密钥、运行时设置）。可任意命名——只需将其保留在工作空间中并提交到备份仓库。
备份流程
1. 确保 Git 远程已配置
bash
cd $WORKSPACE
git remote get-url origin || git remote add origin https://@github.com//.git
2. 导出当前 OpenClaw 配置
保存一份当前配置的副本，以便将来恢复。此文件包含频道令牌、API 密钥和公会设置，这些内容不在工作空间的 Markdown 文件中。
使用 gateway config.get 工具 → 提取 parsed 对象 → 写入工作空间中的 JSON 文件（例如 openclaw-config-backup.json）。
此步骤至关重要——没有此文件，新实例上的频道连接将无法恢复。
3. 提交并推送
bash
git add -A
git commit -m backup: $(date +%Y-%m-%d_%H%M)
git push origin master
4. 验证备份
bash
git log --oneline -1
git diff --stat HEAD~1
备份定时任务（自动化）
设置定期定时任务以自动备份。参见 references/cron-templates.md 获取可直接使用的定义。
恢复流程（夺舍清单）
按顺序执行以下步骤。不要跳过第 5 步——这是最常被遗忘的步骤。
步骤 1：克隆备份仓库
bash
git clone https://@github.com//.git /tmp/soul-backup
步骤 2：审计内容
在恢复之前，检查仓库中的内容：
bash
find /tmp/soul-backup -type f | wc -l
cat /tmp/soul-backup/IDENTITY.md
识别不应复制到 Markdown 的敏感文件：独立的凭证文件（API 令牌、密钥文件等）
步骤 3：恢复工作空间文件
将核心文件从备份复制到 $WORKSPACE：
- - 身份文件：IDENTITY.md、USER.md、SOUL.md
- 记忆文件：MEMORY.md、AGENTS.md、HEARTBEAT.md、NOW.md、SESSION-STATE.md
- 状态文件：heartbeat-state.json
- 每日日志：memory/*.md（全部）
- 技能：skills/ 目录
- 框架文件：任何 .md 或 .json 策略/框架文件
- 配置备份：导出的 OpenClaw 配置 JSON 文件
步骤 4：从 Markdown 文件中清除硬编码凭证
bash
扫描凭证模式
grep -rl ghp_\|AKIA[0-9A-Z]\|sk-[a-zA-Z0-9] $WORKSPACE/ \
--include=*.md 2>/dev/null
将 Markdown 和日志文件中找到的凭证替换为 [REDACTED]。
不要清除配置备份 JSON——它包含第 5 步所需的凭证。
步骤 5：恢复 OpenClaw 配置（⚠️ 关键——不要跳过）
此步骤连接频道、API 密钥和运行时设置。没有它，所有频道将保持断开状态。
从工作空间读取配置备份 JSON。提取：
- - 频道令牌（Discord 机器人令牌、Telegram 令牌等）
- 频道设置（公会、白名单、私信策略、操作）
- API 密钥（网络搜索等）
- 工具设置（执行安全级别）
- 环境变量
通过 gateway config.patch 应用：
json
{
channels: {
discord: {
enabled: true,
token: <来自配置备份>,
groupPolicy: allowlist,
guilds: { ... },
dm: { ... },
actions: { ... }
}
},
tools: {
web: { search: { apiKey: <来自配置备份> } },
exec: { security: full }
}
}
修补后，OpenClaw 会自动重启。使用 openclaw status 验证——频道应显示已连接。
如果 OpenClaw 版本与备份不同，使用 config.schema.lookup 检查字段名称。
步骤 6：重建定时任务
定时任务是运行时状态，不存储在 Git 中。从文档列表或 references/cron-templates.md 重建。
对每个任务使用 cron add。仅恢复仍然需要的任务。
步骤 7：验证并清理
bash
验证频道连接
openclaw status
删除临时克隆
rm -rf /tmp/soul-backup
如果存在 BOOTSTRAP.md，则删除（不再是新实例）
rm -f $WORKSPACE/BOOTSTRAP.md
提交恢复后的状态
cd $WORKSPACE
git add -A && git commit -m 夺舍完成: $(date +%Y-%m-%d_%H%M)
步骤 8：记录事件
在今天的每日日志中记录转移，包含时间戳、文件计数和遇到的任何问题。
常见陷阱
- 1. 跳过配置恢复 — 工作空间文件恢复记忆但不恢复频道连接。配置备份 JSON → config.patch 是强制性的。
- 过度清除凭证 — 不要清除配置备份 JSON；它用于 config.patch。仅清除嵌入在 Markdown/日志文件中的凭证。
- 忘记重建定时任务 — 定时任务是运行时状态，不在 Git 中。
- 新旧配置架构差异 — 在修补前使用 config.schema.lookup 验证字段名称。OpenClaw 版本可能重命名字段。
- Git 远程未配置 — 新实例没有远程；在首次备份推送前进行配置。
备份健康检查
定期运行以验证备份完整性：
bash
cd $WORKSPACE
检查远程是否已配置
git remote -v
检查上次推送时间
git log --oneline -1
检查未提交的更改
git status --short
验证配置备份是否存在并包含频道令牌
grep -c token openclaw-config-backup.json 2>/dev/null || echo ⚠️ 未找到配置备份
