Skip to main content

Installation

OpenClaw runs on macOS, Linux (including 64-bit Raspberry Pi) and Windows. Pick one method below. The official reference is docs.openclaw.ai/install.

Still deciding where to run it? See Choosing Your Setup.

Prerequisites​

  • Node.js 24.16+ or 26.1+ (Node 26 recommended). Node 22, 23 and 25 are unsupported since v2026.9.3 (Node.js requirements). The installer script provisions a supported Node for you if it is missing.
  • An AI provider: an existing Claude Code or Codex CLI login, a provider API key (Anthropic, OpenAI, OpenRouter, Google, xAI and many others), or a local model server. Onboarding can detect and reuse what you have.
  • pnpm only if you build from source.

macOS, Linux and WSL2:

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

Windows (PowerShell):

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

The script detects your OS, installs Node if needed, installs the openclaw package and starts onboarding. To install without onboarding:

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

To keep OpenClaw and its own Node under a local prefix (no system Node), use https://openclaw.ai/install-cli.sh instead. All installer flags are in Installer internals.

Method 2: npm, pnpm or Bun​

If you already manage Node yourself. With npm 12 or 11.16+:

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

npm 12 blocks package lifecycle scripts unless you allow them, so --allow-scripts=openclaw is required there. On npm 11.15 and earlier, drop the flag.

pnpm:

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

Bun 1.4+ works too (Node stays the primary runtime): see Bun.

Permission errors on npm install -g

Do not use sudo npm. Point npm's global prefix at a directory you own (for example npm config set prefix ~/.npm-global and add ~/.npm-global/bin to PATH), or use the installer script. See Node setup.

Method 3: Desktop apps​

  • Windows: the native Windows Hub is the recommended desktop path: a signed installer with setup, tray status, chat and node mode. Download it from the Windows Hub releases (x64 and Arm64). Details: Windows.
  • macOS: download OpenClaw-<version>.dmg from GitHub releases and launch OpenClaw.app (menu bar app). Details: macOS.
  • iOS and Android: official companion apps on the App Store and Google Play. They pair with a running Gateway; they do not replace it. See Platforms.

Both desktop apps can set up a local Gateway on first run or connect to a remote one.

Changing in 2026.10.10 (beta)

2026.10.10-beta.1 (npm beta, 2026-10-15; not in 2026.10.4) requires macOS 26.2, iOS 26.2 and Safari 26.2 or newer for the native apps and the Control UI (PR #168595). 2026.10.4's macOS app needs macOS 15.0 or later. If a Mac, iPhone or iPad you use cannot update to 26.2, stay on 2026.10.4 for the apps, or use the Control UI from another browser.

Method 4: Docker​

Use Docker for a headless server or an isolated Gateway. The supported path is the setup script in the repo, which builds or pulls the image, runs onboarding, writes a Gateway token to .env and starts Docker Compose:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

Then open http://127.0.0.1:18789/ and paste the token from .env. Full guide: Docker.

If you write your own docker run or Compose file, get these right:

  • State lives at /home/node/.openclaw inside the container (the image runs as user node). Mount your volume there, not at /root/.openclaw, or nothing persists.
  • Publish on loopback: -p 127.0.0.1:18789:18789, not -p 18789:18789, which exposes the Gateway on every host interface. Reach it remotely through an SSH tunnel or Tailscale.
  • Set a token: pass OPENCLAW_GATEWAY_TOKEN. Inside a container the Gateway must bind beyond loopback (--bind lan) to receive traffic, and it refuses to do that without auth.
  • Health checks: the image's built-in HEALTHCHECK uses /healthz. /readyz is the deeper, channel-aware probe.
  • Use only ghcr.io/openclaw/openclaw or the Docker Hub mirror openclaw/openclaw.

The container entrypoint runs openclaw doctor --fix --non-interactive against the mounted state each time the Gateway container starts, so an image upgrade migrates state before the Gateway runs. Podman, Nix, Kubernetes, Ansible and cloud recipes are listed on the install index; see also Deployment Options.

Method 5: From source (developers)​

git clone https://github.com/openclaw/openclaw.git
cd openclaw
corepack enable
pnpm install && pnpm build && pnpm ui:build
pnpm add --global "openclaw@link:$PWD"
openclaw onboard --install-daemon

pnpm ui:build builds the Control UI; skip it and the dashboard will not load. Development workflow: Setup.

Raspberry Pi​

Pi 4 or 5 with 2 GB+ RAM and 64-bit Raspberry Pi OS works well as an always-on Gateway (models run in the cloud). Use the installer script as in Method 1. Follow the Raspberry Pi guide for swap and SD-card tips. 32-bit OS images are not supported.

Post-install setup​

The installer script starts onboarding for you. Otherwise run:

openclaw onboard --install-daemon

Onboarding checks your model access with a real request, creates the workspace (~/.openclaw/workspace) and ~/.openclaw/openclaw.json with a generated Gateway token, and with --install-daemon installs the Gateway as a service (LaunchAgent on macOS, systemd user service on Linux and WSL2, Scheduled Task on Windows). The Quick Start walks through it. Without --install-daemon, install the service later with openclaw gateway install.

Change settings afterwards with openclaw configure; add channels with openclaw channels add. Reference: Onboarding (CLI).

Verify installation​

openclaw --version        # CLI is on PATH
openclaw doctor           # config and environment checks
openclaw gateway status   # service running, RPC probe OK
openclaw dashboard        # opens the Control UI with your token

Send a message in the Control UI chat. If you get a reply, the install works. For a one-shot test from the terminal:

openclaw agent --agent main --message "Hello, what can you do?"

If something fails, openclaw triage collects sanitized diagnostics and suggests fixes.

Updating​

openclaw update

openclaw update works for npm, pnpm and git installs. It runs openclaw doctor afterwards, migrates config, and rolls back automatically on failure only when no schema migration ran. Prefer it over npm update -g, which skips those steps. Useful options:

openclaw update --dry-run                    # preview
openclaw update status                       # current channel and version
openclaw update --channel extended-stable    # monthly supported line

Desktop apps update through their own updaters, and Docker installs update by replacing the image. See Updating.

danger

Update promptly. OpenClaw publishes security fixes often (see Known Vulnerabilities). Running an old version exposes you to published exploits.

Uninstalling​

openclaw uninstall --dry-run --all   # preview what would be removed
openclaw uninstall                   # interactive; preselects the Gateway service
openclaw uninstall --all             # service + state + workspace + app

Then remove the CLI itself, for example npm uninstall -g openclaw.

warning

--state keeps your workspace unless you also pass --workspace. Deleting ~/.openclaw by hand removes everything, including ~/.openclaw/workspace (your memory, SOUL.md and skills). Back up first with openclaw backup create. See Uninstall.

Next steps​