How to Install OpenClaw: Mac, Linux, and Docker Guide

Installing OpenClaw takes under two minutes on most systems. It's a Node.js CLI tool, so if you can run npm install, you can run OpenClaw.

This guide covers every platform — macOS, Linux, Docker, and Windows via WSL — plus the common errors that trip people up and how to fix them.

System Requirements

Before installing, make sure your system meets these minimums:

| Requirement | Minimum | Recommended | | ------------- | --------- | ------------- | | Node.js | 18.0+ | 20 LTS | | RAM | 2 GB free | 4 GB free | | Disk space | 500 MB | 1 GB | | OS | macOS 12+, Ubuntu 20.04+, or Windows 10+ (WSL2) | Latest stable | | Network | Required (API calls to model providers) | Stable broadband |

OpenClaw itself is lightweight. The heavy lifting happens in the cloud (model inference), so you don't need a GPU or a powerful CPU.

Installing on macOS

Option 1: npm (Recommended)

# Install OpenClaw globally
npm install -g @anthropic/openclaw

# Verify the installation
openclaw --version

That's it. If you don't have Node.js installed yet:

# Install Node.js via Homebrew
brew install node

# Verify Node.js version (must be 18+)
node --version

Option 2: Homebrew Direct

# Tap the Anthropic formula
brew tap anthropic/openclaw

# Install
brew install openclaw

# Verify
openclaw --version

The Homebrew method handles Node.js as a dependency automatically.

macOS Gotchas

Xcode Command Line Tools: If you get errors about gyp or native modules, install Xcode CLI tools:

xcode-select --install

Permission errors with npm global installs: If npm install -g fails with EACCES, fix your npm permissions instead of using sudo:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to ~/.zshrc
export PATH=~/.npm-global/bin:$PATH
source ~/.zshrc

Apple Silicon (M1/M2/M3/M4): OpenClaw runs natively on ARM64. No Rosetta needed. If you installed Node.js under Rosetta previously, reinstall the native ARM version via Homebrew for better performance.

Installing on Linux

Ubuntu / Debian

# Install Node.js 20 LTS via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install OpenClaw
npm install -g @anthropic/openclaw

# Verify
openclaw --version

Fedora / RHEL / CentOS

# Install Node.js via dnf
sudo dnf module install nodejs:20

# Install OpenClaw
npm install -g @anthropic/openclaw

Arch Linux

sudo pacman -S nodejs npm
npm install -g @anthropic/openclaw

Snap (Any Distro)

sudo snap install openclaw --classic

The snap package bundles Node.js, so no separate installation needed.

Linux Gotchas

Node.js version too old: Many distros ship ancient Node.js (v12 or v14). Always use NodeSource or nvm to get version 18+:

# Check your version
node --version

# If it's below 18, use nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

Global npm without sudo: Same fix as macOS — configure npm to use a user-level prefix directory.

Missing build tools: Some optional dependencies need compilers:

sudo apt-get install build-essential python3

Installing with Docker

Docker is the cleanest option if you want isolation or don't want to install Node.js on your host.

Quick Start

# Pull the official image
docker pull anthropic/openclaw:latest

# Run OpenClaw with your API key
docker run -it \
  -e ANTHROPIC_API_KEY=sk-ant-your-key-here \
  -v $(pwd):/workspace \
  -w /workspace \
  anthropic/openclaw

The -v $(pwd):/workspace flag mounts your current directory into the container, so OpenClaw can read and write your project files.

Docker Compose

For a more permanent setup:

# docker-compose.yml
version: '3.8'
services:
  openclaw:
    image: anthropic/openclaw:latest
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - .:/workspace
    working_dir: /workspace
    stdin_open: true
    tty: true

Run with:

docker compose run openclaw

Docker Gotchas

File permissions: Files created by OpenClaw inside Docker may be owned by root. Add --user $(id -u):$(id -g) to match your host user:

docker run -it --user $(id -u):$(id -g) \
  -e ANTHROPIC_API_KEY=sk-ant-your-key \
  -v $(pwd):/workspace \
  -w /workspace \
  anthropic/openclaw

No shell access inside container: The default Docker image includes common tools (git, curl, python3), but if OpenClaw needs something that's not installed, create a custom Dockerfile:

FROM anthropic/openclaw:latest
RUN apt-get update && apt-get install -y your-tool-here

Network access: By default, Docker containers can reach the internet. If you're on a corporate network with proxy requirements, pass the proxy config:

docker run -it \
  -e HTTP_PROXY=http://proxy:8080 \
  -e HTTPS_PROXY=http://proxy:8080 \
  anthropic/openclaw

