Agent Backup Runbook (Checklist + Manifest) proposal

Goal: a human-style checklist + form (backed by command outputs) that produces an encrypted archive plus restore instructions to rebuild a Newclaw/OpenClaw agent on Linux or macOS.

Contents

Scope & non-goals
Backup artifact layout
Manifest schema
Wizard UX
Restore flow (Linux/macOS)
Dependency detection
Security model
Open questions

Scope & non-goals

In scope

Backup OpenClaw state (config + workspace + skills + skill outputs).
Collect and record runtime dependencies (binaries, versions) into a manifest.
Create an archive (default: .zip for compatibility). Encryption is optional and must be paired with a compatible extractor on restore.
Restore wizard that can run on Linux or macOS and guide installs/copies.

Non-goals (v1)

Fully automated system-level provisioning without confirmation (no silent sudo).
Perfect reconstruction of OS services (systemd launchd, etc.) in one click.
Backing up third-party cloud state (GitHub tokens, etc.) beyond what’s stored locally.

Backup artifact layout

The backup produces a single file, e.g. newclaw-backup-YYYYMMDD-HHMM.zip, containing:

backup/
  manifest.json
  README.txt
  payload/
    openclaw/          # copy of ~/.openclaw (or selected subpaths)
    workspace/         # copy of ~/.openclaw/workspace (or selected)
    system/            # optional: system-level snapshots (Linux)
  restore/
    restore.py
    restore.sh
    restore.zsh

Recommendation: treat “skill outputs” as anything under the workspace by default. Future enhancement: per-skill declarative outputs (see “Open questions”).

Manifest schema (draft)

Manifest is machine-readable so restore can be deterministic and auditable.

{
  "backupVersion": 1,
  "createdAtUtc": "2026-02-10T13:47:00Z",
  "source": {
    "os": "linux|macos",
    "arch": "x64|arm64",
    "hostname": "..."
  },
  "included": {
    "paths": ["~/.openclaw", "~/.openclaw/workspace"],
    "skills": ["idea-capture", "tiktok-video-to-recipe", "website-caddy-deploy"],
    "notes": "user-selected scope summary"
  },
  "dependencies": {
    "binaries": [
      {"name":"yt-dlp","path":"/usr/bin/yt-dlp","version":"..."},
      {"name":"caddy","path":"/usr/bin/caddy","version":"..."},
      {"name":"python3","path":"/usr/bin/python3","version":"..."}
    ],
    "packages": {
      "apt": ["yt-dlp", "ffmpeg", "p7zip-full"],
      "brew": ["yt-dlp", "ffmpeg", "p7zip", "caddy"]
    },
    "services": [
      {"name":"caddy","configFiles":["/etc/caddy/Caddyfile"],"platform":"linux"}
    ]
  },
  "security": {
    "encrypted": true,
    "format": "7z-aes256",
    "containsCredentials": true
  }
}

Wizard UX

Backup wizard prompts:

What to include (defaults checked):
- ~/.openclaw (option to exclude credentials)
- ~/.openclaw/workspace (option to include selected directories only)
- Optional Linux system snapshots: /etc/caddy/Caddyfile, systemd unit(s)
Password (required by default). Optionally allow “no password” only with explicit confirmation.
Output location + filename.
Print checksum (sha256) and a short restore command.

Restore flow (Linux/macOS)

Input: local path or URL to archive, plus password if encrypted.
Extract to a temp directory.
Show summary from manifest.json and ask for confirmation.
Dependency checks:
- If on Linux: offer apt install commands.
- If on macOS: offer brew install commands; if brew missing, guide install.
Copy payload to target locations (default: current user’s home directory).
Print post-restore steps (e.g., re-auth, re-enable services, DNS/certs, etc.).

Dependency detection (v1)

Detect dependencies from two sources:

Global baseline: binaries commonly used by the agent (e.g. python3, zip, 7z).
Skill heuristics: parse installed skills’ SKILL.md for command patterns (e.g. yt-dlp, caddy, ffmpeg) and check command -v plus version flags.

Security model

Archive is encrypted with a user-provided password.
Never echo passwords in logs/output.
Restore must require explicit confirmation before overwriting existing paths.
Credentials inclusion is a user choice; manifest records whether credentials were included.

Open questions

Should credentials be included by default, or excluded by default?
Should system-level configs (e.g. Caddyfile) be included as a snapshot only, or applied automatically with sudo?
Should we add per-skill backup.json metadata for declared outputs/deps?

Last updated: 2026-02-10 (UTC)