Reinstall OpenClaw Skill

This skill provides complete procedures to safely uninstall and reinstall OpenClaw while preserving all user configurations, credentials, memory files, skills, and custom settings.

Use Cases

• Clean reinstall of OpenClaw to fix corrupted installations
• Remove third-party modifications and restore to official version
• Upgrade to latest version with fresh installation
• Migrate OpenClaw to a new environment with existing configurations

Prerequisites

• WSL (Ubuntu 20.04 or later) or Linux/macOS with Node.js
• Node.js 18+ and npm/pnpm
• Access to WSL terminal (for Windows users)

Complete Procedure

Step 1: Check Current Installation

First, identify the OpenClaw installation location and version:

# Check OpenClaw version
npx openclaw --version

# Find OpenClaw npm package location
npm root -g

# List global npm packages
npm list -g --depth=0

Step 2: Backup All User Data

Create a complete backup of all user configurations:

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

# Backup entire .openclaw directory
cp -r ~/.openclaw $BACKUP_DIR/

# Verify backup
ls -la $BACKUP_DIR/

What to Backup (Already included in ~/.openclaw)

Step 3: Stop OpenClaw Services

Stop all running OpenClaw processes:

# Stop gateway if running
npx openclaw gateway stop

# Kill any remaining processes
pkill -f openclaw
pkill -f "node.*openclaw"

# Verify no processes running
ps aux | grep openclaw

Step 4: Uninstall OpenClaw

Use the official uninstall command:

# Full uninstall (removes everything including CLI - optional)
npx openclaw uninstall --all --yes

# OR uninstall but keep CLI (recommended)
npx openclaw uninstall --state --workspace --yes

Note: The --all flag removes the CLI as well. If you want to keep the CLI for reinstallation, omit this flag.

Step 5: Clean Up Remaining Files

Remove any remaining files that might interfere:

# Remove npm cache (optional but recommended)
npm cache clean --force

# Remove old OpenClaw npm package if still exists
sudo npm uninstall -g openclaw

# Remove any remaining .openclaw directories
rm -rf ~/.openclaw
rm -rf ~/.openclaw-dev

Step 6: Install Latest OpenClaw

Install the latest official version:

# Install globally
sudo npm install -g openclaw@latest

# Verify installation
npx openclaw --version

Step 7: Restore User Configuration

Restore your backed-up configurations:

# Restore .openclaw directory
cp -r ~/openclaw-backup-YYYYMMDD/* ~/.openclaw/

# Set correct permissions
chmod 700 ~/.openclaw

Step 8: Run Health Check and Fix

# Run doctor to check for issues
npx openclaw doctor --fix

Step 9: Start OpenClaw Gateway

# Start the gateway
npx openclaw gateway

# Check health
npx openclaw health

# Check status
npx openclaw status

Complete One-Liner Backup Script

Run this before uninstalling to create a timestamped backup:

# Create automatic backup
BACKUP_DIR=~/openclaw-backup-$(date +%Y%m%d-%H%M%S) && mkdir -p $BACKUP_DIR && cp -r ~/.openclaw/* $BACKUP_DIR/ && echo "Backup created: $BACKUP_DIR"

Complete One-Liner Restore Script

Run this after reinstallation to restore configurations:

# Restore from latest backup
LATEST_BACKUP=$(ls -td ~/openclaw-backup-* | head -1) && cp -r $LATEST_BACKUP/* ~/.openclaw/ && chmod 700 ~/.openclaw && echo "Restored from: $LATEST_BACKUP"

Troubleshooting

Gateway won't start after restore

# Stop any stale processes
npx openclaw gateway stop

# Force start
npx openclaw gateway --force

Port already in use

# Find process using the port
lsof -i :18788

# Kill it
kill <PID>

Configuration errors after restore

# Run doctor to fix
npx openclaw doctor --fix

Permission issues

# Fix .openclaw permissions
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json
chmod 700 ~/.openclaw/credentials

Files Reference

Configuration File (~/.openclaw/openclaw.json)

Key settings to preserve:

• gateway.port - Gateway port (default: 18788)
• gateway.auth.token - Gateway authentication token
• channels.feishu - Feishu app credentials
• models.providers - API keys for AI models

Backup Contents

~/.openclaw/
├── openclaw.json          # Main config
├── credentials/           # API secrets
├── memory/main.sqlite     # Memory database
├── agents/main/           # Agent configs
├── skills/                # Installed skills
├── workspace/             # User workspace
│   ├── SOUL.md
│   ├── IDENTITY.md
│   ├── AGENTS.md
│   └── USER.md
├── feishu/                # Feishu config
├── identity/              # Device identity
├── devices/               # Paired devices
└── cron/                  # Scheduled jobs

Important Notes

1. Always backup before uninstalling - Never skip the backup step
2. Keep backup in a safe place - Copy to external storage or cloud
3. Test after restore - Verify all configurations work correctly
4. Third-party modifications - This procedure removes all third-party patches and returns to official version
5. Memory files are preserved - The SQLite memory database is included in the backup