OpenClaw Checkpoint - Personal AI Assistant Backup & Recovery (Github)

# OpenClaw Checkpoint Skill

跨机器备份和还原您的 OpenClaw 身份、记忆、代理和配置。

**平台：** 仅限 macOS 和 Linux。不支持 Windows。

## 概述

此技能通过将您的工作区和代理同步到 git 仓库，为 OpenClaw 提供灾难恢复功能。它保留了：

- **身份**：SOUL.md、IDENTITY.md、USER.md（您和助手是谁） - **记忆**：MEMORY.md 和 memory/*.md 文件（对话历史和上下文） - **Cron 作业**：导出到 memory/cron-jobs-backup.json 的计划任务（晨间简报、每日同步、自动化） - **配置**：TOOLS.md、AGENTS.md、HEARTBEAT.md（工具设置和约定） - **脚本**：您构建的自定义工具和自动化 - **代理**：来自 ~/.openclaw/agents/ 的所有代理文件夹（alex、blake 等）

**未同步**（安全）：API 密钥（.env.*）、凭据、OAuth 令牌

## 安装

### 选项 1：Git 克隆（推荐）

```bash # Clone the skill repo git clone https://github.com/AnthonyFrancis/openclaw-checkpoint.git ~/.openclaw/skills/openclaw-checkpoint

# Copy scripts to tools directory mkdir -p ~/.openclaw/workspace/tools cp ~/.openclaw/skills/openclaw-checkpoint/scripts/checkpoint* ~/.openclaw/workspace/tools/ chmod +x ~/.openclaw/workspace/tools/checkpoint*

# Add to PATH (also add to ~/.zshrc or ~/.bashrc for persistence) export PATH="${HOME}/.openclaw/workspace/tools:${PATH}"

# Run setup wizard checkpoint-setup ```

### 选项 2：快速安装

```bash curl -fsSL https://raw.githubusercontent.com/AnthonyFrancis/openclaw-checkpoint/main/scripts/install-openclaw-checkpoint.sh | bash ```

这将运行安装脚本 —— 如果您希望在执行前进行检查，请先审查它。

## 命令

### checkpoint **显示所有可用命令和用法示例。**

```bash checkpoint ```

**作用：** - 显示所有检查点命令的快速参考，包含描述和示例

**使用时机：** - 当您记不清确切的命令名称时 - 可用选项的快速参考

### checkpoint-setup **用于首次设置的交互式入职流程。**

```bash checkpoint-setup ```

**作用：** - 指导您创建一个私有的 GitHub 仓库 - 设置 SSH 认证（推荐）或个人访问令牌 - 自动检测 SSH 密钥是否已在 GitHub 上授权 - 检测 `~/.openclaw/agents/` 中的代理并报告它们将被包含在备份中 - 生成包含恢复说明和命令的 README.md - 提交 `~/.openclaw/workspace` 中的工作区文件（通过 .gitignore 排除机密） - 配置自动备份 - 测试备份系统 - 显示最终状态

**使用时机：** - 首次设置检查点系统时 - 安装此技能后 - 运行 `checkpoint-reset` 之后 - 新用户的推荐起点

### checkpoint-auth **与 GitHub 进行认证（基于浏览器）。**

```bash checkpoint-auth ```

**作用：** - 选项 1：GitHub CLI（自动打开浏览器） - 选项 2：个人访问令牌（会过期，需要续期） - 选项 3：SSH 密钥（推荐 - 无令牌过期） - 自动将 GitHub 添加到 known_hosts - 设置完成后测试认证

**使用时机：** - 认证过期或失败时 - 切换认证方法时 - 在新机器上设置时

**推荐使用 SSH**，因为： - 无需担心令牌过期 - 无需密码提示即可可靠工作 - GitHub 不再接受 HTTPS 的密码认证

### checkpoint-backup

将当前状态保存到远程仓库。

```bash checkpoint-backup # Backup workspace + all agents checkpoint-backup --workspace-only # Backup workspace only (skip agents) checkpoint-backup --agents-only # Backup agents only (skip workspace/cron) checkpoint-backup --agent alex # Backup only the 'alex' agent (+ workspace) ```

**作用：** - 将 OpenClaw cron 作业备份到 `memory/cron-jobs-backup.json`（需要 `openclaw` CLI 和正在运行的网关） - 将 `~/.openclaw/agents/` 中的代理文件夹复制到工作区仓库的 `agents/` 中（去除嵌套的 `.git` 目录） - 标准化主目录路径（`$HOME` -> `{{HOME}}`）以实现跨机器可移植性 - 提交 ~/.openclaw/workspace 中的所有更改 - 推送到 origin/main - 显示提交哈希和时间戳

**代理备份详细信息：** - 自动检测 `~/.openclaw/agents/` 中的代理（例如 alex、blake） - 每个代理文件夹被复制到备份仓库的 `agents/<name>/` - 嵌套的 `.git` 目录被移除以避免子模块问题 - 如果不存在代理，则优雅地跳过并显示信息消息 - 可用时使用 `rsync --exclude='.git'`，否则回退到 `cp -r` + 手动移除 `.git`

**Cron 作业备份详细信息：** - 运行 `openclaw cron list --json` 以导出所有计划任务 - 剥离运行时状态，仅保留配置（名称、计划、目标、负载） - 非阻塞：如果 CLI 或网关不可用，checkpoint-backup 将继续执行而不进行 cron 备份

**标志：** - `--workspace-only` — 跳过代理备份 - `--agents-only` — 跳过工作区和 cron 备份，仅备份代理 - `--agent <name>` — 仅备份单个指定名称的代理

**使用时机：** - 切换计算机之前 - 重大更改之后（新记忆、更新的 SOUL.md） - 任何时候您想要确保更改已保存时

### checkpoint-schedule

设置具有可配置频率的自动备份。

```bash checkpoint-schedule 15min # Every 15 minutes checkpoint-schedule 30min # Every 30 minutes checkpoint-schedule hourly # Every hour (default) checkpoint-schedule 2hours # Every 2 hours checkpoint-schedule 4hours # Every 4 hours checkpoint-schedule daily # Once per day at 9am checkpoint-schedule disable # Turn off auto-backup ```

**作用：** - macOS：创建 launchd plist 以实现可靠的后台备份 - Linux：添加 cron 作业以进行计划备份 - 将所有活动记录到 ~/.openclaw/logs/checkpoint.log

**使用时机：** - 首次设置：`checkpoint-schedule hourly` - 更改频率：`checkpoint-schedule 15min` - 停止备份：`checkpoint-schedule disable`

### checkpoint-status

检查备份健康状况和状态。

```bash checkpoint-status ```

**它显示：** - 上次备份时间和提交 - 本地是否落后于远程 - 未提交的更改 - 代理备份状态（哪些代理已备份，哪些缺失） - 自动备份计划状态 - 最近的备份活动日志

**使用时机：** - 切换机器之前（验证已同步） - 排查备份问题时 - 定期健康检查

### checkpoint-restore

从远程仓库还原状态，支持检查点选择和首次设置。

```bash checkpoint-restore # Select from recent checkpoints (interactive) checkpoint-restore --latest # Restore most recent checkpoint (skip selection) checkpoint-restore --force # Discard local changes before restoring checkpoint-restore --workspace-only # Restore workspace only (skip agents) checkpoint-restore --agents-only # Restore agents only (skip workspace/cron) checkpoint-restore --agent alex # Restore only the 'alex' agent ```

**作用：** - **首次用户：** 启动交互式还原入职流程 - 指导您完成 GitHub 认证（SSH、GitHub CLI 或 PAT） - 让您指定现有的备份仓库 - 验证访问权限并还原您的检查点 - 如果存在本地文件，处理合并/替换选项 - 显示可用的检查点以供选择（如果仓库有多个提交） - 提供从备份还原 cron 作业 - 提供从备份还原代理 - **回头用户：** 显示最近 10 个检查点的列表以供选择 - 选择最新或任何较旧的检查点进行还原 - 当前检查点在列表中标记 - 还原较旧的检查点会警告下次备份将覆盖较新的远程检查点 - 使用 `--latest` 标志跳过交互式选择并自动还原最新的检查点 - **未提交的更改：** 如果您有本地未提交的更改，系统会提示您： 1. 先保存更改（运行 `checkpoint-backup`） 2. 放弃本地更改并继续还原 3. 取消 - **路径可移植性：** 自动展开 `{{HOME}}` 占位符并为当前机器重写旧的主目录路径 - **Cron 作业：** 还原后自动提供从 `memory/cron-jobs-backup.json` 还原 cron 作业（需要 OpenClaw 网关正在运行） - **代理：** 提供将备份中的 `agents/` 目录还原到 `~/.openclaw/agents/`

**标志：** - `--latest` — 跳过选择，还原最近的检查点 - `--force` — 放弃本地更改且不提示 - `--workspace-only` — 跳过代理还原 - `--agents-only` — 跳过工作区和 cron 还原，仅还原代理 - `--agent <name>` — 仅还原单个指定名称的代理

**使用时机：** - 在新机器上启动 OpenClaw - 硬件故障/灾难之后 - 在不同计算机上恢复工作时 - 从现有备份首次还原 - 在进行不需要的更改后回滚到以前的检查点

**以下情况会触发入职流程：** - 不存在工作区 - 工作区存在但不是 git 仓库 - Git 仓库存在但未配置远程

### checkpoint-init

为检查点系统初始化工作区。

```bash checkpoint-init ```

**作用：** - 在 ~/.openclaw/workspace 中创建 git 仓库 - 生成 .gitignore（排除机密和临时文件） - 创建初始提交

**使用时机：** - 首次设置检查点系统时 - 从备份还原到新机器后

### checkpoint-reset

重置检查点系统以进行全新设置。

```bash checkpoint-reset ```

**作用：** - 选项 1：仅删除本地 git 仓库（保留 SSH 密钥） - 选项 2：删除所有内容（git 仓库 + SSH 密钥 + known_hosts 中的 GitHub） - 提供从工作区 `agents/` 文件夹中删除代理的备份副本 - 提醒您手动删除 GitHub 仓库

注意：重置绝不会触及您在 `~/.openclaw/agents/` 中的实际代理文件夹 —— 仅触及备份副本。

**使用时机：** - 重新开始全新设置时 - 切换到不同的 GitHub 仓库时 - 排查持续的认证问题时

### checkpoint-stop

停止自动备份。

```bash checkpoint-stop ```

**作用：** - 禁用计划的自动备份 - 移除 cron 作业或 launchd 代理（macOS）

**使用时机：** - 暂时暂停备份 - 在进行重大工作区更改之前 - 如果备份导致问题

**要重新启动：** `checkpoint-schedule hourly`（或任何频率）

## 设置

### 简易设置（推荐）

只需运行交互式向导：

```bash checkpoint-setup ```

这将处理所有事情：git init、SSH 密钥、GitHub 设置和首次备份。

### 首次设置（手动）

```bash # 1. Initialize checkpoint system checkpoint-init

# 2. Create PRIVATE GitHub repository # Go to https://github.com/new # Name: openclaw-state # ⚠️ Visibility: PRIVATE (important - contains your personal data!)

# 3. Add remote (use SSH, not HTTPS) cd ~/.openclaw/workspace git remote add origin [email protected]:YOURUSER/openclaw-state.git checkpoint-backup ```

### 在第二台机器上设置

**选项 1：交互式还原（推荐）**

```bash # Install the checkpoint skill first curl -fsSL https://raw.githubusercontent.com/AnthonyFrancis/openclaw-checkpoint/main/scripts/install-openclaw-checkpoint.sh | bash

# Run checkpoint-restore - it will guide you through the entire process checkpoint-restore ```

这将： - 帮助您与 GitHub 进行认证（如果尚未认证） - 询问您的备份仓库详细信息 - 自动克隆/还原您的检查点

**选项 2：手动克隆**

```bash # 1. Clone repository (use SSH) git clone [email protected]:YOURUSER/openclaw-state.git ~/.openclaw/workspace

# 2. Restore secrets from 1Password/password manager # Create ~/.openclaw/workspace/.env.thisweek # Create ~/.openclaw/workspace/.env.stripe # (Copy from secure storage)

# 3. Start OpenClaw openclaw gateway start ```

## 自动备份

### 简易设置（推荐）

```bash # Enable hourly backups checkpoint-schedule hourly

# Or choose your frequency: checkpoint-schedule 15min # Every 15 minutes - high activity checkpoint-schedule 30min # Every 30 minutes - medium activity checkpoint-schedule 2hours # Every 2 hours - low activity checkpoint-schedule daily # Once per day - minimal activity ```

### 检查状态

```bash checkpoint-status ```

显示： - 上次备份时间 - 是否与远程同步 - 自动备份计划 - 最近的 activity 日志

## 多代理备份

检查点系统会自动检测并备份 `~/.openclaw/agents/` 中的所有代理。

### 工作原理

- **备份时**：Agent 文件夹会从 `~/.openclaw/agents/` 复制到备份仓库内的 `agents/` 中，并移除嵌套的 `.git` 目录 - **恢复时**：Agent 文件夹会从备份仓库内的 `agents/` 复制回 `~/.openclaw/agents/` - 如果不存在任何 agents，所有命令都会优雅地跳过 agent 处理

### 备份仓库中的文件结构

``` ~/.openclaw/workspace/ (backup repo root) SOUL.md MEMORY.md memory/ agents/ (auto-created when agents exist) alex/ (copied from ~/.openclaw/agents/alex/) blake/ (copied from ~/.openclaw/agents/blake/) ```

### Agent 标志

这些标志适用于 `checkpoint-backup` 和 `checkpoint-restore`：

| 标志 | 描述 | |------|-------------| | `--workspace-only` | 完全跳过 agent 的备份/恢复 | | `--agents-only` | 跳过工作区和 cron，仅对 agents 进行操作 | | `--agent <name>` | 仅对指定名称的单个 agent 进行操作 |

### 示例

```bash # Backup everything (default) checkpoint-backup

# Backup only agents checkpoint-backup --agents-only

# Backup only the 'alex' agent checkpoint-backup --agent alex

# Restore workspace but skip agents checkpoint-restore --latest --workspace-only

# Restore only agents from backup checkpoint-restore --agents-only

# Check which agents are backed up checkpoint-status ```

### 向后兼容性

- 如果 `~/.openclaw/agents/` 不存在或为空，所有命令都会跳过 agent 处理并显示一条信息提示 - 没有包含 `agents/` 目录的旧备份仓库可以正常工作——恢复操作会直接跳过 agents - 当不存在 agents 时，不会改变任何现有行为

## 跨机器可移植性

当你在一台机器上（例如 `/Users/jerry`）备份，并在另一台机器上（例如 `/Users/tom`）恢复时，工作区文件中硬编码的绝对主目录路径会失效。Checkpoint 系统会自动处理此问题。

### 工作原理

- **备份时**：文本文件中所有出现的 `$HOME` 路径（例如 `/Users/jerry`）都会被替换为占位符 `{{HOME}}`。系统会写入一个 `.checkpoint-meta.json` 文件，其中包含源机器的详细信息。 - **恢复时**：`{{HOME}}` 占位符会被展开为当前机器的 `$HOME`（例如 `/Users/tom`）。为了与规范化之前创建的旧备份保持向后兼容，任何剩余的字面量旧主目录路径也会被重写。

### 处理范围

仅扫描可能包含路径的文本文件： - `*.md`、`*.json`、`*.sh`、`*.txt`、`*.yaml`、`*.yml`、`*.toml`、`*.cfg`、`*.conf`

二进制文件、`.git/` 和 `node_modules/` 永远不会被修改。

### .checkpoint-meta.json

该文件在每次备份时自动生成，并记录源机器信息：

```json { "source_home": "/Users/jerry", "source_user": "jerry", "hostname": "Jerrys-MacBook-Pro" } ```

恢复时，此元数据会告知脚本要重写哪些旧路径。恢复后，该文件会被更新以反映当前机器的信息。

### 手动 Cron 设置（高级）

如果你更喜欢手动设置 cron：

```bash # Edit crontab crontab -e

# Add line for hourly backups: 0 * * * * /Users/$(whoami)/.openclaw/workspace/skills/openclaw-checkpoint/scripts/checkpoint-backup >> ~/.openclaw/logs/checkpoint.log 2>&1 ```

## 灾难恢复工作流

**场景：家庭服务器宕机**

```bash # On new machine:

# 1. Install OpenClaw brew install openclaw # or your install method

# 2. Install checkpoint skill and run interactive restore curl -fsSL https://raw.githubusercontent.com/AnthonyFrancis/openclaw-checkpoint/main/scripts/install-openclaw-checkpoint.sh | bash checkpoint-restore # Follow the interactive prompts to: # - Authenticate with GitHub # - Enter your backup repository (e.g., YOURUSER/openclaw-state) # - Restore your checkpoint

# 3. Restore secrets from 1Password (API keys are not backed up for security) cat > ~/.openclaw/workspace/.env.thisweek << 'EOF' THISWEEK_API_KEY=your_key_here EOF

# 4. Start OpenClaw openclaw gateway start

# 5. Cron jobs are restored automatically during checkpoint-restore # (if the gateway is running and cron backup exists)

# 6. Enable automatic backups on this machine checkpoint-schedule hourly

# 7. Verify # Ask assistant: "What were we working on?" # Should recall everything up to last checkpoint, with all scheduled tasks restored ```

## 安全注意事项

### ⚠️ 关键：仓库必须设为 PRIVATE

你的备份包含敏感的个人数据： - SOUL.md、MEMORY.md（你的身份和记忆） - 个人笔记和对话历史 - 自定义脚本和配置

**如果你将仓库设为公开，任何人都可以看到你的数据！**

**备份的内容：** - ✅ 记忆文件（对话历史） - ✅ 身份文件（SOUL.md 等） - ✅ Cron 任务（memory/cron-jobs-backup.json） - ✅ 脚本和工具 - ✅ 配置 - ✅ Agents（~/.openclaw/agents/ -> 备份仓库中的 agents/）

**不会备份的内容：** - ❌ API 密钥（.env.*）——请存放在 1Password 中 - ❌ OAuth 令牌——需在新机器上重新进行身份验证 - ❌ 下载的媒体文件——临时的 - ❌ 临时文件——临时的

**最佳实践：** - **始终使用 PRIVATE 仓库** - 使用 SSH 身份验证（无令牌过期） - 将 API 密钥存放在密码管理器中，而不是在备份文件中 - 在 GitHub 账户上启用 2FA - 考虑在将敏感笔记添加到记忆之前进行加密

### 权限和调度

该技能使用标准系统调度来自动执行备份：

- **macOS**：在 `~/Library/LaunchAgents/com.openclaw.checkpoint.plist` 创建一个 launchd plist 文件 - **Linux**：添加一个用户级 cron 任务（可通过 `crontab -l` 查看）

自动备份是**选择性启用（opt-in）**的——除非你明确运行 `checkpoint-schedule`，否则永远不会启用它。你可以随时通过 `checkpoint-stop` 或 `checkpoint-schedule disable` 禁用它。

该技能**不会**安装任何后台守护进程、系统服务或 root 级进程。所有调度任务都在你的用户账户下运行。

**文件访问范围**：该技能从 `~/.openclaw/workspace` 和 `~/.openclaw/agents/`（用于多 agent 备份）读取数据。它会将 agents 的备份副本写入 `~/.openclaw/workspace/agents/`。恢复时，它会将 agents 复制回 `~/.openclaw/agents/`。敏感文件（.env.*、凭据、OAuth 令牌）会通过 .gitignore 从备份中排除。

## 故障排除

### “Not a git repository”或“'origin' does not appear to be a git repository”

现在运行 `checkpoint-restore` 将自动启动交互式恢复入门流程，以帮助你连接到备份仓库。或者，运行 `checkpoint-setup` 从头创建一个新的备份。

### “Failed to push checkpoint”

另一台机器推送了更改。请先运行 `checkpoint-restore`，然后再运行 `checkpoint-backup`。

### “You have uncommitted changes”

`checkpoint-restore` 会提示你选择： 1. 先保存更改（运行 `checkpoint-backup`） 2. 丢弃本地更改并继续 3. 取消

你也可以通过 `checkpoint-restore --force` 跳过提示，直接丢弃更改。

### 恢复后落后于远程仓库

如果你上次同步后另一台机器进行了 checkpoint，这是预期行为。

### GitHub 提示输入用户名/密码

GitHub 不再接受 HTTPS 的密码验证。请切换到 SSH：

```bash cd ~/.openclaw/workspace git remote set-url origin [email protected]:YOURUSER/REPO.git ```

### “Host key verification failed”

GitHub 的 SSH 主机密钥不在你的 known_hosts 中。修复方法：

```bash ssh-keyscan -t ed25519 github.com >> ~/.ssh/known_hosts ```

### “Permission denied (publickey)”

你的 SSH 密钥尚未添加到 GitHub。请运行 `checkpoint-auth` 并选择 SSH 选项。

### 设置后 GitHub 仓库为空

旧的 `checkpoint-init` 仅提交了 `.gitignore`。现已修复。请运行：

```bash cd ~/.openclaw/workspace && git add -A && git commit -m "Full backup" && git push ```

### 重新开始

运行 `checkpoint-reset` 删除本地 git 仓库并可选择删除 SSH 密钥，然后运行 `checkpoint-setup`。

### Agents 未被备份

请检查你的 agents 是否位于 `~/.openclaw/agents/`（而非其他位置）。运行 `checkpoint-status` 查看检测到了哪些 agents 以及备份了哪些。请确保你没有传递 `--workspace-only`。

### Agent 存在嵌套的 .git 错误

备份过程会自动从 agent 副本中移除 `.git` 目录。如果你看到子模块警告，请运行一次全新的备份：

```bash rm -rf ~/.openclaw/workspace/agents checkpoint-backup ```

### 恢复的 Agents 缺失文件

Agent 恢复会按原样复制备份。如果备份是在某些文件添加到 agent 之前创建的，这些文件将不存在。请先在源机器上运行 `checkpoint-backup` 以捕获最新状态。

### 在新机器上恢复后出现“Permission denied, mkdir '/Users/olduser'”

这意味着文件包含来自原始机器的硬编码路径。如果备份是在添加路径规范化功能之前创建的，请运行：

```bash cd ~/.openclaw/workspace grep -rl "/Users/olduser" --include="*.md" --include="*.json" --include="*.sh" | \ xargs sed -i '' "s|/Users/olduser|$HOME|g" ``` 未来的备份将自动规范化路径。

### 文件显示 {{HOME}} 而非真实路径

这在 **GitHub 上的备份仓库中**是预期行为。`{{HOME}}` 占位符会在每次恢复时被替换为真实的 `$HOME` 路径。如果你在恢复后的本地工作区中看到 `{{HOME}}`，请再次运行 `checkpoint-restore --latest`。

## 限制

- **一次仅限一台机器**：不要同时在多台机器上运行 OpenClaw - **最大数据丢失量**：如果使用每小时备份（cron），最多丢失 1 小时的数据 - **不同步机密**：必须在新机器上手动恢复 API 密钥 - **大文件**：GitHub 有 100MB 的文件限制（你的文本文件不受影响）

## 文件参考

有关详细的设置说明，请参阅 [references/setup.md](references/setup.md)。