Back up the full OpenClaw environment (~/.openclaw) to a Git repository. Supports scheduled backups, interactive restore, and Git LFS for large model files.
---
name: claw-saver
description: Back up the full OpenClaw environment (~/.openclaw) to a Git repository. Supports scheduled backups, interactive restore, and Git LFS for large model files.
version: 1.6.2
emoji: "💾"
homepage: https://clawhub.ai/skills/claw-saver
metadata:
openclaw:
requires:
env:
- OPENCLAW_BACKUP_GIT_TOKEN
bins:
- git
- git-lfs
config:
- skills/claw-saver/config.json
primaryEnv: OPENCLAW_BACKUP_GIT_TOKEN
envVars:
- name: OPENCLAW_BACKUP_GIT_TOKEN
required: true
description: Git personal access token with repo scope. Injected via openclaw config.
- name: OPENCLAW_DIR
required: false
description: Override OpenClaw home directory. Defaults to ~/.openclaw.
---
# claw-saver
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:**
```
# === 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:
```
.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
```
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
don't have the plugin yet? install it then click "run inline in claude" again.