Fix OpenClaw CLI Errors: PATH, npm, and Windows

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

The "command not found" error means your shell cannot locate the OpenClaw binary. This happens because npm installs global packages into a directory that is not included in your system's PATH variable by default. Around 90% of post-install failures on npm-based CLIs trace back to this single PATH misconfiguration, according to the npm troubleshooting docs.

To fix it, first identify where npm places global binaries on your machine. The npm config get prefix command prints the root directory, and the actual executables live in the bin subdirectory underneath it.

# 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

Once you know the prefix path, add its bin folder to your PATH. The exact file you edit depends on which shell your terminal uses.

Bash (Linux, older macOS)

Bash reads ~/.bashrc on Linux and ~/.bash_profile on macOS at login. Appending the PATH export to this file ensures every new terminal session can find OpenClaw without manual intervention.

# 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)

Apple switched macOS to Zsh as the default shell starting with macOS Catalina (10.15) in 2019. On Zsh, the equivalent config file is ~/.zshrc. The export line is identical to Bash.

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

# Verify
openclaw --version

PowerShell (Windows)

On Windows, npm defaults to %AppData%\npm for global installs. The [Environment]::SetEnvironmentVariable call writes a permanent user-level PATH entry to the Windows registry, so you only run it once.

# 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

The EACCES: permission denied error fires when npm tries to write global packages into a system-owned directory such as /usr/local/lib. The fix is to redirect npm's global prefix to a user-owned directory. Never run sudo npm install -- it creates root-owned files that break future installs and expose a privilege-escalation risk if any package runs postinstall scripts.

macOS / Linux fix

Creating a dedicated ~/.npm-global directory takes under 30 seconds and permanently eliminates EACCES errors for every future global install. This approach is the fix recommended by the npm documentation.

# 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 typically means your current PowerShell session lacks write access to the npm directory under %AppData%. Running PowerShell as Administrator grants the required permissions for the duration of that session, which is enough time to complete the install.

# 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 because it depends on ES module features and the built-in fetch API stabilized in that release. Errors like SyntaxError: Unexpected token or ERR_MODULE_NOT_FOUND during install almost always mean the active Node.js version predates v22. Node.js 22 entered LTS status in October 2024 and is supported through April 2027.

Run node --version to confirm the version your shell is currently using. If the output shows anything older than v22.12.0, upgrade before reinstalling OpenClaw.

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

Upgrade with nvm (recommended)

nvm (Node Version Manager) lets you install and switch between multiple Node.js versions without affecting system packages. Installing Node 22 with nvm takes about 60 seconds including download and compilation.

# 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)

Homebrew tracks the latest stable Node.js release in its core formula. As of May 2026, brew install node installs Node.js 22.x by default.

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 failures in OpenClaw typically stem from 1 of 4 causes: network timeouts, an incorrect package name, a version mismatch between OpenClaw and the plugin, or a corrupted npm cache. Diagnosing the root cause takes under 2 minutes when you run the install with verbose output, which prints each HTTP request and file write as it happens.

Start by listing what plugins are already installed, then retry the install with the --verbose flag to surface the exact failure point.

# 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.

If the verbose output does not point to a single cause, a full reset clears the npm cache, updates OpenClaw to the latest release, and reattempts the plugin install. This 3-step sequence resolves the majority of plugin failures.

# 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 all user settings in a single JSON configuration file at a platform-specific path. Knowing this path matters when you need to reset a broken config, back up settings before an upgrade, or debug plugin-loading issues. The file is created automatically the first time you run openclaw init and weighs less than 1 KB by default.

To reset OpenClaw's configuration to defaults, delete the JSON file and run openclaw init to regenerate it. This does not affect installed plugins or npm global packages -- it only resets OpenClaw's own settings.

# 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

Windows introduces 3 additional failure modes that do not exist on macOS or Linux: PowerShell execution policy restrictions, symlink permission requirements, and antivirus interference with npm's global directory. Each has a one-time fix. Windows 10 version 1703 and later support Developer Mode, which resolves the symlink issue without requiring Administrator access.

Execution policy blocks scripts

Windows PowerShell ships with the execution policy set to Restricted by default, which blocks all scripts. OpenClaw's npm postinstall script triggers an UnauthorizedAccess error under this policy. Changing the policy to RemoteSigned allows locally-created scripts to run while still blocking unsigned scripts downloaded from the internet.

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

# Reinstall
npm install -g openclaw

Symlink permissions

npm uses symbolic links (symlinks) to expose global binaries. On Windows, creating symlinks has required elevated privileges since Windows Vista. Starting with Windows 10 version 1703, enabling Developer Mode grants symlink creation rights to non-admin users -- the preferred option for development machines.

# 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

These are the 4 most common questions developers ask when troubleshooting OpenClaw CLI. Each answer is self-contained with the exact commands needed to diagnose and fix the issue.

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

In roughly 90% of cases, the npm global bin directory isn't in the shell's PATH. Run npm config get prefix, then look for the openclaw binary inside that path's bin folder. If the file is there, the PATH variable needs updating. If the file is missing, the install failed silently -- run npm install -g openclaw again. The command not found section has platform-specific PATH instructions for Bash, Zsh, and PowerShell.

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. The EACCES permission denied section covers both platforms in detail.

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
• Nylas CLI issue tracker (GitHub) — check existing reports and file new ones with reproduction steps