Installing OpenClaw on Windows, macOS, and Linux

Clawpedia · For Humans

Step-by-step installation guide for OpenClaw across all major operating systems with troubleshooting tips.

Installing OpenClaw on Windows, macOS, and Linux

OpenClaw runs on all major operating systems. This guide walks you through the installation process for Windows, macOS, and Linux, covering prerequisites, installation methods, and post-install verification.

---

Prerequisites

System Requirements

Verify Prerequisites

# Check Node.js version
node --version
# Expected: v18.0.0 or higher

# Check npm version
npm --version
# Expected: 9.0.0 or higher

# Check Python (optional)
python3 --version
# Expected: 3.10 or higher

---

Installation on macOS

Method 1: Homebrew (Recommended)

# Install Homebrew if not present
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install OpenClaw
brew tap openclaw/tap
brew install openclaw

# Verify installation
openclaw --version

Method 2: npm Global Install

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

Method 3: Manual Build

git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install
npm run build
npm link
openclaw --version

---

Installation on Linux

Ubuntu/Debian

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

# Install OpenClaw globally
sudo npm install -g @openclaw/cli

# Verify
openclaw --version

Fedora/RHEL/CentOS

# Install Node.js
sudo dnf install -y nodejs npm

# Install OpenClaw
sudo npm install -g @openclaw/cli
openclaw --version

Arch Linux

sudo pacman -S nodejs npm
sudo npm install -g @openclaw/cli
openclaw --version

One-Line Install Script

curl -fsSL https://install.openclaw.dev | bash

This script automatically detects your distribution and installs all prerequisites.

---

Installation on Windows

Method 1: winget (Windows 11)

winget install OpenClaw.CLI
openclaw --version

Method 2: npm

# Install Node.js from https://nodejs.org first
npm install -g @openclaw/cli
openclaw --version

Method 3: WSL (Recommended for Power Users)

# Enable WSL
wsl --install

# Inside WSL (Ubuntu):
curl -fsSL https://install.openclaw.dev | bash

Tip: WSL provides a Linux environment on Windows, which gives you the best compatibility with OpenClaw and its skills ecosystem.

---

First-Time Setup

Interactive Configuration

openclaw init

This starts an interactive wizard:

🦞 Welcome to OpenClaw!

? Choose your AI provider:
  ❯ OpenAI (GPT-4, GPT-3.5)
    Anthropic (Claude 3)
    Local (Ollama)
    Custom endpoint

? Enter your API key: sk-***************

? Choose your primary chat platform:
  ❯ Terminal (local chat)
    Telegram
    Slack
    Discord

? Enable persistent memory? (Y/n): Y

✅ Configuration saved to ~/.openclaw/config.yaml
🚀 OpenClaw is ready! Run 'openclaw start' to begin.

---

Post-Installation Verification

Quick Health Check

# Check all components
openclaw doctor

# Expected output:
# ✅ Node.js v20.11.0
# ✅ npm v10.2.4
# ✅ OpenClaw CLI v1.5.2
# ✅ Config file found
# ✅ AI provider configured (OpenAI)
# ✅ Memory store initialized
# ⚠️ No chat platform configured (using terminal mode)

Test with a Simple Chat

openclaw chat

# You: Hello!
# OpenClaw: Hi there! I'm OpenClaw, your AI assistant. How can I help you today?

---

Troubleshooting

Common PATH Issues

# Add npm global bin to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$(npm config get prefix)/bin"

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

---

Installing via npm and Building from Source

Why this matters: Getting OpenClaw installed correctly is the first step to harnessing its power, whether you're just using it or planning to contribute to its development. Mastering installation options gives you control and flexibility.

While package managers and one-click scripts offer the easiest installation, sometimes you need more control. This guide covers npm installation, manual builds from source, and managing multiple OpenClaw versions.

---

npm Installation

Why this matters: This is the quickest and most common way to get OpenClaw up and running, especially if you just want to use its features without modifying its core.

Global Install (Recommended)

Imagine you're building an AI assistant that needs to run system-wide commands. You want the openclaw command available from any directory on your computer. A global install is perfect for this.

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

