Requirements
- Target platform
- OpenClaw
- Install method
- Manual import
- Extraction
- Extract archive
- Prerequisites
- OpenClaw
- Primary doc
- SKILL.md
Tencent SkillHub ยท Productivity
OpenClaw Checkpoint - Personal AI Assistant Backup & Recovery (Github)
Backup and restore OpenClaw workspace state and agents across machines using git. Enables disaster recovery by syncing SOUL.md, MEMORY.md, memory files, cron...
skill openclawclawhub Free
Backup and restore OpenClaw workspace state and agents across machines using git. Enables disaster recovery by syncing SOUL.md, MEMORY.md, memory files, cron...
โฌ 0 downloads โ
0 stars Unverified but indexed
Install for OpenClaw
Quick setup
- Download the package from Yavira.
- Extract the archive and review SKILL.md first.
- Import or place the package into your OpenClaw setup.
Package facts
- Download mode
- Yavira redirect
- Package format
- ZIP package
- Source platform
- Tencent SkillHub
- What's included
- INSTALL.md, README.md, SKILL.md
Validation
- Use the Yavira download entry.
- Review SKILL.md after the package is downloaded.
- Confirm the extracted package contains the expected setup assets.
Install with your agent
Agent handoff
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
New install
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete.
Upgrade existing
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run.
Trust & source
Release facts
- Source
- Tencent SkillHub
- Verification
- Indexed source record
- Version
- 1.0.5
Provenance
- Publisher
- AnthonyFrancis
- Source page
- View original listing
- Canonical URL
- Open canonical page
Documentation
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
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.
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: Save changes first (runs checkpoint-backup) Discard local changes and continue restoring 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)
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
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: FlagDescription--workspace-onlySkip agent backup/restore entirely--agents-onlySkip 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
โ ๏ธ 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.
"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.
Category context
Workflow acceleration for inboxes, docs, calendars, planning, and execution loops.
Source: Tencent SkillHub
Largest current source with strong distribution and engagement signals.
Package contents
Included in package
3 Docs
- SKILL.md
- INSTALL.md
- README.md