OpenClaw NPM Package: Install and Run in Under 5 Minutes

Most people waste 30 minutes on a broken install because they skip two checks. As of early 2025, the OpenClaw npm package is the most reliable cross-platform install path — faster than the shell script on machines with Node already present, and cleaner than Homebrew for developers managing multiple projects. Skip those two checks and you will hit permission errors or a missing PATH entry that makes every openclaw command fail silently. This guide removes both problems before they happen.

Prerequisites You Must Verify First

Before a single npm command, confirm two things. First, Node.js version. Second, npm itself is functional. Skipping this step is where 80% of failed installs begin.

# Check Node version — must be 18.x or higher
node --version

# Check npm version — must be 9.x or higher
npm --version

If node returns v16 or lower, the install will fail with an engines mismatch error. The package.json in the openclaw npm package specifies "node": ">=18.0.0" explicitly. You need to upgrade Node before proceeding.

The fastest upgrade path is nvm (Node Version Manager). Install nvm, then:

nvm install 20
nvm use 20
nvm alias default 20

That sets Node 20 LTS as your default. OpenClaw works on 18, 20, and 22. We recommend 20 LTS for production stability.

The Global Install Command

With Node 18+ confirmed, install OpenClaw globally:

npm install -g openclaw

This pulls the package from the npm registry, installs all dependencies into your global node_modules, and creates a openclaw binary in your npm global bin directory. The package is roughly 12MB including dependencies. On a standard broadband connection, it completes in under 60 seconds.

Want a specific version? Pin it like this:

# Install a specific version
npm install -g openclaw@1.4.2

# Install the latest beta
npm install -g openclaw@beta

For most users, omitting the version tag is correct — you get the latest stable release. The exception is team environments where everyone needs to run identical versions. In that case, pin explicitly and document the version in your team's setup guide.

PATH Configuration

After install, running openclaw might return "command not found." This is a PATH problem, not an install problem.

Find where npm puts global binaries:

npm config get prefix

On macOS with nvm, this typically returns something like /Users/yourname/.nvm/versions/node/v20.11.0. The actual binary lives at that path + /bin. That directory needs to be in your PATH.

Add it to your shell profile:

# For zsh (macOS default since Catalina)
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# For bash
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

With nvm, this is handled automatically when nvm loads. If you used nvm to install Node, your PATH is almost certainly correct already. The issue appears most often on systems with system-installed Node (via apt, Homebrew without nvm, or manual download).

Installing Without sudo

If your global npm prefix points to a system directory (like /usr/local), you will hit EACCES errors without sudo. The correct fix is to move the prefix to a user-owned directory.

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

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

# Add the bin directory to PATH
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Now install without sudo
npm install -g openclaw

This change persists across shell sessions and applies to all future global npm installs. It is the npm-recommended approach and what the official npm docs suggest for avoiding permission errors without reaching for sudo.

Verifying the Install

Three commands confirm a clean install:

# 1. Check the binary is accessible
openclaw --version

# 2. Run the built-in diagnostics
openclaw doctor

# 3. List available commands
openclaw --help

openclaw --version should print something like openclaw/1.4.2 darwin-arm64 node-v20.11.0. If it returns nothing, the binary is not in PATH. If it returns an error about a missing module, the install was corrupted — run npm install -g openclaw again.

openclaw doctor runs a suite of environment checks: Node version, config file presence, API key validity (if configured), and network connectivity to OpenClaw's service endpoints. Any failures appear in red with remediation instructions.

Your First Run After Install

The install sets up the binary. It does not configure your agent. That happens through onboarding:

openclaw onboard

The onboard command walks you through selecting a model provider, entering your API key, and launching your first agent. It takes under 3 minutes and saves everything to ~/.openclaw/config.json.

Here's where most people stop. They get to onboard, connect a model, then wonder why nothing responds. The missing step: starting the agent runtime.

# Start the agent in the current terminal
openclaw start

# Or start in the background
openclaw start --daemon

With the runtime running, your agent is live. Open the TUI dashboard with openclaw tui to see live status, logs, and connected channels.

Common Mistakes and How to Avoid Them

The same four mistakes account for nearly every failed npm install we've seen:

Wrong Node version. Node 16 is still common on developer machines. OpenClaw requires 18+. Check before installing, not after the error appears.

sudo on macOS. It works once. Then every subsequent npm command breaks. Reconfigure your prefix instead.

Missing PATH update. The binary installs correctly but isn't accessible. Always run source ~/.zshrc or open a new terminal after modifying PATH.

Skipping openclaw doctor. This command catches 90% of post-install issues automatically. Running it costs 10 seconds. Not running it costs hours of debugging.

Frequently Asked Questions

What is the npm command to install OpenClaw globally?

Run npm install -g openclaw. This places the openclaw binary in your global npm bin directory. Verify with openclaw --version afterward. If the command is not found, your PATH likely does not include the npm global bin directory — run npm config get prefix to find it.

Does the OpenClaw npm package require a specific Node.js version?

OpenClaw requires Node.js 18 or higher. The npm package fails to install on older versions with an engine mismatch error. Use nvm or Volta to switch versions cleanly before running the install command. Node 20 LTS is the recommended version as of early 2025.

How do I install openclaw npm without sudo?

Configure npm to use a user-owned directory: run npm config set prefix ~/.npm-global, then add ~/.npm-global/bin to your PATH in your shell profile. After that, npm install -g openclaw works without root access on any platform.

Why does "openclaw command not found" appear after npm install?

The npm global bin folder is not in your PATH. Run npm config get prefix to find the path, then add that path followed by /bin to your PATH variable in ~/.bashrc, ~/.zshrc, or equivalent, and reload your shell with source ~/.zshrc.

Can I install a specific version of the openclaw npm package?

Yes. Run npm install -g openclaw@1.4.2 to pin a specific version. Check available versions at npmjs.com/package/openclaw. Pinning is recommended for production agent deployments where version stability matters more than getting new features.

How do I update the openclaw npm package?

Run npm update -g openclaw to pull the latest stable release. Alternatively, openclaw update handles this internally and migrates config files if schemas changed. Always check release notes before updating in production environments.

What does the openclaw npm package include?

The package includes the CLI binary, the local agent runtime, built-in skill loader, and the TUI dashboard. It does not bundle model weights or API keys — those are configured separately after install via openclaw onboard during the setup wizard.