ContextQMD
Back to Openclaw

macOS dev setup

docs/platforms/mac/dev-setup.md

2026.7.12.7 KB
Original Source

macOS developer setup

Build and run the OpenClaw macOS application from source.

Prerequisites

  • Xcode 26.2+ (Swift 6.2 toolchain), on the latest macOS available in Software Update.
  • Node.js 24.15+ & pnpm for the gateway, CLI, and packaging scripts. Node 22.22.3+ also works.

1. Install dependencies

bash
pnpm install

2. Build and package the app

bash
./scripts/package-mac-app.sh

Outputs dist/OpenClaw.app. Without an Apple Developer ID certificate, the script falls back to ad-hoc signing.

For dev run modes, signing flags, and Team ID troubleshooting, see apps/macos/README.md. Fast dev loop from repo root: scripts/restart-mac.sh (add --no-sign for ad-hoc signing; TCC permissions do not stick with --no-sign).

<Note> Ad-hoc signed apps may trigger security prompts. If the app crashes immediately with "Abort trap 6", see [Troubleshooting](#troubleshooting). </Note>

3. Install the CLI and Gateway

The packaged app embeds the canonical scripts/install-cli.sh installer. On a fresh profile, choose This Mac during onboarding; the app installs the matching user-space CLI and runtime before starting the Gateway wizard.

For manual development recovery, install the matching CLI yourself:

bash
npm install -g openclaw@<version>

pnpm add -g openclaw@<version> and bun add -g openclaw@<version> also work. Node remains the recommended runtime for the Gateway itself.

Troubleshooting

Build fails: toolchain or SDK mismatch

The macOS app build expects the latest macOS SDK and the Swift 6.2 toolchain (Xcode 26.2+).

bash
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 a corrupted TCC cache or signature mismatch.

  1. Reset TCC permissions for the debug bundle id:

    bash
    tccutil reset All ai.openclaw.mac.debug

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

Gateway "Starting..." indefinitely

Check whether a zombie process holds the port:

bash
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 holds the port, stop it (Ctrl+C), or kill the PID found above as a last resort.