OpenClaw 配置备份与恢复策略
背景
OpenClaw 的 Git 仓库通常包含以下内容：
✅ 已备份的内容：
skills/- 自定义技能agents/- 子代理角色定义memory/- 记忆文件（日常日志 + 长期记忆）docs/- 文档资料cron/jobs.json- 定时任务配置（官方默认备份，.gitignore仅排除cron/runs/）AGENTS.md、SOUL.md、USER.md、HEARTBEAT.md等工作区配置文件
❌ 不备份的内容：
openclaw.json- 核心配置文件（含 API 密钥、频道凭证等敏感信息，被.gitignore排除）cron/runs/- 定时任务运行记录（临时文件，被.gitignore排除）
⚠️ 注意：
cron/jobs.json虽然有备份，但它是运行时配置。Gateway 重启或某些异常情况可能导致运行时配置丢失（git 备份还在）。因此 RESTORE.md 中仍需包含 cron 恢复指令，作为双重保障。📌 核心痛点：换设备恢复 Git 备份后，所有技能、记忆、文档都在，但 openclaw.json 配置全部丢失（模型选择、子代理设置、频道开关、插件列表等），用户很难记住曾经做过哪些自定义修改。
解决方案
OpenClaw 自动维护一份 RESTORE.md —— 声明式的配置恢复指令文档。它随 Git 一起备份，新设备恢复后交给 OpenClaw 执行即可完整还原。
RESTORE.md 格式示范
## 子代理配置
在 openclaw.json 中配置：
- agents.defaults.subagents.maxConcurrent = 3
- agents.defaults.subagents.model = "your-model-name"
...
## 模型配置
在 openclaw.json 中配置：
- agents.defaults.model.primary = "your-primary-model"
...
## 频道配置 [含敏感项]
在 openclaw.json 中配置：
- channels.feishu.appId = [询问用户：飞书 appId]
- channels.feishu.appSecret = [询问用户：飞书 appSecret]
...
## 定时任务 (Cron)
执行以下命令恢复定时任务：
```bash
openclaw cron add --name task-name --cron '0 9 * * 1-5' --message '[触发词]' --channel feishu
或直接复制备份的 cron/jobs.json 到 ~/.openclaw/cron/ 目录后重启 gateway
> **格式规则**：
> - 按领域分 `##` 标题：子代理、模型、工具、频道、插件
> - 每个 section 描述**当前状态**，不是变更历史
> - 敏感项（API 密钥、密码等）用 `[询问用户：描述]` 占位，恢复时交互获取
> - 不记录的配置：gateway.*、meta.*、commands.*、session.*、messages.*（安装时已确定）
---
## 更新机制
### 触发时机
| 时机 | 说明 |
|------|------|
| **实时更新** | 用户通过对话修改配置时，立即同步更新 RESTORE.md |
| **备份前校验** | 每次 `git commit/push` 前，自动对比 openclaw.json 与 RESTORE.md，有差异先更新再提交 |
### 更新方式
- 找到对应 `##` section → 整体替换
- 不存在 → 末尾新增
- 更新"最后更新"日期
- **禁止**：只做加法、保留历史值、同一配置项多版本
---
## 配置恢复完整流程
### 步骤一：现有设备部署策略
在**正在使用的 OpenClaw** 终端执行一键部署指令（见下文），完成以下操作：
- 创建 `RESTORE.md` 文件
- 在 `AGENTS.md` 中添加配置维护规则
- 创建 `docs/BACKUP-STRATEGY.md` 简化版规则
部署后，对 OpenClaw 说：
> **"读取你的 openclaw.json，填充 RESTORE.md"**
OpenClaw 会自动解析当前配置，生成 RESTORE.md。之后执行 `git add . && git commit && git push` 完成备份。
### 步骤二：新设备安装 OpenClaw
1. **安装 OpenClaw**：按照官方文档安装新设备
2. **手动调试**：确保对话功能正常（测试模型、频道等基础功能）
3. **上传备份文档**：将 Git 仓库克隆到 `~/.openclaw/workspace/`，或手动复制备份文件
### 步骤三：对话框内激活恢复
在新设备的对话框中对 OpenClaw 说：
> **"按照 RESTORE.md 恢复配置"**
OpenClaw 会：
1. 逐个 section 处理
2. 普通配置直接写入 openclaw.json
3. 敏感项（API 密钥等）逐个询问是否需要配置，可跳过
4. 全部完成后重启 gateway
---
## 日常使用
### 多设备协作规则
当本地和服务器共用同一个 Git 仓库备份时，遵循以下规则：
> **📌 核心原则：用前 pull，用后 push**
| 场景 | 操作流程 |
|------|----------|
| 使用服务器 OpenClaw | 1. `git pull` 取回最新备份 → 2. 正常使用 → 3. 用后 `git add . && git commit && git push` |
| 使用本地 OpenClaw | 1. `git pull` 取回最新备份 → 2. 正常使用 → 3. 用后 `git add . && git commit && git push` |
> **⚠️ 为什么重要**：
> - 不 pull 就用 → 可能覆盖对方的最新修改
> - 不 push 就走 → 对方看不到你的更新
**冲突处理**：
如果 pull 时有冲突，手动解决后再 commit。常见冲突文件：
- `memory/YYYY-MM-DD.md` - 合并两边的记录
- `AGENTS.md` - 保留两边的规则
### 自动化
- OpenClaw 每次新会话自动读取 AGENTS.md，策略即刻生效
- 服务器可通过 cron 定时自动备份（`~/.openclaw/sync-push.sh`）
- 从 Git 取回备份后，建议手动触发一次校验：
> "读取你的 openclaw.json，对照 RESTORE.md，检查差异并更新"
---
## 一键部署指令
复制以下完整内容，在 OpenClaw 终端执行：
```bash
W=~/.openclaw/workspace && mkdir -p "$W/docs" && \
grep -q '配置文档维护' "$W/AGENTS.md" 2>/dev/null || cat >> "$W/AGENTS.md" << 'A'
## 配置文档维护（RESTORE.md）
你负责维护 `RESTORE.md`，这是一份可自执行的配置恢复指令文档。完整规则详见 `docs/BACKUP-STRATEGY.md`。
日常只需记住：
1. **实时**：当用户要求修改 openclaw.json 配置时，按 `docs/BACKUP-STRATEGY.md` 中的规则同步更新 RESTORE.md
2. **备份前校验**：每次执行 git commit/push 前，先读取 openclaw.json 与 RESTORE.md 对比，有差异则先更新再提交
A
cat > "$W/docs/BACKUP-STRATEGY.md" << 'B'
# OpenClaw 配置备份策略
## RESTORE.md 格式
- 声明式，按领域分 `## ` section：子代理、模型、工具、频道、插件
- 每个 section 描述当前状态，不是变更历史
- 敏感项（API 密钥等）用 `[询问用户：描述]` 占位
## 更新规则
- 触发：对话修改配置时实时更新 + git commit/push 前自动校验
- 方式：找到对应 `## ` section 整体替换；不存在则末尾新增；更新最后更新日期
- 禁止：只做加法、保留历史值、同一配置项多版本
## 不记录的配置（安装时已确定）
- gateway.*、meta.*、commands.*、session.*、messages.*、cron.enabled
## 恢复执行
用户说"按照 RESTORE.md 恢复配置"时：
1. 逐个 section 处理
2. 普通 section → 直接写入 openclaw.json
3. 含敏感项 section → 逐个询问"是否需要配置？"，可跳过
4. 用户选择配置的项，交互获取密钥
5. 全部完成后重启 gateway
B
[ -f "$W/RESTORE.md" ] || cat > "$W/RESTORE.md" << 'C'
# OpenClaw 配置恢复指令
> 本文档由 OpenClaw 自动维护，反映 openclaw.json 中用户主动修改的当前状态。
> 最后更新：（待首次更新）
C
echo "deploy complete"
