Skip to content

Alternative Installation Methods: Desktop App, Docker, and npm ​

The previous lesson got the main path working with the official installer; but OpenClaw download and installation doesn't stop there — your work computer won't let you run scripts, you want a desktop App sitting in the tray, you need containerization on a server, or you manage Node yourself and don't want the installer to do it for you. This lesson covers all four alternative routes at once — desktop app, Docker, npm / pnpm / Bun direct installation, and building from source — so that after 8 minutes you can pick one based on your scenario. This page is based on v2026.10.9.

What You'll Be Able to Do After This Lesson ​

  • Download and install Windows Hub (x64 / ARM64 signed installers) or the macOS menu bar app — a way to download OpenClaw without ever touching a terminal
  • Run a containerized Gateway with Docker: the setup script automatically completes onboarding, and you open the Control UI in a browser on port 18789
  • Install OpenClaw directly with all three package managers — npm / pnpm / Bun — and remember the one required parameter for each
  • Install by building from source and link the openclaw CLI to your own checkout
  • Use a comparison table to pick your route based on your scenario (desktop / Docker / direct install / source)

Your Current Situation ​

  • Your work computer won't let you run scripts like curl | bash, and you want a proper installer you can double-click
  • I'm a Windows / macOS desktop user and just want an App sitting in the tray or menu bar — no terminal
  • You need to run 7×24 containerized on a server, or you manage Node yourself — the installer's "auto-install Node" approach actually gets in the way

When to Use This Approach ​

When you need:

  • A graphical way to download and install OpenClaw (desktop app)
  • An isolated, disposable Gateway environment that doesn't pollute your machine (Docker)
  • To install with your own package manager (npm / pnpm / Bun), or to run the latest main branch directly (building from source)

And you don't want:

  • To go through the curl | bash official installer main path from the previous lesson again
  • To install a Node runtime on your system (the desktop app and Docker both bundle their own runtime)

🎒 Prerequisites ​

  • You've gone through Installation: Get OpenClaw running in 5 minutes — this page is its alternative-route supplement; if the main path works for you, there's no need to switch
  • Prepare your environment for the route you plan to take (see the table below)
  • Have a "model pass" ready: the desktop App's first run, Docker setup, and openclaw onboard will all guide you through configuring model credentials (Claude Code / Codex CLI login or API Key — see Model Connection Overview for details)

Environment Requirements for Each Route ​

RouteWhat You Need First
Desktop appJust being able to download the installer: Windows 10 20H2+ / Windows 11 (Hub), macOS 26.2 (Tahoe)+ (menu bar App)
DockerDocker Desktop or Docker Engine + Docker Compose v2; at least 6 GB of memory to build the image locally
npm / pnpm / Bun direct installNode 24.16.0+ (24.x) or 26.1.0+ (24.22.1+ / 26.12.1+ recommended); the Bun route requires Bun 1.4.4+
Building from sourceNode + Corepack (or a self-installed pnpm 12) + git

⚠️ Networks in mainland China

The official documentation does not provide a domestic mirror or download acceleration solution, and this article will not guess at mirror addresses. If downloading the desktop installer from GitHub Releases or pulling the image from GHCR times out, check your network environment first and then retry; if it keeps failing, go to What to do if installation fails to troubleshoot step by step.

Core idea ​

Every installation method installs the same thing: one Gateway process + openclaw CLI + one copy of the configuration. The four alternative routes differ only in "where the Gateway runs and who manages the runtime":

RouteWhere the Gateway runsRuntimeWho it's for
Official installer (main path in the previous lesson)Local background serviceInstaller auto-installs Node if missingThose who want to get running fastest
Desktop appConfigures a local Gateway on first run of the app, or connects to an existing remote GatewayApp manages its own runtime, no dependency on system NodeDesktop users who don't want to touch the terminal
Docker / PodmanInside a containerBundled in the imageIsolated environments, servers, no local installation
npm / pnpm / Bun direct installLocal machine (--install-daemon installed as a service)You manage it yourselfDevelopers, bulk installs in CI
Build from sourceLocal machineYou manage it yourself + pnpmContributors, those who need the latest main

The four routes are independent of each other; just pick one for your scenario. The steps below are numbered continuously for easy cross-referencing.

Follow along ​

Step 1: Download the OpenClaw desktop version — the Windows Hub and the macOS menu bar app ​

Why: The desktop apps are the official OpenClaw download method for users who "don't touch the terminal" — download the installer and follow a graphical setup wizard. The two native desktop apps, Windows Hub and the macOS menu bar app, can both configure a local Gateway during first-run setup, or connect directly to an existing remote Gateway.

