Openclaw Backup and Restore: Protect Your Agent Configuration

We have rebuilt Openclaw memory files from scratch exactly once. It took three weeks of retraining to get the agent back to where it was before a disk failure wiped the workspace. That experience changed how we approach every client deployment: backup is not optional infrastructure, it is the first thing we configure after the initial Openclaw setup.

This guide covers what to back up, how to automate daily encrypted backups with a single cron job, and how to restore onto a fresh machine. We also include something no other Openclaw backup guide provides: a disaster recovery test you can run today to prove your backups work.

What You Need to Back Up

Openclaw stores its state across several directories and files. Miss one during backup and you will discover the gap at the worst possible time.

The State Directory

The state directory (default ~/.openclaw) contains everything the Openclaw gateway needs to run:

• openclaw.json — main configuration file with provider connections, channel settings, and agent behavior
• auth/ — OAuth tokens and credential files for connected services
• sessions/ — conversation history and channel state for WhatsApp, Telegram, Discord, and other integrations
• hooks/ — custom event triggers
• cron/ — scheduled tasks

The Workspace Directory

The workspace directory holds your agent’s personality and learned knowledge. For most setups this lives inside ~/.openclaw/workspace, but custom configurations can place it anywhere:

• MEMORY.md — accumulated knowledge and preferences your agent has learned over time. This file represents weeks or months of training. Losing it means starting over. See our memory configuration guide for how this file works.
• AGENTS.md — agent definitions and role configurations
• SOUL.md — persona rules and behavioral guidelines
• USER.md — user profile and preference data
• TOOLS.md — tool configurations and permissions
• skills/ — custom skills you have built or installed. If you have invested time in skill development, these files are irreplaceable.

Environment and Secrets

Your .env file contains API keys for LLM providers (OpenAI, Anthropic, OpenRouter), integration tokens, and database credentials. Openclaw stores these in cleartext. Recreating a lost .env means regenerating every API key and re-authenticating every integration, which can take hours for a complex setup.

What You Can Skip

Browser cache, node_modules, and log files are all regenerated on startup. The openclaw backup create --dry-run --json command shows exactly what the built-in tool considers essential.

The Built-In Backup Command

Since v2026.3.8, Openclaw ships with native backup commands:

# Full backup — state, config, workspace, credentials
openclaw backup create

# Config only — smaller, faster, good for pre-update snapshots
openclaw backup create --only-config

# Specify output directory
openclaw backup create --output ~/backups/openclaw

# Verify an existing archive
openclaw backup verify ./2026-04-01T00-00-00.000Z-openclaw-backup.tar.gz

You get a timestamped .tar.gz archive with a manifest.json that maps every included file to its original path. The built-in tool handles deduplication: if your workspace lives inside the state directory, it will not archive the same files twice.

One limitation worth knowing: openclaw backup create does not encrypt the archive. Your API keys, OAuth tokens, and session credentials sit in the tarball as plaintext. For any serious data protection, you need encryption on top.

Automated Daily Backups

The built-in command is fine for manual snapshots. For production, you want unattended daily backups with encryption, rotation, and failure notification. Here is the script we use across client deployments:

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

# --- Configuration ---
BACKUP_DIR="$HOME/backups/openclaw"
STATE_DIR="$HOME/.openclaw"
RETENTION_DAYS=14
DATE=$(date +%Y-%m-%d-%H%M)
ARCHIVE="$BACKUP_DIR/openclaw-$DATE.tar.gz.age"
NOTIFY_EMAIL=""  # Set for email alerts on failure

mkdir -p "$BACKUP_DIR"

# --- Create encrypted backup ---
# Uses age (https://github.com/FiloSottile/age) for encryption
# Install: brew install age (macOS) or apt install age (Ubuntu)
tar -czf - \
  -C "$HOME" .openclaw \
  -C "$HOME" .env 2>/dev/null \
  | age -p -o "$ARCHIVE"

# --- Verify archive is not empty ---
if [ ! -s "$ARCHIVE" ]; then
  echo "ERROR: Backup archive is empty or missing"
  [ -n "$NOTIFY_EMAIL" ] && echo "Openclaw backup failed on $(hostname)" | mail -s "Backup FAILED" "$NOTIFY_EMAIL"
  exit 1
fi

echo "Backup created: $ARCHIVE ($(du -h "$ARCHIVE" | cut -f1))"

# --- Rotate old backups ---
find "$BACKUP_DIR" -name "openclaw-*.tar.gz.age" -mtime +$RETENTION_DAYS -delete
echo "Rotated backups older than $RETENTION_DAYS days"

Save this as backup-openclaw.sh, make it executable with chmod +x backup-openclaw.sh, and add it to cron:

# Run daily at 3 AM
crontab -e
# Add this line:
0 3 * * * /home/youruser/backup-openclaw.sh >> /home/youruser/backups/openclaw/backup.log 2>&1

The age encryption tool prompts for a passphrase on first run. Store that passphrase in a password manager, not on the same machine as the backups. If the machine dies and takes the passphrase with it, your encrypted backups become expensive paperweights.

A typical Openclaw state directory runs between 50 MB and 500 MB depending on conversation history length. With 14-day retention, expect 1-7 GB of backup storage.

Git-Based Versioning for Workspace Files

Automated backups protect against hardware failure. Git protects against accidental edits, bad memory merges, and “I liked the previous version better.”

The trick is versioning your workspace files without committing secrets. Here is a .gitignore that handles it:

# Version these (safe, no secrets)
!MEMORY.md
!AGENTS.md
!SOUL.md
!USER.md
!TOOLS.md
!skills/

# Exclude everything else
*
!.gitignore

# Never commit these
.env
auth/
sessions/
*.key
*.pem

