Fix OpenClaw CLI Errors: PATH, npm, and Windows

"openclaw: command not found" or "not recognized"

This is the most common error after installing OpenClaw CLI. Your shell can't find the binary because the npm global bin directory isn't in your PATH. First, find where npm puts global packages:

# Find your npm global prefix (works on all npm versions)
npm config get prefix
# Example output: /usr/local or /home/you/.npm-global
# The binaries live in the "bin" subdirectory of this path

Now add that directory's bin folder to your PATH. The fix depends on your shell.

Bash (Linux, older macOS)

# Add to ~/.bashrc (or ~/.bash_profile on macOS)
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify
openclaw --version

Zsh (macOS default)

# Add to ~/.zshrc
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify
openclaw --version

PowerShell (Windows)

# Find the npm global directory
npm config get prefix
# Example output: C:\Users\you\AppData\Roaming\npm

# Add to your PATH permanently
$npmPrefix = npm config get prefix
[Environment]::SetEnvironmentVariable("Path", "$npmPrefix;$env:Path", "User")

# Restart PowerShell, then verify
openclaw --version

If you still get the error after updating PATH, close and reopen your terminal. Environment variable changes don't apply to existing sessions.

npm EACCES permission denied

Running npm install -g openclaw fails with EACCES: permission denied when npm tries to write to a system-owned directory like /usr/local/lib. Don't use sudo -- that creates files owned by root and causes more problems later.

macOS / Linux fix

# Create a user-owned directory for global packages
mkdir -p ~/.npm-global

# Tell npm to use it
npm config set prefix ~/.npm-global

# Add to your PATH
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
# Or for zsh:
# echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc

source ~/.bashrc

# Now install without sudo
npm install -g openclaw

Windows fix

On Windows, EACCES usually means you need to run PowerShell as Administrator:

# Right-click PowerShell > "Run as Administrator"
npm install -g openclaw

# Verify the install
openclaw --version

According to the npm documentation on EACCES errors, changing the default directory is the recommended fix. Using sudo npm install is explicitly discouraged.

Node.js version too old

OpenClaw CLI requires Node.js 22.12.0 or later. If you see errors like SyntaxError: Unexpected token or ERR_MODULE_NOT_FOUND during install, your Node.js version is probably too old. Check it:

node --version
# If output is below v22.12.0, you need to upgrade

Upgrade with nvm (recommended)

# Install Node.js 22
nvm install 22
nvm use 22

# Verify
node --version
# v22.12.0 or later

# Reinstall OpenClaw with the new Node
npm install -g openclaw

Upgrade with Homebrew (macOS)

brew install node
node --version

Upgrade on Windows

Download the latest LTS installer from nodejs.org and run it. The installer updates your existing Node.js installation in place.

"openclaw plugins install" fails

Plugin installation can fail for several reasons. Start by checking what's already installed:

# List installed plugins
openclaw plugins list

# Try installing with verbose output
openclaw plugins install @nylas/openclaw-nylas-plugin --verbose

Common causes and fixes

• Network timeout -- corporate proxies or VPNs can block npm registry requests. Try npm config set registry https://registry.npmjs.org/ and retry.
• Package not found -- double-check the plugin name. Run openclaw plugins search nylas to find the exact package name.
• Version conflict -- the plugin may require a newer version of OpenClaw. Run npm update -g openclaw first, then retry the plugin install.
• Corrupted cache -- clear the npm cache with npm cache clean --force and retry.

# Full reset: clear cache, update OpenClaw, reinstall plugin
npm cache clean --force
npm update -g openclaw
openclaw plugins install @nylas/openclaw-nylas-plugin

OpenClaw config file location

OpenClaw stores its configuration in a JSON file. The location depends on your operating system:

To reset your config to defaults, delete the file and reinitialize:

# macOS / Linux
rm -rf ~/.openclaw/openclaw.json
openclaw init

# Windows (PowerShell)
Remove-Item "$env:USERPROFILE\.openclaw\openclaw.json" -Force
openclaw init

If you need to find the exact path on your system, run openclaw config path. This prints the full path regardless of OS.

Windows-specific issues

Execution policy blocks scripts

Windows may block OpenClaw's post-install scripts with UnauthorizedAccess. Fix it by setting the execution policy for your user:

# Allow locally-created scripts to run
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Reinstall
npm install -g openclaw

Symlink permissions

npm uses symlinks for global binaries. On Windows, creating symlinks requires either Administrator privileges or Developer Mode enabled:

# Option 1: Enable Developer Mode
# Settings > Update & Security > For developers > Developer Mode: On

# Option 2: Run PowerShell as Administrator
# Right-click PowerShell > "Run as Administrator"
npm install -g openclaw

Antivirus blocking npm global installs

Windows Defender and other antivirus software sometimes quarantine files in %AppData%\npm. If OpenClaw installs but the binary disappears, check your antivirus quarantine. Add %AppData%\npm to your antivirus exclusion list, then reinstall.

Frequently asked questions

Why does my terminal say "openclaw: command not found"?

Nine times out of ten, your npm global bin directory isn't in your PATH. The quickest check: run npm config get prefix, then look for openclaw inside that path's bin folder. If the file is there, your PATH is wrong. If it's not, the install failed silently — run npm install -g openclaw again. See the full fix above.

How do I fix npm EACCES permission denied?

Never use sudo — it creates root-owned files that break future installs. The one-liner fix: npm config set prefix ~/.npm-global && export PATH=~/.npm-global/bin:$PATH. On Windows, right-click PowerShell and choose "Run as Administrator" instead. See the detailed steps above.

What Node.js version does OpenClaw need?

Version 22.12.0 or later. Run node --version to check. If you're below that, upgrade with nvm (nvm install 22), Homebrew, or the nodejs.org installer.

Where is my OpenClaw config file?

On macOS and Linux: ~/.openclaw/openclaw.json. On Windows: %USERPROFILE%\.openclaw\openclaw.json. Run openclaw config path to print the exact location. Delete the file and run openclaw init to reset.

Next steps

• OpenClaw CLI setup guide -- install and configure OpenClaw from scratch
• Install the OpenClaw Nylas plugin -- connect OpenClaw to your Nylas account for email, calendar, and contacts
• Full command reference -- every flag and subcommand documented
• Send email from the terminal -- use the CLI to send, read, and manage email