OpenClaw Cloud Backup#

The cloud layer for OpenClaw's native backup. Wraps openclaw backup create (config, credentials, consistent SQLite snapshots, workspace), then GPG-encrypts and uploads the archive to any S3-compatible bucket, with retention, verification, and staged restore.

All commands: bash "{baseDir}/scripts/cloud-backup.sh" <subcommand>

When to use this skill — and when not to#

Act ONLY on an explicit user request about OpenClaw backups: "back up openclaw", "restore my openclaw state", "set up cloud backups for openclaw", "/cloud-backup", and similar.

• Generic requests ("back up my project", "save this file", "restore the database") are NOT for this skill. Ask what the user means before touching it.
• NEVER run this skill as a side effect of another task, proactively, or "while you're at it".
• Read-only subcommands ( status, list, verify, schedule, and any --dry-run) may run freely once the user has asked about backups. Everything else follows the gates below.

Confirmation gates#

Before ANY state-changing action, show the user exactly what will happen and get an explicit yes. One gate per action — do not re-ask for things the user just confirmed, and never batch-confirm.

ActionWhat you MUST show before doing itWrite config ( openclaw config patch)Every key=value you will write, verbatim. Never write secrets — see Credentials.First backup to a new destinationOutput of backup <mode> --dry-run: scope, sensitivity verdict, encryption status, target s3://bucket/prefix.Store/replace a credentialOnly the file path + storage method (AWS profile / passphrase file). The secret value itself should not transit this conversation — the user runs those commands themselves.RestoreStep 1: always restore <name> --dry-run and show the file list. Step 2: state which paths will be overwritten (staged restores write to a fresh directory; --in-place overwrites live state), then require an explicit yes. Never skip the dry run.PruneOutput of prune --dry-run: which archives (local and remote) will be deleted, by name.Schedule creationThe exact openclaw cron add ... command and full payload text (see Scheduling).

Repeat manual backups to an already-confirmed destination need no new gate — the user's request IS the confirmation. Still echo the one-line plan ("full backup, encrypted, → s3://bucket/prefix") before running.

Unattended runs (cron)#

A scheduled job's payload marks the run as operator-preconfirmed for backup and prune ONLY. In unattended runs: never restore, never change config, never create or modify schedules, never store credentials.

Modes — what each backup contains#

Echo this table when the user asks what gets backed up:

ModeIncludesExcludes by defaultSensitivitybackup full (default)openclaw.json, credentials/, secret stores, state + agent SQLite snapshots, agent memory, workspace, installed skillssession transcripts, codex caches/logs, qmd embedding caches (models + index), tools/, media/, logs/, old backupsSENSITIVE — encryption forcedbackup full --everythingeverything above PLUS session transcripts and codex historyprevious backup archives onlySENSITIVE — encryption forcedbackup settingsopenclaw.json, secret stores, credentials/, auth fileseverything elseSENSITIVE — always encrypted, no opt-outbackup workspaceworkspace directories (skills, memory files)all state/configencrypted by default; --no-encrypt allowed here only

"SENSITIVE — encryption forced" means the script refuses to produce a plaintext archive for that scope (exit 14). Do not work around it; if the user explicitly wants a plaintext-shareable archive, offer config.excludeSecrets=true instead. Users can tune scope with config.exclude / config.include (state-relative globs).

Subcommands#

CommandWhat it doesGate?backup [full|settings|workspace] [--everything] [--no-upload] [--dry-run] [--json]Create archive, encrypt, upload, apply retentiondry-run free; see gateslistLocal + remote backups; flags failure debrisnostatusHealth: last backup, credential sources, sensitivity verdict, schedule, reachabilitynoverify [name|--latest] [--deep]Checksum + decrypt + listing; --deep adds openclaw backup verifynorestore <name|--latest> [--target DIR | --in-place] [--only GLOB] [--dry-run] [--yes] [--force]Staged restore by defaultYES — two-stepprune [--dry-run]Apply retention; remove failure debrisYESschedulePRINT the opt-in cron command (creates nothing)nosetupSetup checklist + connection test (never writes config)config writes gated individually

Exit codes (report them precisely, especially from cron): 0 ok · 3 ok-with-warnings · 4 usage · 10 another run holds the lock · 11 missing dependency · 12 insufficient disk · 13 cloud unreachable/bad credentials · 14 encryption required but unavailable · 20-25 create/filter/encrypt/upload/ verify failures · 30 restore failure.

First-time setup#

Follow references/setup-flow.md step by step. Summary: choose provider → user creates a least-privilege bucket-scoped key (per provider guide) → store credentials OUTSIDE OpenClaw config (AWS profile recommended) → write non-secret config (gate) → test connection → enable encryption with a generated passphrase file → first manual backup (gate) → only then offer scheduling (gate).

Credentials#

Resolution order and storage rules: references/credentials.md. Hard rules:

• NEVER write access keys or passphrases into openclaw.json (no skills.entries.cloud-backup.env.*). Backups archive that file: a plaintext credential in config is carried inside every archive it protects.
• S3 credentials live in an AWS named profile ( config.profile, recommended) or operator-managed process env. The passphrase lives in a chmod-600 passphrase file ( config.passphraseFile).
• Operators who run OpenClaw's secret store can point the skill at it instead: config.accessKeyRef / config.secretKeyRef / config.passphraseRef accept OpenClaw SecretRefs ({source: env|file|exec}) resolved against .secrets.providers — including 1Password-style exec providers. Configured-but-broken refs abort the run; they never fall back.
• Prefer flows where the secret never appears in this conversation: the user runs aws configure --profile ... and the passphrase generator themselves.
• If the script prints a DEPRECATED warning about plaintext config credentials, surface it to the user verbatim and offer the migration in references/credentials.md.

Scheduling — strictly opt-in#

NEVER create, modify, or enable a cron job by default, implicitly, or because "backups should be scheduled". Skills document cron setup; only the user opts in.

Offer scheduling exactly once, AFTER the first successful manual backup:

"Backup verified. Want me to schedule this daily? I'd create this cron job — nothing is scheduled until you confirm:"

Then run schedule to print the exact command, adjust time/timezone/delivery to the user's setup, show it in full, and wait for an explicit yes before running it. If the user declines: drop it, and do not re-offer on later runs (check openclaw cron list first — if a cloud-backup job exists, never offer). To remove a schedule: openclaw cron rm <id>.

Error handling (for you, the agent)#

• Surface script stderr to the user verbatim (trim to the relevant lines). Never summarize an error into vagueness, never hide a WARN.
• Non-zero exit: diagnose using the exit-code table, explain, propose ONE fix. Never auto-retry restore, prune, or any openclaw cron mutation. backup may be retried once, only after the cause is fixed and the user agrees.
• Never invent bucket names, endpoints, or passphrases. Missing value → ask.
• Exit 14 (encryption required, no passphrase) fails hard by design — do not work around it with --no-encrypt or an ad-hoc passphrase. Run setup.
• The script cleans its staging on failure; if it reports it could not, tell the user the exact leftover path.

Reference docs (read only when needed)#

• references/credentials.md — resolution chain, v1→v2 migration, warnings
• references/setup-flow.md — guided first-time setup
• references/providers/{aws-s3,cloudflare-r2,backblaze-b2,digitalocean-spaces,minio,other}.md
• references/security.md — threat model, restore safety, incident response