claw-saver

Back up the full OpenClaw environment (~/.openclaw) to a Git repository. Supports scheduled backups, interactive restore, and Git LFS for large model files.

Back up the entire OpenClaw environment (~/.openclaw) to a Git repository. Supports scheduled backups, interactive restore, and exponential backoff on network failures.

Features

• Full backup: Everything in ~/.openclaw is backed up, including agents, skills, configurations, knowledge bases, and agent memory
• Smart exclusions: Only ignores clearly harmless runtime artifacts (logs, cache, node_modules, canvas)
• Scheduled backups: Configurable cron schedule (default: every 5 hours)
• Atomic commits: Two-commit strategy ensures backup files and restore guide are always consistent
• Git LFS support: Large model files are auto-tracked via Git LFS
• Exponential backoff: Failed pushes retry with 60s -> 120s -> 240s delays
• Stale lock protection: Orphan backup processes are detected and cleaned up
• Dynamic .gitignore: Scans the actual directory structure, no hardcoded assumptions

Quick Start

bash

# 1. Configure your Git token
openclaw config set env.OPENCLAW_BACKUP_GIT_TOKEN <your-token>

# 2. Set your repository URL
# Edit ~/.openclaw/skills/claw-saver/config.json and set "repo"
# Example: "repo": "https://cnb.cool/yourname/your-repo"

# 3. Run your first backup
openclaw backup run

# 4. Enable automatic backups (every 5 hours)
openclaw backup enable-cron

CLI Commands

bash

openclaw backup run            # Run backup immediately
openclaw backup status         # Show last backup time and commit hash
openclaw backup restore        # Restore from a previous commit (interactive)
openclaw backup enable-cron    # Enable scheduled backups
openclaw backup disable-cron   # Disable scheduled backups
openclaw backup set-cron <expr> # Set custom schedule (e.g. "0 */2 * * *")

Configuration

Edit ~/.openclaw/skills/claw-saver/config.json:

json

{
  "repo": "https://cnb.cool/yourname/your-repo",
  "cron": "0 */5 * * *",
  "lfs_threshold_mb": 10,
  "lfs_extensions": [".bin", ".gguf", ".safetensors", ".pt", ".pth", ".onnx", ".msgpack", ".model"],
  "push_retries": 3,
  "push_retry_interval_ms": 60000
}

Option	Default	Description
repo	(required)	Git repository URL
cron	0 */5 * * *	Backup schedule (cron expression, in system timezone)
lfs_threshold_mb	10	Files larger than this are tracked via Git LFS
lfs_extensions	(see above)	File extensions to LFS-track
push_retries	3	Max push retry attempts on failure
push_retry_interval_ms	60000	Initial retry delay (doubles each attempt)

What Is Backed Up

Everything except harmless runtime artifacts:

text

# === BACKED UP ===
agents/              # Agent configurations, auth profiles, session data
credentials/         # Channel credentials and keys
identity/           # Device identity keys
kb/                 # Knowledge base (user docs + vector database)
lts/                # Long-term scripts (cleanup, OOM protection)
openclaw.json       # Core configuration (含 tokens)
skills/             # All installed skills and their configs
workspace-* /       # Agent workspaces, memory, learnings
**/.learnings/      # Agent self-improvement logs
**/.openclaw/       # Per-workspace OpenClaw state
And all other directories in ~/.openclaw/

What Is Excluded (Runtime Artifacts Only)

These are transient or rebuildable and intentionally not backed up:

text

.git/               # Git repository itself (local only)
logs/               # Runtime logs
canvas/             # Canvas runtime state
media/             # Uploaded media files
npm/               # NPM packages (rebuild with npm install)
cron/runs/         # Cron execution history
**/node_modules/   # Dependencies (rebuild with npm install / pip install)
**/__pycache__/     # Python bytecode cache
**/.cache/          # Generic cache
**/dreaming/        # Short-term memory state
*.tmp, *.bak        # OS noise
.backup.lock        # Runtime lock file

User data principle: If in doubt, it is backed up. Credentials, identity keys, knowledge bases, agent memory, and learned data are all preserved.

Security

• Token isolation: The token is stored only in ~/.openclaw/.git/config (local, never pushed to the backup repo) and in the cron environment variable (local system only)
• No token in commits: RESTORE.md and commit messages contain only the repo URL, never the token
• stderr suppressed: git push stderr is redirected to prevent token leakage in error messages
• git directory excluded: .git/ is in .gitignore, so .git/config (containing the token in the remote URL) is never backed up

Restore

bash

openclaw backup restore

This clones the repository to a temp directory, checks out the specified commit, and copies files back to ~/.openclaw. A running backup is preserved (skills/claw-saver stays live during restore).

After restore completes:

bash

openclaw gateway restart

Restore Guide

A RESTORE.md file is generated with each backup, embedded in the backup commit. It contains the exact commit hash, clone instructions, and a list of what was excluded so you know what needs manual restoration.

Architecture

text

skills/claw-saver/
  lib/
    backup.js      # Core orchestration (lock, stage, commit, push)
    git.js         # Git operations (init, add, commit, push, clone)
    lfs.js         # Git LFS setup and tracking
    restore.js     # Interactive restore logic
  scripts/
    cli.js         # CLI entry point (run, status, restore, cron)
  config.json      # User configuration (repo, cron, LFS settings)

Lock Mechanism

Concurrent backup runs are prevented via an atomic mkdir-based lock:

• Lock dir: ~/.openclaw/.backup.lock/ (pid file inside)
• If a stale lock is detected (holder PID is dead), it is forcibly taken over
• Lock is always released via finally{} after backup completes or fails