OpenClaw B2 Backup

Automatic encrypted backup and sync of OpenClaw state to Backblaze B2. Install the plugin, set 3 fields, restart your gateway — backups happen automatically.

What Is OpenClaw B2 Backup?

OpenClaw B2 Backup is a plugin that snapshots your entire OpenClaw state directory to Backblaze B2 on a schedule. It uses incremental SHA-256 diffing and AES-256-GCM encryption so only changed files are uploaded and everything is encrypted at rest. It runs inside the gateway process, uses SQLite's .backup() API for consistent database snapshots, and pushes incremental encrypted diffs to B2.

If you've used OpenClaw for more than a week, you've probably hit one of these:

• Rebuilt from scratch after a broken config or busted channel integration, losing sessions and memory in the process
• Lost agent memory after compaction fired and your agent forgot everything you taught it
• Accidentally deleted MEMORY.md (or had your agent do it) with no way to get it back
• Wanted to move to a new machine but couldn't figure out what to copy
• Worried about compromise from a bad skill and wanted a known-good restore point

This plugin fixes all of that. It snapshots your entire OpenClaw state — config, workspace, sessions, memory, cron, hooks — and stores encrypted, timestamped copies in B2. Backup happens automatically on schedule, before compaction, and on shutdown. Sync to a new machine is automatic on first start. Rollback is one agent command from chat. No scripts, no manual tarball management, no stopping the gateway.

Who Should Use This

Anyone running OpenClaw who wants automatic off-machine backups without managing scripts, cron jobs, or external tools like restic/rclone.

Key Features

• Encrypted by default — AES-256-GCM with per-file random salt/IV, key derived from your B2 application key via scrypt
• Incremental sync — SHA-256 manifest diffing; only changed files are uploaded
• Safe SQLite snapshots — uses .backup() API, no half-written databases
• Auto-restore on new machines — detects empty state dir on start, pulls latest snapshot automatically
• Safety snapshots before rollback — creates a restore point before any pull, stored out-of-band and never auto-pruned
• Compaction protection — triggers a push before compaction fires (5-minute debounce to prevent rapid-fire)
• Conversational rollback — b2_rollback agent tool lets you list and restore snapshots from chat
• Zero runtime dependencies — hand-rolled S3 Sig V4 client, uses only node:crypto and OpenClaw's bundled croner
• Backward-compatible decryption — auto-detects unencrypted data and passes through, so enabling encryption doesn't break old snapshots

Quick Start

1. Install

openclaw plugins install openclaw-b2-backup

2. Configure

Open ~/.openclaw/openclaw.json and add a config block to the openclaw-b2-backup entry the installer created:

"openclaw-b2-backup": {
  "enabled": true,
  "config": {
    "keyId": "004a...",
    "applicationKey": "K004...",
    "bucket": "my-openclaw-backups"
  }
}

You can also configure these fields in the Control UI under plugin settings.

3. Restart

openclaw gateway restart

That's it. Region is auto-detected, encryption is on by default, and the first backup runs at midnight.

Configuration

All optional beyond the 3 required fields:

| Setting | Type | Default | Required | Description | |---------|------|---------|----------|-------------| | keyId | string | — | Yes | B2 application key ID | | applicationKey | string | — | Yes | B2 application key (also used as encryption key source) | | bucket | string | — | Yes | B2 bucket name | | region | string | Auto-detected | No | B2 region (derived from key if omitted) | | prefix | string | "openclaw-backup" | No | Object key prefix in the bucket | | schedule | string | "daily" | No | "daily", "weekly", or a cron expression | | encrypt | boolean | true | No | AES-256-GCM encryption before upload | | keepSnapshots | number | 10 | No | Snapshots retained; oldest auto-pruned |

What Gets Synced

Everything that makes your OpenClaw instance yours:

