Browse guides
Back to Guides
BeginnerGetting StartedOpenClaw

Migrating Your OpenClaw to a New Machine

Move your entire OpenClaw setup to a new server or machine without losing data, covering backups, transfer steps, and verification.

Sam Okafor25 minutes

#When to Migrate

Common reasons to move your OpenClaw setup:

  • Upgrading to a more powerful server
  • Switching VPS providers
  • Moving from local machine to cloud (or vice versa)
  • Setting up a fresh OS but keeping your agent's personality and memory

The entire migration can be done in under 15 minutes. OpenClaw's workspace is self-contained, and everything important lives in one directory.

#What Gets Migrated

ComponentLocationImportant?
SOUL.md~/.openclaw/workspace/SOUL.mdCritical: your agent's personality
MEMORY.md~/.openclaw/workspace/MEMORY.mdCritical: long-term memory
Daily memories~/.openclaw/workspace/memory/Important: recent context
USER.md~/.openclaw/workspace/USER.mdImportant: info about you
TOOLS.mdRetired: openclaw doctor --fix merges it into the ## Tools section of AGENTS.mdSkip it and migrate AGENTS.md instead
AGENTS.md~/.openclaw/workspace/AGENTS.mdImportant: operating rules, and the new home for TOOLS.md notes
HEARTBEAT.mdRetired: heartbeat instructions live in monitor scratch, not in the workspaceSkip it, after openclaw doctor --fix on the old machine
Config~/.openclaw/openclaw.jsonCritical: API keys, channels, settings
Skills~/.openclaw/skills/Important: shared installed skills
Cron jobsStored in configImportant: scheduled tasks
Custom filesAnything else in workspaceVaries

#Step 1: Backup on the Old Machine

#Quick Backup (Everything)

bash
# Create a complete backup archive
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz \
  ~/.openclaw/
# Check the backup size
ls -lh openclaw-backup-*.tar.gz

#Selective Backup (Just the Essentials)

bash
# Backup just the workspace and config
tar -czf openclaw-essentials-$(date +%Y%m%d).tar.gz \
  ~/.openclaw/workspace/ \
  ~/.openclaw/openclaw.json \
  ~/.openclaw/skills/

#Export Cron Jobs

bash
# List current cron jobs and save them
openclaw cron list --json > cron-backup.json
# Review what you have
openclaw cron list

#Save Your Skill List

bash
# List installed skills
ls ~/.openclaw/skills/ > installed-skills.txt
cat installed-skills.txt

#Step 2: Transfer to New Machine

#Option A: SCP (Direct Transfer)

bash
# From your local machine or old server
scp openclaw-backup-*.tar.gz user@NEW_SERVER_IP:~/

#Option B: rsync (Better for Large Workspaces)

bash
# Sync directly between servers
rsync -avz --progress ~/.openclaw/ user@NEW_SERVER_IP:~/.openclaw/

#Option C: Via Git (If Workspace Is a Repo)

If you've been versioning your workspace with git:

bash
# On the old machine: push everything
cd ~/.openclaw/workspace
git add -A && git commit -m "Pre-migration backup" && git push
# On the new machine: clone
git clone YOUR_REPO_URL ~/.openclaw/workspace

#Step 3: Install OpenClaw on the New Machine

bash
# Install Node.js (if not installed)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# Install OpenClaw
npm install -g openclaw
# Verify
openclaw --version

#Step 4: Restore Your Backup

bash
# Extract the backup
cd ~
tar -xzf openclaw-backup-*.tar.gz
# Verify files are in place
ls ~/.openclaw/workspace/SOUL.md
ls ~/.openclaw/openclaw.json
cat ~/.openclaw/workspace/SOUL.md | head -5

#Update Config If Needed

If your new server has a different IP or hostname:

bash
# Review and edit config
nano ~/.openclaw/openclaw.json
# Things to check:
# - Gateway bind address
# - Any localhost references
# - File paths (if username changed)

#Step 5: Reinstall Skills

bash
# If you transferred the skills directory, they should already be there
ls ~/.openclaw/skills/
# If not, reinstall from your backup list
cat installed-skills.txt
# Then: openclaw skills install <skill-name> for each

#Step 6: Restore Cron Jobs

bash
# Review your backed-up cron jobs
cat cron-backup.json
# Recreate each one
openclaw cron create --schedule "0 8 * * *" --task "Morning briefing..."
# Repeat for each cron job

#Step 7: Start and Verify

bash
# Start OpenClaw
openclaw gateway start
# Or set up as systemd service (recommended for servers)
# See: /docs/process-management
# Check status
openclaw status
# Send a test message via your messaging channel
# Verify your agent responds with the right personality

#Verification Checklist

  • Agent responds to messages
  • SOUL.md personality is intact
  • Agent remembers previous context (check MEMORY.md)
  • Skills work (try a weather query, etc.)
  • Cron jobs are scheduled (openclaw cron list)
  • Messaging channel is connected

#Step 8: Decommission Old Machine

Once you've verified everything works on the new machine:

bash
# On the old machine
openclaw gateway stop
# Remove the systemd service (if configured)
sudo systemctl stop openclaw
sudo systemctl disable openclaw
sudo rm /etc/systemd/system/openclaw.service
sudo systemctl daemon-reload
# Optional: remove OpenClaw
npm uninstall -g openclaw

Keep your backup archive for at least a week after migration, just in case you notice something missing.

#Troubleshooting

#Agent Doesn't Recognize Me

  • Check that USER.md was transferred correctly
  • Verify your messaging channel token matches

#Skills Not Working

  • Reinstall skills: openclaw skills install <name>
  • Check if skills need API keys configured separately

#Different Node.js Version

  • OpenClaw requires Node.js 20+
  • Check with: node --version

#Next Steps

Frequently asked questions

Which directories does an OpenClaw migration have to move?
Two. The state directory at ~/.openclaw holds config, channel and provider state, auth profiles, sessions, logs and shared skills, and the agent workspace holds SOUL.md, AGENTS.md, USER.md, MEMORY.md and the memory folder. The workspace defaults to ~/.openclaw/workspace, so a copy of ~/.openclaw usually captures both, but check agents.defaults.workspace first in case yours points elsewhere.
Do I need to copy HEARTBEAT.md or TOOLS.md to the new machine?
No, both are retired. OpenClaw no longer creates HEARTBEAT.md in new workspaces or reads it at runtime, and local tool notes now live in the Tools section of AGENTS.md. Run openclaw doctor --fix on the old machine first and it archives both files and folds their content into the current homes.
Where are my configuration backups after a migration?
Beside the config file, not in a backups folder. Any config write, including a doctor --fix repair, rotates a backup to ~/.openclaw/openclaw.json.bak with a numbered .bak.1 to .bak.4 ring, so copying ~/.openclaw brings the recent rollback points along with the live config.

Sources

  1. OpenClaw: Retired HEARTBEAT.md workspace file
  2. OpenClaw: TOOLS.md retired
  3. OpenClaw: Where things live on disk
  4. OpenClaw: Other checks and repairs

Skip the trial and error

ClawDocx members get 500+ tested prompts, ready-to-install SKILL.md files, SOUL.md and CLAUDE.md templates, and an MCP server so your agent can pull all of it directly while it works.

See plans Connect your agent