How to Install OpenClaw (macOS, Windows, Linux): Clean Setup + Verification

Hey there, automation builders. If you just want OpenClaw running, start here.

The shortest working path is:

For macOS, Linux, or WSL2:

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

For Windows PowerShell:

iwr -useb https://openclaw.ai/install.ps1 | iex
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

That is the first-screen version. If those commands work, you are done with installation and can move on to channels, models, and actual workflows.

If they do not work, do not reinstall three times. I have done that. It mostly creates three versions of the same problem. Use the system requirements and common errors below to find the layer that failed.

Before you pick a VPS or Raspberry Pi, check the OpenClaw hardware requirements guide. If the install finishes but the browser UI will not load, go straight to the OpenClaw dashboard troubleshooting guide.

System Requirements Before You Install

OpenClaw is a long-running Gateway process. It is not heavy by itself, but it does care about runtime versions, OS support, and memory headroom.

The current official OpenClaw install docs list these requirements:

The biggest correction to older install advice: Node 22 is not the ideal target anymore. It still works if you are on a supported 22.19+ build, but Node 24 is now the recommended path.

Second correction: Windows is no longer just "WSL2 or nothing." WSL2 is still a good path if you want a Linux-style Gateway, but current docs also list Windows native options through the Windows Hub and PowerShell installer.

I stopped here because this is where most failed installs start. People debug OpenClaw when they are really debugging an old Node runtime, an unsupported Windows path, or a box with too little RAM.

Choose Your Install Path

Use the installer script unless you have a specific reason not to.

The old question was "CLI or Docker?" The better question is: do you need a local desktop assistant, a server Gateway, or a reproducible deployment?

For most readers, the answer is local desktop assistant. Use the installer.

Fast Path: macOS Install

Run:

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

Then:

openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

What should happen:

• The installer detects your OS.
• Node is installed or validated.
• OpenClaw is installed.
• Onboarding walks through model/provider setup.
• The Gateway service is installed.
• The dashboard opens in your browser.

If you already manage Node yourself and prefer npm:

npm install -g openclaw@latest
openclaw onboard --install-daemon

If openclaw is not found after npm install, it is almost always a global npm PATH issue:

npm prefix -g
echo "$PATH"

Add the global bin path to your shell startup file:

export PATH="$(npm prefix -g)/bin:$PATH"

Then open a new terminal.

Fast Path: Linux Install

For Ubuntu, Debian, Fedora, Arch, or most modern Linux hosts:

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

If you are on a VPS or headless box, openclaw dashboard may print a URL or hint instead of opening a browser. In that case, use an SSH tunnel:

ssh -N -L 18789:127.0.0.1:18789 user@your-server

Then open this on your local machine:

http://127.0.0.1:18789/

For systemd user service checks:

systemctl --user status openclaw-gateway
journalctl --user -u openclaw-gateway -f

If you need the service to start before login on a headless server:

sudo loginctl enable-linger $USER
systemctl --user enable openclaw-gateway

Fast Path: Windows Install

You have three practical Windows paths now.

Option A: Windows PowerShell Installer

Run PowerShell:

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

Then:

openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

This is the cleanest command-line path for native Windows users.

Option B: Windows Hub

Use this if you want the easiest desktop path with setup, tray status, chat, node mode, and local MCP mode. The official docs now point desktop users there as a first-class option.

This path is better if you do not want to spend your first session debugging shells and PATH.

Option C: WSL2 Gateway

Use WSL2 when you specifically want the Linux Gateway environment:

wsl --install

Restart if Windows asks. Then open Ubuntu and run:

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

If systemctl does not work inside WSL2, enable systemd:

sudo nano /etc/wsl.conf

Add:

[boot]
systemd=true

Then from PowerShell:

wsl --shutdown

Reopen Ubuntu and try onboarding again.

Docker Install: Use It When Isolation Matters

Docker is a good fit for VPS deployments, reproducible environments, and setups where you want the Gateway separated from your host.

