OpenClaw Interactive Guide | Nice Spaceship

Mission Steps

00 Prerequisites 01 Install 02 Configure 03 Verify 04 Troubleshooting 05 What's Next

Guide Active

SYS::GUIDE · MACOS + WINDOWS · OPEN CLAW · V1.0

Install OpenClaw on
Mac & Windows

Deploy a self-hosted AI agent on your machine in minutes. Choose your OS, follow the steps, and you'll have an always-on digital operator running locally.

~5-10 min

Install Time

Command

Node 22+

Runtime

2 OS

Supported

00 · Prerequisites

Before You Begin

OpenClaw needs a few things in place on your Mac. The installer handles most automatically.



Apple Silicon Mac

M1, M2, M3, or M4. Intel Macs have limited support.

Required

🔌

macOS Up to Date

System Settings → General → Software Update.

Required

🔐

API Key

From a supported LLM provider (e.g., Anthropic).

Required

⚙️

Xcode CLI Tools

Needed for Node.js and dependencies. Step 1 below.

Auto-installed

WSL2 gives you a full Linux environment on Windows — the most stable way to run OpenClaw.

💻

Windows 10/11

Fully updated via Settings → Windows Update.

Required

🧛

WSL2 + Ubuntu

We'll install it in Step 1 if you don't have it.

Recommended

🔐

API Key

From a supported LLM provider (e.g., Anthropic).

Required

📦

Git

Installed automatically via apt inside WSL.

Auto-installed

The native PowerShell path works but is less tested. Proceed if you prefer to stay in Windows natively.

💻

Windows 10/11

Fully updated via Settings → Windows Update.

Required

📦

Git for Windows

Install via Chocolatey or direct download.

Required

🔐

API Key

From a supported LLM provider (e.g., Anthropic).

Required

🔨

Build Tools

C++ toolchain for native npm modules. Step 2 below.

Step 2

⚠ Less Tested

The OpenClaw developers recommend WSL2 for better stability and compatibility.

⚠ Security Warning

OpenClaw runs with broad system permissions — it can read files, execute commands, and modify your system. Do not install on your primary machine with sensitive data. Use a dedicated device, VM, or VPS.

01 · Installation

Deploy OpenClaw

Three steps: Xcode CLI tools, optional Homebrew, and the one-liner.

Install Xcode Command Line Tools

Open Terminal and run:

Terminal

xcode-select --install

Click Install in the dialog and wait for it to finish.

Install Homebrew (if needed)

Check with brew --version. If not installed:

Terminal

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

Run the OpenClaw Installer

One command — downloads the CLI, installs Node.js if needed, and launches onboarding.

🚀 Main Install Command

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

Alternative: Install via npm▼

Terminal

# Install globally via npm
npm install -g openclaw@latest

# Run onboarding with daemon
openclaw onboard --install-daemon

Fix: sharp build errors▼

If libvips is installed globally and sharp fails:

Terminal

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

Install WSL2, enable systemd, get Node.js, then run the one-liner inside Ubuntu.

Install WSL2

Open PowerShell as Administrator:

PowerShell (Admin)

wsl --install

Restart your computer. After reboot, Ubuntu opens — create a username and password.

💡 Already have WSL?

Check version: wsl --list --verbose. If VERSION shows 1, upgrade: wsl --set-version Ubuntu 2.

Enable systemd

Inside your WSL Ubuntu terminal:

WSL / Ubuntu

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

Then in PowerShell: wsl --shutdown and reopen Ubuntu.

Install Node.js 22+

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

# Verify
node -v  # Should show v22.x.x+

Run the OpenClaw Installer

🚀 Main Install Command

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

Alternative: Install via npm▼

WSL / Ubuntu

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

Install dependencies, then run the PowerShell one-liner.

Install Git & Node.js

Via Chocolatey or direct downloads.

PowerShell (Admin)

# Install Chocolatey (if needed)
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install Git and Node.js
choco install git nodejs --version=22.0.0 -y

Close and reopen PowerShell so PATH updates take effect.

Install Build Tools

PowerShell (Admin)

npm install -g windows-build-tools

💡 Alternative

Install Visual Studio Build Tools with "Desktop development with C++".

Run the OpenClaw Installer

🚀 PowerShell Install

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

Alternative: Install via npm▼

PowerShell

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

02 · Configuration

Onboarding Wizard

After the installer finishes, the wizard guides you through setup. These prompts are the same on every platform.

Security Acknowledgment

Select "I understand this is powerful and inherently risky".

Choose Local vs. Remote

Select "This Mac" or "QuickStart" for a local-only Gateway.

Select Your LLM

