灵魂转移（夺舍）

通过 Git 在不同 OpenClaw 实例之间迁移 Agent 工作区。

核心概念

• 灵魂（Soul） = 工作区文件（记忆、身份、技能、框架）
• 躯体（Body） = OpenClaw 实例（运行时、配置、定时任务）
• 备份仓库（Backup repo） = 存储“灵魂”的 Git 仓库
• 转移（Transfer） = 将“灵魂”克隆至新“躯体”，恢复配置，并重建运行时状态
• $WORKSPACE = Agent 的工作区目录（通过系统提示中的仓库路径解析，或默认回退至 ~/.openclaw/workspace）
• openclaw-config-backup.json = 导出的 OpenClaw 配置快照（含频道 token、API 密钥、运行时设置）。文件名可自定义，但必须置于工作区内并提交至备份仓库。

备份流程

1. 确保已配置 Git 远程仓库

cd $WORKSPACE
git remote get-url origin || git remote add origin https:///.git

2. 导出现有 OpenClaw 配置

保存一份当前活跃配置副本，用于后续恢复。该文件包含频道 token、API 密钥及服务器设置等信息，这些内容不会出现在工作区的 Markdown 文件中。

使用 gateway config.get 工具 → 提取其中的 parsed 对象 → 写入工作区内的 JSON 文件（例如：openclaw-config-backup.json）。

此步骤至关重要——若缺失该文件，则无法在新实例上恢复频道连接。

3. 提交并推送

git add -A
git commit -m "backup: $(date +%Y-%m-%d_%H%M)"
git push origin master

4. 验证备份完整性

git log --oneline -1
git diff --stat HEAD~1

自动备份定时任务（cron）

配置周期性 cron 任务以实现自动备份。详见 references/cron-templates.md 中开箱即用的模板定义。

恢复流程（夺舍检查清单）

请严格按顺序执行以下步骤。切勿跳过第 5 步——这是最容易被遗漏的关键步骤。

第 1 步：克隆备份仓库

git clone https://@github.com//.git /tmp/soul-backup

第 2 步：审计仓库内容

恢复前，请先审查仓库中所含内容：

find /tmp/soul-backup -type f | wc -l
cat /tmp/soul-backup/IDENTITY.md

识别不应复制到 Markdown 文件中的敏感文件：独立凭证文件（如 API token、密钥文件等）。

第 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 文件中清除硬编码凭证

# 扫描凭证模式
grep -rl 'ghp_|AKIA[0-9A-Z]|sk-[a-zA-Z0-9]' $WORKSPACE/ \
  --include='*.md' 2>/dev/null

在 Markdown 和日志文件中，将扫描到的凭证替换为 [REDACTED]。

注意：不要清除配置备份 JSON 文件中的凭证——它将在第 5 步中被 config.patch 所必需。

第 5 步：恢复 OpenClaw 配置（⚠️ 至关重要 —— 不可跳过）

本步骤负责重建频道连接、注入 API 密钥及加载运行时设置。若跳过，所有频道将保持断开状态。

从工作区读取配置备份 JSON 文件，并提取以下字段：

• 频道 token（Discord bot token、Telegram token 等）
• 频道设置（服务器列表、白名单、私信策略、行为规则等）
• API 密钥（网络搜索等）
• 工具设置（如 exec 安全等级）
• 环境变量

通过 gateway config.patch 应用配置：

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "",
      "groupPolicy": "allowlist",
      "guilds": { "..." },
      "dm": { "..." },
      "actions": { "..." }
    }
  },
  "tools": {
    "web": { "search": { "apiKey": "" } },
    "exec": { "security": "full" }
  }
}

完成 patch 后，OpenClaw 将自动重启。可通过 openclaw status 验证——各频道状态应显示为已连接。

若当前 OpenClaw 版本与备份版本不一致，请使用 config.schema.lookup 查询字段名称是否变更。

第 6 步：重建定时任务（cron jobs）

cron 任务属于运行时状态，不会被 Git 跟踪。需依据文档记录或 references/cron-templates.md 重新构建。

对每个任务使用 cron add 命令添加。仅恢复当前仍需启用的任务。

第 7 步：验证并清理

# 验证频道连通性
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 是强制步骤。
2. 过度清除凭证——切勿清除配置备份 JSON 文件；它专为 config.patch 所准备。仅需清除嵌入在 Markdown/日志文件中的凭证。
3. 遗忘重建 cron 任务——cron 属于运行时状态，不存于 Git 中。
4. 新旧配置 Schema 不兼容——patch 前请务必使用 config.schema.lookup 核查字段名是否变更；不同 OpenClaw 版本可能重命名字段。
5. 未配置 Git 远程仓库——新实例默认无远程地址；首次推送备份前需手动配置。

备份健康检查

建议定期运行以下命令，验证备份完整性：

cd $WORKSPACE
# 检查是否已配置远程仓库
git remote -v
# 检查最近一次推送时间
git log --oneline -1
# 检查是否存在未提交更改
git status --short
# 验证配置备份文件是否存在且包含 token 字段
grep -c '"token"' openclaw-config-backup.json 2>/dev/null || echo "⚠️ 未找到配置备份文件"