Installing OpenClaw on macOS: A Step-by-Step Guide

Installing OpenClaw on a Mac has one decision that is easy to miss: the terminal CLI, the native macOS app, and the Gateway are related but not identical pieces. The CLI can run a Gateway in the foreground or install a per-user LaunchAgent. The app adds a menu bar interface and macOS permissions, but an app-owned local Gateway is still managed through an external CLI.

This guide is scoped to OpenClaw v2026.9.4, which GitHub marked as the latest release on September 11, 2026. Its release record shows a signed tag and public macOS DMG and ZIP assets, while also recording that some platform checks were waived or still pending. Treat the commands below as documented procedures, not as a report of an independent installation run. Read the v2026.9.4 release record.

Choose the macOS path before installing

Use the CLI and Gateway path if you work comfortably in Terminal, want a reproducible command-line setup, or intend to run the Gateway on another host. Use OpenClaw.app if you want menu bar controls, native permission prompts, notifications, Quick Chat, or a dashboard-first experience.

The current Node policy is >=24.16.0 <25 || >=26.1.0, with Node 26 recommended. Node 22, 23, and 25 are outside the current support policy. OpenClaw checks more than the version number: it also tests the loaded SQLite capability because the Gateway relies on safe SQLite behavior. Check the Node compatibility reference.

The native app has a separate floor: OpenClaw.app requires macOS 15.0 or later. A Mac that is too old for the app does not become app-compatible just because the Node-based CLI can run on it. Keep the OpenClaw state directory on a local, non-synced disk; the macOS Gateway documentation specifically warns against iCloud Drive and similar folders.

Install the CLI and Gateway

First check the active runtime:

node -v

You also need an AI route that onboarding can use: an existing Claude Code or Codex CLI login, or a provider API key. Provider authentication varies, so have the relevant account or key ready before starting the wizard.

For the normal interactive macOS install, use the official installer:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

The shorter command shown in the getting-started guide is also:

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

The installer checks Node and the linked SQLite library. On macOS it can use Homebrew to provision Node 26 when a suitable runtime is not already available, and it may therefore ask for normal system approval. It normally starts onboarding after installing an unconfigured copy. If you use --no-onboard, or run without an interactive terminal, finish with openclaw onboard. The installer documentation describes these checks and flags in more detail. Read the installer flow.

For a reproducible recovery install, the macOS Gateway page documents an exact package command. With npm 12 or npm 11.16 and later, use:

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

On npm 11.15 and earlier, omit --allow-scripts=openclaw. Use this exact-version route when a recovery instruction names a version or when the app asks you to install a matching external CLI. For ordinary updates, use openclaw update so the updater can retain its recovery information.

Install OpenClaw.app

Download the macOS app from the v2026.9.4 GitHub release. The documentation identifies OpenClaw-<version>.dmg as the preferred asset and OpenClaw-<version>.zip as the alternative. If a future latest release has no macOS asset, the documented fallback is to use the newest release that does or build from source.

On first launch, macOS asks you to approve the downloaded app and asks whether OpenClaw may discover devices on the local network. The latter permission matters when the app connects to a Gateway on another machine. Read the app's security notice before continuing.

Next choose where the Gateway runs:

• This Mac: credentials are configured locally. The app's signed installer provisions a user-space Node runtime and matching CLI under ~/.openclaw, then installs and starts the per-user LaunchAgent.
• Remote: the Gateway remains on another host over SSH or a Tailnet. Credentials for that Gateway must already exist on the Gateway host; the Mac stores the connection information it needs.
• Configure later: the app remains unconfigured until you return to setup.

This local app path is designed not to require Terminal, Homebrew, or administrator access, although it still needs an internet connection to download the separate runtime and OpenClaw package. The app's private worker is not the Gateway itself. The external CLI and LaunchAgent still own the app-managed Gateway lifecycle. See the macOS Gateway ownership and recovery details.

Complete onboarding and prove the model route

For the CLI path, run:

openclaw onboard

Quick start detects available routes, but detection is only a read-only inventory. It does not silently choose a provider, download a local model, or replace a working configuration. Select the route you want, then let OpenClaw perform a real completion. A successful completion is the important boundary: it proves that the selected authentication and model route can answer, rather than merely appearing in a list.

Choose Custom setup when you need more control over the provider, agent name, access mode, channels, daemon behavior, or imports. The CLI documentation says Quick start uses the agent name main and defaults to full access for a fresh local setup. That is convenient for a personal trial but deserves a deliberate review on a Mac containing sensitive files. A failed provider check does not automatically select another provider; read the error, retry, choose another route, or stop and fix the credential.

On a fresh local CLI install, Quick start opens the dashboard with a foreground Gateway after provider verification. Use openclaw onboard --classic only for the separate classic flow's remote Gateway setup, channel pairing, daemon controls, skills, or imports; daemon and remote choices have their own service and host requirements.

The app follows the same important rule. It presents detected connections, waits for your explicit selection, and runs a live confirmation turn before activating the route. In remote mode, do not expect a provider secret configured on the Gateway host to be copied to the Mac. Read the CLI onboarding behavior and read the macOS app onboarding behavior.

