Config Backups

What Config Backups Are

Config backups are automatic snapshots of your instance's openclaw.json configuration file. They capture your LLM settings, channel configuration, personality, skills, cron jobs, and all other settings in that file.

This is a free feature included with every instance. No add-on or subscription needed.

Config backups are different from the Backup Add-on. The Backup Add-on creates full server snapshots (data, chat history, files). Config backups only store the configuration file. They're lightweight, fast, and run automatically.

What Gets Backed Up

Included	Details
LLM settings	Provider, model, API keys, fallback models, task models
Channel config	Telegram, Discord, Slack, WhatsApp tokens and settings
Personality	System prompt, agent configuration
Skills	Installed skills and their configuration
Cron jobs	Scheduled task definitions
Gateway settings	Auth mode, bind mode, proxy settings
Environment variables	Custom env vars set through the config

What Is Not Backed Up

Not Included	Use Instead
Chat history	Backup Add-on
Uploaded files	Backup Add-on
Custom packages	Backup Add-on
Pairing data	Re-pair after restore

Backup Schedule

Automatic backups run twice per day at 05:00 and 17:00 UTC. Each running instance gets its own backup task in the maintenance queue. If your instance is stopped or unreachable during a backup window, the backup is skipped for that cycle.

Retention Policy

Config backups follow a tiered retention policy:

Tier	Retention
Last 7 days	All backups kept (~14 total at 2x/day)
14-day mark	1 backup kept (closest to 14 days ago)
31-day mark	1 backup kept (closest to 31 days ago)
Older than 37 days	Automatically deleted

Manual backups are never automatically deleted. They stay until you remove them yourself.

Creating a Manual Backup

You can create a manual backup at any time from the dashboard:

1. Open your instance
2. Go to Settings > Config Backups
3. Click Backup Now
4. Optionally enter a description (e.g., "Before changing LLM provider")

Manual backups are useful before making significant changes to your configuration. If something breaks, you can restore the previous state.

There's a rate limit of one manual backup per minute per instance.

Previewing a Backup

Click Preview on any backup to see its contents. The preview shows the full configuration with sensitive values masked:

• API keys appear as sk-a...1234
• Bot tokens appear as 1234...5678
• Passwords and secrets are masked

This lets you verify what a backup contains before restoring it, without exposing your credentials.

Restoring from a Backup

1. Go to Settings > Config Backups
2. Find the backup you want to restore
3. Click the Restore icon
4. Read the warning carefully
5. Type your instance name to confirm
6. Click Restore Configuration

The restore runs as a background task. Your instance will restart with the restored configuration. This usually takes under a minute.

What Happens During a Restore

1. The stored configuration is pushed to your instance via SSH
2. OpenClaw's doctor runs to validate the config
3. The gateway restarts to apply changes
4. Health checks verify the instance is operational

Important Warnings

• Restoring overwrites your current configuration. Any changes made after the backup point are lost.
• Your instance will briefly restart. Connected messenger sessions may need to reconnect.
• The restore is not reversible. Consider creating a manual backup of your current config before restoring an older one.
• API keys are restored as-is. If you've rotated keys since the backup, the restored config will have the old (potentially invalid) keys.

Security

Config backups contain sensitive data (API keys, bot tokens). All backup data is encrypted at rest in the database using Rails encrypted attributes. When you preview a backup, secrets are masked before being sent to your browser. The full unmasked config is only used during restore operations.

Finding Config Backups

Open your instance dashboard and go to Settings > Config Backups. The tab shows all available backups sorted by date (newest first), with type badges (Auto/Manual), descriptions, file sizes, and action buttons.

Troubleshooting

No backups showing

• Automatic backups start within 12 hours of instance creation
• Your instance must be running for backups to be created
• If the instance was unreachable during both daily backup windows, no backups were created for that day

Restore failed

• Your instance must be running to restore a config
• Check the activity log for error details
• If the backup contains invalid API keys, your channels may fail to connect after restore. Update the keys in the dashboard.
• Try restoring from a different backup

Preview shows masked values

This is intentional. API keys and tokens are masked in previews for security. The actual values are preserved in the backup and restored correctly.

Related Documentation

• Backup Add-on: Full server snapshots (data + config + files)
• Config Editor: Edit configuration directly
• Rebuilding an Instance: Factory reset (wipes everything)