OpenClaw Server Migration Guide

Migration Scenarios

As your usage scale grows or infrastructure changes, you may need to migrate OpenClaw from one server to another. Common migration scenarios include: upgrading from a low-spec to a high-spec server, switching from one cloud provider to another, migrating from a local development machine to a production server, or moving from a VPS to a dedicated host.

Regardless of the scenario, the core migration goals are: ensure complete configuration transfer, uninterrupted connections, and no data loss. This article provides a systematic migration workflow.

Pre-Migration Preparation

Understanding the Data Structure

All of OpenClaw's critical data is centralized in the ~/.openclaw/ directory. This directory contains:

openclaw.json: Main configuration file, including AI model settings, chat platform credentials, etc.
data/: Runtime data and message records
logs/: Log files (optional to migrate)

Checking the Current Environment

Record key environment information on the old server:

openclaw --version
node --version
cat ~/.openclaw/openclaw.json | head -5

Note the OpenClaw version and Node.js version to ensure the same or higher versions are installed on the new server.

Preparing the New Server Environment

Before migrating, set up the base environment on the new server:

Install Node.js 22+ (do not use Bun)
Install OpenClaw

# Install Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Install OpenClaw
npm install -g openclaw@latest

Verify the installation:

node --version
openclaw --version

Backing Up the Old Server Data

Stop the OpenClaw Service

Before backing up, stop the running OpenClaw service to ensure data consistency:

# If using systemd
sudo systemctl stop openclaw

# If running manually
# Find and terminate the process
pkill -f "openclaw start"

Archive the Configuration Directory

Archive the entire ~/.openclaw directory:

tar czf openclaw-backup-$(date +%Y%m%d).tar.gz -C ~ .openclaw

Record Service Configuration

If you configured a systemd service, back up the service file as well:

cp /etc/systemd/system/openclaw.service ~/openclaw-service-backup.service

If you configured an Nginx reverse proxy, back that up too:

sudo cp /etc/nginx/sites-available/openclaw ~/openclaw-nginx-backup.conf

Transferring Data to the New Server

Use scp or rsync to transfer the backup files to the new server:

Using scp

scp openclaw-backup-*.tar.gz user@new-server-ip:~/
scp openclaw-service-backup.service user@new-server-ip:~/

Using rsync (recommended, supports resume)

rsync -avz --progress openclaw-backup-*.tar.gz user@new-server-ip:~/

If the two servers cannot communicate directly, you can download to your local machine first and then upload, or use intermediate storage (such as object storage).

Restoring Data on the New Server

Extract the Configuration Directory

cd ~
tar xzf openclaw-backup-*.tar.gz

This will restore the .openclaw directory to the new server's user home directory.

Verify the Configuration File

Check that the configuration file has been fully restored:

ls -la ~/.openclaw/
cat ~/.openclaw/openclaw.json

Confirm that AI model keys, chat platform credentials, and other information in the configuration file are complete and correct.

Check Path Compatibility

If the username differs between the old and new servers, you may need to update path references in the configuration file. Open ~/.openclaw/openclaw.json and check for any hardcoded paths that need modification.

Configuring Services on the New Server

Configure systemd Service

Create a systemd service file on the new server. You can modify it based on the backed-up service file:

sudo nano /etc/systemd/system/openclaw.service

Make sure to update the following fields to match the new server's environment:

User and Group: The new server's username
ExecStart: The correct path to the OpenClaw executable
WorkingDirectory and HOME path in Environment

sudo systemctl daemon-reload
sudo systemctl enable openclaw

Configure Reverse Proxy (if needed)

If the old server used an Nginx reverse proxy, configure it on the new server as well:

sudo apt install -y nginx certbot python3-certbot-nginx
sudo nano /etc/nginx/sites-available/openclaw

The configuration content can reference your previously backed-up file. If you're also migrating the domain name, update the DNS records accordingly.

Start and Verify

Start the OpenClaw Service

sudo systemctl start openclaw

Run Diagnostic Checks

openclaw doctor

Carefully check each diagnostic result to ensure:

Node.js version meets the 22+ requirement
Configuration file loads correctly
AI model API connections are working
All chat platform connection statuses are normal

Check the Dashboard

openclaw dashboard

Access the new server's dashboard through a browser to confirm all features are working properly.

DNS and Domain Migration

If you configured a custom domain for OpenClaw, you need to update the DNS records to point to the new server's IP address.

Recommended steps:

First lower the DNS TTL value (e.g., to 60 seconds) and wait for the old TTL to expire
After confirming everything is working on the new server, update the DNS A record to point to the new IP
Wait for DNS propagation to complete (usually minutes to hours)
After confirming the domain resolves to the new server, shut down the old server

Handling SSL Certificates

If using Let's Encrypt certificates, simply request new ones on the new server:

sudo certbot --nginx -d openclaw.yourdomain.com

Verifying Chat Platform Connections

The most important step after migration is verifying that all chat platform connections are working properly:

WhatsApp: Check the WebSocket connection status; you may need to re-scan for authentication
Telegram: The Bot Token is not affected by server changes, but you need to update the Webhook URL
Discord: Also verify that Webhook and Bot connections are working properly

If any platform's Webhook URL contains the old server's domain or IP, update it in the corresponding platform's developer console.

Decommissioning the Old Server

After confirming the new server is running completely normally:

Stop the OpenClaw service on the old server
Keep the old server's backup data for at least 7 days
Disable auto-start settings on the old server
Once confirmed no traffic is reaching the old server, it can be safely shut down

# Execute on the old server
sudo systemctl stop openclaw
sudo systemctl disable openclaw

Migration Checklist

Here's a complete migration checklist:

Node.js 22+ installed on the new server
OpenClaw installed with matching version
Configuration directory ~/.openclaw/ fully restored
systemd service configured and enabled
openclaw doctor all checks passed
Dashboard accessible and functional
All chat platform connections working
Webhook URLs updated
DNS records updated (if applicable)
SSL certificates configured (if applicable)
Old server safely decommissioned

Summary

While server migration involves many steps, following a systematic process ensures a smooth transition for OpenClaw. The key points are: completely back up the ~/.openclaw/ configuration directory, verify all connections in the new environment, and only shut down the old server after confirming everything works. Using this guide's checklist, you can confidently migrate OpenClaw to any new server environment.