# Migrating Your OpenClaw to a New Machine

Canonical: https://clawdocx.com/docs/migration-guide
Author: Sam Okafor
Difficulty: BEGINNER
Published: 2026-02-24
Updated: 2026-09-19

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

## 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

> **Note**
>
> 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

| Component | Location | Important? |
|-----------|----------|-----------|
| **SOUL.md** | `~/.openclaw/workspace/SOUL.md` | Critical: your agent's personality |
| **MEMORY.md** | `~/.openclaw/workspace/MEMORY.md` | Critical: long-term memory |
| **Daily memories** | `~/.openclaw/workspace/memory/` | Important: recent context |
| **USER.md** | `~/.openclaw/workspace/USER.md` | Important: info about you |
| **TOOLS.md** | Retired: `openclaw doctor --fix` merges it into the `## Tools` section of `AGENTS.md` | Skip it and migrate `AGENTS.md` instead |
| **AGENTS.md** | `~/.openclaw/workspace/AGENTS.md` | Important: operating rules, and the new home for TOOLS.md notes |
| **HEARTBEAT.md** | Retired: heartbeat instructions live in monitor scratch, not in the workspace | Skip it, after `openclaw doctor --fix` on the old machine |
| **Config** | `~/.openclaw/openclaw.json` | Critical: API keys, channels, settings |
| **Skills** | `~/.openclaw/skills/` | Important: shared installed skills |
| **Cron jobs** | Stored in config | Important: scheduled tasks |
| **Custom files** | Anything else in workspace | Varies |

---

## 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
```

> **Warning**
>
> 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

- [Security Hardening](/docs/security-hardening): secure your new setup
- [Keeping OpenClaw Running 24/7](/docs/process-management): set up systemd on the new machine

## 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

- [OpenClaw: Retired HEARTBEAT.md workspace file](https://docs.openclaw.ai/reference/templates/HEARTBEAT)
- [OpenClaw: TOOLS.md retired](https://docs.openclaw.ai/reference/templates/TOOLS)
- [OpenClaw: Where things live on disk](https://docs.openclaw.ai/help/faq/where-things-live-on-disk)
- [OpenClaw: Other checks and repairs](https://docs.openclaw.ai/cli/doctor/checks)