Home / Troubleshooting

OpenClaw Install Troubleshooting: Fix Common Errors

Comprehensive troubleshooting guide for OpenClaw installation issues. Find solutions to common errors including Node.js version problems, npm permissions, port conflicts, API connection issues, and platform-specific problems.

🔧 Troubleshooting 💡 Solutions Guide 📖 15 min read

! Common OpenClaw Install Errors

Most OpenClaw install problems fall into these categories. Find your error below for quick solutions.

⚠️

Node.js Version Too Old

Error: OpenClaw requires Node.js 22 or newer. You have v18.x.x

💡 Solution:

OpenClaw requires Node.js 22 or newer. Update your Node.js installation:

macOS (Homebrew):
bash 
brew install node@22
brew link --force --overwrite node@22
Linux (nvm):
bash 
nvm install 22
nvm use 22
nvm alias default 22
Windows:

Download Node.js 22+ installer from nodejs.org and run the setup wizard.

Verify installation:

bash 
node --version

Should output: v22.x.x or higher

🚫

npm Permission Denied

npm ERR! code EACCES npm ERR! syscall mkdir npm ERR! path /usr/local/lib/node_modules/openclaw npm ERR! errno -13 npm ERR! Error: EACCES: permission denied

💡 Solution:

This occurs when npm doesn't have permission to install global packages. Three solutions:

Option 1: Use sudo (Quick Fix - macOS/Linux):
bash 
sudo npm install -g openclaw@latest
Option 2: Fix npm Permissions (Recommended):
bash 
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw@latest
Option 3: Use nvm (Best Practice):

Install Node.js via nvm to avoid permission issues:

bash 
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
npm install -g openclaw@latest
Windows - Run as Administrator:

Right-click PowerShell and select "Run as Administrator", then install OpenClaw.

🔌

Port 18789 Already in Use

Error: listen EADDRINUSE: address already in use :::18789

💡 Solution:

Another process is using OpenClaw's default port (18789). Find and kill the process:

macOS/Linux:
bash 
# Find process using port 18789
lsof -ti:18789

# Kill the process
lsof -ti:18789 | xargs kill -9
Windows (PowerShell):
powershell 
# Find process ID
netstat -ano | findstr :18789

# Kill process (replace <PID> with actual PID)
taskkill /PID <PID> /F
Or Change Port:
bash 
openclaw config set port 8080
openclaw start
📦

Module Not Found / Cannot Find Module

Error: Cannot find module 'some-package' at Function.Module._resolveFilename

💡 Solution:

Corrupted installation or missing dependencies. Reinstall OpenClaw:

bash 
npm uninstall -g openclaw
npm cache clean --force
npm install -g openclaw@latest

This clears npm cache and reinstalls OpenClaw fresh.

🤖 OpenClaw AI Model Connection Errors

🔑

Invalid Claude API Key

Error: Invalid API key provided Status: 401 Unauthorized

💡 Solution:

  1. Verify your API key at console.anthropic.com
  2. Check if your API key is active and has credits
  3. Ensure you're using the correct key format (starts with sk-ant-)
  4. Reconfigure OpenClaw with the correct key:
bash 
openclaw config set apiKey YOUR_CLAUDE_API_KEY
openclaw restart
💳

Insufficient Credits / Rate Limit

Error: Insufficient credits Error: Rate limit exceeded

💡 Solution:

  • Insufficient credits: Add credits to your Anthropic or OpenAI account
  • Rate limit: Wait a few minutes before retrying, or upgrade your API tier
  • Alternative: Switch to local models via Ollama (free)
🌐

Ollama Connection Failed

Error: Could not connect to Ollama ECONNREFUSED 127.0.0.1:11434

💡 Solution:

Ollama service is not running. Start Ollama:

bash 
# Install Ollama if not installed
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama service
ollama serve

# In another terminal, launch OpenClaw
ollama launch openclaw

💻 Platform-Specific OpenClaw Install Issues

🍎

macOS Issues

Xcode Command Line Tools Required

Error: xcode-select: error: tool requires Xcode

Solution:

bash 
xcode-select --install

Apple Silicon (M1/M2/M3) Rosetta Issues

Solution: Install Rosetta 2 if needed:

bash 
softwareupdate --install-rosetta

Full guide: macOS Install Guide

🐧

Linux Issues

Build Tools Missing

Error: make: command not found

Solution: Install build essentials:

bash 
# Ubuntu/Debian
sudo apt-get install build-essential

# Fedora
sudo dnf groupinstall 'Development Tools'

# Arch
sudo pacman -S base-devel

Python Missing

Solution:

bash 
sudo apt-get install python3

Full guide: Linux Install Guide

🪟

Windows Issues

PowerShell Execution Policy

Error: cannot be loaded because running scripts is disabled

Solution:

powershell 
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Windows Build Tools Missing

Solution:

powershell 
npm install -g windows-build-tools

Full guide: Windows Install Guide

🔒 OpenClaw Security Vulnerability Fixes

Critical

CVE-2026-25253: Remote Code Execution Vulnerability

CVSS Score: 8.8 (High)
Affected Versions: All versions before 2026.1.29
Issue: Cross-site WebSocket hijacking allows one-click remote code execution

🚨 Immediate Action Required:

Update to version 2026.1.29 or newer immediately:

bash 
npm update -g openclaw@latest
openclaw --version

Verify you're on v2026.2.6 or newer (current latest: v2026.2.6, released Feb 7, 2026)

Warning

Malicious Skills on ClawHub

341 malicious skills identified on ClawHub repository. Some facilitate data exfiltration.

Protection Measures:

  • Update to v2026.2.6+: VirusTotal integration scans all skills
  • Review before installing: Check skill source code and author reputation
  • Use official skills: Prefer the 53 official bundled skills when possible
  • Check security score: VirusTotal Code Insight provides threat analysis

💬 OpenClaw Messaging Platform Integration Issues

Discord Bot Not Responding

Common causes:

  • Invalid bot token
  • Bot not invited to server with correct permissions
  • Message Content intent not enabled

Solution:

  1. Verify bot token in Discord Developer Portal
  2. Enable "Message Content Intent" in Bot settings
  3. Reinvite bot with proper permissions (Send Messages, Read Message History)
  4. Restart OpenClaw: openclaw restart

Telegram Bot Connection Failed

Solution:

  1. Verify bot token from @BotFather is correct
  2. Check if bot is not blocked
  3. Reconfigure: openclaw config set telegram.token YOUR_TOKEN
  4. Restart OpenClaw

WhatsApp QR Code Scan Issues

Solution:

  • Ensure QR code is displayed correctly in terminal
  • Use a phone with WhatsApp installed to scan
  • Make sure phone and computer are on same network
  • Restart the WhatsApp integration: openclaw platform restart whatsapp

💪 Getting Help with OpenClaw Install Issues

If you can't find a solution above, get help from the OpenClaw community and official support channels.

💬

OpenClaw Discord Community

Join the official Discord server for real-time help from community members and contributors.

  • Active community support
  • Quick responses to common issues
  • Share error logs and get feedback
  • 900+ contributors helping users
Join Discord →
🐛

GitHub Issues

Report bugs, request features, or search existing issues for solutions.

  • Official bug tracker
  • Search 180K+ GitHub stars community
  • Track known issues and fixes
  • Report security vulnerabilities
Browse Issues →
📖

Official Documentation

Comprehensive documentation covering installation, configuration, and troubleshooting.

  • Detailed guides and tutorials
  • API references
  • Best practices
  • Advanced configuration
Read Docs →
🌐

X/Twitter Community

Follow updates and connect with other OpenClaw users on X/Twitter.

  • Latest announcements
  • Community discussions
  • Tips and tricks
  • Peter Steinberger updates
Join Community →

📝 When Asking for Help

Include these details to get faster, more accurate help:

  • OpenClaw version: openclaw --version
  • Node.js version: node --version
  • Operating system and version
  • Complete error message
  • Steps you've already tried
  • Relevant logs from ~/.openclaw/logs/

→ Related OpenClaw Install Guides

📋

System Requirements

Check if your system meets OpenClaw install requirements before installing
⚡

Quick Start Guide

Install OpenClaw in 10 minutes with our streamlined guide
💡

Best Practices

Optimize your OpenClaw installation with security and performance tips
❓

FAQ

Common questions about OpenClaw install and configuration