| Data | Path | Why | |------|------|-----| | Config | openclaw.json (+.bak rotation) | Your setup — channels, models, agent bindings | | Workspace | workspace/**, workspace-*/** | SOUL.md, AGENTS.md, MEMORY.md, custom instructions | | Sessions | agents/*/sessions/*.jsonl | Conversation history | | Session store | agents/*/sessions/sessions.json | Routing metadata | | Memory DB | agents/*/memory/*.sqlite | Long-term knowledge (vector search index) | | Agent state | agents/*/agent/** | Agent runtime config (minus auth profiles) | | Cron jobs | cron/** | Scheduled tasks | | Hooks | hooks/** | Custom hook scripts |

Not Synced (by design)

• credentials/ and auth-profiles.json — secrets stay per-machine; re-auth on new machines
• media/ — ephemeral (2-min TTL), not worth syncing
• extensions/ — install plugins independently per machine
• *.lock, *.tmp, *-wal, *-shm — transient files

Common Scenarios

Your agent forgot everything after compaction

Compaction rewrites your session transcript to save context window space. If important context lived only in the chat history and wasn't captured in MEMORY.md or the memory DB, it's gone.

With this plugin, a snapshot is automatically taken before compaction fires. Roll back from chat:

"Show me my B2 backup snapshots and restore the one from before compaction"

You (or your agent) deleted MEMORY.md

OpenClaw memory is plain Markdown files on disk. A single misinterpreted instruction can permanently delete them. With daily snapshots in B2, you restore MEMORY.md from the last known-good version.

Config got corrupted or you broke a channel integration

One bad edit and you're rebuilding from scratch — re-onboarding channels, re-pairing devices, re-teaching your agent. With this plugin, you restore the entire state directory from a snapshot instead.

You suspect a malicious skill compromised your setup

Restore from a pre-compromise snapshot, rotate your secrets, and you're back to a known-good state. The timestamped snapshots in B2 give you a clear timeline of what your state looked like before and after the incident.

Moving to a new machine

openclaw plugins install openclaw-b2-backup
# Add your B2 config (keyId, applicationKey, bucket) to the openclaw-b2-backup entry in openclaw.json
openclaw gateway restart
# Plugin detects empty state + existing snapshots → auto-restores latest

Your new machine has the same memory, sessions, config, and personality as the old one. No manual file copying.

How It Works

Sync Triggers

| Trigger | When | Behavior | |---------|------|----------| | Cron schedule | Midnight daily (default) | Full incremental push | | gateway_stop | Gateway shutdown | Final push before exit | | before_compaction | Before session compaction | Push with 5-min debounce to prevent rapid-fire | | Auto-restore | Service start, empty state dir | Pull latest snapshot (no safety snapshot created) |

Push (your machine -> B2)

Each sync creates a timestamped snapshot (e.g., openclaw-backup/2026-02-19T00-00-00Z/):

1. Walk the state directory, collect files matching include patterns
2. Create safe SQLite snapshots via .backup() API (no half-written databases)
3. Compute SHA-256 hashes on plaintext, diff against last push
4. Encrypt changed files with AES-256-GCM (if enabled)
5. Upload changed files + unencrypted manifest
6. Prune old snapshots beyond keepSnapshots limit

Manifest hashes are always computed on plaintext so incremental diffing works regardless of encryption (random IV/salt means identical plaintext produces different ciphertext).

Unlike external backup tools (Restic, rclone), this plugin runs inside the gateway process and doesn't require stopping the gateway.

Pull (B2 -> your machine)

1. Push a safety snapshot to {prefix}/safety-{timestamp}/ (preserves current state before overwriting)
2. Fetch manifest from the selected snapshot
3. Compare local files by SHA-256 hash
4. Download + decrypt (if encrypted) only changed/missing files
5. Verify hashes against plaintext before writing

Safety snapshots are stored out-of-band and never auto-pruned, so you can always recover from a bad rollback.

Agent Tool

The plugin registers a b2_rollback tool that lets you manage backups conversationally:

List snapshots:

"Show me my B2 backup snapshots"

Returns all regular snapshots and safety snapshots with timestamps.

Restore a snapshot:

"Roll back to the snapshot from February 15th"

Creates a safety snapshot of current state, then restores the selected snapshot.

The tool is registered as optional so it only appears when the agent needs it.

Architecture

Zero external dependencies beyond what OpenClaw already ships:

| Need | Solution | |------|----------| | S3 API calls | Hand-rolled AWS Sig V4 signing (node:crypto) | | Encryption | AES-256-GCM, scrypt key derivation from applicationKey | | Scheduling | croner (already in OpenClaw core) | | SQLite snapshots | node:sqlite .backup() API (Node 22+) | | Push debounce | Shared timer prevents rapid-fire from overlapping triggers | | JSON persistence | readJsonFileWithFallback / writeJsonFileAtomically from plugin SDK |

src/
  types.ts            # Config + manifest types, SAFETY_PREFIX
  b2-client.ts        # S3-compatible B2 client with Sig V4 signing
  gatherer.ts         # Walk state dir, collect syncable files
  sqlite-snapshot.ts  # Safe .backup() wrapper
  manifest.ts         # SHA-256 hashing + diff logic
  encryption.ts       # AES-256-GCM encrypt/decrypt/isEncrypted
  debounce.ts         # Push rate limiter
  snapshots.ts        # List, prune, filter snapshots in B2
  push.ts             # Upload changed files to B2 (with PushOptions)
  pull.ts             # Download + restore from B2 (with PullOptions)
  service.ts          # Background scheduler + auto-restore
index.ts              # Plugin entry: hooks, tool registration, debounce wiring
openclaw.plugin.json  # Plugin manifest

Storage

Backblaze B2 includes 10 GB of free storage — more than enough for most OpenClaw setups. Typical state is 50-500 MB, so even with 10 encrypted snapshots retained you'll comfortably stay within the free tier.

Security

• Encryption at rest — all file data is AES-256-GCM encrypted before leaving your machine (manifests stay unencrypted as they contain only paths and hashes)
• Per-file random salt/IV — identical files produce different ciphertext
• Key derivation — encryption key is derived from your applicationKey via scrypt (never stored separately)
• Credentials and auth profiles are excluded from sync by design
• Use B2 application keys scoped to a single bucket for least-privilege access

Development

Local install (from the monorepo)

openclaw plugins install -l ./extensions/b2-backup
openclaw plugins list  # should show b2-backup

Run tests

pnpm test

66 tests across 7 test files covering encryption round-trips, manifest diffing, snapshot filtering, file gathering, B2 client signing, debounce timing, and plugin registration.

License

MIT