.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
OpenClaw feels “stateless” when you chat with it. Under the hood it’s the opposite. It keeps config, channel logins, sessions, memory, skills, and a bunch of small files that matter a lot the first time you migrate to a new server.
This guide is my practical backup checklist for OpenClaw. Not theory. Not “just copy the folder” advice. The goal is simple: if your VPS dies at 3AM, you can restore and your assistant behaves like nothing happened.
One note before we get into paths: older installs might still use .clawdbot directories, and older docs and scripts might still say “Moltbot”. The concepts are the same. The names changed.
What you need to back up in OpenClaw
If you only remember one thing from this article, remember this: OpenClaw has two important roots, plus an optional third.
1) State directory
The state directory is where the “plumbing” lives: config, secrets, auth profiles, sessions, and channel state. If you lose it you lose the stuff that is annoying to recreate.
Common contents include:
openclaw.json(main config)- auth profiles and provider tokens (API keys, OAuth tokens)
- session history for each agent
- channel state (for example WhatsApp login blobs)
- config backups like
.bak.*that also contain secrets
The official OpenClaw migration docs recommend stopping the gateway and archiving ~/.openclaw as part of a move. You can read that in OpenClaw migrating.
2) Workspace directory
Your workspace is the “brain files” side: memory markdown, persona rules, local skills, helper scripts, notes. If you lose this, OpenClaw still starts but it forgets who it is.
Typical contents include:
MEMORY.mdandmemory/filesSOUL.md,AGENTS.md,USER.md,TOOLS.md(if you use them)- workspace skills at
<workspace>/skills/<skill>/SKILL.md - anything you keep as “agent context” like templates, checklists, runbooks
If you want background on how memory is stored and why it’s just markdown, this is a good companion read: OpenClaw memory explained.
3) Media and attachments folder (optional but often worth it)
If you use OpenClaw through chat channels, you might have inbound images, voice notes, PDFs, and other files that you later refer back to. Some people don’t care and treat inbound media as disposable. Others absolutely rely on it.
If you do rely on it, back up the folder where you store inbound media. Some setups use a dedicated “media backup” skill to put files under something like:
~/openclaw-media/<channel>/YYYY-MM-DD/...That folder is just files. Treat it like any other folder in your backup tool.
Key default paths on Linux, macOS, and Windows
Paths vary a bit based on packaging and on profiles. Still, most installs follow the same shape.
Linux and macOS defaults
- State dir: usually
~/.openclaw/ - Workspace: often
~/.openclaw/workspaceunless you changed it
Some older setups may still have ~/.clawdbot or a custom workspace like ~/clawd. The safest approach is to confirm your config values by opening openclaw.json in the state dir and checking your agent workspace settings.
Windows defaults
On Windows you’ll usually see one of these, depending on how old the install is:
C:\Users\<User>\.openclawC:\Users\<User>\.clawdbot(older)
If you are unsure where your data is, OpenClaw’s FAQ has a section on operational basics like start/stop and troubleshooting. It’s often the easiest way to find the “what folder is this using” answer for your install. OpenClaw FAQ.
Minimal backup vs full backup
This is where people get burned. They back up the “nice” part (workspace) and forget the “ugly” part (state dir). Then they restore and wonder why WhatsApp needs to be paired again and why sessions vanished.
Minimal backup scope
Minimal backup is fine if you accept re-authentication.
openclaw.json- entire workspace directory (memory, persona files, local skills)
You will lose session history and you will redo channel logins and provider auth. If you run OpenClaw on WhatsApp and you hate pairing flows, you will not enjoy minimal backup.
Full backup scope
Full backup is what you want for a real “restore and continue” recovery.
- entire state dir (config, secrets, auth, sessions, channel state)
- entire workspace directory or directories
- media folder if you store inbound attachments
- database dumps if you use an external database for dashboards or session storage
With a full backup you keep personality, memory, sessions, and channel state intact after a restore.
Backups contain secrets so treat them like production
The state dir contains secrets in cleartext. That includes API keys and OAuth tokens and channel session data. So your backup set is basically a copy of your “keys to the kingdom”.
My baseline rules:
- Encrypt backups. No exceptions for state dir backups.
- Store the passphrase in a password manager. If you lose it, your backup is a brick.
- Don’t ship raw archives over email or Slack or public links.
- If you suspect backup exposure, rotate tokens and re-pair channels.
If you want the OpenClaw side of this (tool access and what counts as sensitive) our guide on hardening deployments is relevant: OpenClaw security best practices.
Quick export of memory and persona files
Memory is just markdown so exporting it can be as boring as copying a folder. If you want a manual “grab it now” export, here’s the simplest approach.
Manual memory-only export
# Adjust WORKSPACE if yours is different
WORKSPACE="$HOME/.openclaw/workspace"
mkdir -p "$HOME/Desktop/openclaw-memory-backup"
cp "$WORKSPACE/MEMORY.md" "$HOME/Desktop/openclaw-memory-backup/" 2>/dev/null || true
cp -r "$WORKSPACE/memory" "$HOME/Desktop/openclaw-memory-backup/" 2>/dev/null || trueManual full workspace export
WORKSPACE="$HOME/.openclaw/workspace"
cp -r "$WORKSPACE" "$HOME/Desktop/openclaw-workspace-backup"This is not a replacement for real backups. It’s the “I’m about to edit a bunch of persona rules and I want a quick rollback” move.
One-command backups with tar on Linux and macOS
If you want the lowest friction backup and you are fine with local archives that you later sync somewhere else, tar works.
Create encrypted archives with age
Tar alone is not encryption. You can combine tar with age (or gpg) and store the encrypted result off-host.
set -euo pipefail
BACKUP_DIR="$HOME/backups/openclaw"
DATE="$(date +%Y-%m-%d_%H-%M-%S)"
STATE_DIR="$HOME/.openclaw"
WORKSPACE_DIR="$HOME/.openclaw/workspace"
mkdir -p "$BACKUP_DIR"
tar -czf - -C "$STATE_DIR" . | age -p -o "$BACKUP_DIR/state-$DATE.tgz.age"
tar -czf - -C "$WORKSPACE_DIR" . | age -p -o "$BACKUP_DIR/workspace-$DATE.tgz.age"Downside: passphrase prompts make cron annoying unless you use an age key file. Upside: dead simple and portable.
Add a cron schedule
crontab -e
# Daily at 03:00
0 3 * * * /usr/local/bin/backup-openclaw.sh >/dev/null 2>&1If you already use OpenClaw cron for automations, it’s still fine to keep backups as a “system thing” via cron or systemd timers. For cron basics inside OpenClaw itself, this is handy: OpenClaw cron scheduler guide.
Backing up OpenClaw with Duplicati
Duplicati is popular because it’s cross-platform and it’s friendly. It also does encryption client-side. Duplicati’s docs cover encrypting and decrypting volumes plus the related tools. Duplicati encryption tools.
One more Duplicati detail: Duplicati community docs describe AES-256 encryption as a core feature and that data is encrypted locally before transfer. Duplicati community docs introduction.
Step 1: Choose your source folders
Add your state dir and your workspace dir.
- Linux/macOS:
~/.openclawand your workspace path - Windows:
C:\Users\<User>\.openclawand your workspace path
If your workspace is not inside .openclaw then add it explicitly. A lot of people put workspaces on a separate disk.
Step 2: Set encryption and keep the passphrase safe
In Duplicati you’ll pick encryption in the job wizard. Use AES-256. Pick a long random passphrase. Store it somewhere you won’t lose it.
Step 3: Schedule and retention
Daily is fine for most personal setups. If OpenClaw runs “all day” and you depend on it, every 6 hours is a reasonable bump.
Retention is personal. I like a simple pattern:
- one per day for 7 to 14 days
- one per week for 4 to 8 weeks
- one per month for a few months
What matters most is that you can restore a point from last week. That’s the “I broke config and didn’t notice right away” scenario.
Step 4: Do a test restore early
Don’t wait for disaster day. Run a restore into a temporary folder and confirm you see:
openclaw.jsonagents/and session filesworkspace/with memory and persona files
Backing up with restic or Borg for server setups
If you are running OpenClaw on a VPS or a homelab box, restic and Borg are common choices because they are scriptable and reliable.
Restic uses encryption by default and its docs describe deriving keys from the repository password using scrypt and then using AES-256 for encryption keys. restic references.
If you want a deeper cryptography explainer, Filippo Valsorda wrote a detailed breakdown of restic’s file encryption format and the encrypt-then-MAC design. restic cryptography notes.
A simple restic example
export RESTIC_REPOSITORY="s3:s3.amazonaws.com/your-bucket/openclaw"
export RESTIC_PASSWORD="use-a-real-passphrase-here"
restic backup "$HOME/.openclaw"
restic forget --keep-daily 14 --keep-weekly 8 --keep-monthly 6 --pruneIf you do this on a VPS, keep the password out of shell history. Use environment files with strict permissions or a secret manager.
Docker and volume backups
Docker setups are simple once you accept one fact: the “important folders” are usually volumes. So you back up volumes.
You may have:
- a volume for
OPENCLAW_STATE_DIR - a volume for workspace directories
- a database volume if you run Postgres or MySQL
Consistent snapshots
If you need consistent point-in-time backups, you can stop the service, snapshot, then start it again. That creates downtime but it avoids weird partial copies.
If you are on ZFS or LVM you can also do filesystem snapshots. That’s often the sweet spot for 24/7 services because it gives a consistent view without a long stop window.
Database dumps
If you store sessions or dashboards in Postgres or MySQL, back up the database too. That usually means:
pg_dumpfor Postgresmysqldumpfor MySQL
Keep database dumps encrypted like everything else.
Migration to a new machine
This is the scenario most people care about: you bought a new mini PC or you are moving OpenClaw from a test VPS to a production VPS.
The official migration docs are short and good. They recommend stopping the gateway and archiving .openclaw plus the workspace. OpenClaw migrating.
On the old machine
# Stop the gateway so files are not changing during copy
openclaw gateway stop
# Archive state dir
cd ~
tar -czf openclaw-state.tgz .openclaw
# Archive workspace (adjust if your workspace is elsewhere)
tar -czf openclaw-workspace.tgz .openclaw/workspaceOn the new machine
Install OpenClaw first. Then restore the archives into place.
cd ~
tar -xzf /path/to/openclaw-state.tgz
tar -xzf /path/to/openclaw-workspace.tgzThen start the gateway:
openclaw gateway start
openclaw statusVerify:
- channels are connected and replying
- memory recall works (ask it something you know is in memory)
- your skills are loaded
If you only restore the workspace and not the state dir, you will re-auth providers and re-pair channels. That’s not “wrong” but you should expect it.
Sessions and chat history
Session transcripts live in the state dir under per-agent directories. There is no universal “export session to JSON and import” button yet. So if you care about sessions, back up the state dir.
One practical tip: if you are debugging session behavior or you want to confirm sessions exist after a restore, listing sessions from the CLI is often the fastest sanity check.
A Git backup plan that does not leak secrets
Git is great for persona files and skills. Git is terrible for secrets and it’s also not great for fast-growing memory logs.
Good Git candidates:
SOUL.md,AGENTS.md,USER.md,TOOLS.mdskills/folders- templates and reference files you want versioned
Bad Git candidates:
openclaw.jsonif it contains secrets- large and frequently changing memory files if you care about repo size
A pattern I’ve seen work well is: Git for skills and persona files, encrypted backups for state dir and memory. That way you get clean diffs for “what changed” plus real recovery for everything sensitive.
Restore runbook you can copy into your notes
I like having a short runbook that fits on one screen. Here’s mine.
Backup checklist
- state dir included
- workspace dir included
- media folder included if used
- database dumps included if used
- backup encrypted
- off-host copy exists
- retention configured
Restore sequence
- stop OpenClaw gateway
- restore state dir
- restore workspace dir or dirs
- restore database if you use one
- start OpenClaw gateway
- verify channels, sessions, memory, skills
Small practical advice that saves you later
Don’t keep your only backup on the same disk
This sounds obvious. People still do it. If the disk dies, your backups died too.
Make your workspace path explicit
If you run multiple agents, name workspaces clearly and keep them stable. Moving a workspace later is fine but you will end up touching config and scripts and a few assumptions.
Back up after big config edits
OpenClaw config files tend to grow over time. After you add channels, skills, or agents, trigger a backup manually. It’s boring and it works.
