openclaw-checkpoint

name

openclaw-checkpoint

description

Backup and restore OpenClaw workspace state and agents across machines using git. Enables disaster recovery by syncing SOUL.md, MEMORY.md, memory files, cron jobs, agents (~/.openclaw/agents/), and configuration to a remote repository. Use when user wants to checkpoint their OpenClaw state, restore on a new machine, migrate between computers, or protect against data loss. Provides commands checkpoint (help overview), checkpoint-setup (interactive onboarding), checkpoint-backup, checkpoint-restore (with interactive checkpoint selection or --latest for most recent), checkpoint-schedule (auto-backup), checkpoint-stop, checkpoint-status, checkpoint-init, and checkpoint-reset. Supports multi-agent backup with flags --workspace-only, --agents-only, and --agent <name>. Automatically backs up cron jobs to memory/cron-jobs-backup.json on each checkpoint-backup.

OpenClaw Checkpoint Skill

Backup and restore your OpenClaw identity, memory, agents, and configuration across machines.

Platform: macOS and Linux only. Windows is not supported.

Overview

This skill provides disaster recovery for OpenClaw by syncing your workspace and agents to a git repository. It preserves:

• Identity: SOUL.md, IDENTITY.md, USER.md (who you and the assistant are)
• Memory: MEMORY.md and memory/*.md files (conversation history and context)
• Cron Jobs: Scheduled tasks exported to memory/cron-jobs-backup.json (morning briefs, daily syncs, automations)
• Configuration: TOOLS.md, AGENTS.md, HEARTBEAT.md (tool setups and conventions)
• Scripts: Custom tools and automation you've built
• Agents: All agent folders from ~/.openclaw/agents/ (alex, blake, etc.)

Not synced (security): API keys (.env.*), credentials, OAuth tokens

Installation

Option 1: Git Clone (Recommended)

# 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

Option 2: Quick Install

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

This runs the install script -- review it first if you prefer to inspect before executing.

Commands

checkpoint

Show all available commands and usage examples.

checkpoint

What it does:

• Displays a quick reference of all checkpoint commands with descriptions and examples

When to use:

• When you can't remember the exact command name
• Quick reference for available options

checkpoint-setup

Interactive onboarding flow for first-time setup.

checkpoint-setup

What it does:

• Guides you through creating a PRIVATE GitHub repository
• Sets up SSH authentication (recommended) or Personal Access Token
• Automatically detects if SSH key is already authorized on GitHub
• Detects agents in ~/.openclaw/agents/ and reports they will be included in backups
• Generates a README.md with recovery instructions and commands
• Commits workspace files within ~/.openclaw/workspace (secrets excluded via .gitignore)
• Configures automatic backups
• Tests the backup system
• Shows final status

When to use:

• First time setting up checkpoint system
• After installing the skill
• After running checkpoint-reset
• Recommended starting point for new users

checkpoint-auth

Authenticate with GitHub (browser-based).

checkpoint-auth

What it does:

• Option 1: GitHub CLI (opens browser automatically)
• Option 2: Personal Access Token (expires, needs renewal)
• Option 3: SSH Key (recommended - no token expiry)
• Automatically adds GitHub to known_hosts
• Tests authentication after setup

When to use:

• Authentication expired or failed
• Switching authentication methods
• Setting up on a new machine

SSH is recommended because:

• No token expiration to worry about
• Works reliably without password prompts
• GitHub no longer accepts password authentication for HTTPS

checkpoint-backup

Save current state to remote repository.

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)

What it does:

• Backs up OpenClaw cron jobs to memory/cron-jobs-backup.json (requires openclaw CLI and running gateway)
• Copies agent folders from ~/.openclaw/agents/ into agents/ in the workspace repo (strips nested .git dirs)
• Normalizes home-directory paths ($HOME -> {{HOME}}) for cross-machine portability
• Commits all changes in ~/.openclaw/workspace
• Pushes to origin/main
• Shows commit hash and timestamp

Agent backup details:

• Auto-detects agents in ~/.openclaw/agents/ (e.g., alex, blake)
• Each agent folder is copied to agents/<name>/ in the backup repo
• Nested .git directories are removed to avoid submodule issues
• If no agents exist, skips gracefully with an info message
• Uses rsync --exclude='.git' when available, falls back to cp -r + manual .git removal

Cron job backup details:

• Runs openclaw cron list --json to export all scheduled tasks
• Strips runtime state, keeps only configuration (name, schedule, target, payload)
• Non-blocking: if the CLI or gateway is unavailable, checkpoint-backup continues without cron backup

Flags:

• --workspace-only — skip agent backup
• --agents-only — skip workspace and cron backup, only back up agents
• --agent <name> — back up a single named agent only

When to use:

• Before switching computers
• After significant changes (new memory, updated SOUL.md)
• Any time you want to ensure changes are saved

checkpoint-schedule

Set up automatic backups with configurable frequency.

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

What it does:

• macOS: Creates launchd plist for reliable background backups
• Linux: Adds cron job for scheduled backups
• Logs all activity to ~/.openclaw/logs/checkpoint.log

When to use:

• First time setup: checkpoint-schedule hourly
• Change frequency: checkpoint-schedule 15min
• Stop backups: checkpoint-schedule disable

checkpoint-status

Check backup health and status.

checkpoint-status

What it shows:

• Last backup time and commit
• Whether local is behind remote
• Uncommitted changes
• Agent backup status (which agents are backed up, which are missing)
• Auto-backup schedule status
• Recent backup activity log

When to use:

• Before switching machines (verify synced)
• Troubleshooting backup issues
• Regular health checks

checkpoint-restore

Restore state from remote repository, with checkpoint selection and first-time onboarding.

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

What it does:

• First-time users: Launches interactive restore onboarding flow
  • Guides you through GitHub authentication (SSH, GitHub CLI, or PAT)
  • Lets you specify your existing backup repository
  • Verifies access and restores your checkpoint
  • Handles merge/replace options if local files exist
  • Shows available checkpoints to pick from (if the repo has more than one commit)
  • Offers to restore cron jobs from backup
  • Offers to restore agents from backup
• Returning users: Shows a list of the 10 most recent checkpoints to choose from
  • Pick the latest or any older checkpoint to restore
  • Current checkpoint is marked in the list
  • Restoring an older checkpoint warns that the next backup will overwrite newer remote checkpoints
  • Use --latest flag to skip the interactive selection and restore the most recent checkpoint automatically
• Uncommitted changes: If you have local uncommitted changes, you're prompted to:
  1. Save changes first (runs checkpoint-backup)
  2. Discard local changes and continue restoring
  3. Cancel
• Path portability: Automatically expands {{HOME}} placeholders and rewrites old home-directory paths for the current machine
• Cron jobs: Automatically offers to restore cron jobs from memory/cron-jobs-backup.json after restoring (requires OpenClaw gateway to be running)
• Agents: Offers to restore agents from agents/ directory in the backup to ~/.openclaw/agents/

Flags:

• --latest — skip selection, restore most recent checkpoint
• --force — discard local changes without prompting
• --workspace-only — skip agent restore
• --agents-only — skip workspace and cron restore, only restore agents
• --agent <name> — restore a single named agent only

When to use:

• Starting OpenClaw on a new machine
• After hardware failure/disaster
• When resuming work on different computer
• First-time restore from an existing backup
• Rolling back to a previous checkpoint after unwanted changes

Onboarding flow triggers when:

• No workspace exists
• Workspace exists but not a git repository
• Git repository exists but no remote configured

checkpoint-init

Initialize workspace for checkpoint system.

checkpoint-init

What it does:

• Creates git repository in ~/.openclaw/workspace
• Generates .gitignore (excludes secrets and ephemeral files)
• Creates initial commit

When to use:

• First time setting up checkpoint system
• After restoring from backup to new machine

checkpoint-reset

Reset checkpoint system for fresh setup.

checkpoint-reset

What it does:

• Option 1: Removes local git repository only (keeps SSH keys)
• Option 2: Removes everything (git repo + SSH keys + GitHub from known_hosts)
• Offers to remove backed-up agent copies from workspace agents/ folder
• Reminds you to delete the GitHub repo manually

Note: Reset never touches your actual agent folders in ~/.openclaw/agents/ -- only the backup copies.

When to use:

• Starting over with a fresh setup
• Switching to a different GitHub repository
• Troubleshooting persistent authentication issues

checkpoint-stop

Stop automatic backups.

checkpoint-stop

What it does:

• Disables scheduled automatic backups
• Removes cron job (Linux) or launchd agent (macOS)

When to use:

• Temporarily pausing backups
• Before making major workspace changes
• If backups are causing issues

To restart: checkpoint-schedule hourly (or any frequency)

Setup

Easy Setup (Recommended)

Just run the interactive wizard:

checkpoint-setup

This handles everything: git init, SSH keys, GitHub setup, and first backup.

First Time Setup (Manual)

# 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 [e-mail]:YOURUSER/openclaw-state.git
checkpoint-backup

Setup on Second Machine

Option 1: Interactive Restore (Recommended)

# 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

This will:

• Help you authenticate with GitHub (if not already)
• Ask for your backup repository details
• Clone/restore your checkpoint automatically

Option 2: Manual Clone

# 1. Clone repository (use SSH)
git clone [e-mail]: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

Automated Backups

Easy Setup (Recommended)

# 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

Check Status

checkpoint-status

Shows:

• Last backup time
• Whether synced with remote
• Auto-backup schedule
• Recent activity log

Multi-Agent Backup

The checkpoint system automatically detects and backs up all agents from ~/.openclaw/agents/.

How It Works

• On backup: Agent folders are copied from ~/.openclaw/agents/ into agents/ inside the backup repo, with nested .git directories stripped
• On restore: Agent folders are copied from agents/ in the backup repo back to ~/.openclaw/agents/
• If no agents exist, all commands skip agent handling gracefully

File Structure in Backup Repo

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

These flags work on checkpoint-backup and checkpoint-restore:

Flag	Description
--workspace-only	Skip agent backup/restore entirely
--agents-only	Skip workspace and cron, only operate on agents
--agent <name>	Operate on a single named agent only

Examples

# 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

Backwards Compatibility

• If ~/.openclaw/agents/ does not exist or is empty, all commands skip agent handling with an info message
• Old backup repos without an agents/ directory work fine -- restore simply skips agents
• No existing behavior changes when no agents are present

Cross-Machine Portability

When you back up on one machine (e.g. /Users/jerry) and restore on another (e.g. /Users/tom), hardcoded absolute home-directory paths in workspace files would break. The checkpoint system handles this automatically.

How It Works

• On backup: All occurrences of your $HOME path (e.g. /Users/jerry) are replaced with the placeholder {{HOME}} in text files. A .checkpoint-meta.json file is written with the source machine's details.
• On restore: The {{HOME}} placeholder is expanded to the current machine's $HOME (e.g. /Users/tom). For backwards compatibility with older backups that were created before normalization, any remaining literal old home paths are also rewritten.

What Gets Processed

Only text files likely to contain paths are scanned:

• *.md, *.json, *.sh, *.txt, *.yaml, *.yml, *.toml, *.cfg, *.conf

Binary files, .git/, and node_modules/ are never touched.

.checkpoint-meta.json

This file is auto-generated on each backup and records the source machine:

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

On restore, this metadata tells the script which old paths to rewrite. The file is updated after restore to reflect the current machine.

Manual Cron Setup (Advanced)

If you prefer manual 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

Disaster Recovery Workflow

Scenario: Home server dies

# 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

Security Considerations

⚠️ CRITICAL: Repository MUST be PRIVATE

Your backup contains sensitive personal data:

• SOUL.md, MEMORY.md (your identity & memories)
• Personal notes and conversation history
• Custom scripts and configurations

If you make the repo public, anyone can see your data!

What gets backed up:

• ✅ Memory files (conversation history)
• ✅ Identity files (SOUL.md, etc.)
• ✅ Cron jobs (memory/cron-jobs-backup.json)
• ✅ Scripts and tools
• ✅ Configuration
• ✅ Agents (~/.openclaw/agents/ -> agents/ in backup repo)

What does NOT get backed up:

• ❌ API keys (.env.*) — keep in 1Password
• ❌ OAuth tokens — re-authenticate on new machine
• ❌ Downloaded media — ephemeral
• ❌ Temporary files — ephemeral

Best practices:

• Always use a PRIVATE repository
• Use SSH authentication (no token expiry)
• Store API keys in password manager, not in backed-up files
• Enable 2FA on GitHub account
• Consider encrypting sensitive notes before adding to memory

Permissions and Scheduling

This skill uses standard system scheduling to automate backups:

• macOS: Creates a launchd plist at ~/Library/LaunchAgents/com.openclaw.checkpoint.plist
• Linux: Adds a user-level cron job (visible via crontab -l)

Auto-backup is opt-in only -- it is never enabled unless you explicitly run checkpoint-schedule. You can disable it at any time with checkpoint-stop or checkpoint-schedule disable.

The skill does not install any background daemons, system services, or root-level processes. All scheduling runs under your user account.

File access scope: The skill reads from ~/.openclaw/workspace and ~/.openclaw/agents/ (for multi-agent backup). It writes backup copies of agents into ~/.openclaw/workspace/agents/. On restore, it copies agents back to ~/.openclaw/agents/. Sensitive files (.env.*, credentials, OAuth tokens) are excluded from backups via .gitignore.

Troubleshooting

"Not a git repository" or "'origin' does not appear to be a git repository"

Running checkpoint-restore will now automatically start the interactive restore onboarding flow to help you connect to your backup repository. Alternatively, run checkpoint-setup to create a new backup from scratch.

"Failed to push checkpoint"

Another machine pushed changes. Run checkpoint-restore first, then checkpoint-backup.

"You have uncommitted changes"

checkpoint-restore will prompt you to choose:

1. Save changes first (runs checkpoint-backup)
2. Discard local changes and continue
3. Cancel

You can also skip the prompt with checkpoint-restore --force to discard changes directly.

Behind remote after restore

This is expected if another machine checkpointed since you last synced.

GitHub prompting for username/password

GitHub no longer accepts password authentication for HTTPS. Switch to SSH:

cd ~/.openclaw/workspace
git remote set-url origin [e-mail]:YOURUSER/REPO.git

"Host key verification failed"

GitHub's SSH host key isn't in your known_hosts. Fix with:

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

"Permission denied (publickey)"

Your SSH key isn't added to GitHub. Run checkpoint-auth and choose SSH option.

GitHub repo is empty after setup

The old checkpoint-init only committed .gitignore. This is fixed now. Run:

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

Starting fresh

Run checkpoint-reset to remove local git repo and optionally SSH keys, then checkpoint-setup.

Agents not being backed up

Check that your agents are in ~/.openclaw/agents/ (not somewhere else). Run checkpoint-status to see which agents are detected and which are backed up. Make sure you're not passing --workspace-only.

Agent has nested .git errors

The backup process automatically strips .git directories from agent copies. If you see submodule warnings, run a fresh backup:

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

Restored agents missing files

Agent restore copies the backup as-is. If the backup was taken before certain files were added to the agent, those files won't be present. Run checkpoint-backup on the source machine first to capture the latest state.

"Permission denied, mkdir '/Users/olduser'" after restoring on a new machine

This means files contain hardcoded paths from the original machine. If the backup was created before path normalization was added, run:

cd ~/.openclaw/workspace
grep -rl "/Users/olduser" --include="*.md" --include="*.json" --include="*.sh" | \
  xargs sed -i '' "s|/Users/olduser|$HOME|g"

Future backups will normalize paths automatically.

Files show {{HOME}} instead of real paths

This is expected in the backup repo on GitHub. The {{HOME}} placeholder is replaced with the real $HOME path on each restore. If you see {{HOME}} in your local workspace after a restore, run checkpoint-restore --latest again.

Limitations

• Single machine at a time: Don't run OpenClaw on multiple machines simultaneously
• Max data loss: 1 hour if using hourly backups (cron)
• Secrets not synced: Must restore API keys manually on new machine
• Large files: GitHub has 100MB file limit (your text files are fine)

File Reference

See references/setup.md for detailed setup instructions.