OpenClaw Upgrade Standard

Safe OpenClaw upgrade procedure with backup, doctor fix, service migration, rollback, and post-upgrade testing. Prevents silent failures from Dashboard upgra...

Security Scan

The instructions, required actions, and file accesses align with a legitimate OpenClaw upgrade/rollback procedure — no unexplained or disproportionate requirements were found.

Purpose & Capability

The name/description (safe OpenClaw upgrade with backup, doctor fix, service migration, rollback and testing) matches the instructions: backing up ~/.openclaw, running openclaw doctor, npm global upgrade/rollback, fixing the systemd user service, restarting and testing. Required tools (npm, systemctl, journalctl, sed, cp) are reasonable for the stated task.

Instruction Scope

All runtime steps stay within upgrade/rollback scope: they read and back up OpenClaw config/credentials, check/repair config, modify the OpenClaw systemd user service if entrypoint changed, restart it, and collect logs if needed. The instructions do not request unrelated files, network exfiltration, or external endpoints beyond the official GitHub releases page and filing issues on the OpenClaw repo.

Install Mechanism

This is an instruction-only skill with no install spec or bundled code. That lowers risk — nothing is downloaded or written by the skill itself beyond user-run commands described in the doc.

Credentials

No environment variables or external credentials are required by the skill, which is proportional. However the backup step explicitly copies credential and agents directories into a backup folder; while appropriate for rollback, users should understand these backups contain sensitive secrets and protect/encrypt the backup location.

Persistence & Privilege

always:false and no install means no persistent privileged presence. The described actions modify only user-level OpenClaw files and the systemd user service (expected for an upgrade). No cross-skill or system-wide configuration changes beyond the user's OpenClaw service are requested.

Assessment

This procedure appears legitimate and coherent, but take these precautions before following it: - Inspect and, if needed, adjust the BACKUP_DIR path. Backups include credentials and should be stored securely (restrict filesystem permissions and consider encrypting the backup archive). - Confirm your npm global prefix matches the script's assumed path (~/.npm-global); adapt the entrypoint checks if your npm global modules are located elsewhere. - Run the commands as the same user who runs the OpenClaw user service (systemctl --user) to avoid permission mismatches. - Review the sed replacement step before running it (make a copy of the service file first) to avoid corrupting the unit file. - Test the procedure in a staging environment if possible before applying in production. If you want extra assurance, provide the exact environment (OS, npm prefix) or a copy of your openclaw-gateway.service and I can point out any adjustments needed.

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

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