Proven fixes: 7 OpenClaw install and gateway errors

TLDR

Your OpenClaw agent installation fails when npm cannot find git, Node version is too old, or ports are already in use. Gateway startup crashes come from config validation errors or permission issues.

Run openclaw doctor to diagnose most agent setup problems. This guide walks through fixing each error with actual commands.

Overview

When you install OpenClaw, the process should complete cleanly and your agent gateway should start immediately. But sometimes npm crashes with spawn errors, your agent gateway refuses to start, or post-upgrade configs break.

This happens because your agent requires specific dependencies like git and Node 22+. Your agent also needs clean port availability and valid JSON config.

This guide covers the seven most common installation errors your OpenClaw agent encounters. For each error, I explain why it happens and how to fix it with terminal commands you can copy-paste. By the end, your agent will be installed and running.

npm install failures: ENOENT spawn git

You run npm install -g openclaw and it crashes with:

Error: spawn git ENOENT

Why it happens

npm is trying to clone a git dependency but cannot find the git command. Your agent installation fails because git is not installed or not in your PATH.

How to fix it

Install git first.

On Ubuntu or Debian:

sudo apt update
sudo apt install git

On macOS:

brew install git

On Windows, download and install Git for Windows. Make sure you check "Add to PATH" during installation.

After installing git, try the npm install again:

npm install -g openclaw

Verify git is installed

Run:

git --version

If it shows a version number, git is installed correctly. If it says "command not found", restart your terminal or check your PATH.

npm permission errors: EACCES

You run npm install -g openclaw and get:

Error: EACCES: permission denied

Why it happens

Global npm packages install to a system directory that requires elevated permissions. This is common on Linux and macOS.

Fix without sudo

Do not use sudo npm install. It causes ownership issues later.

Instead, configure npm to use a directory you own:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

Add this to your shell profile (~/.bashrc, ~/.zshrc, or equivalent):

export PATH=~/.npm-global/bin:$PATH

Reload your shell:

source ~/.bashrc

Now install openclaw without sudo:

npm install -g openclaw

If you already used sudo

If you already ran sudo npm install and now have permission errors, you need to fix ownership.

Run these commands:

sudo chown -R $USER:$USER ~/.npm-global
sudo chown -R $USER:$USER /usr/local/lib/node_modules

Then reinstall openclaw:

npm uninstall -g openclaw
npm install -g openclaw

Node version too old (requires Node 22+)

You run openclaw and get:

Error: openClaw requires Node.js 22 or higher
Current version: v18.12.0

Why it happens

Your agent uses features only available in Node 22 and later. With older versions, your agent can crash or behave unpredictably.

How to fix it

Upgrade Node.js using nvm (recommended):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Reload your shell:

source ~/.bashrc

Install Node 22:

nvm install 22
nvm use 22
nvm alias default 22

Verify the version:

node --version

You should see v22.x.x or higher.

Now reinstall openclaw:

npm install -g openclaw

If you cannot use nvm

On some systems (VPS, Docker, corporate machines), nvm is blocked or breaks.

Install Node 22 from NodeSource:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Or download the binary from nodejs.org and install manually.

Gateway won't start: EADDRINUSE port conflict

You run openclaw gateway start and it crashes:

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

Why it happens

Another process is using port 18789 (the default OpenClaw gateway port). This has a few common causes.

Typically:

• The gateway is already running
• A previous gateway process crashed and did not clean up
• Another application is using that port

How to fix it

First, check if the gateway is already running:

openclaw gateway status

If it shows "running", stop it first:

openclaw gateway stop

Then start it again and your agent will come back online:

openclaw gateway start

If stop does not work

The process might be stuck.

Find it:

lsof -i :18789

You see output like:

COMMAND   PID   USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
node    12345  user   20u  IPv6 123456      0t0  TCP *:18789 (LISTEN)

Kill the process:

kill 12345

If it does not die, force it:

kill -9 12345

Now start the gateway:

openclaw gateway start

Change the port

If another application needs port 18789, change OpenClaw's port in ~/.openclaw/config/config.json:

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

Restart the gateway after saving.

Gateway won't start: config validation errors

You run openclaw gateway start and get:

Error: invalid configuration
Config validation failed: ...

Why it happens

Your config file has invalid JSON, missing required fields, or incorrect data types.

How to fix it

Run the diagnostic command:

openclaw doctor

It shows exactly what is wrong with your config.

Common issues:

• Missing comma. JSON requires commas between array items and object properties.
• Trailing comma. JSON does not allow commas after the last item.
• Wrong quotes. Use double quotes " not single quotes '.
• Invalid token. Bot token is empty or malformed.

Fix the errors listed by openclaw doctor, then start the gateway again.

Reset config to Defaults

If your config is completely broken, back it up and regenerate:

cp ~/.openclaw/config/config.json ~/.openclaw/config/config.json.backup
openclaw init --force