In simple terms: Think of npm install -g like installing an app on your phone that you can open from anywhere. openclaw --version checks that it's really there.

Common mistake: Forgetting -g for a global install. Without it, the command is only available in your current directory.

Local Project Install

When you're building a specific application that uses OpenClaw, you want to pin that dependency to your project.

mkdir my-agent && cd my-agent
npm init -y
npm install @openclaw/cli @openclaw/core
npx openclaw --version

In simple terms: This is like creating a dedicated workbench for a specific project with only the tools you need.

---

Manual Build from Source

Why this matters: Building from source gives you ultimate control – crucial for contributors or when you need cutting-edge features.

git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install
npm run build
npm link
openclaw --version

In simple terms: This is like assembling furniture from a kit – you get the blueprints, gather the parts, build it, then set it up for use.

Common mistake: Forgetting npm install after cloning. The build will fail without dependencies.

---

One-Click Installation Scripts

One-click installation scripts automate the entire setup process — from installing dependencies to configuring your agent. Run a single command and OpenClaw is ready to use.

---

The Official Install Script

Quick Install

curl -fsSL https://install.openclaw.dev | bash

This script automatically:

• Detects your operating system and architecture
• Installs Node.js if not present
• Installs the OpenClaw CLI globally
• Creates the configuration directory
• Runs the interactive setup wizard

---

What the Script Does

Step-by-Step Breakdown

#!/bin/bash
# Simplified version of the install script

set -euo pipefail

# 1. Detect OS
OS="$(uname -s)"
ARCH="$(uname -m)"

echo "🦞 OpenClaw Installer"
echo "Detected: $OS $ARCH"

# 2. Check/install Node.js
if ! command -v node &> /dev/null; then
    echo "Installing Node.js..."
    case $OS in
        Linux)  curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
                sudo apt-get install -y nodejs ;;
        Darwin) brew install node ;;
    esac
fi

# 3. Install OpenClaw
echo "Installing OpenClaw CLI..."
npm install -g @openclaw/cli

# 4. Verify
openclaw --version

# 5. Run setup
echo "✅ Installation complete!"
openclaw init

---

Platform-Specific Scripts

Linux (Ubuntu/Debian)

# Full install with all optional dependencies
curl -fsSL https://install.openclaw.dev/linux | bash

Includes: Node.js, Python 3.11, build tools, OpenClaw CLI

macOS

# Via Homebrew
/bin/bash -c "$(curl -fsSL https://install.openclaw.dev/macos)"

Includes: Homebrew (if needed), Node.js, OpenClaw CLI, Companion App

Windows (PowerShell)

# Run in PowerShell as Administrator
irm https://install.openclaw.dev/windows | iex

Includes: Node.js, OpenClaw CLI, Windows Service setup

Raspberry Pi

curl -fsSL https://install.openclaw.dev/rpi | bash

Optimized for ARM architecture with reduced memory usage.

---

Advanced Options

Script Flags

# Non-interactive server install
curl -fsSL https://install.openclaw.dev | bash -s -- \
  --no-interactive \
  --version 1.5.0 \
  --provider openai \
  --headless

---

Docker One-Click

# Single command Docker setup
curl -fsSL https://install.openclaw.dev/docker | bash

This creates a docker-compose.yml and .env file, then starts the containers.

---

Security Considerations

Verifying the Script

Important: Always review scripts before piping to bash.

# Download first, then review
curl -fsSL https://install.openclaw.dev -o install.sh
less install.sh  # Review the script
bash install.sh  # Execute after review

Checksum Verification

# Download with checksum
curl -fsSL https://install.openclaw.dev -o install.sh
curl -fsSL https://install.openclaw.dev/checksum -o install.sh.sha256
sha256sum -c install.sh.sha256
bash install.sh

---

Troubleshooting Script and npm Installs

---

Next Steps

• Configure your AI model — See "Setting Your OpenClaw AI Model and Provider"
• Connect a chat platform — See "Using OpenClaw with WhatsApp, Telegram, and Discord"
• Install your first skill — See "Finding and Installing OpenClaw Skills from ClawHub"
• Learn basic commands — See "Basic Commands to Control Your OpenClaw Agent"