OpenClaw 2026.3.13 Upgrade Guide: From Backup to Pitfall Avoidance

This weekend, I upgraded OpenClaw from version 2026.2.2 to 2026.3.13. What I thought would be a simple version update turned into a two-day saga where I stumbled into six distinct pitfalls. I’ve compiled the entire process here to help you avoid the same headaches.

📋 Upgrade Overview

  • Before: OpenClaw 2026.2.2 + Node.js 18 + Manual Token Configuration
  • After: OpenClaw 2026.3.13 + Node.js 22 + Auto-generated Tokens
  • Environment: Ubuntu 22.04 + nvm (Node Version Manager) + Feishu Local Plugin
  • Time Taken: 2 days (mostly troubleshooting)

💾 Step 1: Pre-Upgrade Backup (Critical!)

⚠️ Hard-learnt Lesson: Always back up before upgrading! During my troubleshooting, I wanted to roll back multiple times. Having backups gave me the confidence to keep trying without fear of breaking everything permanently.

OpenClaw’s configuration is scattered across several locations. Ensure you save the following files:

Files You Must Backup

One-Click Backup Command

# Create a backup directory with a timestamp
BACKUP_DIR="$HOME/openclaw-backup-$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

# Backup config files
cp ~/.openclaw/openclaw.json "$BACKUP_DIR/"
cp ~/.openclaw/.openclaw/openclaw.json "$BACKUP_DIR/runtime.json"

# Archive workspace and memory data
tar -czf "$BACKUP_DIR/workspace.tar.gz" -C ~/.openclaw workspace
tar -czf "$BACKUP_DIR/memory.tar.gz" -C ~/.openclaw memory_v2

# Backup service file (if applicable)
sudo cp /etc/systemd/system/openclaw-gateway.service "$BACKUP_DIR/" 2>/dev/null

echo "Backup completed: $BACKUP_DIR"
💡 Pro Tip: Set up an automated daily backup cron job to run at midnight, retaining the last 7 days of backups.

🚀 Step 2: Standard Upgrade Process

Follow these steps to upgrade to OpenClaw 2026.3.13:

  1. 1 Upgrade Node.js
    Version 3.x requires Node.js ≥ 22.12. If you use nvm:

    nvm install 22 && nvm alias default 22

  2. 2 Upgrade OpenClaw

    pnpm update -g openclaw

  3. 3 Configure gateway.mode
    Version 3.x mandates this configuration; there is no default value:

    openclaw config set gateway.mode local

  4. 4 Start the Gateway

    openclaw gateway start

⚠️ Three Critical Changes Before Upgrading

Change 1: Node.js Version Requirement

Version 3.x strictly requires Node.js ≥ 22.12.
Note: If you manage services via systemd, you must explicitly configure the Node path in the service file. Otherwise, the service will launch using the system default version (likely v18), causing failures.

Change 2: Auto-Generated Tokens (Crucial!)

This is the biggest shift. Version 3.13 deprecates manual token configuration in favour of high-strength tokens generated automatically at startup.

The Catch: There are now two config files:

Tokens are stored in the runtime cache. Changes to the main config require a Gateway restart to sync.

Change 3: Binding Mode Syntax

Direct configuration of 0.0.0.0 or localhost is deprecated. Use bindMode instead:

openclaw config set gateway.bindMode loopback

🕳️ Pitfall Log & Solutions

Pitfall 1: Node.js Version Incompatibility

Error: Node.js v22.12+ is required (current: v18.19.1)
Symptom: Systemd service enters a restart loop.
Cause: Systemd environments are isolated; the Node version switched in your terminal does not propagate to the service.
Fix: Add an environment variable to your systemd service file to explicitly specify the Node path.

Pitfall 2: Incorrect Systemd Startup Method

Error: SyntaxError: missing ) after argument list
Cause: Mistakenly treating the openclaw script as a Node script by adding a node prefix in ExecStart.
Fix: Remove the node prefix; execute the openclaw command directly.

Pitfall 3: Missing Configuration

Error: Missing config. Run openclaw setup or set gateway.mode=local
Cause: Version 3.13 enforces gateway.mode configuration; it has no default.
Fix: Run openclaw config set gateway.mode local.

Pitfall 4: Port Occupation

Error: Port 18789 is already in use
Cause: Lingering processes from repeated restarts.
Fix: Kill the process occupying the port:
sudo kill -9 $(lsof -t -i:18789)

Pitfall 5: Token Authentication Mismatch (The Trickiest!)

Error: token_mismatch
Symptom: Feishu cannot connect; authentication fails.
Cause: Manually configured tokens do not match the newly auto-generated tokens.
Fix:

  1. Extract the auto-generated token: grep token ~/.openclaw/.openclaw/openclaw.json
  2. Sync it to the main config: openclaw config set gateway.auth.token "EXTRACTED_TOKEN"
  3. Update the token in the Feishu plugin.

Pitfall 6: Binding Mode Syntax Change

Error: gateway.bind host aliases are legacy
Cause: Version 3.13 deprecated direct 0.0.0.0/localhost configuration.
Fix: Use the new command: openclaw config set gateway.bindMode loopback.

✅ Verifying a Successful Upgrade

Run the following command to check the status:

openclaw status
Expected Output:
  • Gateway service: running (active)
  • Channel: Feishu — ON · OK
  • Bind mode: loopback
  • Node Version: 22.x.x

💡 Key Takeaways