Cloud Backup [S3, R2, B2, MinIO & more]

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"

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.

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:

"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

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 .

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