OpenClaw Install: Step-by-Step Setup Guide for Mac, Linux, and Windows

Getting OpenClaw running takes about 10 minutes if you know what you're doing. This guide covers every step — prerequisites, install, config, first run — plus the errors people actually hit and how to fix them.

Before you start, if you're unclear on what OpenClaw is, read What Is OpenClaw first. If you're planning a Docker deployment instead of a local install, skip to OpenClaw Docker Setup.

---

Prerequisites

OpenClaw runs on Node.js. That's the only hard dependency. Everything else is optional depending on what you want to do.

Required:

• Node.js 18+ (LTS recommended — v20 or v22)
• npm 9+ (comes with Node)
• An LLM API key — Anthropic Claude, OpenAI, or Google Gemini

Recommended:

• Git (for managing your workspace and skills)
• A terminal you're comfortable in

Optional:

• Docker (if you want containerized deployment)
• A Telegram bot token (for Telegram channel integration)
• A Discord bot token (for Discord integration)

Checking Your Node Version

node --version
npm --version

If you're on Node 16 or below, upgrade before proceeding. OpenClaw uses modern ESM syntax that requires Node 18+.

Quick Node upgrade options:

# Using nvm (recommended — works on Mac, Linux, WSL)
nvm install 20
nvm use 20

# Using Homebrew on Mac
brew install node@20

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

---

Installing OpenClaw

Global npm Install

npm install -g openclaw

This installs the openclaw CLI globally. After install, verify it worked:

openclaw --version

You should see a version string like openclaw/1.x.x. If you get command not found, see the PATH fix in the troubleshooting section below.

What Gets Installed

The global install puts OpenClaw's runtime and CLI into your npm global prefix. Your actual workspace — config, memory files, skills, credentials — lives separately in ~/.openclaw/ and is never touched by reinstalls or upgrades.

---

Platform Differences

macOS

macOS installs are generally smooth. A few things to know:

• Permissions: If you get EACCES errors during npm install -g, your npm global prefix isn't writable. Fix this by setting a user-owned prefix:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Then retry the install.

• Homebrew Node users: Homebrew Node typically installs without the permission issue, but verify your PATH includes /opt/homebrew/bin (Apple Silicon) or /usr/local/bin (Intel).

• Gatekeeper: On first run, macOS may warn about unverified developer. OpenClaw is distributed via npm, not a signed macOS app — this is expected. The warning is about the Node binary, not a security risk.

Linux

Linux is OpenClaw's native environment. Runs cleanly on Ubuntu 20.04+, Debian 11+, Fedora 36+, Arch.

• Root installs: If you installed Node via apt or yum with sudo, npm's global prefix may require sudo. Avoid running sudo npm install -g openclaw — it works but causes permission headaches later. Use nvm for a clean user-owned Node setup instead.

• Headless servers: OpenClaw runs fine without a display. If you're on a VPS, everything works except browser-based features (which require Chromium). Set browser.enabled: false in your config if you're headless-only.

Windows

OpenClaw works on Windows, but the path of least resistance is WSL2 (Windows Subsystem for Linux). If you're a developer already using WSL2, install OpenClaw inside the WSL2 environment and treat it as a Linux install.

Native Windows (PowerShell/CMD):

Install Node via the official installer or via winget:

winget install OpenJS.NodeJS.LTS

Then:

npm install -g openclaw

File paths in your OpenClaw workspace will use Windows-style paths, but the agent runtime handles this correctly. If you use the exec tool to run shell commands from agents, use powershell or cmd syntax.

WSL2 (recommended for Windows):

# Inside WSL2 terminal
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20
npm install -g openclaw

Everything after this works identically to Linux.

---

Initial Configuration

After install, run the setup wizard:

openclaw setup

This walks you through:

1. Workspace location — defaults to ~/.openclaw/workspace. Accept the default unless you have a specific reason to change it.
2. LLM provider — choose Anthropic, OpenAI, or Google. You'll enter your API key here.
3. Default model — e.g., anthropic/claude-sonnet-4-6. You can change this later.
4. Channel setup — optionally configure Telegram or Discord. Can be skipped and added later.

The setup wizard writes to ~/.openclaw/config.yaml. You can edit this file directly after initial setup.

Manual Config

If you prefer to skip the wizard or need to reconfigure, edit ~/.openclaw/config.yaml directly:

workspace: /home/youruser/.openclaw/workspace
providers:
  anthropic:
    apiKey: sk-ant-...
    defaultModel: anthropic/claude-sonnet-4-6
channels:
  telegram:
    botToken: "123456:ABC..."
    allowedUsers:
      - 123456789

The full config schema is documented in the OpenClaw GitHub repo.

---

First Run

Start the OpenClaw gateway:

openclaw gateway start

Then open a new terminal and test the agent:

openclaw chat

Type a message. You should get a response from your configured LLM provider within a few seconds.

If Telegram is configured, open Telegram, find your bot, and send it a message. The bot should respond.

Running as a Background Service

For persistent operation (especially on a VPS or home server), run the gateway as a daemon:

# Start in background
openclaw gateway start --daemon

# Check status
openclaw gateway status

# Stop the daemon
openclaw gateway stop

On Linux, you can also register OpenClaw as a systemd service for automatic startup on boot. The OpenClaw Docker article covers the containerized version of this setup.

---

Common Install Errors and Fixes

command not found: openclaw After Install

npm's global bin directory isn't in your PATH.

Fix:

# Find where npm puts global bins
npm config get prefix

# Add to PATH (adjust path as needed)
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

EACCES: permission denied During npm Install

You're trying to write to a directory owned by root.

Fix: Use nvm (see prerequisites section) or change npm's global prefix to a user-owned directory.

Error: Cannot find module on First Run

Usually means the install was incomplete. Try:

npm uninstall -g openclaw
npm install -g openclaw

If it persists, clear npm's cache first:

npm cache clean --force
npm install -g openclaw

API Key Rejected on First Chat

Double-check that:

1. The key is correctly copied (no trailing spaces)
2. It's the right key type for the provider you selected
3. The key has available credits/quota

Anthropic keys start with sk-ant-, OpenAI keys with sk-, Google keys vary by auth method.

Node Version Mismatch

Error: The engine "node" is incompatible with this module

You're on Node 16 or older. Upgrade to Node 18+ using nvm or your package manager.

Port Already in Use

Error: listen EADDRINUSE :::3000

Another process is using OpenClaw's default gateway port. Either kill the process or change the port in your config:

gateway:
  port: 3001

---

After Install: What's Next

Once OpenClaw is running, the two most valuable things to set up next:

1. Skills — Skills are what turn OpenClaw from a chat interface into an automation platform. Read How OpenClaw Skills Work to understand the system and start building your own.

2. Dashboard — The OpenClaw dashboard gives you a web UI to manage agents, view sessions, and monitor activity. See OpenClaw Dashboard Setup.

---

Skip the Self-Hosted Complexity

If you want to avoid setup friction, use this guide as your checklist and work through hosting, keys, channels, and verification in order.