It is not always the easiest first install.

A minimal shape looks like this:

docker pull openclaw/openclaw:latest
docker run -d \
  --name openclaw-gateway \
  -v ~/.openclaw:/root/.openclaw \
  -p 127.0.0.1:18789:18789 \
  openclaw/openclaw:latest \
  gateway --port 18789

Notice the bind:

127.0.0.1:18789:18789

That keeps the dashboard local to the host. If you put OpenClaw behind nginx, Caddy, Tailscale, or another remote access layer, plan the auth and WebSocket path deliberately. Do not expose the Gateway casually to the public internet.

For small VPS sizing and browser automation memory trade-offs, use the hardware requirements guide before you choose a plan.

Verify the Install

Run these in order:

openclaw --version
openclaw doctor
openclaw gateway status
openclaw dashboard

You want:

• CLI is available.
• Doctor does not report blocking config or service issues.
• Gateway is running.
• Gateway is listening on port 18789.
• Dashboard opens.
• You can send a first message in the Control UI.

The official getting started guide uses the same flow: install, onboard, verify Gateway, open dashboard, send a message.

If the dashboard does not load after the Gateway is running, do not keep reinstalling. That is usually a browser, auth, WebSocket, bind address, or reverse proxy problem. Use the dashboard not loading guide instead.

What "Working" Looks Like

A working local setup should pass this sequence:

openclaw gateway status

Expected idea:

Gateway: running
URL: http://127.0.0.1:18789/

Then:

openclaw dashboard

Expected result:

• Browser opens the Control UI.
• Auth is accepted or prompted clearly.
• Chat input is usable.
• A basic message gets a response.

My rule: installation is not finished when npm install completes. Installation is finished when the Gateway is running and the dashboard can talk to it.

Common Install Errors and Fixes

Error: openclaw: command not found

Most likely cause: global package bin is not in your PATH.

Check:

npm prefix -g
echo "$PATH"

Fix:

export PATH="$(npm prefix -g)/bin:$PATH"

Add that line to ~/.zshrc, ~/.bashrc, or your shell's startup file, then open a new terminal.

Error: Node Version Too Old

Check:

node --version

You need Node 22.19+ at minimum. Node 24 is the recommended target.

If you installed with the official script, rerun the installer or check the Node setup docs. If you manage Node yourself, update through your normal tool: nvm, Homebrew, package manager, or Windows installer.

Error: Onboarding Starts, Then Gateway Does Not Run

Check:

openclaw doctor
openclaw gateway status
openclaw logs --follow

On Linux:

systemctl --user status openclaw-gateway

On macOS, check the LaunchAgent path if you installed the daemon:

~/Library/LaunchAgents/

Do not reset your config yet. First find out whether the service failed to install, failed to start, or started on a different port.

Error: Port 18789 Is Already in Use

Check:

lsof -i :18789

If something else owns the port, stop that process or configure OpenClaw to use another port. Then reopen the matching dashboard URL.

The subtle mistake is changing the port and continuing to use the old browser bookmark.

Error: Dashboard Opens, But Stays Disconnected

This is no longer an install problem.

Open DevTools, go to Network, filter by WS, and reload. If the WebSocket handshake fails, use the OpenClaw dashboard troubleshooting guide.

The common causes are:

• wrong token or password.
• stale browser session state.
• Gateway bound to the wrong interface.
• reverse proxy missing WebSocket upgrade headers.
• HTTPS page trying to use ws:// instead of wss://.
• origin not allowed.

Error: WSL2 Install Works, But Windows Browser Cannot Reach It

Start with:

openclaw dashboard
openclaw gateway status

If you are using WSL2 as a Linux Gateway, remember that Windows and WSL networking can behave differently depending on your Windows version and configuration.

The simplest reliable test is an SSH-style local forward or opening the URL printed by openclaw dashboard. If you manually use the WSL IP, confirm the Gateway is actually listening on an address Windows can reach.

