openclaw-checkpoint

# OpenClaw Checkpoint Skill Backup and restore your OpenClaw identity, memory, 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 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) - **Configuration**: TOOLS.md, AGENTS.md, HEARTBEAT.md (tool setups and conventions) - **Scripts**: Custom tools and automation you've built **Not synced** (security): API keys (.env.*), credentials, OAuth tokens ## Installation ### Option 1: One-Liner Install (Recommended) ```bash curl -fsSL https://raw.githubusercontent.com/AnthonyFrancis/openclaw-checkpoint/main/scripts/install-openclaw-checkpoint.sh | bash ``` This will: - Download and install the skill - Add commands to your PATH automatically - Offer to run the interactive setup wizard ### Option 2: Manual Install ```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 ``` ## Commands ### checkpoint-setup **Interactive onboarding flow for first-time setup.** ```bash 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 - Generates a README.md with recovery instructions and commands - Commits ALL workspace files (not just .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).** ```bash 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 Save current state to remote repository. ```bash checkpoint ``` **What it does:** - Commits all changes in ~/.openclaw/workspace - Pushes to origin/main - Shows commit hash and timestamp **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. ```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 ``` **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. ```bash checkpoint-status ``` **What it shows:** - Last backup time and commit - Whether local is behind remote - Uncommitted changes - Auto-backup schedule status - Recent backup activity log **When to use:** - Before switching machines (verify synced) - Troubleshooting backup issues - Regular health checks ### checkpoint-resume Restore state from remote repository, with first-time onboarding. ```bash checkpoint-resume # Normal resume (or onboarding if not set up) checkpoint-resume --force # Discard local changes, pull remote ``` **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 - **Returning users:** Fetches and pulls latest changes from remote **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 **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. ```bash 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. ```bash 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) - Reminds you to delete the GitHub repo manually **When to use:** - Starting over with a fresh setup - Switching to a different GitHub repository - Troubleshooting persistent authentication issues ### checkpoint-stop Stop automatic backups. ```bash 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: ```bash checkpoint-setup ``` This handles everything: git init, SSH keys, GitHub setup, and first backup. ### First Time Setup (Manual) ```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 git@github.com:YOURUSER/openclaw-state.git checkpoint ``` ### Setup on Second Machine **Option 1: Interactive Restore (Recommended)** ```bash # Install the checkpoint skill first curl -fsSL https://raw.githubusercontent.com/AnthonyFrancis/openclaw-checkpoint/main/scripts/install-openclaw-checkpoint.sh | bash # Run checkpoint-resume - it will guide you through the entire process checkpoint-resume ``` 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** ```bash # 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) ```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 ``` ### Check Status ```bash checkpoint-status ``` Shows: - Last backup time - Whether synced with remote - Auto-backup schedule - Recent activity log ### Manual Cron Setup (Advanced) If you prefer manual cron: ```bash # Edit crontab crontab -e # Add line for hourly backups: 0 * * * * /Users/$(whoami)/.openclaw/workspace/skills/openclaw-checkpoint/scripts/checkpoint >> ~/.openclaw/logs/checkpoint.log 2>&1 ``` ## Disaster Recovery Workflow **Scenario: Home server dies** ```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-resume # 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. Enable automatic backups on this machine checkpoint-schedule hourly # 5. Start OpenClaw openclaw gateway start # 6. Verify # Ask assistant: "What were we working on?" # Should recall everything up to last checkpoint ``` ## 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.) - ✅ Scripts and tools - ✅ Configuration **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 ## Troubleshooting ### "Not a git repository" or "'origin' does not appear to be a git repository" Running `checkpoint-resume` 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-resume` first, then `checkpoint`. ### "You have uncommitted changes" You have local work that isn't checkpointed. Either: - Run `checkpoint` to save it first - Or `checkpoint-resume --force` to discard it ### Behind remote after resume 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: ```bash 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: ```bash 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: ```bash 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`. ## 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](references/setup.md) for detailed setup instructions.