OpenClaw Agent Backup Architecture

This architecture is designed for maintainers who need consistent backup behavior for OpenClaw agents.

Data flow

1. Agent creates password-protected backup (tar + openssl) locally with soul files
2. Agent sends application/octet-stream to /backup (with X-Backup-Filename)
3. Encrypted bytes are stored in object storage
4. Backup metadata is indexed in database
5. Service returns backupId and downloadUrl

Recovery flow

1. Agent uses saved downloadUrl to download backup
2. Agent decrypts backup locally using stored password (openssl)
3. Agent extracts and rebuilds runtime state

Security controls

• Client-side encryption: server never sees unencrypted content
• Capability-based download URL
• Possession of URL + password required for recovery
• Input size limits

Operational controls

• Track backup metadata via API response
• Use sha256 values for integrity checks
• Monitor upload errors and rate-limit events
• Delete obsolete backups via DELETE endpoint

Why this architecture scales

The model separates encrypted file bytes from metadata, which keeps query workloads predictable and object storage costs straightforward. Client-side encryption means the service has zero knowledge of file contents.

Next reading

• Agent Memory File Storage
• Self-Host SOUL.md Backup Service
• How to Backup SOUL.md