OpenClaw Troubleshooting Guide: 15+ Common Errors and Fixes

Stuck on an installation step? Don’t worry — most errors fall into a handful of familiar patterns and can be resolved in a few minutes. This guide covers all the most common errors when installing and using OpenClaw, organized into 5 groups. Each error includes: symptoms, cause, and specific fix.

Haven’t installed yet? Follow the How to Install OpenClaw: Complete A-Z Guide first to make sure you’re going in the right order.

Your #1 debugging tool — openclaw doctor: Before reading through individual errors below, try running:

openclaw doctor

This automatically checks: config file, file permissions, daemon/service status, port conflicts, OAuth tokens, model auth, and more. If it finds a problem, it suggests a fix. Add --repair to auto-fix common issues:

openclaw doctor --repair

---

Group 1: Installation errors

Error 1: “node: command not found” or Node.js version too old

Symptoms: OpenClaw install command fails, or node -v shows a version below 22.

Cause: Node.js not installed, or the system default version is too old (Ubuntu often ships with Node v12–v18).

Fix: Use nvm to install the correct version:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 24
nvm use 24
node -v   # Should show v24.x.x

On macOS, alternative via Homebrew:

brew install node@24
brew link --overwrite node@24

On Windows: Download the LTS installer from nodejs.org/en/download. If using WSL2, use the nvm method above inside your WSL terminal.

---

Error 2: “openclaw: command not found” after install

Symptoms: openclaw --version returns command not found even though the install appeared to succeed.

Cause: The directory where npm installs global packages isn’t in your PATH. A new shell session is needed to pick up the updated PATH.

Fix:

source ~/.bashrc   # Linux
source ~/.zshrc    # macOS

Or close the terminal completely and reopen. If still not working, check where npm installs global bins:

npm config get prefix

The path shown + /bin should be in your PATH. Add it to ~/.bashrc or ~/.zshrc if it’s missing.

---

Error 3: “npm ERR! node-gyp rebuild failed”

Symptoms: Installation fails with a long error involving node-gyp, native modules, or sharp.

Cause: Missing build tools (compilers) needed to build native Node.js modules.

Fix:

Ubuntu/Debian:

sudo apt install -y build-essential python3

macOS:

xcode-select --install

Fedora:

sudo dnf install -y gcc gcc-c++ make python3

After installing build tools, re-run the OpenClaw install script.

---

Error 4: “EACCES: permission denied” when installing npm global package

Symptoms: Error about permissions when running npm install -g openclaw.

Cause: npm is trying to write to a system directory that requires root access.

Fix: Change npm’s global prefix to a user-owned directory (never use sudo npm install):

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Then re-run the install. On macOS, using nvm instead of system Node avoids this issue entirely.

---

Error 5: “pnpm install” timeout or failure (Windows native)

Symptoms: Building from source on Windows — pnpm install hangs or fails with network errors.

Cause: Windows Defender or antivirus scanning each file write during install, causing timeouts. Corporate firewall blocking npm registry.

Fix:

• Temporarily disable Windows Defender real-time protection during install
• Check if your network blocks registry.npmjs.org — try from a different network
• Consider switching to WSL2 where this is rarely an issue (see Windows installation guide)

---

Group 2: Configuration errors

Error 6: “Invalid API key” or “Authentication failed” (401/403)

Symptoms: OpenClaw installs correctly but fails when you try to use it. Error mentions 401, 403, “authentication failed”, or “invalid API key”.

Cause (in order of likelihood):

1. API key copied with extra whitespace at the start or end
2. API key was rotated or deleted on the provider’s dashboard
3. Account has no credits remaining
4. Wrong key pasted (e.g., using an OpenAI key in the Claude field)

Fix:

1. Go to your provider’s dashboard, copy the key again, paste it without leading/trailing spaces
2. Check your account balance / credit status
3. Verify you’re using the right key type for the selected model
4. Re-run openclaw configure to re-enter the key

---

Error 7: Config file bad format — daemon won’t start

Symptoms: openclaw doctor reports a config error. Daemon fails to start with no clear error message.

Cause: Manual editing of ~/.openclaw/openclaw.json introduced invalid JSON (missing comma, unclosed bracket, etc.).

Fix: Validate the JSON:

cat ~/.openclaw/openclaw.json | python3 -m json.tool

If it reports a syntax error, fix it. For a fresh start, you can reset to defaults:

openclaw configure --reset

---

Error 8: “Cannot connect to LLM provider” — timeout or connection refused

Symptoms: OpenClaw starts but every request times out. No response from the AI model.

Cause:

• No internet connection
• Corporate firewall blocking API endpoints (api.anthropic.com, api.openai.com, etc.)
• Provider service outage

Fix:

# Test connectivity to Claude's API
curl -I https://api.anthropic.com

# Test OpenAI
curl -I https://api.openai.com

If the curl commands time out or return errors, the issue is network-level. Check your internet connection, VPN settings, or corporate proxy configuration.

---

Group 3: Gateway and daemon errors

Error 9: “EADDRINUSE” — Port 18789 already in use

Symptoms: Gateway fails to start. Error mentions port 18789 or EADDRINUSE.

Cause: Another process is already using port 18789 (could be a previous OpenClaw instance that didn’t shut down cleanly).

Fix: Find and stop what’s using the port:

# Linux / macOS
lsof -ti:18789 | xargs kill -9

# Windows (PowerShell)
netstat -ano | findstr :18789
# Note the PID, then:
taskkill /PID <pid> /F

Then restart the Gateway:

systemctl --user restart openclaw-gateway   # Linux
launchctl stop io.openclaw.gateway          # macOS

---

Error 10: “refusing to bind gateway without auth”

Symptoms: Gateway refuses to start. Error explicitly mentions “auth” or “authentication required”.