Initialize the repo inside your workspace directory:

cd ~/.openclaw/workspace
git init
git add .
git commit -m "Initial workspace snapshot"

You can push this to a private GitHub or GitLab repository for off-site protection. The .gitignore ensures credentials never leave the machine.

We commit workspace changes after every significant memory update or skill addition. It takes five seconds and has saved us from bad agent behavior changes more than once.

Restoring to a New Machine

Migration follows a predictable sequence that works across Ubuntu VPS instances, macOS workstations, and Docker deployments:

1. Install Openclaw on the new machine:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
./scripts/setup.sh

2. Stop the gateway before restoring:

openclaw gateway stop

3. Decrypt and extract your backup:

age -d -o /tmp/openclaw-restore.tar.gz ~/backups/openclaw-2026-04-01-0300.tar.gz.age
tar -xzf /tmp/openclaw-restore.tar.gz -C "$HOME"
rm /tmp/openclaw-restore.tar.gz  # Clean up decrypted file

4. Restore your .env file separately if it was backed up independently:

cp /path/to/backup/.env ~/openclaw/.env

5. Start the gateway and verify:

openclaw gateway start

6. Run the post-restore verification checklist (see next section).

If you are migrating between different Openclaw versions, run openclaw doctor after restoring. The doctor command detects config schema mismatches and offers to apply migrations. Create a backup of the restored state before running doctor with the --fix flag, in case the migration introduces issues.

Docker Volume Backups

If you run Openclaw in Docker (see our Docker deployment guide), your state lives in named volumes rather than host directories. Back them up with:

# Stop the container first
docker compose -f docker-compose.yml stop openclaw

# Back up the named volume
docker run --rm \
  -v openclaw_data:/source:ro \
  -v $(pwd)/backups:/backup \
  alpine tar -czf /backup/openclaw-docker-$(date +%Y-%m-%d).tar.gz -C /source .

# Restart
docker compose -f docker-compose.yml start openclaw

Restore follows the same pattern in reverse: stop the container, extract the archive into the volume, start the container.

Disaster Recovery Testing

A backup you have never tested is a backup that might not work. We run this test monthly on every client deployment:

Step 1: Create a fresh test environment. Use a separate VPS, a Docker container, or even a different user account on the same machine.

Step 2: Restore from your most recent backup following the steps in the restore section above.

Step 3: Run the verification checklist:

# 1. Gateway starts without errors
openclaw gateway start
echo "Gateway: $(openclaw gateway status)"

# 2. Configuration loads correctly
openclaw doctor

# 3. Memory file exists and has content
wc -l ~/.openclaw/workspace/MEMORY.md

# 4. Skills directory is populated
ls -la ~/.openclaw/workspace/skills/

# 5. Agent definitions are present
cat ~/.openclaw/workspace/AGENTS.md | head -5

Step 4: Test channel connectivity. Send a test message through each connected channel (WhatsApp, Telegram, Discord, email) and confirm the agent responds with its trained personality intact.

Step 5: Verify scheduled tasks. Check that heartbeats and cron jobs fire on schedule. If you use heartbeat scheduling, confirm those triggers are restored.

Step 6: Document the result. Record the date, which backup was tested, and whether anything failed. When something does fail, you want to fix it now rather than during an actual emergency.

The entire DR test takes about 15 minutes. That is a small price for knowing your backups work.

Frequently Asked Questions

What files do I need to back up in Openclaw?

Back up the entire ~/.openclaw directory (state, config, credentials, sessions) and your .env file. The state directory contains everything the gateway needs. The workspace subdirectory within it holds your memory, agent definitions, and skills, which are the hardest to recreate from scratch.

How do I automate daily Openclaw backups?

Use the backup script in this guide with a cron job. The script creates an encrypted archive using age, validates it is not empty, and rotates archives older than 14 days. Schedule it with crontab -e for whatever time your agent is least active.

Are Openclaw backups encrypted by default?

No. The built-in openclaw backup create produces an unencrypted .tar.gz. Your API keys, OAuth tokens, and messaging credentials are visible to anyone with access to the archive. Wrap the output with age or GPG encryption for any backup stored off the local machine.

How large are Openclaw backup files?

A typical state directory runs 50-500 MB depending on conversation history. Config-only backups with --only-config are usually a few kilobytes. Encrypted compressed archives add minimal overhead.

Can I restore a backup to a different Openclaw version?

Usually yes, with caveats. Restore the backup, then run openclaw doctor to detect config schema differences. The doctor command can apply migrations automatically. Always create a snapshot of the restored state before running doctor --fix in case the migration introduces problems.

How do I back up Openclaw running in Docker?

Stop the container, use docker run with an Alpine image to tar the named volume, then restart. The Docker volume backup section above has the exact commands. Do not back up a running container’s volume as you risk capturing inconsistent state.

How do I test that my backup actually restores correctly?

Follow the disaster recovery testing protocol in this guide. Restore to an isolated environment, run openclaw doctor, verify memory and skills are present, test channel connectivity, and confirm scheduled tasks fire. Run this monthly.

What happens if I lose my Openclaw memory file?

You lose all learned preferences, accumulated knowledge, and personality training. The agent reverts to its default persona. Rebuilding takes days to weeks depending on complexity. This is why MEMORY.md is the single most important file to protect.

Key Takeaways

• Back up the entire ~/.openclaw directory and your .env file. Missing either one means a painful rebuild.
• The built-in openclaw backup create does not encrypt. Layer age or GPG encryption on top for any backup leaving the local machine.
• Automate with cron. Manual backups are backups that stop happening.
• Test your restores monthly. A backup you have never restored is a hope, not a plan.
• Version your workspace files with Git for protection against accidental changes, separate from your daily encrypted backups.