macOS dev setup

macOS developer setup

Build and run the OpenClaw macOS application from source.

Prerequisites

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

1. Xcode 26.2+: Required for Swift development.
2. Node.js 24 & pnpm: Recommended for the gateway, CLI, and packaging scripts. Node 22 LTS, currently
   text

   Copy

   22.14+
   , remains supported for compatibility.

1. Install Dependencies

Install the project-wide dependencies:

bash
Copy
pnpm install

2. Build and Package the App

To build the macOS app and package it into

, run:

bash
Copy
./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

3. Install the CLI

The macOS app expects a global

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:

bash
Copy
npm install -g openclaw@<version>

and also work. For the Gateway runtime, Node remains the recommended path.

Troubleshooting

Build fails: toolchain or SDK mismatch

The macOS app build expects the 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:

bash
Copy
xcodebuild -version
xcrun swift --version

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

App crashes on permission grant

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
   Copy
   tccutil reset All ai.openclaw.mac.debug
   

2. If that fails, change the

   text

   Copy

   BUNDLE_ID
   temporarily in
   text

   Copy

   scripts/package-mac-app.sh
   to force a "clean slate" from macOS.

Gateway "Starting..." indefinitely

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

bash
Copy
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 (Ctrl+C). As a last resort, kill the PID you found above.

Related

• macOS app
• Install overview