Backup & Restore

Back up your OpenClaw config, credentials, and data so you can recover from failures or migrate to a new machine. This guide covers what to back up, how to do it safely, and how to restore.

📘 Best practice: Back up before upgrading or making large config changes. Keep backups in a secure location; they may contain paths to credentials.

What to Back Up

  • Config directory - Typically ~/.openclaw (or the path reported by openclaw doctor). This holds config files, and often references to credentials. See Config File Structure.
  • Credentials - If you store API keys and tokens in files under the config directory (e.g. ~/.openclaw/credentials/), include them in the backup. Ensure the backup itself is stored securely (encrypted, restricted access). Prefer environment variables or a secrets manager in production; then backing up “where secrets are stored” is enough.
  • Session and memory data - If OpenClaw persists sessions or memory to disk in a known path (e.g. under the config directory), include that path so you can restore conversation context. Check the official docs for your version.
  • Custom skills - Any locally developed or modified skills that are not reinstallable from ClawHub. Copy the skill directories or repos.

How to Back Up

  1. Stop the Gateway (if running) so files are not in use: openclaw gateway stop or your platform’s equivalent.
  2. Copy the config directory to a safe location (another disk, network share, or encrypted archive). Example (Unix): tar -czvf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw. Exclude large or disposable caches if the docs say so.
  3. Document where credentials live - If you use environment variables, note which env vars are required so you can recreate them on a new machine. See Credential Management.
  4. Store the backup securely - Encrypt and restrict access. Do not commit backups containing secrets to public repos.

Restore

  1. Install OpenClaw on the target machine (or recover the same machine) using the Quick Start or a platform guide.
  2. Stop the Gateway if it is running. Restore the config directory from your backup (e.g. extract the tarball to the default path or set the config path to the restored location if your install supports it).
  3. Restore or reconfigure credentials (env vars or credential files) so the Gateway can access APIs and channels. Verify with openclaw config validate and openclaw doctor.
  4. Reinstall any skills from ClawHub that were in use; restore custom skills from your backup.
  5. Start the Gateway and test at least one channel. See Troubleshooting if something fails.

Migrating to a New Machine

Migration is effectively “backup on the old machine, install on the new, then restore.” Use the same steps as above. On the new machine, ensure Node.js version and OS compatibility match the installation requirements. If you change hostnames or IPs, update any channel webhooks or callback URLs that point at the old host. See Channel Setup and Network Isolation for remote access and security.

Related