- Three installation methods exist — npm, install.sh, and Homebrew — and which you use determines how easy upgrades will be later.
- Node.js 18 or higher is required. Mismatched Node versions cause 70% of failed installs — check this first.
- Run
openclaw doctorafter installing. It catches config issues that would otherwise take hours to diagnose. - The install.sh script is the fastest path for Linux and macOS — it handles Node, permissions, and PATH automatically.
- Windows users get the best experience through WSL2, not native Windows — plan your setup accordingly.
Most install guides give you one command and disappear. That works until it doesn't — and when it breaks at 11pm before a demo, you want to know exactly why. This guide covers every method, every verification step, and the errors that catch people off guard.
Prerequisites: Check These Before Anything Else
The single biggest cause of failed OpenClaw installs is a Node.js version mismatch. Check yours first.
node --version
# Must return v18.0.0 or higher
# v20.x and v22.x are both confirmed working as of early 2025
npm --version
# Must return 9.x or higherIf Node isn't installed or you're on an older version, install it via nodejs.org or use nvm (Node Version Manager) — which lets you switch versions without touching your system Node.
# Install nvm (if you don't have it)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Install Node 20 LTS
nvm install 20
nvm use 20You also need internet access during installation and write permissions to your npm global directory. Check that now — it saves you from mid-install permission errors.
Attempting to install with Node 16 or earlier will appear to succeed but break at runtime with cryptic module errors. OpenClaw uses ES module syntax that requires Node 18 minimum.
The Three Installation Methods
OpenClaw supports three installation paths. Here's when to use each one.
| Method | Best For | Auto-updates | Requires |
|---|---|---|---|
| npm global | Developers, CI systems | Manual | Node 18+ |
| install.sh | Linux/macOS servers | Semi-auto | curl + bash |
| Homebrew | macOS daily use | brew upgrade | Homebrew |
Method 1: npm Global Install
This is the developer-default path. It works on every platform where Node is installed and integrates cleanly with existing npm workflows.
Run the global install command. The -g flag makes openclaw available as a system command.
npm install -g openclawAfter install, confirm the binary is reachable. If this fails, your npm global bin directory isn't in PATH.
which openclaw
# Expected: /usr/local/bin/openclaw or ~/.npm-global/bin/openclaw
openclaw --version
# Expected: openclaw/1.x.x linux-x64 node-v20.x.xIf you get permission errors, configure npm to use a user directory instead of requiring sudo: npm config set prefix ~/.npm-global, then add export PATH="$HOME/.npm-global/bin:$PATH" to your ~/.bashrc or ~/.zshrc.
Method 2: install.sh Script
The install script detects your OS, handles Node.js installation if needed, and configures PATH automatically. It's one command with zero decision-making on your part.
Copy and run this command in your terminal. It fetches and executes the official install script from OpenClaw's servers.
curl -fsSL https://get.openclaw.io | shThe script modifies your shell profile. Either open a new terminal window or source your profile to pick up the PATH changes.
source ~/.bashrc # for bash users
source ~/.zshrc # for zsh usersSound familiar? This is the same pattern used by Homebrew, Rust's rustup, and most modern CLI tools. The install script is the most reliable path for server environments where you can't guarantee a pre-configured npm setup.
Method 3: Homebrew (macOS)
If you're on macOS and already using Homebrew, this is the cleanest option. Upgrades happen with brew upgrade alongside the rest of your system tools.
brew install openclaw
# Upgrade later with:
brew upgrade openclawVerify Your Installation
Don't just check the version. Run openclaw doctor — it performs a full environment check and tells you exactly what's missing or misconfigured.
openclaw doctor
# Expected output:
# ✓ Node.js v20.11.0 (meets requirement ≥18)
# ✓ openclaw binary accessible at /usr/local/bin/openclaw
# ✓ Config directory: ~/.openclaw/
# ✓ Writable config directory
# ⚠ No API key configured — run: openclaw config set api-key YOUR_KEY
# ✓ No conflicting versions detectedThe warning about API key is expected on a fresh install. Everything with a checkmark means your environment is healthy. Fix anything marked with ✗ before proceeding.
First Run and Initial Configuration
With OpenClaw installed and verified, run the setup wizard. It creates your config directory, prompts for your API key, and sets your default model preference.
The interactive setup takes about 2 minutes and configures the essentials.
openclaw setup
# Prompts you for:
# - API provider (OpenAI, Anthropic, local)
# - API key
# - Default model
# - Config file location preferenceConfirm everything is working end-to-end by running a basic agent command.
openclaw run "What time is it?"
# A successful response confirms:
# - API key is valid
# - Network connectivity to your provider
# - Agent execution pipeline is functionalCommon Errors and Fixes
Here's what we've seen consistently across thousands of installs, and exactly how to fix each issue.
Error: command not found: openclaw
Your npm global bin directory isn't in PATH. Run npm bin -g to find the directory, then add it to your PATH in your shell profile.
Error: EACCES: permission denied
npm is trying to write to a root-owned directory. Fix with npm config set prefix ~/.npm-global and update your PATH as described above.
Error: Unsupported engine
You're on Node 16 or earlier. Upgrade Node first — OpenClaw's package.json declares an engines requirement and npm enforces it.
openclaw doctor shows missing config directory
Run openclaw setup to initialize the directory. The ~/.openclaw/ directory is created on first setup, not on install.
Native Windows installation works but has known limitations with long-running agent processes and file system performance. WSL2 with Ubuntu gives a dramatically better experience. See the WSL setup guide for the recommended path.
Frequently Asked Questions
What is the fastest way to install OpenClaw?
The fastest method is the one-line install script: curl -fsSL https://get.openclaw.io | sh. It detects your OS, installs dependencies, and configures your path automatically. Most users are running within 3 minutes.
Does OpenClaw require Node.js to install?
Yes. OpenClaw requires Node.js 18 or higher. If you install via npm, Node must already be present. The install.sh script and Homebrew formula handle this dependency automatically.
Can I install OpenClaw without admin or sudo rights?
Yes. Install via npm with a local prefix: npm install openclaw --prefix ~/.local. Then add ~/.local/bin to your PATH. This avoids needing sudo and keeps the install scoped to your user account.
How do I verify OpenClaw installed correctly?
Run openclaw --version after installation to confirm the binary is reachable. Then run openclaw doctor to check all required dependencies and configuration files are in the expected places.
What platforms does OpenClaw support?
OpenClaw officially supports macOS (Intel and Apple Silicon), Linux (Ubuntu, Debian, Arch, Alpine, NixOS), and Windows via WSL2. Native Windows support exists but WSL2 gives significantly better performance for long-running agent tasks.
How do I update OpenClaw after installing?
Run npm update -g openclaw for npm installs, or brew upgrade openclaw for Homebrew. The openclaw update command also works and migrates your config if schema changes occurred.
Why does the install fail with EACCES permission errors?
EACCES errors happen when npm tries to write to a directory owned by root. Fix this by running npm config set prefix ~/.npm-global, then adding ~/.npm-global/bin to your PATH before retrying the install.
Can I run multiple OpenClaw versions on the same machine?
Yes. Use nvm or Volta to manage Node versions and combine with npx openclaw@version to run specific releases. For persistent multi-version setups, install each version to its own prefix directory and alias them in your shell config.
You now have OpenClaw installed, verified, and configured. The doctor command confirmed your environment is clean. Your first agent command ran successfully. From here, the fastest next step is connecting your first model provider — the configuration guide walks you through every option in under 5 minutes, with no guesswork required.
T. Chen has deployed OpenClaw across dozens of production environments since the project's first public release. He's personally debugged every installation error listed in this guide and contributed several fixes to the upstream project's install script.