Workspace Backup & Restore

OpenClaw keeps config, credentials, prompts, skills, and conversation state on disk. If you reinstall the OS, move to a new machine, or recover from a failure, you need to know what to back up and where it lives. This page lists the important paths and a simple restore flow. For full path details, see Architecture – Workspace structure and Configuration.

These locations hold the data that defines your OpenClaw setup. Paths are defaults; your install may use different roots if configured.

• Config — ~/.openclaw/openclaw.json (or your config file path). Model, gateway, cron, webhooks, session routing, skills enabled.
• Credentials — ~/.openclaw/credentials/. OAuth tokens, API keys stored by OpenClaw. Sensitive; store backups encrypted.
• Workspace root — ~/.openclaw/workspace/ by default. Contains:
  • AGENTS.md, SOUL.md, TOOLS.md — Agent identity and system prompts
  • skills/ — Installed skills (each skills/<name>/SKILL.md and any scripts)
  • Daily memory files, session state, and other runtime data the agent writes
• Secrets — If you use openclaw secrets or SecretRef, back up the secrets store in the same way you protect credentials. See Secrets.

Optionally version-control your workspace (e.g. ~/.openclaw/workspace/) and config in a private repo so you have history and can restore to any point.

CLI backup (recommended): OpenClaw provides built-in backup and verify commands. Use these for fast, consistent archives of config, credentials, sessions, and optionally the workspace:

openclaw backup create
openclaw backup create --only-config
openclaw backup create --no-include-workspace
openclaw backup verify <path-to-archive>

By default openclaw backup create archives config, credentials, and sessions; include the workspace unless you use --no-include-workspace. Use openclaw backup verify <archive> to check an archive before restoring. Destructive flows in the CLI may prompt you to create a backup first.

Manual backup: You can also copy the directories above to a safe place (external drive, cloud storage, or encrypted archive). Example:

# Create a timestamped backup
BACKUP=~/openclaw-backup-$(date +%Y%m%d)
mkdir -p "$BACKUP"
cp -r ~/.openclaw "$BACKUP/"
# Optionally compress
tar -czf "$BACKUP.tar.gz" "$BACKUP" && rm -rf "$BACKUP"

Exclude very large or ephemeral data (e.g. caches, temp files) if you only need config, prompts, and skills. Include credentials/ only if your backup is encrypted and access-controlled.

1. Install OpenClaw on the new machine or after reinstall — Installation.
2. Stop the Gateway if it is running.
3. Restore config: Copy openclaw.json (and any other config files) to ~/.openclaw/ (or your configured path).
4. Restore credentials: Copy the contents of credentials/ back to ~/.openclaw/credentials/. Ensure permissions are correct so only your user can read them.
5. Restore workspace: Copy your backed-up workspace tree into ~/.openclaw/workspace/ (or the path set in agents.defaults.workspace).
6. Restore secrets if you use a secrets store — see Secrets.
7. Start the Gateway and verify channels and skills. Re-authenticate OAuth or re-pair channels if tokens were invalidated.

If you moved to a new machine, you may need to reconnect channels (e.g. WhatsApp QR, Telegram bot) and re-authorize any OAuth apps (Gmail, Google Calendar, etc.) because tokens are often tied to the device or app instance.

Same as restore: back up config, credentials, and workspace on the old machine; install OpenClaw on the new one; restore the three; start the Gateway. Then re-pair or re-authorize any channel or provider that requires a new login. Use the same Node/OpenClaw version where possible to avoid config drift.

Architecture – Workspace structure, Configuration, Secrets, Memory.