OpenClaw error: openclaw: command not found
In almost every case the install worked and the binary exists. Your shell simply does not have the global npm bin directory on its PATH, which is a two-line fix once you know which shell file to edit.
The message is exactly what it says:
openclaw: command not found
bash: openclaw: command not found
zsh: command not found: openclawAlmost always the install succeeded and the shell simply cannot find the result.
Step 1: prove the binary exists before touching anything
npm prefix -g
ls "$(npm prefix -g)/bin" | grep openclawIf openclaw is listed, stop worrying about the install. You have a
PATH problem and the rest of this page applies. If it is not listed, the install
genuinely did not complete, and you should rerun it and read the output rather than
scrolling past it.
Step 2: the fix
export PATH="$(npm prefix -g)/bin:$PATH"That works for the current terminal only. To make it permanent, add the same line to the profile your shell actually reads:
| Shell | File to edit |
|---|---|
| zsh, the macOS default | ~/.zshrc |
| bash on Linux | ~/.bashrc |
| bash on macOS | ~/.bash_profile |
| fish | ~/.config/fish/config.fish, using fish_add_path |
Then open a new terminal and check:
openclaw --versionStep 3: the trap that catches people who already fixed the PATH
This is the part worth reading even if the command now works for you.
Background services do not read your shell profile. A systemd
unit, a launchd agent, or a cron job starts with a minimal environment, so the PATH
you carefully exported in .bashrc does not exist there. The result is
confusing: openclaw works perfectly when you type it and the service
fails with command not found.
Two ways out. Either give the service the full path to the binary rather than the bare command, or create a symlink somewhere already on the system PATH:
sudo ln -s "$(which openclaw)" /usr/local/bin/openclawNode version managers make this worse
If you installed Node through nvm, the binary lives inside a version-specific directory that only exists after nvm's shell hook runs. systemd never runs it, so the path is not merely missing from PATH, it can be missing entirely from the service's point of view. The symlink above is the standard workaround, and it is worth doing proactively on any machine where OpenClaw runs as a service.
Platform notes
Windows
Close and reopen PowerShell after installing. Windows does not refresh the environment of a session that was already open, so a fresh install genuinely is invisible until you start a new shell.
Docker
Inside a container, the command exists only if it was installed in that image and
for that user. Check with docker exec <container> which openclaw
before assuming the container is broken.
pnpm
pnpm blocks build scripts by default, which can leave a global install incomplete.
Run pnpm approve-builds -g and install again.
If it really did fail to install
The most common genuine failure is the native sharp dependency. Skip
the global libvips lookup and retry:
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latestFrequently asked questions
- Do I need to reinstall?
- Almost never. Check whether the binary exists first with ls on the global npm bin directory. If it is there, this is a PATH problem, not an install problem.
- Why does it work in my terminal but not in my service?
- Because systemd and launchd do not read your shell profile. A PATH exported in .bashrc or .zshrc does not exist for a background service.
- Do I need sudo?
- If a global install requires sudo, that is a sign npm's global prefix points somewhere your user cannot write. Changing the prefix to a directory you own is better than installing everything as root.
Related guides
- OpenClaw stuck on starting, or the gateway will not come upA gateway that hangs on starting is nearly always failing for a reason it already wrote to the logs. Read the logs first, because the five causes below have five different fixes and guessing between them wastes the most time.
- Where is the OpenClaw config file, and how do you change its location?The short answer is ~/.openclaw/openclaw.json, written in JSON5. The longer answer matters when your edits appear to be ignored, which is almost always a second config file or an environment variable winning over the one you edited.
- OpenClaw error: RangeError, maximum call stack size exceededUnlike most errors, this one is usually not your configuration. It has been reported and fixed three separate times in OpenClaw for three different reasons, so the first thing to establish is which version you are running.
- How to Fix "Hermes backend exited before it became ready"The number in the brackets decides everything. Zero means a healthy backend shut itself down, usually a Windows watchdog misfire, and any other number means it genuinely failed, usually an update applied while Hermes was still running.