OpenClaw Setup Guide: Install, Configure, and Run Your Gateway

OpenClaw is a self-hosted assistant gateway you run on your own machine (or server). Once it’s installed, you can finish onboarding, connect your preferred chat channels, and keep your personal customization in a workspace that won’t break when you update.

This guide walks you through a clean install + first-time setup, plus the most common fixes when something doesn’t work.

What you need before you start

OpenClaw’s official install path expects:

Node.js 22+ (the installer can install it if missing)
macOS / Linux / Windows
pnpm only if you build from source
On Windows, WSL2 is strongly recommended for the smoothest experience.

Option A (recommended): Install OpenClaw using the installer script

This is the quickest and most reliable route because it handles Node detection, installs the CLI, and runs onboarding in one go.

macOS / Linux / WSL2

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

Windows (PowerShell)

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

Want to install without onboarding?

If you prefer to run onboarding later:

macOS / Linux / WSL2

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

Windows (PowerShell)

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

Option B: Install via npm (if you already have Node 22+)

If you want full control (and you already manage Node yourself):

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

If you hit “sharp” build errors (common on macOS)

If sharp fails because of global libvips, you can force prebuilt binaries:

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

Option C: Build OpenClaw from source (for contributors)

Use this if you’re planning to modify OpenClaw or run from a local repo checkout:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build

Then make the CLI available globally:

pnpm link --global

Finally, run onboarding:

openclaw onboard --install-daemon

Verify your install (do this before anything else)

After installation, confirm everything is healthy:

openclaw doctor
openclaw status
openclaw dashboard

doctor checks for config issues
status shows gateway status
dashboard opens the browser UI

First-time setup: create your workspace + config the safe way

To keep updates painless, OpenClaw recommends keeping your personal customization outside the repo:

Workspace: ~/.openclaw/workspace
Config: ~/.openclaw/openclaw.json

Bootstrap everything once:

openclaw setup

This is the “set it up once, customize forever” step.

Connect your channels (WhatsApp / Telegram / Discord / etc.)

After setup, connect the channels you want your assistant to respond on.

A common flow is:

openclaw channels login
openclaw health

channels login links your messaging surfaces
health is a quick sanity check that the gateway and connections work

If onboarding isn’t available in your build, the docs recommend doing: openclaw setup → openclaw channels login → start the gateway manually.

When you need to start the Gateway manually

In some setups (or dev workflows) you may want to run the gateway directly:

openclaw gateway

(Used as a manual “bring it up” command when the app isn’t managing it.)

Dev workflow (hot reload gateway)

If you’re working from source, you can run the gateway in watch mode:

pnpm gateway:watch

Where OpenClaw stores data (so you know what to back up)

OpenClaw keeps user state under ~/.openclaw/ and calls out paths like:

Credentials and channel auth under ~/.openclaw/credentials/…
Session transcripts stored on disk under ~/.openclaw/agents/<agentId>/sessions/*.jsonl

If you’re migrating machines, backing up ~/.openclaw/ (carefully) is usually the “don’t lose everything” folder.

Security setup you should do early (especially if you connect chat apps)

OpenClaw can execute tools that read/write files, run commands, and send messages—so treat it like a powerful local agent, not a harmless chatbot.

Run the built-in security audit

OpenClaw includes an audit command that checks for common security foot-guns and can optionally apply fixes:

openclaw security audit
openclaw security audit --deep
openclaw security audit --fix

Consider sandboxing tool execution (recommended for safer experimentation)

OpenClaw can run tool execution inside Docker containers to reduce blast radius (optional, config-controlled).

Also: treat skill folders as trusted code—restrict who can modify them.

Troubleshooting (fast fixes)

“openclaw: command not found”

Use the docs’ “After install” checks first (openclaw doctor) and confirm your terminal session sees the installed global binary.

Windows issues

If you’re on Windows and things feel flaky, follow the recommendation to run OpenClaw under WSL2. It’s the most consistent path.

Install succeeds but onboarding doesn’t appear

Run:

openclaw setup
openclaw channels login
openclaw gateway

That’s the documented fallback flow.

Recommended “clean setup” checklist

If you want the shortest path that avoids 90% of future headaches:

Install via the installer script (Option A)
Verify with openclaw doctor + openclaw status
Run openclaw setup to generate workspace/config
Connect channels: openclaw channels login
Sanity check: openclaw health
Run openclaw security audit and fix anything obvious