OpenClaw 检查点技能

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

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

概述

该技能通过将您的工作空间和代理同步到 git 仓库，为 OpenClaw 提供灾难恢复功能。它保存以下内容：

• 身份: SOUL.md, IDENTITY.md, USER.md 文件（您和助手的身份信息）
• 记忆: MEMORY.md 和 memory/*.md 文件（对话历史和上下文）
• 定时任务: 导出到 memory/cron-jobs-backup.json 的预定任务（晨间简报、每日同步、自动化任务）
• 配置: TOOLS.md, AGENTS.md, HEARTBEAT.md 文件（工具设置和惯例）
• 脚本: 您构建的自定义工具和自动化脚本
• 代理: ~/.openclaw/agents/ 目录下的所有代理文件夹（例如 alex, blake 等）

不同步的内容（安全）：API密钥（.env.*）、凭证、OAuth令牌

安装

选项一：Git克隆（推荐）

# 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

选项二：快速安装

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

此操作会运行安装脚本——如果您希望在执行前检查脚本内容，请先审阅。

命令

checkpoint

显示所有可用命令及使用示例。

checkpoint

功能说明：

• 显示所有checkpoint命令的快速参考，包含描述和示例

使用场景：

• 当您记不清确切命令名称时
• 快速查看可用选项

checkpoint-setup

面向首次设置的交互式引导流程。

checkpoint-setup

功能说明：

• 引导您创建私有GitHub仓库
• 设置SSH身份验证（推荐）或个人访问令牌
• 自动检测SSH密钥是否已在GitHub完成授权
• 检测~/.openclaw/agents/目录中的代理，并报告它们将被包含在备份中
• 生成带有恢复说明和命令的 README.md 文件
• 提交工作空间文件，位于~/.openclaw/workspace目录内（通过 .gitignore 排除敏感信息）
• 配置自动备份
• 测试备份系统
• 显示最终状态

使用时机：

• 首次设置检查点系统时
• 安装此技能后
• 运行checkpoint-reset
• 命令后

新用户的推荐起点

checkpoint-auth

checkpoint-auth

通过 GitHub 进行身份验证（基于浏览器）。

• 功能说明：
• 选项1：GitHub CLI（自动打开浏览器）
• 选项3：SSH密钥（推荐 - 令牌永不过期）
• 自动将GitHub添加到known_hosts
• 设置后测试认证

使用场景：

• 认证过期或失败时
• 切换认证方法时
• 在新机器上设置时

推荐使用SSH原因：

• 无需担心令牌过期
• 可靠运行，无需密码提示
• GitHub不再接受HTTPS的密码认证

检查点备份

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

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定时任务备份至memory/cron-jobs-backup.json（需要openclawCLI及运行中的网关）
• 从以下目录复制代理文件夹：~/.openclaw/agents/进入代理/工作区仓库中（去除嵌套的.git目录）
• 规范化主目录路径（$HOME->{{HOME}}）以实现跨机器可移植性
• 提交 ~/.openclaw/workspace 中的所有更改
• 推送到 origin/main
• 显示提交哈希和时间戳

代理备份详情：

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

Cron任务备份详情：

• 运行openclaw cron list --json以导出所有计划任务
• 剥离运行时状态，仅保留配置（名称、计划、目标、有效载荷）
• 非阻塞：如果CLI或网关不可用，checkpoint-backup会继续执行而不备份cron任务

标志：

• --workspace-only— 跳过代理备份
• --agents-only— 跳过工作空间和cron备份，仅备份代理
• --agent <名称>— 仅备份单个指定名称的代理

使用场景：

• 在切换计算机之前
• 在发生重大更改后（新增记忆、更新了SOUL.md）
• 任何时候您想确保更改已保存

检查点计划

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

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

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

checkpoint-status

显示内容：

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

使用时机：

• 切换设备前（验证同步状态）
• 排查备份问题
• 定期健康检查

检查点恢复

从远程仓库恢复状态，支持检查点选择和首次载入配置

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）
  • 支持指定现有备份仓库
  • 验证访问权限并恢复检查点
  • 若存在本地文件，可处理合并/替换选项
  • 显示可选择的检查点（若仓库存在多次提交记录）
  • 提供从备份恢复定时任务的选项
  • 提供从备份恢复代理的选项
• 返回用户：显示可供选择的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 <名称>— 仅恢复单个指定名称的代理

使用时机：

• 在新机器上启动 OpenClaw
• 硬件故障/灾难发生后
• 在不同计算机上恢复工作时
• 从现有备份首次恢复
• 在发生意外更改后回滚到之前的检查点

入职流程在以下情况触发：

• 工作空间不存在
• 工作空间存在但不是 git 仓库
• Git 仓库存在但未配置远程仓库

checkpoint-init

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

checkpoint-init

其功能：

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

使用时机：

• 首次设置检查点系统时
• 从备份恢复到新机器后

checkpoint-reset

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

checkpoint-reset

其功能：

• 选项1：仅移除本地git仓库（保留SSH密钥）
• 选项2：移除所有内容（git仓库 + SSH密钥 + known_hosts中的GitHub记录）
• 提供从工作区移除已备份的智能体副本agents/文件夹
• 提醒您手动删除GitHub仓库

注意：重置操作永远不会触碰您在~/.openclaw/agents/中的实际智能体文件夹——仅涉及备份副本。

使用场景：

• 重新开始全新设置
• 切换到不同的GitHub仓库
• 排查持续存在的身份验证问题

checkpoint-stop

停止自动备份。

checkpoint-stop

功能说明：

• 禁用计划中的自动备份
• 移除cron任务（Linux）或launchd代理（macOS）

使用场景：

• 需要临时暂停备份时
• 在进行重大工作空间更改之前
• 如果备份导致问题

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

设置

简易设置（推荐）

只需运行交互式向导：

checkpoint-setup

它会处理所有事项：git 初始化、SSH 密钥、GitHub 设置和首次备份。

首次设置（手动）

# 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 git@github.com:YOURUSER/openclaw-state.git
checkpoint-backup

在第二台机器上设置

选项 1：交互式恢复（推荐）

# 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：手动克隆

# 1. Clone repository (use SSH)
git clone git@github.com: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

自动备份

简易设置（推荐）

# 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

检查状态

checkpoint-status

显示：

• 上次备份时间
• 是否与远程同步
• 自动备份计划
• 近期活动日志

多智能体备份

检查点系统会自动检测并备份来自~/.openclaw/agents/目录的所有智能体

运行机制

• 执行备份时：智能体文件夹将从~/.openclaw/agents/复制到备份仓库内的agents/目录，并自动剥离嵌套的.git目录
• 执行恢复时：智能体文件夹将从备份仓库的agents/目录复制回~/.openclaw/agents/
• 目录

备份仓库中的文件结构

~/.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/)

代理标志

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

标志	说明
--workspace-only	完全跳过代理的备份/恢复
--agents-only	跳过工作区和定时任务，仅对代理进行操作
--agent <名称>	仅对单个指定名称的代理进行操作

示例

# 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/目录不存在或为空，所有命令将跳过代理处理并显示信息提示
• 没有包含agents/目录的旧备份仓库仍可正常工作——恢复操作将直接跳过代理部分
• 没有代理存在时，现有行为保持不变

跨机器可移植性

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

工作原理

• 备份时：所有文本文件中出现的$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

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

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

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

手动设置Cron（高级）

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

# 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

灾难恢复工作流程

场景：家庭服务器宕机

# 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

安全注意事项

⚠️ 关键提示：代码仓库必须是私有的

您的备份包含敏感的个人数据：

• SOUL.md、MEMORY.md（您的身份和记忆）
• 个人笔记和对话历史
• 自定义脚本和配置

如果您将仓库设为公开，任何人都能看到您的数据！

备份内容包括：

• ✅ 记忆文件（对话历史）
• ✅ 身份文件（SOUL.md等）
• ✅ Cron 定时任务（内存/cron-jobs-backup.json）
• ✅ 脚本和工具
• ✅ 配置
• ✅ 智能体（~/.openclaw/agents/ -> 备份仓库中的 agents/ 目录）

不进行备份的内容：

• ❌ API 密钥 (.env.*) — 保存在 1Password 中
• ❌ OAuth 令牌 — 在新机器上重新认证
• ❌ 下载的媒体文件 — 临时性文件
• ❌ 临时文件 — 临时性文件

最佳实践：

• 始终使用私有仓库
• 使用 SSH 认证（令牌不会过期）
• 将 API 密钥存储在密码管理器中，而非备份文件里
• 在 GitHub 账户上启用双重认证
• 考虑在添加到内存前对敏感笔记进行加密

权限与调度

此技能使用标准系统调度来自动化备份：

• macOS：在以下位置创建 launchd plist 文件~/Library/LaunchAgents/com.openclaw.checkpoint.plist
• Linux：添加一个用户级别的cron任务（可通过crontab -l命令查看）

自动备份功能仅限选择启用——除非您明确运行checkpoint-schedule命令，否则该功能永远不会被启用。您可以随时使用checkpoint-stop或checkpoint-schedule disable命令来禁用它。

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

文件访问范围：该技能从~/.openclaw/workspace和~/.openclaw/agents/（用于多代理备份）读取数据。它将代理的备份副本写入~/.openclaw/workspace/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来直接丢弃更改。

恢复后落后于远程

如果您上次同步后，另一台机器进行了检查点操作，这是正常现象。

GitHub 提示输入用户名/密码

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

cd ~/.openclaw/workspace
git remote set-url origin git@github.com:YOURUSER/REPO.git

"主机密钥验证失败"

GitHub 的 SSH 主机密钥不在您的 known_hosts 文件中。通过以下方式修复：

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

"权限被拒绝（公钥）"

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

设置后 GitHub 仓库为空

旧的checkpoint-init仅提交了.gitignore. 这个问题现在已经修复了。请运行：

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

重新开始

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

代理程序未被备份

请检查您的代理程序是否位于~/.openclaw/agents/目录下（而不是其他地方）。运行checkpoint-status以查看哪些代理被检测到以及哪些已被备份。请确保您没有传递--workspace-only参数。

代理程序存在嵌套的 .git 错误

备份过程会自动从代理程序副本中剥离.git目录。如果您看到子模块警告，请重新运行一次备份：

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

恢复的代理程序缺少文件

代理程序恢复会原样复制备份。如果备份是在某些文件被添加到代理程序之前进行的，那么这些文件将不会存在。请运行检查点备份首先在源机器上执行以捕获最新状态。

在新机器上恢复后出现“权限被拒绝，无法创建目录 '/Users/olduser'”

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

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以获取详细的安装说明。

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。