How to Back Up and Restore OpenClaw Agent Data

OpenClaw agents accumulate state over time. Configuration files, OAuth tokens, conversation history, learned memory, custom skills, and workspace context all live in local directories. Lose those directories and your agent still installs, but it forgets who it is, what it learned, and how to authenticate with external services.

The risk is real for several deployment scenarios. A developer running OpenClaw on a laptop faces disk failure or accidental deletion. A Docker deployment can lose volume data during container recreation. A team migrating to new infrastructure needs to transfer agent state without downtime.

OpenClaw ships a built-in backup command that archives everything into a single .tar.gz file. The native command handles archiving, but not encryption, scheduling, or recovery testing. A complete backup strategy layers those concerns on top of the built-in tooling.

OpenClaw's built-in backup command captures four categories of data by default, as documented at docs.openclaw.ai.

State directory: The core data store containing your agent configuration, OAuth tokens, authentication profiles, conversation history, hooks, and scheduled tasks. This directory holds everything the agent needs to resume its identity after restoration.

Configuration file: The active configuration that defines agent behavior, model preferences, and connected services. This is the single file that determines how your agent operates on startup.

Credentials directory: API keys, integration tokens, and service account files stored outside the state directory. The backup command collects these automatically so you do not lose access to connected services.

Workspace directory: The files your agent references and updates during operation, including learned memory, agent definitions, personality files, and custom skills. The SFAI Labs backup guide identifies the memory file as the highest-priority item because "losing it means starting over" after weeks of agent training.

The backup command excludes session transcripts, logs, temporary files, and plugin dependencies that can be rebuilt after restoration. It also deduplicates paths that overlap with the state directory to keep archives lean.

Typical archive sizes range from 50 MB to 500 MB depending on workspace content. Large workspaces with media files can push higher. For a minimal backup, a config-only flag captures just the configuration file.

The basic backup command creates a timestamped .tar.gz archive in your current working directory:

openclaw backup create

The archive includes a manifest.json that maps every file to its source path and position in the archive. This manifest is what makes verification possible.

Useful Flags

• --output <path>: Write the archive to a specific location instead of the current directory
• --dry-run: Preview what would be backed up without creating an archive
• --verify: Validate the archive immediately after creation
• --no-include-workspace: Exclude workspace directories for a smaller archive
• --only-config: Back up only the configuration file
• --json: Output results in JSON format for scripting

Start with --dry-run to see exactly what will be archived before committing:

openclaw backup create --dry-run

For production backups, always combine --output with --verify:

openclaw backup create --output ~/backups/openclaw/ --verify

Verifying an Existing Archive

The verify subcommand checks that the manifest is present and valid, all declared files exist in the archive, and no path traversal attacks are embedded:

openclaw backup verify ./openclaw-backup-2026-05-10.tar.gz

The verify command intentionally bypasses normal config validation. This means it works even when you are restoring to a different OpenClaw version or recovering from a broken configuration. If you have an invalid config and need to back up anyway, use --no-include-workspace to avoid config validation errors during the backup itself.

One safety detail worth noting: the backup command never overwrites existing archives and rejects output paths that fall within the directories being backed up. You will not accidentally overwrite a previous backup or create a recursive archive.

Keep your agent backups versioned and accessible

Upload encrypted OpenClaw archives to a Fast.io workspace with audit trails and team access. 50 GB free, no credit card required.

Sign Up Free

OpenClaw backups contain sensitive data in plaintext. Your API keys, OAuth tokens, and session credentials sit in the archive unprotected. For any environment beyond local development, encrypt your backups before storing them.

The OpenClaw community has converged on age as the recommended encryption tool. It is simple, audited, and does not require the key management complexity of GPG.

Encrypted Backup with age

openclaw backup create --output /tmp/openclaw-backup.tar.gz
age -p -o ~/backups/openclaw-$(date +%Y-%m-%d).tar.gz.age /tmp/openclaw-backup.tar.gz
rm /tmp/openclaw-backup.tar.gz

The -p flag prompts for a passphrase. Store that passphrase in a password manager, not on the same machine as your backups. If your backup disk is compromised alongside your passphrase, encryption provides no protection.

Alternative: Pipe Directly

You can skip the intermediate unencrypted file by piping the tar output through age:

tar -czf - -C "$HOME" .openclaw | age -p -o ~/backups/openclaw-$(date +%Y-%m-%d).tar.gz.age

This approach keeps plaintext data out of disk entirely, though it bypasses OpenClaw's built-in deduplication and manifest generation.

Off-Site Storage Options

Encrypted archives should not live on the same disk as your agent. The 3-2-1 backup rule applies here: three copies, two different media types, one off-site.

For off-site storage, you have several practical options. Cloud object storage like S3 or GCS gives you durability and versioning. A tool like restic handles incremental encrypted backups to cloud storage with built-in retention policies:

export RESTIC_REPOSITORY="s3:s3.amazonaws.com/your-bucket/openclaw"
export RESTIC_PASSWORD="use-a-real-passphrase"
restic backup "$HOME/.openclaw"
restic forget --keep-daily 14 --keep-weekly 8 --keep-monthly 6 --prune

For teams that already use Fast.io as a workspace for agent output, it doubles as encrypted off-site storage. Upload your encrypted archives to a dedicated workspace, and you get versioning, audit trails, and the ability to share recovery files with team members through controlled access. The free agent plan includes 50 GB of storage, which covers months of daily backups at typical archive sizes.

Manual backups stop happening. A backup strategy that depends on someone remembering to run a command is a strategy that fails the week you need it most.

