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

💡 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

⚙️ Configuration

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

📋 Tips & Best Practices

"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 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.