OpenClaw Upgrade Standard

---

name: openclaw-upgrade-standard description: Safe OpenClaw upgrade procedure with backup, doctor fix, service migration, rollback, and post-upgrade testing. Prevents silent failures from Dashboard upgrades, entrypoint renames, and config breaking changes. metadata: openclaw: emoji: "⬆️"

---

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)

| Test | Command / Action | Expected | |---|---|---| | Gateway running | systemctl --user status openclaw-gateway | active (running) | | Version correct | openclaw --version | New version number | | Doctor clean | openclaw doctor | No "invalid config" errors | | WebChat | Send message in Dashboard | Response within 30s | | Telegram | Send message to bot | Response within 30s | | Agents listed | openclaw status | All agents shown | | Cron jobs | Check cron list | Jobs intact |

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@
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

| Problem | Cause | Fix | |---|---|---| | Dashboard upgrade fails | Uses pnpm (not installed) | Always use npm update -g openclaw | | Gateway won't start | Entrypoint renamed | Fix service file (Step 6) | | Config invalid | Schema breaking changes | openclaw doctor --fix | | Telegram silent | Gateway crashed or misconfigured | Check service status + logs | | "first-time setup mode" | Pairing state reset | Re-pair or check config | | Skills path errors | Skill paths changed | Re-check skill directories |

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