Cron-Based Automation

A cron job running daily at 3 AM covers most use cases. Here is a minimal backup script that creates encrypted archives with 14-day retention:

#!/usr/bin/env bash
set -euo pipefail

BACKUP_DIR="$HOME/backups/openclaw"
RETENTION_DAYS=14
DATE="$(date +%Y-%m-%d)"

mkdir -p "$BACKUP_DIR"

### Create and encrypt backup
openclaw backup create --output "/tmp/openclaw-$DATE.tar.gz" --verify
age -p -o "$BACKUP_DIR/openclaw-$DATE.tar.gz.age" "/tmp/openclaw-$DATE.tar.gz"
rm "/tmp/openclaw-$DATE.tar.gz"

### Rotate old backups
find "$BACKUP_DIR" -name "*.tar.gz.age" -mtime +$RETENTION_DAYS -delete

echo "Backup complete: $BACKUP_DIR/openclaw-$DATE.tar.gz.age"

Schedule it with cron:

crontab -e
### Add this line:
0 3 * * * /usr/local/bin/backup-openclaw.sh >> /var/log/openclaw-backup.log 2>&1

With 14-day retention, expect 1 to 7 GB of total backup storage depending on your workspace size.

Docker Deployments

Containerized OpenClaw needs special handling. Never back up a running Docker volume because the archive can capture inconsistent state. Stop the container first:

docker compose stop openclaw
docker run --rm \
  -v openclaw_data:/source:ro \
  -v $(pwd)/backups:/backup \
  alpine tar -czf /backup/openclaw-$(date +%Y-%m-%d).tar.gz -C /source .
docker compose start openclaw

The downtime is typically under a minute. For zero-downtime backups, use filesystem snapshots (ZFS or LVM) to capture a consistent point-in-time copy of the volume.

Git for Workspace Versioning

Encrypted archives protect against data loss. Git versioning protects against unwanted changes. Track your workspace files in a private repository so you can diff changes, roll back memory edits, and audit how your agent's knowledge evolves:

cd ~/.openclaw/workspace
git init
git add MEMORY.md AGENTS.md SOUL.md TOOLS.md skills/
git commit -m "Initial workspace snapshot"

Keep a .gitignore that excludes secrets and session data. Push to a private remote. This gives you fine-grained version history that tar archives cannot provide.

Restoration is the part that matters. A backup you have never restored is a hope, not a plan.

Standard Restoration Steps

1. Install OpenClaw on the target machine
2. Stop the gateway to prevent state conflicts:

   openclaw gateway stop
  

3. If your backup is encrypted, decrypt it first:

   age -d -o /tmp/openclaw-restore.tar.gz backup-2026-05-10.tar.gz.age
  

4. Extract the archive to your home directory:

   tar -xzf /tmp/openclaw-restore.tar.gz -C "$HOME"
  

5. Start the gateway:

   openclaw gateway start
  

6. Run the doctor command to check for issues:

   openclaw doctor
  

Post-Restore Verification Checklist

After restoration, verify these items before considering the agent operational:

• Gateway starts without errors
• openclaw doctor returns clean results
• Memory file has content and reflects your agent's learned knowledge
• Skills directory is populated
• Agent definitions are present
• Channel connections work (messaging services, email, webhooks)
• Scheduled tasks fire on schedule

Version Migration

When restoring to a different OpenClaw version than the one that created the backup, run openclaw doctor before applying any fixes. Schema mismatches between versions can require specific migration steps. Create a snapshot of the freshly extracted state before running openclaw doctor --fix so you can roll back if the fix introduces new issues.

Migration Between Machines

For machine-to-machine migration, the process is the same as disaster recovery. On the old machine, create and encrypt a backup. Transfer the encrypted archive to the new machine via secure copy, a shared drive, or a workspace platform like Fast.io where you can upload from one machine and download from another with audit logging. Decrypt and extract on the new machine, then verify.

The SFAI Labs guide recommends monthly disaster recovery testing, and the investment is small: about 15 minutes per test. The goal is to confirm that your most recent backup actually produces a working agent.

Monthly DR Test Protocol

Spin up a clean environment (a fresh VM, a Docker container, or a separate user account on your machine) and attempt a full restore using your latest backup. Walk through the verification checklist from the restoration section above. Document the results: what worked, what broke, and how long recovery took.

Pay special attention to channel connectivity. OAuth tokens for messaging services (Telegram, Discord, Slack) may expire or require re-authorization after restoration. Knowing this before an actual emergency saves panic debugging at 2 AM.

Backup Monitoring

Add basic monitoring to your backup script so failures are visible:

• Check that today's archive exists and is non-empty
• Verify the archive with openclaw backup verify
• Send a notification (email, Slack automation hooks, or monitoring service) on failure
• Track backup sizes over time to catch unexpected growth or shrinkage

A backup that silently fails for three weeks is worse than no backup at all, because it gives you false confidence.

Recovery Time Targets

For most OpenClaw deployments, a reasonable recovery target is under 30 minutes from "disk is gone" to "agent is answering." That breaks down to about 5 minutes for installation, 5 minutes for decryption and extraction, 5 minutes for verification, and a buffer for troubleshooting. If your recovery consistently exceeds this, simplify your backup structure or pre-stage restoration scripts.

Teams running OpenClaw in production should keep a written runbook alongside their backups. The runbook should include where backups are stored, which passphrase entry in the password manager decrypts them, the exact restoration commands, and who to contact if channels fail to reconnect. When the person who set up backups is unavailable during an incident, the runbook is what keeps recovery on track.