OpenClaw Install & First-Run Errors: Complete Troubleshooting Guide (2026)

February 17, 2026

You followed the install guide, ran the commands, and… something broke. This guide covers every common error from npm install through your first successful gateway start — with exact commands to diagnose and fix each one.

Already running but gateway won’t start? See Gateway & Browser Relay Troubleshooting instead. This guide focuses on getting from zero to a working install.

Step 0: The diagnostic ladder

Before diving into specific errors, run these commands in order. They’ll tell you exactly where things stand:

node -v                          # Need v22+
npm -v                           # Should work if Node is installed
which openclaw                   # Is it installed?
openclaw --version               # What version?
openclaw doctor                  # Auto-diagnose common issues
openclaw status                  # Full system status

If openclaw doctor finds and fixes your issue — great, you’re done. If not, find your error below.

1. Node.js version errors

Symptom: `engine` compatibility error or syntax errors on startup

npm warn EBADENGINE Unsupported engine {
  required: { node: '>=22' },
  current:  { node: 'v18.19.0' }
}

Or you see unexpected token errors like:

SyntaxError: Unexpected token '??='

Fix: upgrade Node.js to v22+

OpenClaw requires Node.js 22 or newer. Check your version:

node -v

If it’s below v22, install the latest LTS:

# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
nvm alias default 22

# Or using NodeSource (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Verify after install:

node -v   # Should show v22.x.x or higher

Gotcha: multiple Node versions

If node -v shows the right version but OpenClaw still fails, you may have multiple Node installs. Check:

which node
which -a node

If there’s a system Node at /usr/bin/node conflicting with nvm’s version, make sure your shell profile loads nvm correctly and that systemd services use the right path (see Section 5).

2. npm install failures

Symptom: permission denied (EACCES)

npm ERR! Error: EACCES: permission denied, mkdir '/usr/lib/node_modules/openclaw'

Fix: resolve global npm permission errors

Never use sudo npm install -g. Instead, fix npm’s global directory:

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

Then reinstall:

npm install -g openclaw

Symptom: network timeout or registry errors

npm ERR! code ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/openclaw failed

Fix: resolve npm network/registry timeouts

Check your network, then try switching registries:

# Test connectivity
curl -I https://registry.npmjs.org/

# If behind a corporate proxy
npm config set proxy http://your-proxy:port
npm config set https-proxy http://your-proxy:port

# For users in mainland China, use a mirror
npm config set registry https://registry.npmmirror.com

Symptom: native module build failures

gyp ERR! build error
npm ERR! code 1

Install build essentials:

# Ubuntu/Debian
sudo apt-get install -y build-essential python3

# CentOS/RHEL
sudo yum groupinstall 'Development Tools'
sudo yum install python3

3. Config file errors

Symptom: JSON parse error on startup

SyntaxError: Unexpected token } in JSON at position 423

Your openclaw.json has a syntax error — usually a trailing comma or missing quote.

Fix: repair JSON syntax and schema issues

Validate your config:

# Check JSON syntax
python3 -m json.tool ~/.openclaw/openclaw.json

# Or use jq
jq . ~/.openclaw/openclaw.json

The error output will point to the exact line. Common mistakes:

{
  "gateway": {
    "mode": "local",
    "port": 18789,     // ← trailing comma on last property
  }
}

JSON doesn’t allow trailing commas or comments. Remove them.

Symptom: config validation error

Config validation failed: "gateway.mode" must be one of [local, remote]

Fix: set `gateway.mode` explicitly

Run the configuration wizard:

openclaw configure

Or check the valid options:

openclaw config get gateway

Then edit manually:

nano ~/.openclaw/openclaw.json

Symptom: “set gateway.mode=local”

Gateway start blocked: set gateway.mode=local

OpenClaw requires you to explicitly declare the gateway mode. Fix:

openclaw configure
# Or manually add to openclaw.json:
# "gateway": { "mode": "local" }

4. API key and provider errors

Symptom: 401 Unauthorized from AI provider

Error: 401 Unauthorized — invalid x-api-key

Fix: reconfigure provider API keys

Check your API key is set and valid:

# View current config (keys are masked)
openclaw config get providers

# Re-enter your key
openclaw configure

Make sure the key is in the right config field. For Anthropic:

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-api03-..."
    }
  }
}

Symptom: 429 Too Many Requests / rate limiting

Error: 429 — rate limit exceeded

This means you’re hitting the provider’s rate limit. Solutions:

Configure fallback models so OpenClaw auto-switches when one provider throttles:

{
  "models": {
    "default": "anthropic/claude-sonnet-4-5",
    "fallbacks": ["openai/gpt-4.1", "google/gemini-3-pro"]
  }
}

Upgrade your API tier with the provider (Anthropic tier upgrades reduce rate limits significantly).

See our Model Fallback Strategy Guide for details.

Symptom: connection timeout to provider API

Error: ETIMEDOUT connecting to api.anthropic.com

If you’re in a region where direct API access is restricted:

# Test connectivity
curl -I https://api.anthropic.com/v1/messages

