Build and Run OpenClaw on macOS: Developer Guide

Setting up a local development environment can sometimes feel like a puzzle, especially when you’re dealing with specific toolchains and system permissions. If you want to get OpenClaw running on your Mac from source, this guide will help you get everything configured without the usual headaches.

Prerequisites

Before you start building, you need to make sure your machine has these two requirements ready:

1. Xcode 26.2+: This is necessary for Swift development.
2. Node.js 24 & pnpm: This is the recommended setup for the gateway, CLI, and packaging scripts. If you are using Node 22 LTS (specifically 22.14+), that is also supported.

1. Install Dependencies

First, you need to grab all the project-wide dependencies. Run this command in your terminal:

pnpm install

2. Build and Package the App

Once the dependencies are in place, you can build the macOS app and package it into dist/OpenClaw.app. Use the provided script:

./scripts/package-mac-app.sh

If you don’t have an Apple Developer ID certificate on your machine, don’t worry. The script is set up to automatically use ad-hoc signing (-).

For more details on dev run modes, signing flags, or Team ID troubleshooting, you can check the macOS app README: https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

Note: Ad-hoc signed apps might trigger security prompts from macOS. If the app crashes immediately with an “Abort trap 6” error, take a look at the Troubleshooting section below.

3. Install the CLI

The macOS app needs a global openclaw CLI installation to handle background tasks properly.

To install it (recommended):

1. Open the OpenClaw app.
2. Go to the General settings tab.
3. Click “Install CLI”.

If you prefer the manual route, you can install it via npm:

npm install -g openclaw@<version>

Troubleshooting

Build Fails: Toolchain or SDK Mismatch

The build process requires the latest macOS SDK and the Swift 6.2 toolchain.

System dependencies (required):

• Latest macOS version available in Software Update (this is required by Xcode 26.2 SDKs)
• Xcode 26.2 (Swift 6.2 toolchain)

Checks:

To verify your versions, run:

xcodebuild -version
xcrun swift --version

If these versions don’t match what’s required, you’ll need to update macOS or Xcode and try the build again.

App Crashes on Permission Grant

If you see a crash when trying to allow Speech Recognition or Microphone access, it usually means the TCC cache is corrupted or there is a signature mismatch.

Fix:

1. You can reset the TCC permissions with this command:

   tccutil reset All ai.openclaw.mac.debug

2. If that doesn’t solve it, try changing the BUNDLE_ID temporarily in scripts/package-mac-app.sh. This forces macOS to treat it as a new app and gives you a clean slate.

Gateway “Starting…” indefinitely

If the gateway status is stuck on “Starting…”, a zombie process might be holding onto the port.

Fix:

Check the status and try to stop it:

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 run is holding the port, stop that process using Ctrl+C. If all else fails, kill the PID you found using the lsof command.

Next Steps

• macOS App README
• CLI Command Reference

Need more help with your environment? Talk to the AI Setup Assistant.