Cause: The Gateway detected that no authentication is configured — it won’t start without auth to prevent unauthorized access.

Fix: Run the Onboard Wizard to configure authentication:

openclaw onboard

Or manually add a user to the auth config in ~/.openclaw/openclaw.json under the auth section. See the API Key Configuration Guide for the full config structure.

---

Error 11: systemd service won’t start (Linux)

Symptoms: systemctl --user status openclaw-gateway shows failed or inactive.

Fix: Check the exact error:

journalctl --user -u openclaw-gateway --no-pager -n 30

Common causes and fixes:

• Wrong Node.js in PATH: systemd uses a different PATH than your shell. Fix: add the full path to node in the service file’s Environment=PATH=...
• Missing config file: run openclaw onboard first to generate the config
• Port conflict: see Error 9 above

---

Error 12: LaunchAgent not running (macOS)

Symptoms: OpenClaw daemon doesn’t start on login. Menu bar app shows “stopped”.

Fix: Reload the LaunchAgent:

launchctl unload ~/Library/LaunchAgents/io.openclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/io.openclaw.gateway.plist

Check logs:

log show --predicate 'subsystem == "io.openclaw.gateway"' --last 5m

If the plist file is missing, re-run:

openclaw onboard --install-daemon

---

Group 4: Channel and messaging errors

Error 13: Bot not responding to messages

Symptoms: You send a message to the Telegram/Discord/Slack bot but get no reply.

Cause (check in order):

1. Gateway isn’t running — check openclaw doctor
2. Channel token is invalid or expired
3. Your user hasn’t been added to the allowlist

Fix:

openclaw doctor

If Gateway shows “stopped”, restart it:

systemctl --user start openclaw-gateway   # Linux

To add yourself to the allowlist:

openclaw pairing approve <channel> <pairing-code>

(The pairing code is sent to you when you first message the bot)

---

Error 14: “mention required” in Discord/Telegram group

Symptoms: The bot only responds when you @mention it, not to every message.

Cause: OpenClaw is configured to only respond when directly mentioned in group contexts — this is intentional behavior to avoid responding to every message in busy groups.

Fix: Either @mention the bot in your message, or change the group response mode in config:

openclaw configure --channel discord --group-mode all

(Use all instead of mention for the group mode)

---

Error 15: WhatsApp pairing/login error

Symptoms: WhatsApp connection fails during setup or drops unexpectedly.

Cause: WhatsApp uses QR code session authentication that expires. Multiple device conflicts can also cause drops.

Fix: Re-initiate the pairing:

openclaw channel restart whatsapp

A new QR code appears — scan it from WhatsApp on your phone (Settings → Linked Devices → Link a Device). Make sure no other OpenClaw instance is trying to use the same WhatsApp account.

---

Group 5: Runtime and performance errors

Error 16: OpenClaw crash — “JavaScript heap out of memory”

Symptoms: Gateway crashes with out-of-memory error, especially on low-RAM VPS (1 GB).

Fix:

Add swap space:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Increase the Node.js heap limit:

openclaw configure --max-old-space-size 512

---

Error 17: “Rate limit exceeded” (429)

Symptoms: OpenClaw returns rate limit errors, especially during heavy usage.

Cause: You’ve exceeded the API provider’s rate limit for your tier.

Fix:

• Reduce concurrent requests in OpenClaw config
• Upgrade your API plan with the provider
• Switch to a model with higher rate limits (e.g., GPT-4o mini for frequent small tasks)
• Add delays between automated batch tasks

---

60-second debug checklist

If something isn’t working and you’re not sure where to start:

# 1. Check overall health
openclaw doctor

# 2. Check if Gateway is running
systemctl --user status openclaw-gateway    # Linux
launchctl list | grep openclaw              # macOS

# 3. View recent logs
journalctl --user -u openclaw-gateway -n 20 --no-pager   # Linux

# 4. Test API connectivity
openclaw test-connection

# 5. Restart everything
systemctl --user restart openclaw-gateway   # Linux

---

OS-specific errors

macOS: “Operation not permitted”

Caused by macOS System Integrity Protection (SIP) or TCC (Transparency, Consent, Control) blocking access. Grant Terminal full disk access in System Settings → Privacy & Security → Full Disk Access.

Windows: “execution of scripts is disabled” (PowerShell)

PowerShell is blocking script execution. Fix:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Windows: WSL2 can’t be installed — “Virtualization not enabled”

Virtualization is disabled in BIOS. Restart your PC, enter BIOS settings, and enable Intel VT-x or AMD-V (varies by motherboard manufacturer).

Linux: Config file permission warning

chmod 600 ~/.openclaw/openclaw.json

---

Update caused issues? Migration errors

After running openclaw update, old config files may be incompatible with the new version. Run:

openclaw doctor --repair

This automatically detects legacy config keys and migrates them. Common migrations: routing.allowFrom → channels.whatsapp.allowFrom, legacy voice config keys to the new provider format.

---

The simplest fix: no install = no errors

If you’ve spent hours debugging and still can’t get it running, TryOpenClaw.io is the cloud option with everything pre-configured:

• No Node.js, Git, or any dependencies to install
• No API key errors, port conflicts, or permission issues
• Dedicated cloud instance, auto-recovery when something goes wrong
• Starting from $4/month, full money-back guarantee

Learn more: Run OpenClaw on Cloud — No Installation Needed

---

Summary

Most OpenClaw errors fall into 5 groups: installation errors (Node.js, build tools, PATH), configuration errors (API key, config format), Gateway/daemon errors (port conflicts, service failures), channel errors (allowlist, pairing), and runtime errors (memory, rate limits). Always start with openclaw doctor --repair — it auto-fixes about 80% of problems.