Fix 'npm install failed for openclaw@latest' and Other Install Errors

Q: 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.

Q: 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.

Key takeaways

Run openclaw doctor first. If that's clean, the install failure is usually missing git, Node below v22, or a permission error on the global npm directory. Gateway won't start when port 18789 is already in use or openclaw.json has invalid syntax. Each fix below has the exact command to run.

Feed this to your OpenClaw agent

Read https://www.stack-junkie.com/blog/fix-openclaw-installation-errors and follow the instructions to help me with: Fix 'npm install failed for openclaw@latest' and Other Install Errors. Summarize each step before running commands and confirm with me first.

Always review commands your agent suggests before approving them. Don't paste prompts from sources you don't trust.

Fixes when it breaks. Workflows when it doesn't.

OpenClaw guides, configs, and troubleshooting notes. Every two weeks.

Overview

OpenClaw (previously known as Clawdbot and Moltbot) installation should be straightforward: npm install -g openclaw, start the gateway, done. Instead you're looking at spawn errors, version conflicts, or a gateway that crashes on startup.

The usual suspects: missing dependencies (git, Node 22+), permission problems, port conflicts, or broken config JSON. Here's how to fix each one.

npm install failures: ENOENT spawn git

You run npm install -g openclaw and immediately hit:

text

Error: spawn git ENOENT

I see this on fresh Linux VPS installs all the time. npm needs git to pull down some dependencies, but git isn't installed by default on minimal server images. The fix:

Install git first.

On Ubuntu or Debian:

bash

sudo apt update
sudo apt install git

On macOS:

bash

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:

bash

npm install -g openclaw

Verify git is installed

Run:

bash

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 try to install and hit:

text

Error: EACCES: permission denied

This happens on Linux and macOS when npm tries to write to a system directory it doesn't own. The temptation is to slap sudo in front of the command. Don't. That causes worse problems later when npm can't write to folders you own.

Fix it properly:

Instead, configure npm to use a directory you own:

bash

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

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

bash

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

Reload your shell:

bash

source ~/.bashrc

Now install openclaw without sudo:

bash

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:

bash

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

Then reinstall openclaw:

bash

npm uninstall -g openclaw
npm install -g openclaw

Node version too old (requires Node 22+)

You run openclaw and get:

text

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). Check the nvm releases page for the current version and replace the version number in the command:

bash

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

Reload your shell:

bash

source ~/.bashrc

Install Node 22:

bash

nvm install 22
nvm use 22
nvm alias default 22

Verify the version:

bash

node --version

You should see v22.x.x or higher.

Now reinstall openclaw:

bash

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:

bash

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 get:

text

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

Port 18789 is taken. Either the gateway is already running (check with openclaw gateway status), a crashed process didn't clean up, or something else grabbed that port. I've had this happen after a server reboot when the gateway tried to auto-start twice.

Check if it's already running:

First, check if the gateway is already running:

bash

openclaw gateway status

If it shows "running", stop it first:

bash

openclaw gateway stop

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

bash

openclaw gateway start

If stop does not work

The process might be stuck.

Find it:

bash

lsof -i :18789

You see output like:

text

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

Kill the process:

bash

kill 12345

If it does not die, force it:

bash

kill -9 12345

Now start the gateway:

bash

openclaw gateway start

Change the port

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

json

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

Restart the gateway after saving.

Gateway won't start: config validation errors

You run openclaw gateway start and get:

text

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:

bash

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:

bash

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:

bash

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

text

