Introduction
When upgrading OpenClaw in a production environment, the biggest risk is service interruption. Active user conversations may be disrupted and Webhook callbacks may miss messages. This article introduces several zero-downtime or minimal-downtime upgrade strategies to help you complete version updates without affecting user experience.
1. Pre-Upgrade Preparation
1.1 Check Current and Target Versions
# Check the current running version
openclaw version
# Check the latest available version
openclaw update check
# Example output
# Current version: 1.2.0
# Latest version: 1.3.0
# Update type: Feature update (minor)
# Changelog: https://openclaw.com/changelog/1.3.0
1.2 Read the Changelog
Before upgrading, be sure to read the target version's changelog, paying special attention to:
- Breaking Changes: Any incompatible configuration format changes
- Database Migrations: Whether data format migrations are required
- Dependency Changes: Whether Node.js or other dependencies need updating
- New Configuration Options: Whether new configuration items need to be manually added
# View the changelog between versions
openclaw update changelog --from 1.2.0 --to 1.3.0
1.3 Create a Pre-Upgrade Backup
# Full backup (required step)
openclaw backup create --output /backup/openclaw-pre-upgrade-$(date +%Y%m%d).tar.gz
# Verify backup integrity
openclaw backup verify /backup/openclaw-pre-upgrade-$(date +%Y%m%d).tar.gz
1.4 Validate in a Test Environment
# Upgrade and validate in the test environment first
OPENCLAW_ENV=staging openclaw update --to 1.3.0
OPENCLAW_ENV=staging openclaw doctor
2. PM2 Zero-Downtime Reload
If you use PM2 to manage OpenClaw, you can leverage PM2's reload feature for zero-downtime updates.
2.1 Basic Flow
# Step 1: Upgrade the OpenClaw package
npm install -g [email protected]
# Step 2: Use PM2 reload (zero-downtime reload)
pm2 reload openclaw
# Step 3: Verify the new version
openclaw version
curl -s http://localhost:18789/health | jq '.version'
2.2 PM2 reload vs restart
| Operation | Downtime | How It Works |
|---|---|---|
pm2 restart |
~5-15 seconds | Stops the old process first, then starts the new one |
pm2 reload |
Near zero | Starts the new process first, waits for it to be ready, then stops the old one |
2.3 Configuring Graceful Reload
For PM2 reload to work properly, you need to configure graceful shutdown:
// openclaw-ecosystem.config.js
module.exports = {
apps: [{
name: "openclaw",
script: "openclaw",
args: "up",
// Graceful shutdown wait time (milliseconds)
kill_timeout: 15000,
// New process ready wait time
listen_timeout: 20000,
// Wait for ready signal
wait_ready: true,
// Maximum memory before reload
max_memory_restart: "512M"
}]
};
OpenClaw sends a ready signal after startup is complete and the health check passes. PM2 only stops the old process after receiving this signal.
2.4 Monitoring the Reload Process
# Watch the reload process in real time
pm2 logs openclaw --lines 20
# Monitor process status changes
watch -n 1 pm2 status
3. Systemd Graceful Restart
3.1 Using ExecReload
Configure the reload command in the systemd service file:
# /etc/systemd/system/openclaw.service
[Service]
ExecStart=/usr/local/bin/openclaw up
ExecReload=/bin/kill -SIGUSR2 $MAINPID
ExecStop=/bin/kill -SIGTERM $MAINPID
# Graceful shutdown timeout
TimeoutStopSec=30
Restart=always
RestartSec=5
# Upgrade flow
npm install -g [email protected]
sudo systemctl daemon-reload
sudo systemctl reload openclaw
# If reload is not supported, use restart
sudo systemctl restart openclaw
3.2 Systemd Downtime
Systemd's restart will cause a brief downtime. If zero downtime is required, consider using a dual-instance approach or pairing with Nginx.
4. Blue-Green Deployment
Blue-green deployment is a classic approach for achieving true zero downtime. It runs both the old and new versions simultaneously, completing the upgrade by switching traffic.
4.1 Architecture Overview
User Requests -> Nginx -> +-- Blue (old version v1.2.0) port 18789
+-- Green (new version v1.3.0) port 18790
4.2 Deployment Steps
# Step 1: Current production (Blue) is running on port 18789
# Confirm current status
curl -s http://localhost:18789/health
# Step 2: Start the new version (Green) on a new port
OPENCLAW_PORT=18790 openclaw up -d --name openclaw-green --config ~/.config/openclaw/openclaw.production.json5
# Step 3: Wait for the Green environment to be ready
sleep 20
curl -s http://localhost:18790/health
# Step 4: Verify Green environment functionality
openclaw doctor --port 18790
# Step 5: Switch Nginx traffic to Green
Modify the Nginx configuration to point traffic to the new port:
upstream openclaw_backend {
# Before switch: pointing to Blue
# server 127.0.0.1:18789;
# After switch: pointing to Green
server 127.0.0.1:18790;
}
server {
listen 443 ssl;
server_name openclaw.yourdomain.com;
location / {
proxy_pass http://openclaw_backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
# Reload Nginx configuration (zero downtime)
sudo nginx -t && sudo nginx -s reload
# Step 6: Confirm traffic has switched
curl -s https://openclaw.yourdomain.com/health | jq '.version'
# Should return "1.3.0"
# Step 7: Stop the old version (Blue)
openclaw stop --name openclaw-blue
4.3 Quick Rollback
If the new version has issues, simply switch Nginx back to the old port:
# Modify Nginx upstream to point to the old version port
# server 127.0.0.1:18789;
sudo nginx -s reload
5. Docker Rolling Upgrade
5.1 Using Docker Compose
# docker-compose.yml
version: '3.8'
services:
openclaw:
image: openclaw/openclaw:1.3.0
deploy:
update_config:
parallelism: 1
delay: 30s
order: start-first # Start new container first, then stop old one
failure_action: rollback
rollback_config:
parallelism: 1
delay: 10s
healthcheck:
test: ["CMD", "curl", "-sf", "http://localhost:18789/health"]
interval: 15s
timeout: 5s
retries: 3
start_period: 30s
ports:
- "18789:18789"
volumes:
- openclaw-data:/root/.openclaw
restart: always
# Pull the new image and perform a rolling update
docker compose pull
docker compose up -d
# Docker Compose will:
# 1. Start the new container
# 2. Wait for the health check to pass
# 3. Stop the old container
5.2 Docker Swarm Rolling Upgrade
# Update the service image
docker service update --image openclaw/openclaw:1.3.0 openclaw
# Monitor upgrade progress
docker service ps openclaw --format "table {{.ID}}\t{{.Image}}\t{{.CurrentState}}"
6. Data Migration Handling
6.1 Automatic Migration
OpenClaw automatically detects and executes necessary data migrations during version upgrades:
# Automatic migration on startup
openclaw up
# [INFO] Data format migration detected: v1.2 -> v1.3
# [INFO] Backing up current data...
# [INFO] Running migration: migrate_sessions_v1.3
# [INFO] Migration complete, 156 session records processed
6.2 Manual Migration
If automatic migration fails, you can run it manually:
# View pending migrations
openclaw migrate status
# Run migrations
openclaw migrate run
# Rollback migrations
openclaw migrate rollback --to 1.2.0
7. Upgrade Checklist
Before each upgrade, follow this checklist:
Upgrade Checklist: v1.2.0 -> v1.3.0
================================
[ ] Read changelog, confirm no Breaking Changes
[ ] Create full backup
[ ] Validate new version in test environment
[ ] Confirm channel connections work in test environment
[ ] Confirm message sending/receiving works in test environment
[ ] Confirm skill execution works in test environment
[ ] Notify team of upgrade plan and time window
[ ] Choose the lowest-traffic period for the upgrade
[ ] Execute upgrade
[ ] Verify production health check passes
[ ] Verify all channels have reconnected
[ ] Send test messages to confirm functionality
[ ] Monitor for 30 minutes to confirm no anomalies
[ ] Upgrade complete, record upgrade log
8. Rollback Strategies
8.1 Quick Rollback
# Option 1: PM2 environment downgrade
npm install -g [email protected]
pm2 reload openclaw
# Option 2: Restore from backup
openclaw stop
openclaw backup restore /backup/openclaw-pre-upgrade-20260314.tar.gz
npm install -g [email protected]
openclaw up -d
8.2 Post-Rollback Verification
# Confirm version
openclaw version # Should show 1.2.0
# Run diagnostics
openclaw doctor
# Confirm data integrity
openclaw stats --period 1h
Zero-downtime upgrades are not a one-time task but an operational practice that requires standardized processes and continuous rehearsal. Choose an upgrade strategy that fits your deployment scale, and prepare thoroughly before each upgrade to minimize risk.