🦞 How to Migrate OpenClaw
to a New Machine

VPS · Mac Mini · Laptop — Step by Step

~10 min walkthrough · Works for any Linux or macOS target

Why Migrate?

Three common scenarios

🖥️
VPS for 24/7 Uptime
Move from your laptop to a $5/mo VPS. Your agent runs while you sleep. Cron jobs, Discord bot, always on.
🍎
Mac Mini Home Server
Apple ecosystem integration. Siri Shortcuts, AirDrop files to your agent, low power draw.
💻
New Laptop / Upgrade
Got a new machine? Bring your skills, workspace, and config with you. 15 minutes tops.

What Files Need to Move

Your entire agent lives in one folder

~ — bash
$ tree ~/.openclaw/ -L 2
/home/user/.openclaw/
├── 📁 workspace/ # ← your agent's brain
│ ├── SOUL.md # personality & identity
│ ├── MEMORY.md # long-term memory
│ ├── memory/ # daily context files
│ └── skills/ # workspace-level skills
├── 📁 skills/ # ← custom skills you built
│ ├── crypto-analysis/
│ ├── ssh/
│ └── ...
├── 🔑 .env # ← API keys (IMPORTANT)
├── 📄 openclaw.json # ← main config
├── agents/ # agent definitions
└── sessions/ # can skip — regenerated
💡 The workspace/, skills/, openclaw.json, and .env are the critical four. Everything else regenerates.

Step 1: Install Node + OpenClaw

On the NEW machine

🐧 Linux / VPS
ubuntu@vps — bash
# Install Node.js 18+
$ sudo apt update && sudo apt install -y curl
$ curl -fsSL https://deb.nodesource.com/setup_18.x \
  | sudo -E bash -
$ sudo apt install -y nodejs

# Install OpenClaw globally
$ npm install -g openclaw

$ openclaw --version
openclaw v2026.2.23
🍎 macOS
mac-mini — zsh
# Install Node.js via Homebrew
$ brew install node

# Install OpenClaw globally
$ npm install -g openclaw

$ openclaw --version
openclaw v2026.2.23

# That's it. Homebrew handles
# everything for you.

Step 2: Backup the Old Machine

One command — grab everything that matters

old-machine — bash
$ cd ~

# Bundle the critical files into one archive
$ tar -czf openclaw-backup.tar.gz \
    .openclaw/workspace/ \
    .openclaw/skills/ \
    .openclaw/openclaw.json \
    .openclaw/.env

$ ls -lh openclaw-backup.tar.gz
-rw-r--r-- 1 user user 2.4M Feb 25 12:00 openclaw-backup.tar.gz

# ✅ That's your entire agent in one file
💡 Skip sessions/ — they're large and regenerate automatically. Skip node_modules/ — npm install handles that.

Step 3: Transfer the Backup

Pick your method

🖥️ VPS → VPS
scp openclaw-backup.tar.gz \
user@new-vps-ip:~/
🍎 Mac → Mac
AirDrop · USB Drive
iCloud Drive
🌐 Cross-Platform
Google Drive · Dropbox
rsync · USB stick
new-machine — bash
# On the NEW machine — extract into place
$ mkdir -p ~/.openclaw
$ tar -xzf openclaw-backup.tar.gz -C ~/

$ ls ~/.openclaw/
workspace/ skills/ openclaw.json .env
✅ All files restored

Step 4: Set Up API Keys

Check your .env — update if needed

new-machine — nano ~/.openclaw/.env
# ~/.openclaw/.env
# Your API keys live here — NOT in .bashrc

OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Optional — for specific features
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=eyJhbGciOi...
DISCORD_TOKEN=MTIzNDU2Nzg5...
⚠️ Keep keys in .env, not in shell profiles. The .env file is loaded by OpenClaw directly and stays out of your shell history.

Step 5: Configure & Start

Fire it up

new-machine — bash
$ openclaw gateway start

╔══════════════════════════════════════╗
║ 🦞 OpenClaw Gateway v2026.2.23 ║
╚══════════════════════════════════════╝

✓ Loading workspace from ~/.openclaw/workspace
✓ 4 skills loaded
✓ Discord channel connected
✓ Gateway started on port 3000

Ready. Listening for messages...

# Test it — send a message in Discord
[Discord] Michael: hey, you alive?
[Discord] 🦞: I'm here! Running on the new machine.
Migration successful. 🎉

Step 6: Auto-Start on Boot — Linux

systemd service — survives reboots

nano /etc/systemd/system/openclaw.service
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu
ExecStart=/usr/bin/openclaw gateway start
Restart=on-failure
RestartSec=5
EnvironmentFile=/home/ubuntu/.openclaw/.env

[Install]
WantedBy=multi-user.target
ubuntu@vps — bash
$ sudo systemctl daemon-reload
$ sudo systemctl enable openclaw
Created symlink ... → openclaw.service
$ sudo systemctl start openclaw
$ sudo systemctl status openclaw
● openclaw.service - OpenClaw Gateway
Active: active (running) since Tue 2026-02-25 12:05:00 UTC

Step 6: Auto-Start on Boot — macOS

launchd plist — the Mac way

nano ~/Library/LaunchAgents/com.openclaw.gateway.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.openclaw.gateway</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/openclaw</string>
    <string>gateway</string>
    <string>start</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
</dict></plist>
mac-mini — zsh
$ launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist
✅ Service loaded — starts automatically on login

Step 7: Reboot Test

The moment of truth

new-machine — bash
$ sudo reboot

Connection to new-machine closed.
...
# Wait 30 seconds, SSH back in
...

$ systemctl status openclaw

● openclaw.service - OpenClaw Gateway
Loaded: loaded (/etc/systemd/system/openclaw.service; enabled)
Active: active (running) since Tue 2026-02-25 12:06:32 UTC; 45s ago
Main PID: 1842 (node)
Memory: 128.4M
CPU: 2.1s

Feb 25 12:06:33 vps openclaw[1842]: 🦞 Gateway started on port 3000
Feb 25 12:06:34 vps openclaw[1842]: ✓ Discord connected
Feb 25 12:06:34 vps openclaw[1842]: ✓ Ready. Listening for messages...
💡 If it doesn't start, check journalctl -u openclaw -f for logs. Most common issue: wrong Node.js path in the service file.

✅ Migration Checklist

Everything in one place

✅ Install Node.js 18+ on new machine
✅ npm install -g openclaw
✅ Backup: tar workspace, skills, config, .env
✅ Transfer backup to new machine
✅ Extract into ~/.openclaw/
✅ Verify / update API keys in .env
✅ openclaw gateway start
✅ Set up auto-start (systemd / launchd)
✅ Reboot test — confirm it survives
⚠️ Common Issues

Gateway won't start?
→ Check node path: which openclaw

Bot not responding?
→ Verify DISCORD_TOKEN in .env

Skills missing?
→ Ensure skills/ was in your tar backup

Permission denied?
→ Check file ownership: chown -R $USER ~/.openclaw

🦞

That's it. Your agent is migrated.

The whole process takes about 15 minutes.
Your skills, memory, and personality come with you.

👍 Subscribe for more OpenClaw guides

Drop a comment if you hit any snags — I'll help you debug it.

github.com/openclaw/openclaw · MIT License · Free forever