Install the background service and verify the Gateway

On fresh CLI Quick start, press Ctrl+C to stop the foreground Gateway; the configuration remains saved. Then install the per-user background service:

openclaw gateway install

Then check the three layers separately:

openclaw --version
openclaw doctor
openclaw gateway status --deep
openclaw health
openclaw dashboard

Documented healthy output includes a running runtime, a successful connectivity probe, and a Gateway listening on port 18789. The dashboard opening proves that the Control UI can connect, but send one test message and wait for an AI reply to close the loop on provider inference. A port listening by itself is not proof that authentication or model access works.

For the native app, the Connection window remains available even when the dashboard cannot connect. The bundled diagnostic command openclaw-mac status --json reports the app version and build. Use the app's Connection tab for Install Gateway, Update Gateway, or Repair Gateway when the app owns the local service.

Troubleshoot the first failing layer

OpenClaw's official first-minute ladder is:

openclaw triage
openclaw status
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw logs --follow

openclaw triage begins with read-only checks and produces a sanitized diagnosis. The main troubleshooting page maps common symptoms to the following actions. Open the complete troubleshooting decision tree.

Update with a recovery path

Before a significant update, create an independent verified backup:

mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify

The archive can include credentials, provider data, channel state, sessions, configuration, and workspaces. Store it with the same care as the live state. Never copy live .sqlite, -wal, -shm, or -journal files directly; the supported backup command captures committed SQLite state safely. Read the backup coverage and restore rules.

Preview and apply the managed update:

openclaw update --dry-run
openclaw update

The managed updater detects whether the installation is npm-, pnpm-, Bun-, or Git-owned. Where supported, it validates the candidate while the old Gateway is still serving, then activates and verifies the new one. It already coordinates the normal restart and verification. After manual repair or when investigating a reported problem, use:

openclaw doctor
openclaw gateway restart
openclaw health

Use openclaw update status --json and openclaw triage if an update fails. Preserve the recovery artifacts named in the update report until the new installation has passed its own checks. Read the managed update workflow.

Understand downgrade and automatic rollback limits

For a known-good package that can still read the current state, preview and run an exact-tag downgrade:

# When the saved channel is not extended-stable
openclaw update --tag <known-good-version> --dry-run
openclaw update --tag <known-good-version>

# When the saved channel is extended-stable, use --channel stable
openclaw update --channel stable --tag <known-good-version> --dry-run
openclaw update --channel stable --tag <known-good-version>

A package downgrade does not reverse configuration or database migrations. If a newer release has migrated state beyond what the older release understands, use a verified pre-update backup paired with the matching OpenClaw release. Stop the Gateway and other writers, preserve current state separately, and restore into a new staging directory outside the live state and agent directories:

ARCHIVE=./openclaw-backup.tar.gz
openclaw backup restore "$ARCHIVE" --target ./restored-openclaw

The target must be new or empty. Reinstall the matching package through its package manager; the backup archive does not contain the package. For an npm-owned install, use the matching version and apply the npm script-approval caveat above:

npm install -g openclaw@<matching-version> --allow-scripts=openclaw

With the Gateway still stopped, point OPENCLAW_STATE_DIR at the restored state asset or move it into place, and restore custom agent roots from the manifest. Run Doctor before restarting, then verify the running service:

openclaw doctor
openclaw gateway restart
openclaw health
openclaw gateway status --deep

The documented updater behavior includes automatic recovery for a narrower case: when a newly activated package fails verification, it can restore the retained package, service, and pre-activation configuration if database schemas remain compatible and the configuration has not been edited. A schema change, incompatible new database, or intervening configuration edit blocks that rollback. Even a successful automatic recovery remains a failed update with a nonzero exit status, so verify the restored Gateway before cleanup. Read the rollback and recovery boundaries.

Which path should you use?

Choose the CLI if your Mac is on macOS 13.5 through 14.x, if you prefer Terminal, or if the Gateway belongs on a remote or headless host. Choose OpenClaw.app on macOS 15 or later when native Mac permissions, notifications, menu bar access, and Quick Chat matter. In local app mode, remember that the app's convenience does not remove the external Gateway service boundary.

Your installation is in a useful state when all of these are true:

• The macOS and Node requirements are satisfied.
• A provider was selected explicitly and passed a real completion.
• openclaw doctor reports no blocking configuration or service errors.
• The background Gateway is running, reachable, and listening on the documented port.
• The dashboard loads and one test message receives an AI reply.
• State is on a local disk and a verified backup exists before the first consequential update.

Evidence boundary: this article uses live-opened official documentation and the release record. The expected outputs are documentation-derived; no independent macOS installation, provider login, hardware test, or app permission test was performed for this draft.

Sources

1. OpenClaw v2026.9.4 release record
2. Getting started
3. Node.js compatibility
4. Installer internals
5. macOS app
6. CLI onboarding
7. macOS app onboarding
8. Gateway on macOS
9. General troubleshooting
10. Updating
11. Backups
12. Rollback and recovery
13. Historical macOS Gateway issue #40550