Error: Docker Container Runs, But Dashboard Fails Remotely

First check local host access:

curl -i http://127.0.0.1:18789/

If local access works but the domain fails, the problem is your reverse proxy or remote access layer, not the install.

Check:

• nginx or Caddy WebSocket support.
• Upgrade and Connection headers.
• wss:// for HTTPS pages.
• Gateway auth mode.
• trusted proxy / Tailscale identity settings if used.

Again, use the dashboard troubleshooting guide for this layer.

Error: The VPS Runs Out of Memory

This one is usually hardware, not install.

2 GB can test. 4 GB is a better daily minimum. Browser automation, multiple channels, local models, and long-running agents need more.

If you are choosing a box, read OpenClaw hardware requirements before you resize blindly. RAM is normally the constraint.

Uninstall or Reset

Try a restart before a reset:

openclaw gateway restart
openclaw doctor
openclaw gateway status

If the CLI itself is broken:

npm uninstall -g openclaw

If you installed through the official script, use the official uninstall docs for your install path.

If you want to preserve data but rerun onboarding:

mv ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
openclaw onboard

If you want a full fresh state:

openclaw gateway stop
mv ~/.openclaw ~/.openclaw.backup
openclaw onboard --install-daemon

I would only do that after you have checked service status, logs, and the dashboard connection path. A reset is clean. It is also a good way to delete the evidence you needed.

Where to Go Next

If install succeeded but you are not sure your machine is enough, read OpenClaw hardware requirements before adding channels, browser automation, or local models.

If the Gateway runs but the browser dashboard does not connect, use OpenClaw dashboard not loading. That guide is specifically about ports, WebSockets, reverse proxies, auth, and browser storage.

If both are working, then you are past setup. Now connect a channel, configure a model provider, and test one real workflow.

At Macaron, we built for the moment after setup: turning a real task into a usable AI workflow without managing a Gateway, daemon, Node version, or dashboard port. If you want to test the workflow before committing to self-hosting, create a Macaron account and run one task end to end.

FAQ

Q: What is the fastest way to install OpenClaw now? Use the official installer script. macOS/Linux/WSL2 use curl -fsSL https://openclaw.ai/install.sh | bash; Windows PowerShell uses iwr -useb https://openclaw.ai/install.ps1 | iex.

Q: Do I need Node 22 or Node 24? Current docs recommend Node 24. Node 22.19+ is still supported. Older Node 22 builds and Node 21 or below are where strange syntax/runtime failures start.

Q: Is Windows supported? Yes, current docs list native Windows paths through the Windows Hub and PowerShell installer, plus WSL2 Gateway for people who want the Linux environment.

Q: Should beginners use Docker? Usually no. Use the installer first. Docker is better when you need isolation, repeatable server deployment, or a VPS/container workflow.

Q: How do I know installation is actually finished? openclaw --version, openclaw doctor, openclaw gateway status, and openclaw dashboard should all work. The final proof is sending a message in the dashboard and getting a response.

Q: Gateway is running, but the dashboard will not load. Is that an install failure? Usually not. Treat it as a dashboard connectivity problem: port, bind address, auth, browser storage, WebSocket, TLS, or reverse proxy. Use the dashboard troubleshooting article.

Q: How much RAM do I need? 2 GB can test, 4 GB is a safer daily floor, and 8 GB+ is better if you use browser automation or multiple channels. For local models, read the hardware requirements article first.

Internal Link Updates for the Other Two Pages

Add these short reciprocal links so the cluster is genuinely bidirectional:

On /blog/openclaw-hardware-requirements near the first requirements table: Once you pick the machine, use the OpenClaw install guide for the current installer commands, Node requirement, and first verification checks.

On /blog/openclaw-dashboard-not-loading near the opening diagnostic section: If you have not completed the base setup yet, start with the OpenClaw install guide first, then come back here once openclaw gateway status shows the Gateway running.