🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί OpenClaw Checkpoint - Personal AI Assistant Backup & Recovery (Github)
πŸ¦€ ClawHub

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

by @anthonyfrancis

Backup and restore OpenClaw workspace state and agents across machines using git. Enables disaster recovery by syncing SOUL.md, MEMORY.md, memory files, cron...

Versionv1.0.5
Downloads3,747
Stars⭐ 2
#clawhub
TERMINAL
clawhub install openclaw-checkpoint

πŸ“– About This Skill

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 . 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// 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 β€” 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 β€” 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 | 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 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.

    πŸ’‘ 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.