Installing on Windows (WSL2)

OpenClaw doesn't run natively on Windows. Use WSL2 (Windows Subsystem for Linux) instead.

Step 1: Enable WSL2

# In PowerShell (as Administrator)
wsl --install

This installs Ubuntu by default. Restart your computer when prompted.

Step 2: Set Up Node.js in WSL

Open your WSL terminal and follow the Linux instructions:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Step 3: Install OpenClaw

npm install -g @anthropic/openclaw
openclaw --version

Windows Gotchas

WSL1 vs WSL2: Make sure you're on WSL2. Check with wsl --list --verbose. WSL1 has compatibility issues with some Node.js packages.

File system performance: Working on files in /mnt/c/ (your Windows drive) is slow from WSL. Clone repos into your WSL home directory (~/projects/) instead for 10x better I/O performance.

VS Code integration: Install the "WSL" extension in VS Code to edit files in your WSL filesystem directly. OpenClaw running in WSL can then modify files that VS Code sees in real time.

First Run: Setting Up Your API Key

Once installed, configure your API key:

# Anthropic (default provider)
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# Add to your shell profile for persistence
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.zshrc
source ~/.zshrc

Get your API key from console.anthropic.com.

Your First Task

# Start an interactive session
openclaw

# Or run a one-shot command
openclaw "create a hello world Express.js server in server.js"

OpenClaw will create the file, write the code, and confirm what it did. Check the output with cat server.js.

Verifying Your Installation

Run through this checklist to make sure everything works:

# 1. Check OpenClaw version
openclaw --version

# 2. Check Node.js version (should be 18+)
node --version

# 3. Check API key is set
echo $ANTHROPIC_API_KEY | head -c 10
# Should print "sk-ant-xxx" (first 10 chars)

# 4. Run a simple test task
openclaw "print hello world to a file called test.txt"

# 5. Verify the output
cat test.txt

If all five steps pass, you're good to go.

Common Installation Errors

npm ERR! code EACCES

Permission denied on global install. Fix with the npm prefix method shown above, or use nvm which handles permissions automatically.

node: command not found

Node.js isn't installed or isn't in your PATH. Install via the platform-specific instructions above, then restart your terminal.

Error: Unsupported engine

Your Node.js is too old. OpenClaw requires 18+. Upgrade with nvm install 20 or reinstall from NodeSource.

ANTHROPIC_API_KEY not set

The API key environment variable is missing. Set it with export ANTHROPIC_API_KEY=your-key. Make sure you added it to your shell profile for persistence.

ETIMEDOUT or ECONNREFUSED

Network issues. Check your internet connection. If you're behind a corporate proxy, configure the HTTP_PROXY and HTTPS_PROXY environment variables.

For teams deploying OpenClaw across multiple machines or cloud environments, RunAgents handles provisioning, configuration, and monitoring from a single dashboard — no SSH-ing into servers to debug installations.

Frequently Asked Questions

Can I install OpenClaw without npm?

Yes. Use Homebrew on macOS (brew install openclaw), Snap on Linux (snap install openclaw --classic), or Docker. The Docker option requires no local Node.js installation at all.

Does OpenClaw auto-update?

No. Update manually with npm update -g @anthropic/openclaw or brew upgrade openclaw. Check for new versions with openclaw --version and compare against the GitHub releases page.

Can I have multiple versions of OpenClaw installed?

Use nvm to manage multiple Node.js environments, each with its own global packages. Or use Docker with specific image tags (anthropic/openclaw:1.2.3) to pin versions.

Does OpenClaw need internet access to run?

Yes. OpenClaw sends prompts to cloud-hosted AI models (Anthropic, OpenAI, etc.) and receives responses. Without internet access, it can't function. The tool access (files, shell) is all local, but the reasoning engine is remote.

Is there a GUI installer for OpenClaw?

No official GUI installer exists. The CLI installation is the supported method. If you want a visual interface for managing OpenClaw agents after installation, RunAgents provides a web-based dashboard.

Can I install OpenClaw on a Raspberry Pi?

Yes, as long as you're running a 64-bit OS with Node.js 18+. Performance will be limited by the Pi's RAM (4GB+ recommended). Use Raspberry Pi OS (64-bit) and install Node.js via nvm for the best compatibility.

Want to skip installation and go straight to agents? RunAgents gives you managed OpenClaw hosting with task management, team collaboration, and agent debugging built in. Get started free

Related Guides

• Run OpenClaw in Docker -- Docker-based setup

• What Is OpenClaw? -- What you are installing

• OpenClaw Skills Guide -- First things to set up