How to install OpenClaw: step-by-step setup guide

Checked against official sources ยท 2026-11-19

This guide walks through installing OpenClaw on macOS, Linux and Windows, running onboarding, and keeping the Gateway running in the background. Everything below follows the official install and getting-started docs.

System requirements

  • Node.js: Node 26 is recommended. Supported versions are 24.16.0+ on the 24.x line, or 26.1.0+. The docs strongly recommend 24.22.1+ or 26.12.1+ for security fixes. When Node is missing, the installer provisions Node 26 on macOS and Node 24 LTS on Linux.
  • Operating system: macOS, Linux or Windows.
  • pnpm is only needed if you build from source.
  • AI access: an existing Claude Code or Codex CLI login, or a provider API key.

Check your Node version first:

node --version

Option 1: the installer script (recommended)

This is the fastest route. The script detects your OS, installs Node if needed, installs OpenClaw and launches onboarding.

macOS, Linux or WSL2:

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

Windows (PowerShell):

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

To install without starting onboarding on macOS, Linux or WSL2:

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

Option 2: try it with one command

If you just want to try OpenClaw, the docs offer a one-line start:

npx openclaw@latest

On a fresh install choose Quick start. If you answer yes to "Keep OpenClaw running in the background?", it installs a copy under ~/.openclaw and runs the Gateway as a background service, so clearing the npx cache does not stop it.

Option 3: npm, pnpm or bun

Use these if you already manage Node yourself.

npm 12 or npm 11.16+:

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

On npm 11.15 and earlier, run the same install command without --allow-scripts=openclaw. npm 12 blocks unapproved package lifecycle scripts by default, and this flag allows OpenClaw's preinstall and postinstall steps.

pnpm:

pnpm add -g --allow-build=openclaw openclaw@latest
openclaw onboard --install-daemon

bun:

bun add -g --trust openclaw@latest
bun run --bun openclaw onboard --install-daemon --daemon-runtime bun

The docs note that Node remains the primary runtime; Bun 1.4.4 or newer can also run the CLI, local agent and Gateway.

Option 4: build from source

For contributors, the docs describe cloning the repository, enabling Corepack, then running pnpm install && pnpm build && pnpm ui:build and linking the CLI with pnpm add --global "openclaw@link:$PWD". Docker, Podman, Nix and Ansible installs are documented separately on docs.openclaw.ai.

Run onboarding

The installer starts the onboarding wizard automatically:

  • Quick start reuses AI access it detects (a Claude Code or Codex CLI login, or an API key), verifies it with a real completion, saves the config and opens the web dashboard.
  • Custom setup walks through all guided options.
  • openclaw configure lets you come back later for more settings, and openclaw onboard --classic opens the classic step-by-step wizard.

Keep the Gateway running in the background

If you did not accept the background option during Quick start, stop the foreground Gateway with Ctrl+C and install the service:

openclaw gateway install
openclaw gateway start

This installs a LaunchAgent on macOS, a systemd user unit on Linux and WSL2, or a Scheduled Task on native Windows. gateway start waits until the Gateway passes its health and readiness checks.

Verify the install

openclaw --version
openclaw doctor
openclaw gateway status

According to the getting-started docs, a healthy Gateway listens on port 18789. Then open the Control UI and send a message:

openclaw dashboard

Is OpenClaw safe to run?

According to the official Gateway security docs, OpenClaw ships with conservative defaults:

  • The Gateway binds to loopback on a regular host install, so it is not reachable from other machines unless you change that. Container images are the exception: they default to an exposed bind, which the docs say to pair with authentication.
  • Unknown senders get a pairing code. Most chat channels answer a direct message from an unknown sender with a pairing code instead of processing it, and group access is allowlisted, usually behind a mention gate.
  • One trust boundary per Gateway. The docs say OpenClaw is not a security boundary between users who distrust each other. For mixed-trust use, run separate Gateways and credentials, ideally on separate OS users or hosts.
  • Cross-conversation messaging is on by default for agents with message-tool access; you can restrict it if your setup needs that.

Check your own setup with one command:

openclaw security audit

The security docs also cover hardened baseline configs, allowlists, prompt injection, tool and agent permissions, sandboxing, network exposure and where secrets are stored on disk. If you want stricter isolation out of the box, our OpenClaw alternatives comparison shows options such as NanoClaw, which runs each agent in its own container.

Connect a chat app

To chat from your phone, connect a channel. The docs call Telegram the fastest channel to set up, since it only needs a bot token. Discord, Slack, WhatsApp, Signal, iMessage and others have their own setup guides in the official channel docs.

Troubleshooting: "openclaw: command not found"

The docs say this is almost always a PATH issue: npm's global bin directory is not on your shell's PATH. Check these three things:

node -v
npm prefix -g
echo "$PATH"

If the global bin directory from npm prefix -g is missing from your PATH, add it in your shell profile and open a new terminal.

Troubleshooting: npm says install scripts were blocked

npm 12 blocks unapproved package lifecycle scripts by default. Re-run the install with the flag the official docs give:

npm install -g openclaw@latest --allow-scripts=openclaw

On npm 11.15 and earlier, leave the flag out. The docs also note that npm approve-scripts openclaw does not work for a global install. With pnpm, use --allow-build=openclaw on the pnpm add -g command.

Troubleshooting: the Gateway is not running

Run the built-in checks in this order:

openclaw doctor
openclaw gateway status
openclaw gateway start

openclaw doctor checks for config issues, gateway status shows whether the Gateway is up (it listens on port 18789), and gateway start waits until the Gateway passes its health and readiness checks.

Windows: native app, PowerShell or WSL2?

The official docs recommend the native Windows Hub companion app for desktop use; it includes setup, tray status and chat. The PowerShell installer and a Gateway inside WSL2 are also supported. Pick WSL2 if you already work in a Linux shell.

Keeping OpenClaw up to date

The install docs say you can switch between the stable package and a git checkout with openclaw update --channel stable and openclaw update --channel dev. The installer script also accepts --install-method git --version main to install from the main branch.

Where to go next

Not sure OpenClaw is the right pick? Compare it with Hermes Agent, Grok Bot, Alma and others in our OpenClaw alternatives table.

Frequently asked questions

What is the fastest way to install OpenClaw?
Run the official installer script: curl -fsSL https://openclaw.ai/install.sh | bash on macOS, Linux or WSL2, or iwr -useb https://openclaw.ai/install.ps1 | iex in Windows PowerShell. It installs Node if needed and starts onboarding.
Is OpenClaw safe to install?
Per the official security docs, a normal install binds the Gateway to loopback and makes unknown chat senders pair first. Run openclaw security audit to check your setup, and do not expose the Gateway beyond loopback without authentication.
What Node.js version does OpenClaw need?
The official docs recommend Node 26. Supported versions are 24.16.0+ on the 24.x line or 26.1.0+, with 24.22.1+ or 26.12.1+ strongly recommended for security fixes.
Why does npm block the OpenClaw install scripts?
npm 12 blocks unapproved package lifecycle scripts by default. Add --allow-scripts=openclaw on npm 12 or npm 11.16+. On npm 11.15 and earlier, leave the flag out.
Which port does the OpenClaw Gateway use?
According to the getting-started docs, a running Gateway listens on port 18789. Check it with openclaw gateway status.