Why does 'npm install openclaw' fail?

The most common cause is running Node.js below version 22. Check with node -v and upgrade if needed. Other causes include corrupted npm cache (fix with npm cache clean --force), network issues behind corporate proxies, and insufficient disk space. On macOS, missing Xcode CLI tools also cause native module compilation failures.

How do I fix 'brew: command not found' when installing OpenClaw?

This means Homebrew is not installed on your Mac. Install it with: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)". After installation, follow the terminal instructions to add brew to your PATH. On Apple Silicon Macs, Homebrew installs to /opt/homebrew, which may need to be added to your shell profile.

What does 'gateway not configured' mean in OpenClaw?

This error means OpenClaw cannot find valid gateway settings in your configuration file at ~/.openclaw/config. Run openclaw configure to launch the interactive setup wizard, which will guide you through setting the gateway host, port, and authentication token. If the file exists but is corrupted, delete it and run openclaw init to regenerate defaults.

How do I fix 'access not configured telegram' in OpenClaw?

This error means your Telegram bot token is missing, invalid, or expired. Go to @BotFather on Telegram, verify your bot exists, and copy the token. Then run openclaw pair telegram and paste the token when prompted. If the token was revoked, generate a new one via @BotFather's /revoke command and re-pair.

How do I completely uninstall OpenClaw?

To fully remove OpenClaw: 1) Stop the service: openclaw stop. 2) Remove the global package: npm uninstall -g openclaw. 3) Delete config and data: rm -rf ~/.openclaw. 4) If using Homebrew: brew uninstall openclaw. 5) If using Docker: docker compose down -v in the openclaw directory. 6) Remove the workspace: rm -rf ~/openclaw.

How do I reinstall OpenClaw without losing my configuration?

