Openclaw Upgrade Standard

OpenClaw Upgrade Standard

A battle-tested upgrade procedure for OpenClaw, born from a real production failure where a Dashboard upgrade silently broke Gateway communication (Telegram, WebChat) with no clear error message.

Use this skill when: upgrading OpenClaw to a new version, planning a safe upgrade path, or recovering from a failed upgrade.

Why This Exists

In March 2026, a Dashboard-triggered upgrade from 2026.3.13 to 2026.3.22 caused:

• Silent Gateway failure (Telegram showed "typing" but never delivered)
• Dashboard used pnpm which wasn't installed
• Gateway entrypoint renamed (entry.js → index.js) without service file migration
• openclaw doctor --fix fixed config but NOT the systemd service file
• Required backup restore to recover

This procedure prevents all of these issues.

Golden Rule

NEVER upgrade via the Dashboard. Always use CLI.

Procedure

Step 1: Backup (2 min)

BACKUP_DIR="$HOME/.openclaw/workspace/backups/openclaw-upgrade-$(date -u +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"

# Config + credentials + agents
cp ~/.openclaw/openclaw.json "$BACKUP_DIR/"
cp -r ~/.openclaw/credentials "$BACKUP_DIR/" 2>/dev/null
cp -r ~/.openclaw/agents "$BACKUP_DIR/agents" 2>/dev/null

# Service file
cp ~/.config/systemd/user/openclaw-gateway.service "$BACKUP_DIR/" 2>/dev/null

# Version info
openclaw --version > "$BACKUP_DIR/state-info.txt"
npm list -g openclaw >> "$BACKUP_DIR/state-info.txt" 2>&1

echo "Backup saved to: $BACKUP_DIR"

Step 2: Read Release Notes (5 min)

Check https://github.com/openclaw/openclaw/releases

Red flags to watch for:

• "Breaking" entries → config or plugin changes
• Plugin SDK changes → can break Telegram/Discord
• Entrypoint changes → service file needs update
• Config/State migration → may invalidate existing config

Step 3: Doctor Baseline (1 min)

openclaw doctor 2>&1 | tee "$BACKUP_DIR/doctor-before.txt"

Step 4: Upgrade (3 min)

# ALWAYS use npm, never pnpm or Dashboard
npm update -g openclaw

# Verify
openclaw --version

Step 5: Doctor Fix (2 min)

# Check what needs migration
openclaw doctor

# Apply fixes (config schema changes, deprecations)
openclaw doctor --fix

Step 6: Fix Service Entrypoint (1 min)

# Check if entrypoint still matches
CURRENT_ENTRY=$(grep ExecStart ~/.config/systemd/user/openclaw-gateway.service | grep -oP 'dist/\K[^\ ]+')
ACTUAL_ENTRY=$(ls ~/.npm-global/lib/node_modules/openclaw/dist/index.js 2>/dev/null && echo "index.js" || echo "entry.js")

if [ "$CURRENT_ENTRY" != "$ACTUAL_ENTRY" ]; then
  echo "⚠️  Entrypoint mismatch: service=$CURRENT_ENTRY actual=$ACTUAL_ENTRY — fixing..."
  sed -i "s|dist/$CURRENT_ENTRY|dist/$ACTUAL_ENTRY|g" ~/.config/systemd/user/openclaw-gateway.service
  echo "✅ Fixed"
else
  echo "✅ Entrypoint OK"
fi

Step 7: Restart Gateway (1 min)

systemctl --user daemon-reload
systemctl --user restart openclaw-gateway.service
sleep 5
systemctl --user status openclaw-gateway.service

Step 8: Test (5 min)

Step 9: Document (2 min)

Success: Note version change + any fixes applied in your daily log.

Failure: Save all evidence, then rollback:

# Capture evidence BEFORE rollback
openclaw doctor 2>&1 > "$BACKUP_DIR/doctor-failed.txt"
journalctl --user -u openclaw-gateway -n 200 > "$BACKUP_DIR/gateway-logs-failed.txt" 2>&1
openclaw --version >> "$BACKUP_DIR/failure-info.txt"

Rollback Procedure

# 1. Install previous version
npm install -g openclaw@<OLD_VERSION>

# 2. Restore config
cp "$BACKUP_DIR/openclaw.json" ~/.openclaw/openclaw.json
cp "$BACKUP_DIR/openclaw-gateway.service" ~/.config/systemd/user/

# 3. Restart
systemctl --user daemon-reload
systemctl --user restart openclaw-gateway.service

# 4. Verify
openclaw --version
openclaw status

Known Pitfalls

Filing a Bug Report

If the upgrade fails and rollback is needed, file a bug at github.com/openclaw/openclaw/issues with:

1. OS, Node version, npm version
2. Upgrade path (from → to)
3. Install method (npm global / pnpm / other)
4. openclaw doctor output (before and after)
5. Gateway logs (journalctl --user -u openclaw-gateway -n 200)
6. Steps to reproduce
7. Whether rollback succeeded