Openclaw Workspace Backup Guide

logs/, tmp/, service-env/, memory/, __pycache__/, .DS_Store, *.log, node_modules/, .git/ — runtime noise that's either regenerated automatically or has no recovery value.

Say any of these to trigger a backup:

• "back yourself up"
• "make a backup"
• "snapshot yourself"
• "back up but keep 10 backups"
• "show me a dry run backup"

Truc runs the script, parses the output, and responds conversationally with the archive name, compressed size, and current backup count.

# Normal backup
python3 ~/.openclaw-trucbot1/skills/backup-truc/backup_truc.py

# Preview without writing anything
python3 ~/.openclaw-trucbot1/skills/backup-truc/backup_truc.py --dry-run

# Keep more backups than the default 7
python3 ~/.openclaw-trucbot1/skills/backup-truc/backup_truc.py --retention 10

On success, one line:

Backed up. trucbot1_backup_2026-06-08_1041.zip → iCloud (28 KB compressed, 24 files). 3 backup(s) in rotation.

If old backups were retired:

Retired: trucbot1_backup_2026-05-25_0800.zip

On failure, a single ERROR: line with the reason. No raw tracebacks.

~/Library/Mobile Documents/com~apple~CloudDocs/TrucBot1-Backups/

This is the standard iCloud Drive filesystem mount on macOS. The script writes directly here — no API, no daemon communication. The iCloud sync process picks up new files automatically and syncs them to Apple's servers.

Backups are accessible from:

• MacTruc Finder: iCloud Drive → TrucBot1-Backups
• BigMac or any other Mac: same iCloud Drive folder (once synced)
• iPhone / iPad: Files app → iCloud Drive → TrucBot1-Backups
• iCloud.com: browser access as a fallback

After each successful backup, the script lists all trucbot1_backup_*.zip files in the destination folder, sorts them by filename (which is chronological by design), and deletes the oldest ones beyond the keep limit.

Default: keep the last 7 backups. Override with --retention N for any single run.

Open Finder → iCloud Drive → TrucBot1-Backups. Pick the most recent .zip file (or the last known-good one if the most recent is suspect).

# Extract to a temp location first — don't overwrite live files yet
cd ~/Desktop
unzip ~/Library/Mobile\ Documents/com\~apple\~CloudDocs/TrucBot1-Backups/trucbot1_backup_YYYY-MM-DD_HHMM.zip -d truc_restore

# Verify contents look right before touching anything
ls truc_restore/
cat truc_restore/.openclaw/workspace-trucbot1/SOUL.md

# Stop both gateways first
launchctl unload ~/Library/LaunchAgents/ai.openclaw.trucbot1.plist
launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist

# Copy the files you need back into place (example: full skills restore)
cp -R ~/Desktop/truc_restore/.openclaw-trucbot1/skills/ ~/.openclaw-trucbot1/skills/

# Restart
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.trucbot1.plist

Restore only what's needed — you don't have to restore everything from a backup. Surgical restores (e.g., recovering a single skill or the soul files) are the most common case.

Run a backup whenever you:

• Add or significantly modify a skill
• Edit soul files (AGENTS.md, SOUL.md, MEMORY.md, etc.)
• Change either openclaw.json
• Are about to do something risky — OS update, OpenClaw upgrade, MacTruc reboot

A weekly automated backup via cron or launchd is a reasonable baseline for normal use.

Both openclaw.json files contain API keys and tokens in plaintext. iCloud encrypts backups in transit and at rest (Apple's standard encryption). Access requires your Apple ID credentials.

This is an acceptable risk for a personal LAN/cloud setup. If you ever need to share a backup zip with someone else for troubleshooting, strip the config files first.

• File count drift: A sudden jump or drop from the normal range (currently ~24 files) warrants investigation
• Archive size drift: Gradual growth is normal. A sudden 5x jump suggests something unexpected got included
• Missing paths note: If the output includes a "missing paths skipped" line, check whether a path was renamed or moved
• iCloud sync status: Occasionally verify the TrucBot1-Backups folder actually shows up on another device — confirms iCloud is syncing correctly

Standard ZIP with DEFLATE compression (zipfile.ZIP_DEFLATED). The archive preserves the relative path structure from ~ — so .openclaw/openclaw.json restores to exactly the right place.

The zip is written to a temporary file first, then renamed atomically into the destination folder. This prevents a partial archive from appearing in iCloud mid-write.

Python 3 standard library only. No pip installs required. No external tools.

• zipfile — archive creation
• pathlib / os — filesystem operations
• tempfile — atomic write staging
• argparse — CLI flags