Windows users: Windows Hub (officially recommended) ​

On Windows, the official recommendation is Windows Hub — a native WinUI companion app covering Windows 10 20H2+ and Windows 11, installs without administrator privileges, with signed installers for both x64 and ARM64:

After downloading and installing, launch OpenClaw Companion from the Start menu or system tray (the installer also adds shortcuts for Gateway Setup, Chat, Settings, check for updates, and uninstall). If no usable Gateway is found on first launch, it automatically enters setup: the fastest path is Set up locally — it creates an app-managed OpenClawGateway WSL distribution, installs the Gateway into it, and completes pairing, without touching your existing Ubuntu distribution. If you already have a Gateway, choose Advanced setup, which can connect to a Gateway on the local machine, in WSL, on a remote host (URL + token), or via an SSH tunnel.

You should see: after setup completes, the tray icon turns green; open Command Center from the tray and confirm that connection, pairing, node status, and channel health are all normal.

💡 Direct link 404'd out?

Windows Hub's release cadence is independent of OpenClaw CLI and Gateway. When the direct links above stop working, go to the Windows Hub releases page and open the latest stable release. For details, see the official Windows platform documentation.

Windows alternative: the cross-platform Tauri desktop app — the OpenClaw-<version>-windows-x86_64.exe installer ships with OpenClaw official releases (GitHub Releases); it can use its built-in Bun to set up a local Windows Gateway, or connect to a remote Gateway.

macOS users: the menu bar app ​

The macOS desktop version is a menu bar companion app: download OpenClaw GitHub Releases OpenClaw-<version>.dmg (preferred) or .zip, then install and launch OpenClaw.app.

System requirements: macOS 26.2 (Tahoe) or later.

You should see: on first launch after a fresh install, a progress window appears — the app prepares its bundled runtime, starts the Gateway on "This Mac", and opens the dashboard's onboarding dialog; once ready, the window closes automatically. Afterwards, the OpenClaw icon stays in the menu bar, and Quick Chat is summoned by default with ⌥Space.

💡 Latest release has no macOS package?

Some releases only include the CLI or Windows assets. Official guidance: use the latest version that includes a macOS package — the official macOS app page currently pins the three DMGs for 2026.10.3 (Apple Silicon / Intel / Universal); for details, see the official macOS app documentation.

  • Desktop app launched: the Windows tray icon turns green, or the OpenClaw icon appears in the macOS menu bar

Step 2: Run a containerized Gateway with Docker ​

Why: The official positioning of the OpenClaw Docker route is "optional" — it suits cases where you want an isolated, disposable Gateway environment, or a host that does no local installation. For everyday use on your own dev machine, the official recommendation is the normal installation flow (previous lesson).

First, get the prerequisites ready:

  • Docker Desktop (or Docker Engine) + Docker Compose v2
  • At least 6 GB of memory to build the image locally from source — you can avoid this by using the official prebuilt image
  • Enough disk space for the image and logs

Then four commands (the setup script must be run from the repository root, so clone it first):

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

OPENCLAW_IMAGE points to the official pre-built image (GitHub Container Registry is the primary release channel, package page); if unset, the script builds openclaw:local locally. The same Release also publishes the image openclaw/openclaw on Docker Hub. The officials explicitly warn: use only these two official addresses and avoid third-party mirrors—their release cadence and retention policies are not kept in sync. To pin a version, use a specific version tag (e.g. 2026.9.3); variants include slim, -browser (with bundled Chromium), etc., and the default image bundles the codex and diagnostics-otel plugins.

You should see: setup completes onboarding automatically—prompting for a provider API Key → generating a Gateway token written into .env → starting the Gateway via Docker Compose.

Open the Control UI: visit http://127.0.0.1:18789/ in your browser and paste the token from .env into Settings. If you forget the address, retrieve it again:

bash
docker compose run --rm openclaw-cli dashboard --no-open