Back up your config first: cp -r ~/.openclaw ~/.openclaw-backup. Then uninstall (npm uninstall -g openclaw), reinstall (npm install -g openclaw@latest), and run openclaw init --keep-config to preserve your existing settings. Restore from backup if anything is lost: cp -r ~/.openclaw-backup/* ~/.openclaw/.

Why does OpenClaw say 'command not found' after installation?

Your shell cannot find the openclaw binary in its PATH. This usually happens when npm's global bin directory is not in your PATH. Run npm config get prefix to find the install location, then add its bin directory to your PATH. For nvm users, ensure the correct Node version is active. Restarting your terminal or running source ~/.bashrc (or ~/.zshrc) usually resolves this.

Can openclaw doctor fix my installation automatically?

openclaw doctor diagnoses most common issues automatically -- it checks Node.js version, system dependencies, config file validity, port availability, API key format, and messaging platform connectivity. It reports problems with suggested fixes. For most issues, it provides a one-line command to resolve the problem. Run it as your first troubleshooting step.

Can I install OpenClaw from GitHub instead of npm?

Yes. Clone the repository with git clone https://github.com/openclaw/openclaw.git, cd into the directory, run npm install to install dependencies, then npm run build. Link the CLI globally with npm link. This is useful for contributors, developers who want to inspect the source, or users behind firewalls that block the npm registry. For most users, npm install -g openclaw is simpler and receives automatic updates.

OpenClaw Troubleshooting: Fix Common Install & Setup Errors (2026)

Most OpenClaw installation errors are caused by outdated Node.js (need 22+), missing system dependencies, or incorrect configuration. Run openclaw doctor to diagnose issues automatically, or check the error-specific fixes below.

This guide covers every common OpenClaw error with step-by-step fixes, plus complete reinstall and uninstall instructions for all platforms.

Quick-Fix Table npm Install Failed Brew Not Installed Gateway Not Configured Telegram Access Reinstall Uninstall FAQ

Quick-Fix Reference Table

Find your error message below for the fastest one-line fix. Scroll down for detailed walkthroughs.

Error	Fix	Command
npm install failed	Check Node.js version (need 22+)	`node -v`
npm install failed macos	Install Xcode CLI tools	`xcode-select --install`
brew: command not found	Install Homebrew	`/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
gateway not configured	Run the configuration wizard	`openclaw configure`
access not configured telegram	Re-pair Telegram bot token	`openclaw pair telegram`
EACCES permission denied	Fix directory ownership	`sudo chown -R $(whoami) ~/.openclaw`
port 18789 already in use	Find and kill the blocking process	`sudo lsof -i :18789`
openclaw: command not found after install	Add npm global bin to PATH or restart terminal	`export PATH="$(npm config get prefix)/bin:$PATH"`

How to Fix 'npm install failed' in OpenClaw

Most npm install failures are caused by an outdated Node.js version (OpenClaw requires 22+), corrupted npm cache, or missing build tools. Run node -v first, then follow the steps below.

Check your Node.js version

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

Install or upgrade Node.js via nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

Clean the npm cache and retry

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

If compilation errors persist, install build tools

# macOS
xcode-select --install

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

How to Fix 'brew not installed' on macOS

The 'brew: command not found' error means Homebrew is not installed or not in your PATH. This is required for the brew install openclaw method. Install Homebrew first, then retry.

Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Add Homebrew to your PATH (Apple Silicon Macs)

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Verify Homebrew works, then install OpenClaw

brew --version
brew install openclaw/tap/openclaw
openclaw init

If brew update hangs, reset Homebrew

brew update-reset && brew update

How to Fix 'gateway not configured' Error

The gateway not configured error means OpenClaw's config file is missing, incomplete, or has invalid values. The config lives at ~/.openclaw/config. You can regenerate it with the setup wizard or manually edit the required fields.

Run the interactive configuration wizard

openclaw configure

Or manually check the config file

cat ~/.openclaw/config
# Verify these fields exist:
#   gateway.host = "127.0.0.1"
#   gateway.port = 18789
#   gateway.token = "your-token-here"

Reset to defaults if the file is corrupted

cp ~/.openclaw/config ~/.openclaw/config.bak
openclaw init --reset-config

Verify the gateway starts

openclaw gateway restart && openclaw status

How to Fix 'access not configured telegram'

This error means your Telegram bot token is missing or invalid. You need a valid bot token from @BotFather and must pair it with OpenClaw. Re-pairing usually resolves the issue in under 2 minutes.

Open Telegram and message @BotFather

# In Telegram:
# 1. Search for @BotFather
# 2. Send /mybots to see your existing bots
# 3. Select your bot and click 'API Token'
# 4. Copy the token (format: 123456789:ABCdefGHI...)

If you don't have a bot, create one

# In @BotFather:
# 1. Send /newbot
# 2. Choose a display name
# 3. Choose a username (must end in 'bot')
# 4. Copy the token provided

Pair the bot token with OpenClaw

openclaw pair telegram
# Paste your bot token when prompted

Verify the connection

openclaw status --channels
# Should show Telegram: connected

How to Fix Permission Errors on Mac/Linux

EACCES or permission denied errors happen when the ~/.openclaw directory is owned by root (usually from running with sudo). Fix ownership so your regular user account controls the files. Never run openclaw with sudo.

Fix ownership of the OpenClaw directory

sudo chown -R $(whoami) ~/.openclaw

Fix npm global permissions (if npm install fails)

mkdir -p ~/.npm-global
npm config set prefix "~/.npm-global"
export PATH="~/.npm-global/bin:$PATH"
# Add the export line to ~/.bashrc or ~/.zshrc

Verify correct permissions

ls -la ~/.openclaw
# Owner should be your username, not root

Set correct file permissions

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/config
# Config contains API keys -- keep it private

How to Reinstall OpenClaw

A clean reinstall fixes most persistent issues. Follow these steps to preserve your configuration while getting a fresh installation.

Back up your configuration

cp -r ~/.openclaw ~/.openclaw-backup

Stop the running service

openclaw stop

Remove the current installation

npm uninstall -g openclaw

Clean npm cache

npm cache clean --force

Install the latest version

npm install -g openclaw@latest

Restore config and reinitialize

openclaw init --keep-config
openclaw start && openclaw status

After Reinstalling

Run openclaw doctor to verify everything is working. If you backed up your config, your API keys, messaging integrations, and preferences should be preserved. Re-pair any messaging platforms that show as disconnected.

How to Uninstall OpenClaw

Complete removal instructions for every platform. This removes the binary, configuration, data, and workspace files.

Mac / Linux (npm)

openclaw stop
npm uninstall -g openclaw
rm -rf ~/.openclaw
rm -rf ~/openclaw

macOS (Homebrew)

openclaw stop
brew uninstall openclaw
rm -rf ~/.openclaw
rm -rf ~/openclaw

Windows WSL

openclaw stop
npm uninstall -g openclaw
rm -rf ~/.openclaw
rm -rf ~/openclaw

Docker

cd ~/openclaw
docker compose down -v
rm -rf ~/.openclaw
rm -rf ~/openclaw

Warning: This is irreversible

Removing ~/.openclaw deletes all API keys, bot tokens, conversation history, and skill configurations. Back up the directory first if you might want to reinstall later: cp -r ~/.openclaw ~/.openclaw-backup

Still Stuck?

If none of the fixes above solved your issue, these resources can help you get unstuck fast.

Workshop

Step-by-step setup guidance

Setup Call

1-on-1 troubleshooting help

Stop Wasting 40-60% of Your AI Budget

Download the free '6 Token Drains' guide — identify the hidden patterns burning through your tokens and get copy-paste fixes for each one.

Read the Free Guide

See what we've built for real businesses →

Tired of Debugging?

Our workshop walks you through a clean setup that just works — no errors, no guesswork.

Save 10+ hours/week Cut AI costs by 97% Deploy in under 20 min

Get the Automation Playbook (Free)

One deploy-ready automation every week. Same strategies our clients pay thousands for. 400+ business owners already inside.

Need it done for you?

Book a Free Strategy Call See what we've built for real businesses →