Troubleshooting the openclaw Command Not Found After Installation

Problem Description

After successfully installing via npm install -g openclaw, running the openclaw command in the terminal results in a "command not found" error:

$ openclaw --version
bash: openclaw: command not found

Or on Windows:

'openclaw' is not recognized as an internal or external command, operable program or batch file.

Or in PowerShell:

openclaw: The term 'openclaw' is not recognized as the name of a cmdlet, function, script file, or operable program.

Globally installed npm packages are placed in a specific global directory, where symbolic links to the executables are created. If this directory is not in the system's PATH environment variable, the terminal cannot find the openclaw command.

Diagnostic Steps

Step 1: Check the npm Global Install Path

Run the following command to see the npm global package installation prefix:

npm prefix -g

This will output a path like:

Linux / macOS: /usr/local or /home/username/.nvm/versions/node/v22.x.x
Windows: C:\Users\username\AppData\Roaming\npm

Global executables are located in the bin subdirectory (Linux/macOS) or the root directory (Windows) of that path.

Step 2: Verify the openclaw Binary Exists

# Linux / macOS
ls -la $(npm prefix -g)/bin/openclaw

# Windows (Git Bash)
ls -la "$(npm prefix -g)/openclaw.cmd"

If the file exists, the installation itself is fine — only the PATH configuration is incorrect. If the file doesn't exist, the installation may have encountered an error and needs to be redone.

Step 3: Check the PATH Environment Variable

echo $PATH

Search for the npm global path in the output. If it's not there, you need to add it manually.

You can also use npm's built-in path utility:

npm bin -g

This directly outputs the directory path where global executables reside.

Solutions

Linux / macOS Users

Add the npm global bin directory to your PATH. Edit the configuration file for your shell:

# Bash users
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Zsh users
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

If you use nvm to manage Node.js, nvm's initialization script usually sets the PATH automatically. Check your shell config file for the nvm initialization code:

grep -n "nvm" ~/.bashrc

You should see lines similar to:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

If these lines are missing or commented out, uncomment or re-add them.

Windows Users

The npm global path on Windows is typically %APPDATA%\npm. You need to add it to the system PATH environment variable:

Press Win + R, type sysdm.cpl, and press Enter
Switch to the "Advanced" tab and click "Environment Variables"
Find Path under "User variables" and double-click to edit
Add a new entry: %APPDATA%\npm
Click OK to save, then reopen the terminal

Or quickly add it with PowerShell:

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:APPDATA\npm", "User")

After adding, you need to restart the terminal for the changes to take effect.

Using npx as a Temporary Workaround

If you need to use OpenClaw urgently but can't modify PATH right away, you can run it directly via npx:

npx openclaw --version
npx openclaw start

npx will automatically locate the globally installed package or temporarily download and execute it. However, this is not a long-term solution — fixing the PATH configuration is recommended.

Using pnpm or yarn for Global Installation

If you use pnpm or yarn as your package manager, the global install path may differ:

# pnpm
pnpm add -g openclaw
pnpm bin -g  # View the global bin path

# yarn
yarn global add openclaw
yarn global bin  # View the global bin path

Similarly, make sure the corresponding bin path is in your PATH.

Verifying the Fix

After fixing the PATH, open a new terminal window (this is important — old windows may not load the updated environment variables) and run:

openclaw --version
which openclaw   # Linux / macOS
where openclaw   # Windows

If the command outputs the version number and executable path, the issue is resolved. You can then initialize the configuration:

openclaw init

This will create a default openclaw.json configuration file in the ~/.openclaw/ directory.