clawdbot/docs/platforms/mac/dev-setup.md

summary, read_when

summary	read_when
Setup guide for developers working on the Clawdbot macOS app	Setting up the macOS development environment

macOS Developer Setup

This guide covers the necessary steps to build and run the Clawdbot 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 & pnpm: Required for the gateway and CLI components.
3. Bun: Required to package the embedded gateway relay.

   curl -fsSL https://bun.sh/install | bash
   

1. Initialize Submodules

Clawdbot depends on several submodules (like Peekaboo). You must initialize these recursively:

git submodule update --init --recursive

2. Install Dependencies

Install the project-wide dependencies:

pnpm install

3. Build and Package the App

To build the macOS app and package it into dist/Clawdbot.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 (-).

Note

: Ad-hoc signed apps may trigger security prompts. If the app crashes immediately with "Abort trap 6", see the Troubleshooting section.

4. Install the CLI Helper

The macOS app requires a symlink named clawdbot in /usr/local/bin or /opt/homebrew/bin to manage background tasks.

To install it:

1. Open the Clawdbot app.
2. Go to the General settings tab.
3. Click "Install CLI helper" (requires administrator privileges).

Alternatively, you can manually link it from your Admin account:

sudo ln -sf "/Users/$(whoami)/Projects/clawdbot/dist/Clawdbot.app/Contents/Resources/Relay/clawdbot" /usr/local/bin/clawdbot

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:

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:

   tccutil reset All com.clawdbot.mac.debug
   

2. If that fails, change the BUNDLE_ID temporarily in 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:

clawdbot daemon status
clawdbot daemon stop

# If you’re not using a LaunchAgent (dev mode / manual runs), find the listener:
lsof -nP -iTCP:18789 -sTCP:LISTEN

Kill any existing node or clawdbot processes listening on that port and restart the app.