Skip to main content

​
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
If a manual run is holding the port, stop that process (Ctrl+C). As a last resort, kill the PID you found above.