How to install OpenClaw: step-by-step setup guide
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 configurelets you come back later for more settings, andopenclaw onboard --classicopens 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.