Container health check (no auth required; the image's built-in HEALTHCHECK hits exactly this):

bash
curl -fsS http://127.0.0.1:18789/healthz

You should see: healthz returns normally; /startupz (startup check) and /readyz (deep readiness) are also on the same port.

  • curl http://127.0.0.1:18789/healthz returns normally, and the Control UI can be logged into with the token in .env

💡 Want to run 7×24 on a server?

This step only walks you through running the containerized Gateway. For VPS selection, Compose operations, and security rules for public exposure (including the Docker DOCKER-USER firewall chain), see Server Deployment: Running 7×24 on Docker/VPS and Security Hardening (Part 1).

Step 3: Direct install via npm / pnpm / Bun ​

Why: developers who manage Node themselves don't need an installer to do it for them—OpenClaw an npm install (same for pnpm / Bun) finishes in one command, then run onboarding to install the Gateway as a background service. This is also the standard path on CI / bulk machines.

Prerequisites: Node 24.16.0+ (24.x) or 26.1.0+ (officials strongly recommend 24.22.1+ / 26.12.1+). Verify first with node --version.

Option A: npm (npm 12 or 11.16+) ​

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

npm 11.15 and earlier: drop --allow-scripts=openclaw (that version has neither this policy nor this option).

Why include --allow-scripts: npm 12 blocks unapproved package lifecycle scripts by default, so without it OpenClaw's preinstall / postinstall will be reported as blocked because they are not covered by allowScripts. npm 11.16 accepts this option but only warns and still executes.

Option B: pnpm ​

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

pnpm requires explicit approval for packages with build scripts, and approve-builds -g doesn't support global installs—so put --allow-build=openclaw directly on the install command.

Option C: Bun ​

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

--trust allows OpenClaw's package lifecycle scripts; bun run --bun forces the Bun runtime, and --daemon-runtime bun installs the managed Gateway under Bun. Bun 1.4.4 or later is required to run OpenClaw's CLI, local agents, and Gateway; Node remains the primary runtime—the bare openclaw executable keeps its Node shebang.

You should see: all three options produce the same result—the openclaw command works, onboarding proceeds as usual, and the Gateway is installed as a background service.

  • In the terminal, openclaw --version prints the version number

💡 Manual npm installs and the "freshness" policy

The official managed installer clears npm freshness filters like min-release-age for the OpenClaw package; when you npm install -g manually, your own npm policies still apply as usual. If a policy blocks the install, check your npm configuration first.

Step 4: Install OpenClaw from source ​

Why: this path is for contributors, those who want to run the latest main, or those who need to modify the source—clone the source from GitHub, build with pnpm, and link the CLI to this checkout.

bash
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

Three details:

  • pnpm add --global "openclaw@link:$PWD" links the CLI to the current checkout without modifying package files; if pnpm reports that the global bin directory is not on PATH, run pnpm setup, reopen the terminal, and try again
  • Corepack selects the exact pnpm version based on package.json (currently pnpm 12)
  • For a server checkout that only runs the Gateway, pnpm build:runtime works (it doesn't produce TypeScript declarations); if you don't want a global install, just run pnpm openclaw ... inside the repo

You should see: the build completes without errors, and openclaw points to your local copy of the source.

  • pnpm build and pnpm ui:build both finish without errors

Step 5: Verify the installation—three commands to confirm the Gateway is alive ​

Why: whichever route you took, use the same set of commands afterward to confirm—the CLI is present, the config is fine, and the Gateway is running.

bash
openclaw --version      # CLI 可用
openclaw doctor         # 检查配置问题
openclaw gateway status # Gateway 正在运行

You should see: --version prints the version number (this tutorial's baseline is v2026.10.9); doctor gives a health-check result; gateway status shows the Gateway running and listening on 18789.

The corresponding operations for the Docker route (the Gateway is in a container; the host doesn't have it):

bash
docker compose run --rm openclaw-cli dashboard --no-open   # 重新拿到 Control UI 地址
curl -fsS http://127.0.0.1:18789/healthz                   # 容器健康检查
  • All three verification commands pass (for the Docker route, use healthz + dashboard)

Checkpoint ✅ ​

  • Desktop route: the Windows Hub tray icon turns green, or the macOS menu bar App opened the dashboard onboarding
  • Docker route: http://127.0.0.1:18789/healthz returns normally, and the Control UI was logged into with the token in .env
  • npm / pnpm / Bun route: openclaw --version produces output and onboarding completes
  • Source route: pnpm build && pnpm ui:build finishes without errors, and openclaw links to the local checkout
  • I can say, using the "core idea" table, which route fits my scenario

Pitfall warnings ​

❌ npm 12 direct install reports blocked because they are not covered by allowScripts ​

Cause: npm 12 blocks unapproved package lifecycle scripts by default, so OpenClaw's preinstall / postinstall get blocked.

bash
# ❌ npm 12 不带参数
npm install -g openclaw@latest
# → blocked because they are not covered by allowScripts

# ✅ 带上允许脚本的参数
npm install -g openclaw@latest --allow-scripts=openclaw

Keep version differences in mind: npm 11.16 accepts this option but only warns and still runs; npm 11.15 and earlier have neither this policy nor this option, so do not include it in the command. Also, the npm approve-scripts openclaw recommended by npm 11.16 does not work for global installs—it reports ENOMATCH No installed packages match: openclaw.

❌ macOS system not new enough, cannot install the menu bar App ​

Cause: OpenClaw.app requires macOS 26.2 (Tahoe) or later, and this hard threshold is not lowered just because the CLI can run—the official Node 24 / 26 macOS binaries support macOS 13.5+, but "the CLI runs" does not mean "the native App is compatible".

Correct approach: on an older Mac, take the CLI installation route from the previous lesson (official Node binaries support macOS 13.5+).

❌ Building the Docker image locally: not enough memory or build failure ​

Cause: building the Gateway image locally from source requires at least 6 GB of memory.

Correct approach: use the official prebuilt image—run export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" before setup; and stick to ghcr.io/openclaw/openclaw or Docker Hub's openclaw/openclaw, avoiding third-party images.

❌ After a global pnpm install: openclaw: command not found ​

Cause: pnpm's global bin directory is not in PATH.

Correct approach: run pnpm setup, reopen the terminal, and try again (wording from the official source-install section). For the same kind of issue with global npm installs (also mostly PATH-related), see What to do if the install fails.

Advanced tips (optional) ​

Local-prefix installer: leaves the system Node untouched. If you want to keep OpenClaw together with Node under the ~/.openclaw local prefix without depending on a system-level Node:

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

It installs via npm by default, and also supports a git checkout install under the same prefix; after installing, use openclaw update --channel dev / --channel stable to switch between the package install and the git install.

Bun-only install (official pinned fork). On macOS and glibc Linux (arm64 / x64) you can do the whole install without touching Node:

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

It downloads the OpenClaw Bun fork pinned by that Release and verifies it; when --runtime is omitted, Node remains the default. On macOS it installs Homebrew SQLite as needed (OpenClaw on Bun refuses Apple's system SQLite). For details, see the official Bun docs.

Running the latest main (without manual compilation). If you don't want a full source build but still want to follow the main branch:

bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git --version main

Podman / Nix / cloud platforms. Don't want Docker? The official docs also offer a Podman rootless route (./scripts/podman/setup.sh, with the host CLI as the control plane); Nix for declarative flake installs; Ansible for batch deployment. For deployments on cloud platforms (Cloudflare, Render, Fly, Railway, etc.) and VPS with 7×24, see Server Deployment.

Lesson summary ​

✅ All the fallback routes for downloading OpenClaw are laid out: desktop editions (Windows Hub / macOS menu bar / Windows alternative Tauri), Docker containerization, direct installs via npm / pnpm / Bun, and building from source—four routes that all install the same Gateway + CLI + configuration, so pick one per scenario.

✅ You now know how to choose a desktop edition: for Windows the official recommendation is Windows Hub (no admin rights, signed installer, self-managed WSL Gateway); the macOS menu bar App requires macOS 26.2+.

✅ You can run Docker now: OPENCLAW_IMAGE + ./scripts/docker/setup.sh, with onboarding done automatically and the Control UI at 18789.

✅ You've memorized the parameter pitfalls of direct installs: npm 12 / 11.16+ with --allow-scripts=openclaw, pnpm with --allow-build=openclaw, Bun with --trust.

Key command recap:

RouteKey command / fileNotes
Windows HubOpenClawCompanion-Setup-x64.exe / -arm64.exeOfficially recommended Windows desktop edition; installs without admin rights
macOS menu barOpenClaw-<version>.dmgRequires macOS 26.2 (Tahoe) +
Windows alternativeOpenClaw-<version>-windows-x86_64.exeTauri desktop App, can bundle Bun
DockerOPENCLAW_IMAGE + ./scripts/docker/setup.shGHCR as the main channel; Docker Hub image openclaw/openclaw
npmnpm install -g openclaw@latest --allow-scripts=openclawnpm 12 / 11.16+; 11.15 and earlier: drop the parameter
pnpmpnpm add -g --allow-build=openclaw openclaw@latestapprove-builds -g does not support global installs
Bunbun add -g --trust openclaw@latestBun 1.4.4+; Node remains the primary runtime
Sourcepnpm install && pnpm build && pnpm ui:buildCorepack picks the pnpm version per package.json
Common verificationopenclaw --version / openclaw doctor / openclaw gateway statusRun these after installing via any route

For the full command cheat sheet, see CLI Commands and Configuration Cheat Sheet.

Next lesson preview ​

After getting any of the four fallback routes working, the safety-net lesson wraps up the series: What to do when install or startup fails: installation and launch troubleshooting.

You will learn:

  • Steps to troubleshoot install-time errors like a Node version below requirement or openclaw command not found
  • How to diagnose when the Gateway won't start
  • How to handle failed updates
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.