# macOS Dev Setup

## Prerequisites

The following tools are required:

1. **Xcode 26.2+**: Necessary for Swift development
2. **Node.js 22+ & pnpm**: Required for the gateway, CLI, and packaging scripts

## 1. Install Dependencies

```bash
pnpm install
```

## 2. Build and Package the App

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

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

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

For additional configuration options, see the apps/macos/README.md file in the repository.

> Ad-hoc signed apps may trigger security prompts. Immediate crashes with "Abort trap 6" are addressed in troubleshooting.

## 3. Install the CLI

The app requires a global `openclaw` CLI installation for background task management.

**To install:**

1. Open the OpenClaw app
2. Navigate to the **General** settings tab
3. Click **"Install CLI"**

Or manually install:

```bash
npm install -g openclaw@<version>
```

## Troubleshooting

### Build Fails: Toolchain or SDK Mismatch

Verify your toolchain versions:

```bash
xcodebuild -version
xcrun swift --version
```

Update macOS and Xcode if versions don't align.

### App Crashes on Permission Grant

Reset TCC permissions:

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

### Gateway "Starting..." Indefinitely

Check for zombie processes:

```bash
openclaw gateway status
openclaw gateway stop
lsof -nP -iTCP:18789 -sTCP:LISTEN
```