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
openclawCLI 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 | bashofficial 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 onboardwill 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
| Route | What You Need First |
|---|---|
| Desktop app | Just being able to download the installer: Windows 10 20H2+ / Windows 11 (Hub), macOS 26.2 (Tahoe)+ (menu bar App) |
| Docker | Docker Desktop or Docker Engine + Docker Compose v2; at least 6 GB of memory to build the image locally |
| npm / pnpm / Bun direct install | Node 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 source | Node + 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":
| Route | Where the Gateway runs | Runtime | Who it's for |
|---|---|---|---|
| Official installer (main path in the previous lesson) | Local background service | Installer auto-installs Node if missing | Those who want to get running fastest |
| Desktop app | Configures a local Gateway on first run of the app, or connects to an existing remote Gateway | App manages its own runtime, no dependency on system Node | Desktop users who don't want to touch the terminal |
| Docker / Podman | Inside a container | Bundled in the image | Isolated environments, servers, no local installation |
| npm / pnpm / Bun direct install | Local machine (--install-daemon installed as a service) | You manage it yourself | Developers, bulk installs in CI |
| Build from source | Local machine | You manage it yourself + pnpm | Contributors, 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:
- x64:OpenClawCompanion-Setup-x64.exe
- ARM64:OpenClawCompanion-Setup-arm64.exe
- All versions: Windows Hub releases page
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):
git clone https://github.com/openclaw/openclaw.git
cd openclaw
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.shOPENCLAW_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:
docker compose run --rm openclaw-cli dashboard --no-openContainer health check (no auth required; the image's built-in HEALTHCHECK hits exactly this):
curl -fsS http://127.0.0.1:18789/healthzYou 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/healthzreturns 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+)
npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemonnpm 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
pnpm add -g --allow-build=openclaw openclaw@latest
openclaw onboard --install-daemonpnpm 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
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 --versionprints 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.
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-daemonThree 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, runpnpm 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:runtimeworks (it doesn't produce TypeScript declarations); if you don't want a global install, just runpnpm openclaw ...inside the repo
You should see: the build completes without errors, and openclaw points to your local copy of the source.
pnpm buildandpnpm ui:buildboth 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.
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):
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/healthzreturns normally, and the Control UI was logged into with the token in.env - npm / pnpm / Bun route:
openclaw --versionproduces output and onboarding completes - Source route:
pnpm build && pnpm ui:buildfinishes without errors, andopenclawlinks 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.
# ❌ npm 12 不带参数
npm install -g openclaw@latest
# → blocked because they are not covered by allowScripts
# ✅ 带上允许脚本的参数
npm install -g openclaw@latest --allow-scripts=openclawKeep 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:
curl -fsSL https://openclaw.ai/install-cli.sh | bashIt 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:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --runtime bunIt 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:
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git --version mainPodman / 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:
| Route | Key command / file | Notes |
|---|---|---|
| Windows Hub | OpenClawCompanion-Setup-x64.exe / -arm64.exe | Officially recommended Windows desktop edition; installs without admin rights |
| macOS menu bar | OpenClaw-<version>.dmg | Requires macOS 26.2 (Tahoe) + |
| Windows alternative | OpenClaw-<version>-windows-x86_64.exe | Tauri desktop App, can bundle Bun |
| Docker | OPENCLAW_IMAGE + ./scripts/docker/setup.sh | GHCR as the main channel; Docker Hub image openclaw/openclaw |
| npm | npm install -g openclaw@latest --allow-scripts=openclaw | npm 12 / 11.16+; 11.15 and earlier: drop the parameter |
| pnpm | pnpm add -g --allow-build=openclaw openclaw@latest | approve-builds -g does not support global installs |
| Bun | bun add -g --trust openclaw@latest | Bun 1.4.4+; Node remains the primary runtime |
| Source | pnpm install && pnpm build && pnpm ui:build | Corepack picks the pnpm version per package.json |
| Common verification | openclaw --version / openclaw doctor / openclaw gateway status | Run 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