Choose your AI model and paste your API key when prompted (e.g., from console.anthropic.com).

💡 Tip

You can also use a local model via Ollama. The wizard detects it automatically.

Gateway Settings

Accept defaults. Default port is 18989.

Channel Setup (Optional)

Connect WhatsApp, Telegram, Discord, Slack, or iMessage (macOS only). Or skip and use the browser Control UI.

🔒 Channel Safety

If you connect WhatsApp, use a dedicated number — not your personal one.

Install the Daemon

Select Yes so OpenClaw auto-starts on boot.

If you skipped this

openclaw onboard --install-daemon

03 · Verification

Confirm It's Running

Three quick commands to validate your deployment.

Terminal / PowerShell
# Check for config issues
openclaw doctor

# Confirm gateway is running
openclaw status

# Open browser Control UI
openclaw dashboard

Dashboard opens at http://127.0.0.1:18789/. If it prompts for auth:

Get Auth Token

openclaw config get gateway.token

🔒 Security

The Control UI is an admin surface. Never expose it publicly. Keep on localhost or behind a VPN.

✅ Verification Checklist

openclaw doctor — no critical errors

openclaw status — Gateway running

Control UI loads at 127.0.0.1:18789

Test message sends successfully

04 · Troubleshooting

Common Issues

Mac-specific problems and fixes.

"openclaw: command not found"▼

npm's global bin isn't in your PATH:

Terminal
npm prefix -g
echo "$PATH"

# Fix — add to ~/.zshrc
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Node.js version too old▼

Terminal

node -v
brew install node@22

Gateway disconnected / Menu bar offline▼

Terminal
openclaw gateway   # foreground debug
openclaw status    # check service

Microphone / iMessage permissions denied▼

System Settings → Privacy & Security → enable permissions for OpenClaw.

WSL-specific problems and fixes.

"openclaw: command not found"▼

WSL / Ubuntu

npm prefix -g
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Dashboard not loading from Windows▼

WSL / Ubuntu

hostname -I  # e.g. 172.22.5.3

Open http://[that-IP]:18789/. For firewall:

PowerShell (Admin)

netsh advfirewall firewall add rule name="OpenClaw" dir=in action=allow protocol=TCP localport=18789

Port 18789 already in use▼

WSL / Ubuntu

sudo lsof -i :18789
kill [PID]

Native Windows problems and fixes.

"openclaw" not recognized▼

PowerShell

npm prefix -g

# Add to PATH permanently
$npmPath = npm prefix -g
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$npmPath", "User")

Close and reopen PowerShell.

Git "spawn git ENOENT" errors▼

PowerShell (Admin)

choco install git -y
# Restart PowerShell, then retry
npm install -g openclaw@latest

Port 18789 already in use▼

PowerShell (Admin)

netstat -ano | findstr :18789
taskkill /PID [PID_NUMBER] /F

05 · What's Next

You're Operational

OpenClaw is live. Here's where to go from here.

💬

Connect Channels

Link WhatsApp, Telegram, Discord, Slack, or iMessage (macOS) to chat from anywhere.

🧰

Install Skills

Extend capabilities — file management, browsing, code execution. Vet plugins carefully.

🎨

Companion Apps

macOS menu bar app or Windows Terminal for a better CLI experience.

📚

Read the Docs

Multi-agent routing, workspace isolation, Docker, and advanced config.

Commands Reference
# Health check
openclaw doctor

# Gateway status
openclaw status

# Open Control UI
openclaw dashboard

# Update
npm update -g openclaw

# Connect channels
openclaw channels login

# Restart gateway
openclaw gateway restart

# View config
cat ~/.openclaw/openclaw.json

# Follow logs
openclaw logs --follow

Mission Steps

Install OpenClaw onMac & Windows

Before You Begin

Apple Silicon Mac

macOS Up to Date

API Key

Xcode CLI Tools

Windows 10/11

WSL2 + Ubuntu

API Key

Git

Windows 10/11

Git for Windows

API Key

Build Tools

Deploy OpenClaw

Install Xcode Command Line Tools

Install Homebrew (if needed)

Run the OpenClaw Installer

Install WSL2

Enable systemd

Install Node.js 22+

Run the OpenClaw Installer

Install Git & Node.js

Install Build Tools

Run the OpenClaw Installer

Onboarding Wizard

Security Acknowledgment

Choose Local vs. Remote

Select Your LLM

Gateway Settings

Channel Setup (Optional)

Install the Daemon

Confirm It's Running

✅ Verification Checklist

Common Issues

You're Operational

Connect Channels

Install Skills

Companion Apps

Read the Docs

Install OpenClaw on
Mac & Windows