How to Back Up Your OpenClaw Agent Before Migrating Servers
Server migrations are one of those things that seem straightforward until you're three hours in and your agent can't find its memory files. I've helped enough people recover from botched migrations that I can now predict exactly which files they forgot to back up.
Here's the complete list, including the ones nobody remembers.
## The files everyone remembers
Your OpenClaw workspace directory is the obvious one. It contains SOUL.md, AGENTS.md, HEARTBEAT.md, and your skill manifests. Most people grab this directory first, and that's correct. These files define who your agent is and what it can do.
If you're using git for your workspace (and you should be), this is already backed up in your repo. Just make sure you've pushed recently. I've seen people with weeks of uncommitted SOUL.md changes that existed only on the server they were about to decommission.
## The files most people forget
Here's where it gets interesting.
**Memory files.** Your agent's memory directory contains everything it has learned from interactions. Conversation summaries, user preferences, long-term context, pattern recognition data. This directory can be surprisingly large for agents that have been running for months. It's often in a different location than your workspace root, usually something like /var/lib/openclaw/memory/ or wherever your hosting provider puts persistent data.
**Environment variables.** Every agent has them. API keys for LLM providers, database connection strings, webhook secrets, feature flags. They live in your hosting platform's config (Coolify, Docker Compose, Fly.io secrets, whatever) and they definitely don't live in your git repo. Write them all down. Every single one.
I keep a secure note with every env var my agents use. Not the values (those go in a password manager), but the names and what they're for. When migration day comes, I know exactly which secrets need to be recreated on the new server.
**Skill-specific state.** Some skills maintain their own data files separate from the main workspace. A web scraping skill might cache crawled pages. A CRM skill might store customer interaction logs. A scheduling skill might have its own SQLite database. These files live wherever the skill decided to put them, which varies by skill.
Check each skill's documentation for where it stores state. Or just search for any files modified by the skill's process: that usually surfaces everything.
**Cron jobs and scheduled tasks.** If your agent runs periodic tasks (health checks, data syncs, report generation), those schedules are configured in your hosting platform, not in OpenClaw config files. Miss these and your agent will run fine but never do any of its scheduled work. You'll only notice when the weekly report doesn't show up.
**SSL certificates and domain config.** If your agent has a web interface or API endpoints with custom domains, the SSL certs and DNS records need attention. Let's Encrypt certs won't transfer (you'll generate new ones on the destination), but you need to know which domains point where so you can update DNS after migration.
## The practical checklist
Before you start migrating, go through this list:
**Workspace files** - [ ] SOUL.md, AGENTS.md, HEARTBEAT.md are committed and pushed - [ ] All skill manifests are in the workspace directory - [ ] Any custom config files in the workspace root are accounted for
**Memory and state** - [ ] Memory directory identified and backed up (check the actual path, don't assume) - [ ] Database dumps created if using PostgreSQL/MySQL for memory storage - [ ] SQLite files copied if any skills use local databases
**Environment and secrets** - [ ] Full list of environment variable names documented - [ ] All secret values stored in password manager - [ ] OAuth tokens and refresh tokens noted (some expire during migration) - [ ] API keys verified as still active
**Infrastructure config** - [ ] Cron jobs and scheduled tasks documented - [ ] Webhook URLs listed with their providers (you'll need to update these) - [ ] Reverse proxy config exported (nginx, Caddy, Traefik, etc.) - [ ] Docker Compose files or deployment configs backed up - [ ] Resource limits documented (CPU, memory, disk)
**Post-migration verification** - [ ] Health check endpoint URL noted - [ ] Test conversation scripts saved (to verify agent behavior after migration) - [ ] Monitoring and alerting configs backed up - [ ] Log aggregation settings documented
## What ClawSail does with this list
ClawSail automates about 80% of this checklist. It scans your agent's complete dependency tree, finds memory files regardless of where they're stored, enumerates environment variables from your hosting platform, and builds a migration package with everything included.
The remaining 20% is stuff that requires human judgment: verifying API keys are still active, deciding which webhook URLs need updating, confirming the destination server meets resource requirements. ClawSail flags these as manual review items.
## The one thing I'd add
After migration, run your agent for 24 hours before decommissioning the old server. Not because you think something will break, but because problems with migrations tend to be subtle. The agent works fine for basic interactions but fails when it tries to access a memory file that didn't transfer, or calls a webhook URL that still points to the old server.
Give it a full day of real usage. Then, and only then, shut down the original.