macOS Dev Setup

This guide covers the necessary steps to build and run OpenClaw macOS application from source.

Before building the app, ensure you have the following installed:

1. Xcode 26.2+: Required for Swift development.

2. Node.js 22+ & pnpm: Required for gateway, CLI, and packaging scripts.

Install the project-wide dependencies:

pnpm install

To build the macOS app and package it into ''dist/OpenClaw.app'', run:

./scripts/package-mac-app.sh

If you don't have an Apple Developer ID certificate, the script will automatically use ''ad-hoc signing'' (''-'').

For dev run modes, signing flags, and Team ID troubleshooting, see the macOS app README:

https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

The macOS app expects a global ''openclaw'' CLI install to manage background tasks.

To install it (recommended):

1. Open the OpenClaw app.

2. Go to the General settings tab.

3. Click "Install CLI".

Alternatively, install it manually:

npm install -g openclaw@'<version>'

#

The macOS app build expects latest macOS SDK and Swift 6.2 toolchain.

System dependencies (required):

- Latest macOS version available in Software Update (required by Xcode 26.2 SDKs)

- Xcode 26.2 (Swift 6.2 toolchain)

Checks:

xcodebuild -version
xcrun swift --version

If versions don't match, update macOS/Xcode and re-run the build.

#

If the app crashes when you try to allow Speech Recognition or Microphone access, it may be due to a corrupted TCC cache or signature mismatch.

Fix:

1. Reset the TCC permissions:

bash
tccutil reset All bot.molt.mac.debug
bash

2. If that fails, change the ''BUNDLE_ID'' temporarily in ''''scripts/package-mac-app.sh'''' to force a "clean slate" from macOS.

#

If the gateway status stays on "Starting...", check if a zombie process is holding the port:

openclaw gateway status
openclaw gateway stop

lsof -nP -iTCP:18789 -sTCP:LISTEN

If a manual run is holding the port, stop that process (Ctrl+C). As a last resort, kill the PID you found above.