OpenClaw Stable Operations

Most OpenClaw failures happen during or immediately after an update. This guide covers safe update procedure, config backup, rollback, and ongoing health monitoring — so you can update with confidence.

1-Minute Pre-Update Checklist

Run before every update.

Pre-Update Checklist

# 1. Backup current config
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-$(date +%Y%m%d)

# 2. Note current version
openclaw --version

# 3. Check Gateway is healthy before update
openclaw gateway status

# 4. Run update
npm update -g openclaw

# 5. Re-register Gateway after update
openclaw gateway install --force
openclaw gateway restart

# 6. Verify
openclaw gateway status
openclaw doctor

Safe Update Procedure

OpenClaw updates can regenerate internal tokens, modify Gateway configuration, or change WebSocket handshake behavior. Clients connected during an update will get token mismatch or 1006 errors. Do this instead:

Step 1: Backup config first

See the Backup section below. Takes 10 seconds.

Step 2: Stop the Gateway before updating

Prevents clients from getting a mid-update 1006 error.

Step 3: Update, then run gateway install --force

Reinstalls the Gateway service with new binaries. Skipping this causes token mismatch after update.

Step 4: Verify with openclaw doctor

Catches config regressions introduced by the update before you put it back in service.

Full Safe Update Sequence

# Stop Gateway
openclaw gateway stop

# Backup (if not done yet)
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

# Update
npm update -g openclaw

# Re-register service
openclaw gateway install --force

# Start
openclaw gateway start

# Verify
openclaw doctor

Config Backup

The entire OpenClaw state you need to preserve is in ~/.openclaw/. The config file is JSON — easy to diff, easy to restore.

Backup Config

# Manual backup with datestamp
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-$(date +%Y%m%d)

# Full directory backup
cp -r ~/.openclaw ~/.openclaw-backup-$(date +%Y%m%d)

# List your backups
ls ~/.openclaw/*.bak* 2>/dev/null || echo "No backups found"

Your openclaw.json contains API keys. Do not commit backups to a public git repo. Store them in a password manager or encrypted storage if you need them long-term.

Windows Path

Windows Backup

# Windows — backup config
copy %APPDATA%openclawopenclaw.json %APPDATA%openclawopenclaw.json.bak

# Full directory
xcopy %APPDATA%openclaw %APPDATA%openclaw-backup-%date:~-4,4%%date:~-10,2%%date:~7,2% /E /I

Rollback After a Bad Update

If an update breaks your setup, you have two rollback levers: config and version.

Rollback Config Only

If the update changed your config and broke things, restore from backup:

Restore Config Backup

# Restore most recent backup
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json

# Or restore a specific datestamped backup
cp ~/.openclaw/openclaw.json.bak-20260225 ~/.openclaw/openclaw.json

# Restart with restored config
openclaw gateway restart
openclaw doctor

Rollback OpenClaw Version

If the update itself is broken, downgrade to the previous version:

Downgrade OpenClaw Version

# Check available versions
npm view openclaw versions --json

# Install a specific version
npm install -g [email protected]

# Re-register
openclaw gateway install --force
openclaw gateway restart

After a version downgrade, always run openclaw gateway install --force. Without it, the Gateway service binary is still the new version even though the CLI is downgraded.

Health Monitoring

Proactive monitoring catches Gateway crashes before they interrupt running tasks. Basic options by setup type:

CLI health check script

Run periodically with cron or Task Scheduler. Alerts you if the Gateway stops responding.

Docker healthcheck directive

Docker restarts the container automatically and reports UNHEALTHY in docker ps.

External uptime monitor

Services like UptimeRobot (free tier) can ping your Gateway's health endpoint and send email/Slack alerts.

Basic Cron Health Check

Cron Health Check

# macOS / Linux — add to crontab (crontab -e)
# Checks Gateway every 5 minutes, restarts if not running
*/5 * * * * openclaw gateway status || (openclaw gateway restart && echo "Gateway restarted at $(date)" >> ~/openclaw-restarts.log)

# View restart history
cat ~/openclaw-restarts.log

Docker Healthcheck

# docker-compose.yml
services:
  openclaw-gateway:
    image: openclaw/gateway:latest
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Get notified the moment your Gateway goes down.

Gateway Monitor watches your instance and sends an alert before your agents notice. Early access — free.

Get Early Access

Related Troubleshooting

Errors you may hit during updates:

Other Tools

Config Wizard

Generate a production-ready clawhub.json in 30 seconds.

Local Doctor

Diagnose Node.js, permissions, and config issues instantly.

Cost Simulator

Calculate your agent burn rate before you get surprised.

Gateway Monitor

Detect token spikes and gateway incidents before users complain.

Skill Finder

Describe your use case and find the right Claude Code skill instantly.

Did this guide solve your problem?