Backup OpenClaw Configuration

---

name: backup-openclaw-config

description: Backup and restore OpenClaw configuration files. Use when backing up OpenClaw settings before upgrades, transferring configuration to another machine, restoring from a previous backup, or preparing for system maintenance.

---

# Backup OpenClaw Configuration

Overview

This skill provides automated backup and restore functionality for all OpenClaw configuration files. It creates timestamped archives containing your complete OpenClaw setup, including main configuration, workspace, skills, and user data.

**What gets backed up:**

Quick Start

Backup Your Configuration

Run the backup script:

~/.openclaw/workspace/skills/backup-openclaw-config/scripts/backup_openclaw.sh [output-directory]

**Example:**

# Backup to default location ($HOME/backups/openclaw)
~/.openclaw/workspace/skills/backup-openclaw-config/scripts/backup_openclaw.sh

# Backup to custom location
~/.openclaw/workspace/skills/backup-openclaw-config/scripts/backup_openclaw.sh ~/my-backups

**Output:**

Restore from Backup

Run the restore script:

~/.openclaw/workspace/skills/backup-openclaw-config/scripts/restore_openclaw.sh <backup-archive.tar.gz>

**Example:**

~/.openclaw/workspace/skills/backup-openclaw-config/scripts/restore_openclaw.sh \
  ~/backups/openclaw/openclaw_backup_20260306_095000.tar.gz

**Process:**

1. Shows backup information from .info file

2. Lists all files that will be restored

3. Requires confirmation before proceeding

4. Backs up existing files with .bak extension

5. Restores configuration to original locations

**After restore:**

# Restart OpenClaw Gateway to apply changes
systemctl --user restart openclaw-gateway

Workflow

Backup Workflow

1. **Check prerequisites**

- Verify backup directory exists or can be created

- Check if OpenClaw directories exist

2. **Create backup structure**

- Generate timestamp for unique backup name

- Create temporary directory for staging

3. **Copy configuration files**

- Backup `~/.openclaw/` (main config)

- Backup `~/.config/openclaw/` (system config)

- Backup `~/.local/share/openclaw/` (local data)

- Skip directories that don't exist (with warning)

4. **Create archive**

- Compress all files into `.tar.gz` archive

- Create `.info` file with metadata (timestamp, hostname, user, size)

5. **Report results**

- Show archive location and size

- Display restore command

- Warn if any directories were missing

Restore Workflow

1. **Validate backup**

- Check if archive file exists

- Display backup information from .info file

- List contents of archive

2. **Safety confirmation**

- Show warning about overwriting current config

- List all files that will be restored

- Require explicit "yes" confirmation

3. **Backup existing files**

- Rename existing directories to `.bak`

- Preserve current configuration before overwriting

4. **Extract and restore**

- Extract archive to temporary directory

- Move files to original locations

- Restore `~/.openclaw/`, `~/.config/openclaw/`, `~/.local/share/openclaw/`

5. **Complete and notify**

- Show restore completion message

- Display restart command for Gateway

- Note that .bak files were created

Use Cases

Before Upgrade

# Backup before updating OpenClaw
~/.openclaw/workspace/skills/backup-openclaw-config/scripts/backup_openclaw.sh

# Then upgrade
openclaw update

Transfer to New Machine

# On old machine: create backup
~/.openclaw/workspace/skills/backup-openclaw-config/scripts/backup_openclaw.sh

# Transfer backup archive to new machine (scp, rsync, etc.)
scp ~/backups/openclaw/openclaw_backup_*.tar.gz user@new-machine:~/

# On new machine: restore
~/.openclaw/workspace/skills/backup-openclaw-config/scripts/restore_openclaw.sh \
  ~/backups/openclaw/openclaw_backup_*.tar.gz

Disaster Recovery

# Restore from backup after system failure
~/.openclaw/workspace/skills/backup-openclaw-config/scripts/restore_openclaw.sh \
  /path/to/backup/openclaw_backup_20260306.tar.gz

# Restart services
systemctl --user restart openclaw-gateway

Configuration Locations

For detailed information about what gets backed up, see [config-locations.md](references/config-locations.md).

**Summary:**

Best Practices

Regular Backups

Create backups regularly, especially after:

Secure Storage

Testing Backups

After creating a backup, verify it:

# Test extraction to temporary location
tar -tzf backup.tar.gz | head

# Verify critical files are present
tar -tzf backup.tar.gz | grep -E "(config.json|AGENTS.md|MEMORY.md)"

Troubleshooting

Permission Denied

If you see permission errors:

# Ensure scripts are executable
chmod +x ~/.openclaw/workspace/skills/backup-openclaw-config/scripts/*.sh

# Ensure backup directory is writable
mkdir -p ~/backups/openclaw
chmod 755 ~/backups/openclaw

Gateway Won't Start After Restore

If Gateway fails to start after restore:

# Check Gateway logs
journalctl --user -u openclaw-gateway -n 50

# Restore from .bak if needed
mv ~/.openclaw ~/.openclaw.bad
mv ~/.openclaw.bak ~/.openclaw

systemctl --user restart openclaw-gateway

Missing Directories

The backup script gracefully handles missing directories: