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 git@github.com: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 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

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

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:

Save changes first (runs
```
checkpoint-backup
```
)
Discard local changes and continue
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 git@github.com: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.

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

AI Skill Market Insights

Be Part of the 0+ Developer Community

OpenClaw Checkpoint Skill

Overview

Installation

Option 1: Git Clone (Recommended)

Copy scripts to tools directory

Add to PATH (also add to ~/.zshrc or ~/.bashrc for persistence)

Run setup wizard

Option 2: Quick Install

Commands

checkpoint

checkpoint-setup

checkpoint-auth

checkpoint-backup

checkpoint-schedule

checkpoint-status

checkpoint-restore

checkpoint-init

checkpoint-reset

checkpoint-stop

Setup

Easy Setup (Recommended)

First Time Setup (Manual)

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)

Setup on Second Machine

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

2. Restore secrets from 1Password/password manager

Create ~/.openclaw/workspace/.env.thisweek

Create ~/.openclaw/workspace/.env.stripe

(Copy from secure storage)

3. Start OpenClaw

Automated Backups

Easy Setup (Recommended)

Or choose your frequency:

Check Status

Multi-Agent Backup

How It Works

File Structure in Backup Repo

Agent Flags

Examples

Backup only agents

Backup only the 'alex' agent

Restore workspace but skip agents

Restore only agents from backup

Check which agents are backed up

Backwards Compatibility

Cross-Machine Portability

How It Works

What Gets Processed

.checkpoint-meta.json

Manual Cron Setup (Advanced)

Add line for hourly backups:

Disaster Recovery Workflow

1. Install OpenClaw

2. Install checkpoint skill and run interactive 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)

4. Start OpenClaw

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

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

Permissions and Scheduling

Troubleshooting

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

"Failed to push checkpoint"

"You have uncommitted changes"