OpenClaw Backup and Migration Guide: Move Your Agent Without Losing It

I moved my main agent from an old Intel Mac mini to an M-series one last spring. I had a backup. It was a Time Machine drive, it was current, and the restore still took most of a Saturday, because the agent that woke up on the new machine had its config and none of its habits.

The workspace files had come across. The memory folder had come across. What had not come across was the launchd plist that started the gateway at login, two skills I had installed with absolute paths pointing at /usr/local/bin (which does not exist the same way on Apple Silicon Homebrew), and the WhatsApp session, which refused to resume on new hardware and wanted a fresh QR scan from my phone.

None of that was hard to fix. All of it was avoidable. This guide is the backup routine I run now and the order I restore in.

Know What Lives in ~/.openclaw

Everything that makes your agent yours sits under one state directory, which is ~/.openclaw unless you moved it. The exact layout shifts a little between releases, so run ls -la ~/.openclaw on your own machine before trusting my list. On the versions I run, the pieces that matter are these.

openclaw.json is the main config: agents, models, channels, tool policy. It also tends to hold API keys and bot tokens, which changes how you store it. workspace/ holds AGENTS.md, SOUL.md, MEMORY.md and the dated files in workspace/memory/, plus any workspace skills. skills/ holds managed skills. Channel credentials and session state (the WhatsApp pairing, for instance) live in their own subfolders. Per-agent session transcripts pile up too. logs/ is noise for backup purposes.

Those pieces are not equally precious. A missing openclaw.json costs you an evening with the docs. A missing workspace/memory/ costs you months of context that no amount of effort will recreate, because the agent wrote it and you never read most of it. The memory system deep dive explains why those files carry so much weight.

Put the Workspace in Git, Keep Secrets Out

My strong opinion: the workspace belongs in a private git repository, and openclaw.json does not. Git gives you history, which a nightly tarball does not. When the agent rewrites AGENTS.md in a way you dislike, or a memory file gets clobbered by a bad skill, git log -p shows you exactly when and what. I have rolled back an agent's own edits to its instructions three times this year. Without history I would not have noticed two of them.

cd ~/.openclaw/workspace
git init
cat > .gitignore <<'IGNORE'
tmp/
*.log
CREDENTIALS.md
.env*
IGNORE
git add -A && git commit -m "workspace snapshot"

Grep the workspace for tokens before the first push. Agents copy keys into notes more often than you would expect, usually while debugging something for you at 1am. The security hardening guide has a pattern list worth borrowing for that grep.

Snapshot the Rest Nightly

Git covers the workspace. Everything else gets an encrypted tarball. I stop the gateway for the snapshot, because session files and channel state copied mid-write can restore into something half-valid, and twenty seconds of downtime at 3:40am costs nothing.

#!/usr/bin/env bash
# claw-backup: encrypted snapshot of OpenClaw state
set -euo pipefail
STAMP=$(date +%Y%m%d-%H%M)
DEST="$HOME/Backups/openclaw"
mkdir -p "$DEST"

openclaw gateway stop
trap 'openclaw gateway start' EXIT

tar -C "$HOME" -czf - \
  --exclude='.openclaw/logs' \
  --exclude='.openclaw/workspace/tmp' \
  .openclaw \
  | age -r "$(cat "$HOME/.config/claw-backup.pub")" \
  > "$DEST/openclaw-$STAMP.tar.gz.age"

openclaw --version > "$DEST/openclaw-$STAMP.version"
ls -t "$DEST"/openclaw-*.age | tail -n +15 | xargs rm -f

A few choices in there are deliberate. The trap restarts the gateway even if tar fails, because a backup script that leaves your agent offline is worse than no backup script. The .version file records which OpenClaw release wrote the snapshot, which matters more than you think (more on that below). Fourteen copies is two weeks. I use age because the key is one line and I can print it, but GPG works if you already live in it. Schedule the script through the cron guide setup or plain launchd, and copy the output folder off the machine. A backup on the same disk as the agent protects you from typos and nothing else.

Restore in This Order

Migration and disaster recovery are the same procedure. Order matters, mostly because the gateway will happily start against a half-restored state directory and write fresh defaults over the files you were about to copy in.

# 1. install the SAME version the snapshot came from
cat openclaw-20261001-0340.version

# 2. make sure nothing is running yet
openclaw gateway stop 2>/dev/null || true

# 3. unpack state
age -d -i ~/.config/claw-backup.key openclaw-20261001-0340.tar.gz.age \
  | tar -C "$HOME" -xzf -

# 4. workspace from git, if you keep it there
git clone git@github.com:you/claw-workspace.git ~/.openclaw/workspace

# 5. read-only health check, then install the service
openclaw doctor
openclaw gateway install
openclaw gateway start
openclaw channels status --probe

Step one is the one people skip. Restoring a snapshot written by an older release onto the latest one means a migration and a machine move happen at the same time, and when something breaks you cannot tell which of the two caused it. Restore onto the matching version, confirm the agent works, then upgrade with the upgrade guide as a separate step on a separate day.

gateway install regenerates the service definition for the new machine, which is how you avoid my launchd problem: a copied plist carries the old binary path, the old username if it changed, and sometimes the old Node location. Let the CLI write a new one.

Expect to Re-Pair Some Channels

Bot-token channels (Telegram, Discord, Slack) usually come back fine, since the token in the config is all they need. Session-based channels are a different animal. WhatsApp ties its linked-device session to more than a file, and in my experience it wants a new scan after a hardware move about half the time. Keep your phone nearby. If channels status --probe shows one channel failing after restore, the gateway doctor guide covers the diagnosis, and the fix is almost always re-pairing rather than anything in the backup.

Hunt for Hardcoded Paths

This is the part Time Machine cannot help with. Skills and cron jobs written months ago tend to contain absolute paths to binaries, home directories, and Python virtualenvs. Before you call a migration done, search for them:

grep -rnE "/usr/local/bin|/Users/[a-z]+/|/home/[a-z]+/" \
  ~/.openclaw/skills ~/.openclaw/workspace/skills ~/.openclaw/openclaw.json

Every hit is a skill that works today and breaks quietly the first time it runs on the new box, which for a weekly job could be six days after you thought you were finished. Swap them for $HOME and command -v lookups while you are in there.

Run a Restore Drill

A backup you have never restored is a rumor.

Common Failure Modes

Final Verdict

Version the workspace in git. Encrypt a nightly snapshot of everything else, record which release wrote it, and get it off the machine. When you restore, match versions first and upgrade later, let the CLI generate the service file, and grep for paths that only made sense on the old hardware.

Then pick a quiet Sunday, restore last night's snapshot into a spare user account, and talk to the agent that wakes up there. If it remembers what you asked it on Thursday, you have a backup.