Neura Market Logo

macOS Developer Setup Guide for OpenClaw App

This guide covers how to compile and launch the OpenClaw macOS application from source. It is intended for developers who need to set up their macOS environment for OpenClaw development.

Read this when

  • Setting up the macOS development environment

macOS developer setup

Compile and launch the OpenClaw macOS application from its source code.

Prerequisites

  • Xcode 26.2+ (includes the Swift 6.2 toolchain), running on the newest macOS version offered through Software Update.
  • Node.js 24.15+ and pnpm for the gateway, CLI, and packaging scripts. Node 22.22.3+ is also compatible.

1. Install dependencies

pnpm install

2. Build and package the app

./scripts/package-mac-app.sh

The result is dist/OpenClaw.app. If you lack an Apple Developer ID certificate, the script defaults to ad-hoc signing.

For guidance on development run modes, signing flags, and Team ID troubleshooting, refer to apps/macos/README.md. To iterate quickly from the repository root, use scripts/restart-mac.sh (append --no-sign for ad-hoc signing; TCC permissions are not persistent with --no-sign).

Note

Apps signed ad-hoc may display security warnings. If the application crashes immediately with "Abort trap 6", consult the Troubleshooting section.

3. Install the CLI and Gateway

The packaged application includes the standard scripts/install-cli.sh installer. On a new user profile, select This Mac during the initial setup; the app installs the appropriate user-space CLI and runtime before launching the Gateway wizard.

For manual development recovery, install the matching CLI yourself:

npm install -g openclaw@<version>

Both pnpm add -g openclaw@<version> and bun add -g openclaw@<version> are also acceptable. Node remains the preferred runtime for the Gateway itself.

Troubleshooting

Build fails: toolchain or SDK mismatch

Building the macOS app requires the latest macOS SDK and the Swift 6.2 toolchain (Xcode 26.2+).

xcodebuild -version
xcrun swift --version

If the versions are incompatible, update macOS or Xcode and rebuild.

App crashes on permission grant

If the application crashes when granting Speech Recognition or Microphone access, a corrupted TCC cache or signature mismatch may be the cause.

  1. Reset TCC permissions for the debug bundle identifier:

    tccutil reset All ai.openclaw.mac.debug

  2. If that does not resolve the issue, temporarily modify BUNDLE_ID in scripts/package-mac-app.sh to force a clean slate from macOS.

Gateway "Starting..." indefinitely

Check whether a zombie process is holding the port:

openclaw gateway status
openclaw gateway stop

# If you're not using a LaunchAgent (dev mode / manual runs), find the listener:
lsof -nP -iTCP:18789 -sTCP:LISTEN

If a manual process is occupying the port, stop it with Ctrl+C, or kill the PID found above as a last resort.