[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:

bash

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:

bash

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:

Back up your current config:

bash

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

Generate a new default config:

bash

openclaw init --force

Copy your bot tokens and settings from the old config to the new one.
Restart the gateway:

bash

openclaw gateway restart

Downgrade if Needed

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

bash

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:

text

cannot be loaded because running scripts is disabled

Fix it by allowing scripts:

powershell

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:

bash

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:

Open Task Scheduler
Find the OpenClaw task
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:

Open Windows Defender Firewall
Click "Advanced settings"
Click "Inbound Rules" then "New Rule"
Select "Port", click Next
Enter 18789 (or your custom port)
Allow the connection, click Next
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:

bash

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:

bash

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:

bash

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.

Changelog

2026-02-15: Initial publication
2026-02-25: Added changelog, structural improvements

Key takeaways

Feed this to your OpenClaw agent

Read https://www.stack-junkie.com/blog/fix-openclaw-installation-errors and follow the instructions to help me with: Fix 'npm install failed for openclaw@latest' and Other Install Errors. Summarize each step before running commands and confirm with me first.

Always review commands your agent suggests before approving them. Don't paste prompts from sources you don't trust.

Fixes when it breaks. Workflows when it doesn't.

OpenClaw guides, configs, and troubleshooting notes. Every two weeks.

Overview

The usual suspects: missing dependencies (git, Node 22+), permission problems, port conflicts, or broken config JSON. Here's how to fix each one.

npm install failures: ENOENT spawn git

You run npm install -g openclaw and immediately hit:

text

Error: spawn git ENOENT

I see this on fresh Linux VPS installs all the time. npm needs git to pull down some dependencies, but git isn't installed by default on minimal server images. The fix:

Install git first.

On Ubuntu or Debian:

bash

sudo apt update
sudo apt install git

On macOS:

bash

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:

bash

npm install -g openclaw

Verify git is installed

Run:

bash

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 try to install and hit:

text

Error: EACCES: permission denied

Fix it properly:

Instead, configure npm to use a directory you own:

bash

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

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

bash

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

Reload your shell:

bash

source ~/.bashrc

Now install openclaw without sudo:

bash

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:

bash

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

Then reinstall openclaw:

bash

npm uninstall -g openclaw
npm install -g openclaw

Node version too old (requires Node 22+)

You run openclaw and get:

text

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). Check the nvm releases page for the current version and replace the version number in the command:

bash

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

Reload your shell:

bash

source ~/.bashrc

Install Node 22:

bash

nvm install 22
nvm use 22
nvm alias default 22

Verify the version:

bash

node --version

You should see v22.x.x or higher.

Now reinstall openclaw:

bash

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:

bash

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 get:

text

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

Check if it's already running:

First, check if the gateway is already running:

bash

openclaw gateway status

If it shows "running", stop it first:

bash

openclaw gateway stop

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

bash

openclaw gateway start

If stop does not work

The process might be stuck.

Find it:

bash

lsof -i :18789

You see output like:

text

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

Kill the process:

bash

kill 12345

If it does not die, force it:

bash

kill -9 12345

Now start the gateway:

bash

openclaw gateway start

Change the port

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

json

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

Restart the gateway after saving.

Gateway won't start: config validation errors

You run openclaw gateway start and get:

text

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:

bash

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:

bash

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:

bash

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

text

[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:

bash

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:

bash

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:

Back up your current config:

bash

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

Generate a new default config:

bash

openclaw init --force

Copy your bot tokens and settings from the old config to the new one.
Restart the gateway:

bash

openclaw gateway restart

Downgrade if Needed

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

bash

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:

text

cannot be loaded because running scripts is disabled

Fix it by allowing scripts:

powershell

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:

bash

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:

Open Task Scheduler
Find the OpenClaw task
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:

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

Restart the gateway after allowing the port.

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:

bash

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:

bash

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.

2026-02-15: Initial publication
2026-02-25: Added changelog, structural improvements

More Troubleshooting guides

Related Articles

OpenClaw Logs Command: Monitor Your Agent in Real Time

How to Run Multiple OpenClaw Agents on a Single Server

Fix OpenClaw Telegram Connection Errors: ETIMEOUT and ECONNREFUSED

More Troubleshooting guides

Related Articles

OpenClaw Logs Command: Monitor Your Agent in Real Time

How to Run Multiple OpenClaw Agents on a Single Server

Fix OpenClaw Telegram Connection Errors: ETIMEOUT and ECONNREFUSED