How to Install OpenClaw - Complete Setup Guide

Getting OpenClaw installed is one of those things that's either dead simple or mildly frustrating depending on your setup. I've done this enough times across different machines and client environments that I can tell you exactly where people get stuck and how to avoid it.

What You Need Before You Start

OpenClaw needs Node.js 22 or newer. That's the main dependency. Check what you've got:

node --version

If you get nothing back or something below v22, you'll need to install or upgrade Node first. On macOS, brew install node is the fastest path. On Linux, NodeSource repositories work well for Ubuntu and Debian. Windows users can grab it through winget or Chocolatey.

One thing that catches people out: if you use a version manager like nvm or fnm, make sure it's initialised in your shell startup file (~/.zshrc or ~/.bashrc). Otherwise the openclaw command won't be found after installation because the PATH isn't set up properly.

Installing OpenClaw

The install itself is a one-liner.

macOS and Linux:

curl -fsSL https://openclaw.ai/install.sh | bash

Windows (PowerShell):

iwr -useb https://openclaw.ai/install.ps1 | iex

That downloads and installs the CLI. Takes about 30 seconds on a decent connection.

Running the Setup Wizard

After installation, run the onboarding wizard:

openclaw onboard --install-daemon

This walks you through the initial configuration. It sets up your gateway (the background process that manages all your messaging channels and agent connections), configures authentication, and gets you to a working state.

Once that finishes, verify everything is running:

openclaw gateway status

You should see the gateway running on port 18789. If not, you can start it manually:

openclaw gateway --port 18789

The Fastest Way to Start Chatting

You don't need to set up WhatsApp or Telegram or any messaging channel to start using OpenClaw. The quickest path is the built-in Control UI:

openclaw dashboard

This opens a web interface at http://127.0.0.1:18789/ where you can chat directly with your agent. It's useful for testing your setup before connecting any external channels.

Docker Installation

If you prefer running OpenClaw in a container (and honestly, for production deployments this is usually the better option), there's a Docker setup script:

./docker-setup.sh

This handles building the image, running the onboarding wizard inside the container, starting the gateway via Docker Compose, and generating authentication tokens.

The Docker approach needs at least 2 GB of RAM and Docker Compose v2. You can configure it with environment variables:

• OPENCLAW_IMAGE to use a pre-built remote image instead of building locally
• OPENCLAW_SANDBOX to enable Docker-based sandboxing for agent tool execution
• OPENCLAW_EXTENSIONS to pre-install extension dependencies during the build

After setup, open http://127.0.0.1:18789/ and paste your generated token into Settings.

The Docker image runs as a non-root node user (UID 1000) by default. Storage works through bind mounts for config and workspace directories, so your data persists between container restarts.

Connecting Your First Channel

With the gateway running, you can connect messaging channels. The most common ones we see in business deployments are WhatsApp, Telegram, and Discord. Each channel has its own login process through the CLI:

openclaw channels login

This gives you a list of available channels and walks you through connecting each one. WhatsApp uses a QR code pairing process, Telegram needs a bot token from BotFather, and Discord requires a bot application from the Discord developer portal.

Common Installation Problems

"openclaw: command not found" after installing. This is almost always a PATH issue. Check where npm installed it:

npm config get prefix

Make sure that path's bin directory is in your shell's PATH.

Permission errors on Linux. If you see EACCES errors, redirect npm's global prefix to a user-writable directory:

npm config set prefix ~/.npm-global

Then add ~/.npm-global/bin to your PATH.

Gateway won't start. Usually means port 18789 is already in use. Check what's using it and either stop that process or configure OpenClaw to use a different port.

Environment Variables

Three environment variables control where OpenClaw stores its data:

• OPENCLAW_HOME sets the home directory for path resolution
• OPENCLAW_STATE_DIR overrides the state directory location
• OPENCLAW_CONFIG_PATH points to a custom config file

Most people never need to touch these. They're useful if you're running multiple OpenClaw instances or have specific directory requirements for compliance.

What Happens Next

Once you've got OpenClaw installed and running, you'll want to set up your agent workspace, configure your AI model provider (OpenAI, Anthropic, or one of the many other supported providers), and start building skills.

If you're looking at deploying OpenClaw across a team or for business use, we help organisations get set up through our OpenClaw managed service. The install is straightforward for a single machine, but production deployments across multiple users with proper security, monitoring, and channel management benefit from having someone who's done it before.

Get in touch if you want help with your OpenClaw setup.