This creates a fresh default config. You will need to re-add your bot tokens and settings.

openclaw doctor: diagnostic commands

The openclaw doctor command checks your installation and config.

Run it anytime you have problems:

openclaw doctor

It checks:

• Node.js version
• npm installation
• Config file validity
• Gateway status
• Plugin availability
• Permission issues

The output tells you exactly what to fix.

Example output

[OK] Node.js version: v22.1.0
[OK] OpenClaw installed globally
[OK] Config file exists
[ERROR] Config validation failed: missing required field "token" in telegram config
[OK] Gateway is running
[WARNING] Port 18789 is in use by another process

Fix the errors and re-run openclaw doctor to verify.

Check specific Components

You can check individual parts:

openclaw doctor --config
openclaw doctor --gateway
openclaw doctor --plugins

This is faster if you know where the problem is.

Post-upgrade breakage: config drift

You upgraded OpenClaw and now the gateway will not start or your agent will not respond.

Why it happens

New versions sometimes change config structure or add stricter validation. Old configs become incompatible.

How to fix it

Check the changelog for breaking changes:

openclaw changelog

Or read the GitHub releases page.

Common post-upgrade issues:

• Auth defaults changed. Older versions allowed bots to respond to anyone, new versions require allowFrom.
• Config structure changed. Settings moved to different sections.
• Deprecated fields removed. Old config options no longer work.

Run openclaw doctor to identify specific issues.

Migrate config

If the upgrade changed config structure, migrate manually:

1. Back up your current config:

cp ~/.openclaw/config/config.json ~/.openclaw/config/config.json.old

2. Generate a new default config:

openclaw init --force

3. Copy your bot tokens and settings from the old config to the new one.

4. Restart the gateway:

openclaw gateway restart

Downgrade if Needed

If the new version is broken and you cannot migrate, downgrade:

npm install -g openclaw@previous-version

Replace previous-version with the last working version number.

Windows-specific issues

OpenClaw works on Windows but has quirks.

PowerShell execution policy

PowerShell blocks scripts by default. When you run openclaw, you get:

cannot be loaded because running scripts is disabled

Fix it by allowing scripts:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Run this in PowerShell as Administrator, then try openclaw again.

Path not Updated

After installing openclaw globally, the command is not found.

Restart your terminal or add npm's global bin to your PATH manually.

Find the global bin path:

npm config get prefix

Add that path plus \bin to your Windows PATH environment variable.

Scheduled task Cleanup

If you used Task Scheduler to auto-start the gateway and now it crashes on boot, disable the task:

1. Open Task Scheduler
2. Find the OpenClaw task
3. Right-click and select "Disable" or "Delete"

Then fix the underlying issue (config, port conflict, etc.) before re-enabling the task.

Windows firewall blocking port

Windows Firewall might block the gateway port. Allow it:

1. Open Windows Defender Firewall
2. Click "Advanced settings"
3. Click "Inbound Rules" then "New Rule"
4. Select "Port", click Next
5. Enter 18789 (or your custom port)
6. Allow the connection, click Next
7. Apply to all profiles, finish

Restart the gateway after allowing the port.

FAQ

I reinstalled OpenClaw but the gateway still crashes. Why?

Reinstalling does not reset your config. The old broken config is still in ~/.openclaw/config/. Run openclaw doctor to diagnose config issues or reset the config with openclaw init --force.

Can i run multiple OpenClaw instances on the same machine?

Yes, but each needs a separate config directory and port. Use the OPENCLAW_CONFIG_DIR environment variable:

export OPENCLAW_CONFIG_DIR=~/.openclaw-bot2
openclaw init
openclaw gateway start

Change the port in the config to avoid conflicts.

The gateway starts but stops after a few seconds. How do I debug this?

Check the logs:

openclaw logs --follow

The last few lines before the crash show the error. Common causes are invalid bot tokens, network issues, or plugin crashes.

I am behind a corporate proxy and npm install fails. What do I do?

Configure npm to use your proxy:

npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

Replace the URL with your actual proxy address. Then retry npm install -g openclaw.

Can I install OpenClaw without npm?

No, npm is required. OpenClaw is distributed as an npm package. If you cannot use npm, you can clone the GitHub repo and build from source, but this is not recommended. Once installed properly, your agent can run reliably.

Conclusion

Most agent installation errors come from missing dependencies like git and Node 22, permission issues, or port conflicts. Run openclaw doctor to diagnose problems quickly. Check the config with openclaw doctor --config after upgrades. On Windows, allow script execution and firewall rules for your agent. For agent communication issues, see the Telegram troubleshooting guide.

For complete setup instructions, see the OpenClaw Telegram setup guide. The DigitalOcean VPS deployment guide covers remote deployment. The official OpenClaw docs have full installation reference and troubleshooting guides.