openclaw-checkpointBackup and restore OpenClaw workspace state and agents across machines using git. Enables disaster recovery by syncing SOUL.md, MEMORY.md, memory files, cron...
Install via ClawdBot CLI:
clawdbot install AnthonyFrancis/openclaw-checkpointBackup and restore your OpenClaw identity, memory, agents, and configuration across machines.
Platform: macOS and Linux only. Windows is not supported.
This skill provides disaster recovery for OpenClaw by syncing your workspace and agents to a git repository. It preserves:
Not synced (security): API keys (.env.*), credentials, OAuth tokens
# 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-setupcurl -fsSL https://raw.githubusercontent.com/AnthonyFrancis/openclaw-checkpoint/main/scripts/install-openclaw-checkpoint.sh | bashThis runs the install script -- review it first if you prefer to inspect before executing.
Show all available commands and usage examples.
checkpointWhat it does:
When to use:
Interactive onboarding flow for first-time setup.
checkpoint-setupWhat it does:
~/.openclaw/agents/ and reports they will be included in backups~/.openclaw/workspace (secrets excluded via .gitignore)When to use:
checkpoint-resetAuthenticate with GitHub (browser-based).
checkpoint-authWhat it does:
When to use:
SSH is recommended because:
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:
memory/cron-jobs-backup.json (requires openclaw CLI and running gateway)~/.openclaw/agents/ into agents/ in the workspace repo (strips nested .git dirs)$HOME -> {{HOME}}) for cross-machine portabilityAgent backup details:
~/.openclaw/agents/ (e.g., alex, blake)agents// in the backup repo.git directories are removed to avoid submodule issuesrsync --exclude='.git' when available, falls back to cp -r + manual .git removalCron job backup details:
openclaw cron list --json to export all scheduled tasksFlags:
--workspace-only — skip agent backup--agents-only — skip workspace and cron backup, only back up agents--agent — back up a single named agent onlyWhen to use:
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-backupWhat it does:
When to use:
checkpoint-schedule hourlycheckpoint-schedule 15mincheckpoint-schedule disableCheck backup health and status.
checkpoint-statusWhat it shows:
When to use:
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' agentWhat it does:
--latest flag to skip the interactive selection and restore the most recent checkpoint automatically 1. Save changes first (runs checkpoint-backup)
2. Discard local changes and continue restoring
3. Cancel
{{HOME}} placeholders and rewrites old home-directory paths for the current machinememory/cron-jobs-backup.json after restoring (requires OpenClaw gateway to be running)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 onlyWhen to use:
Onboarding flow triggers when:
Initialize workspace for checkpoint system.
checkpoint-initWhat it does:
When to use:
Reset checkpoint system for fresh setup.
checkpoint-resetWhat it does:
agents/ folderNote: Reset never touches your actual agent folders in ~/.openclaw/agents/ -- only the backup copies.
When to use:
Stop automatic backups.
checkpoint-stopWhat it does:
When to use:
To restart: checkpoint-schedule hourly (or any frequency)
Just run the interactive wizard:
checkpoint-setupThis handles everything: git init, SSH keys, GitHub setup, and first backup.
# 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-backupOption 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-restoreThis will:
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# 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 activitycheckpoint-statusShows:
The checkpoint system automatically detects and backs up all agents from ~/.openclaw/agents/.
~/.openclaw/agents/ into agents/ inside the backup repo, with nested .git directories strippedagents/ in the backup repo back to ~/.openclaw/agents/~/.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/)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 |
# 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~/.openclaw/agents/ does not exist or is empty, all commands skip agent handling with an info messageagents/ directory work fine -- restore simply skips agentsWhen 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.
$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.{{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.Only text files likely to contain paths are scanned:
.md, .json, .sh, .txt, .yaml, .yml, .toml, .cfg, *.confBinary files, .git/, and node_modules/ are never touched.
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.
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>&1Scenario: 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 restoredYour backup contains sensitive personal data:
If you make the repo public, anyone can see your data!
What gets backed up:
What does NOT get backed up:
Best practices:
This skill uses standard system scheduling to automate backups:
~/Library/LaunchAgents/com.openclaw.checkpoint.plistcrontab -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.
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.
Another machine pushed changes. Run checkpoint-restore first, then checkpoint-backup.
checkpoint-restore will prompt you to choose:
checkpoint-backup)You can also skip the prompt with checkpoint-restore --force to discard changes directly.
This is expected if another machine checkpointed since you last synced.
GitHub no longer accepts password authentication for HTTPS. Switch to SSH:
cd ~/.openclaw/workspace
git remote set-url origin git@github.com:YOURUSER/REPO.gitGitHub's SSH host key isn't in your known_hosts. Fix with:
ssh-keyscan -t ed25519 github.com >> ~/.ssh/known_hostsYour SSH key isn't added to GitHub. Run checkpoint-auth and choose SSH option.
The old checkpoint-init only committed .gitignore. This is fixed now. Run:
cd ~/.openclaw/workspace && git add -A && git commit -m "Full backup" && git pushRun checkpoint-reset to remove local git repo and optionally SSH keys, then checkpoint-setup.
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.
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-backupAgent 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.
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.
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.
See references/setup.md for detailed setup instructions.
Generated Mar 1, 2026
An AI developer needs to migrate their OpenClaw setup from their office desktop to a home laptop for remote work. They use checkpoint-setup to create a private GitHub repository, then checkpoint-backup to save their workspace, agents, and cron jobs. On the new machine, they run checkpoint-restore --latest to recover their complete AI development environment with all custom agents and scheduled tasks intact.
A research team using OpenClaw for data analysis experiences a hardware failure on their primary workstation. They had been using checkpoint-schedule for automatic daily backups. The team lead runs checkpoint-restore on a replacement machine, recovering all research agents, conversation memory (MEMORY.md files), and analysis scripts from the latest backup, minimizing disruption to their project timeline.
A startup building specialized AI agents for customer service needs to backup only their production agents while excluding development workspaces. They use checkpoint-backup --agent customer-service-bot to backup specific agents, and checkpoint-backup --agents-only for backing up all agent configurations separately from workspace files, enabling selective restoration during testing phases.
A freelance AI consultant completes a client project involving multiple custom OpenClaw agents. They use checkpoint-backup --workspace-only to archive the project workspace, tools, and configurations to a private repository. This creates a portable snapshot they can restore later for maintenance work or use as a template for similar future projects, while excluding personal agents.
A university instructor needs to replicate an identical OpenClaw environment across 20 lab computers for a course on AI assistants. After setting up the master configuration with checkpoint-setup, they create a backup repository. Teaching assistants then run checkpoint-restore on each lab machine, ensuring all students have the same starting environment with pre-configured agents, tools, and example memory files.
Offer a subscription service providing automated monitoring, backup verification, and priority restoration support for enterprise OpenClaw deployments. Includes SLA guarantees for recovery time, regular backup health reports, and assistance with multi-machine synchronization. Targets companies with critical AI workflows who need reliable disaster recovery.
Extend the backup system with team features like branch-based checkpointing, change conflict resolution, and collaborative agent development workflows. Enables multiple developers to work on shared OpenClaw agents with proper version history and rollback capabilities. Integrates with existing team Git workflows for seamless collaboration.
Provide integration services connecting OpenClaw checkpoint system with enterprise backup solutions like Veeam, Commvault, or cloud storage services (AWS S3, Azure Blob). Includes custom retention policies, encryption enhancements, and compliance reporting for regulated industries. Targets large organizations needing to fit AI assistant backups into existing IT governance frameworks.
💬 Integration Tip
Integrate checkpoint-schedule with existing cron monitoring tools by checking the generated memory/cron-jobs-backup.json file, and use the --workspace-only flag during initial testing to avoid backing up large agent directories until the workflow is verified.
Transform AI agents from task-followers into proactive partners that anticipate needs and continuously improve. Now with WAL Protocol, Working Buffer, Autonomous Crons, and battle-tested patterns. Part of the Hal Stack 🦞
Use the ClawdHub CLI to search, install, update, and publish agent skills from clawdhub.com. Use when you need to fetch new skills on the fly, sync installed skills to latest or a specific version, or publish new/updated skill folders with the npm-installed clawdhub CLI.
Clawdbot documentation expert with decision tree navigation, search scripts, doc fetching, version tracking, and config snippets for all Clawdbot features
Interact with Moltbook social network for AI agents. Post, reply, browse, and analyze engagement. Use when the user wants to engage with Moltbook, check their feed, reply to posts, or track their activity on the agent social network.
OpenClaw CLI wrapper — gateway, channels, models, agents, nodes, browser, memory, security, automation.
MoltGuard — runtime security plugin for OpenClaw agents by OpenGuardrails. Helps users install, register, activate, and check the status of MoltGuard. Use wh...