# If blocked, set up a proxy
# See our proxy guide: /blog/openclaw-proxy-config-troubleshooting

For users in mainland China, you’ll likely need a proxy for Anthropic and OpenAI APIs. Check our Proxy Configuration Guide and Claude API Access Strategy.

5. Systemd service issues

Symptom: service fails to start

sudo systemctl status openclaw-gateway
# Shows: Active: failed (Result: exit-code)

Fix: inspect service logs first

journalctl -u openclaw-gateway -n 50 --no-pager

Common cause: wrong ExecStart path

The service file must point to the correct openclaw binary:

# Find the actual path
which openclaw

# Check what the service uses
cat /etc/systemd/system/openclaw-gateway.service | grep ExecStart

If they don’t match (common with nvm installs), update the service:

sudo nano /etc/systemd/system/openclaw-gateway.service

Set the correct path:

[Service]
ExecStart=/home/youruser/.nvm/versions/node/v22.22.0/bin/openclaw gateway start --foreground

Then reload:

sudo systemctl daemon-reload
sudo systemctl restart openclaw-gateway

Common cause: environment not loaded

Systemd services don’t load your shell profile, so nvm, PATH, and environment variables may be missing.

Fix by adding environment to the service file:

[Service]
Environment=PATH=/home/youruser/.nvm/versions/node/v22.22.0/bin:/usr/local/bin:/usr/bin:/bin
Environment=HOME=/home/youruser
Environment=NODE_ENV=production

Common cause: wrong user

If you run OpenClaw as a dedicated user (e.g., openclaw), make sure the service runs as that user:

[Service]
User=openclaw
Group=openclaw
WorkingDirectory=/home/openclaw

And the config is in the right place:

# Config should be at:
ls -la ~openclaw/.openclaw/openclaw.json

Reinstall the service cleanly

If all else fails, let OpenClaw set up the service itself:

openclaw gateway install
sudo systemctl daemon-reload
sudo systemctl enable openclaw-gateway
sudo systemctl start openclaw-gateway

6. Port conflicts (EADDRINUSE)

Symptom

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

Fix: clear port conflicts

Find what’s using the port:

sudo lsof -i :18789
# or
sudo ss -tlnp | grep 18789

Options:

Kill the conflicting process:

# If it's an old OpenClaw instance
openclaw gateway stop
# Or force kill
sudo kill $(sudo lsof -t -i :18789)

Change OpenClaw’s port:

{
  "gateway": {
    "port": 18790
  }
}

If it’s a stale lock file:

openclaw doctor --fix

7. First channel connection failures

Telegram bot won’t connect

Symptom: Bot is created but OpenClaw doesn’t receive messages.

Checklist:

# 1. Verify token is set
openclaw config get channels.telegram

# 2. Check channel status
openclaw channels list

# 3. Watch logs for errors
openclaw logs --follow

Common fixes:

Invalid token: Re-create the bot via @BotFather and update the token in config.
Privacy mode: Disable privacy mode in BotFather (/setprivacy → Disable) if the bot needs to see group messages.
Webhook conflict: If you previously set a webhook, clear it:

curl "https://api.telegram.org/bot<YOUR_TOKEN>/deleteWebhook"

Network issues: If your server can’t reach api.telegram.org, configure a proxy or check your firewall.

For in-depth Telegram troubleshooting, see our Telegram Troubleshooting Guide.

8. The nuclear option: clean reinstall

If nothing works and you want a fresh start:

# 1. Stop everything
openclaw gateway stop

# 2. Back up your config
cp ~/.openclaw/openclaw.json ~/openclaw-config-backup.json

# 3. Uninstall
npm uninstall -g openclaw

# 4. Clean install
npm install -g openclaw

# 5. Run doctor
openclaw doctor

# 6. Restore config
cp ~/openclaw-config-backup.json ~/.openclaw/openclaw.json

# 7. Start
openclaw gateway start

Quick reference: error → fix table

Error	Section	Quick fix
`EBADENGINE` / syntax error	Node.js	Install Node 22+
`EACCES` on npm install	npm	Fix npm global dir
`ETIMEDOUT` npm	npm	Check network/proxy
JSON parse error	Config	Fix JSON syntax
`set gateway.mode=local`	Config	Run `openclaw configure`
401 Unauthorized	API keys	Check/re-enter API key
429 rate limit	API keys	Add fallback models
systemd service failed	Systemd	Check ExecStart path + env
EADDRINUSE	Port conflicts	Kill process or change port
Telegram no messages	Channels	Check token + privacy mode

Where to deploy

Need a server to run OpenClaw 24/7? These providers work well for self-hosted AI agents:

Vultr — Starts at $6/mo, global locations, fast SSD. Great for getting started quickly.
DigitalOcean — $6/mo droplets with excellent documentation. One-click Node.js setup available.
Tencent Cloud — Best latency for mainland China users. Lightweight instances from ¥38/mo.

A 2 vCPU / 2GB RAM instance is plenty for OpenClaw. See our VPS Deployment Guide for the full setup walkthrough, or Deployment Pricing Comparison to find the best value.