97 lines
2.9 KiB
Markdown
97 lines
2.9 KiB
Markdown
---
|
||
summary: "Setup guide for developers working on the Clawdbot macOS app"
|
||
read_when:
|
||
- 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.
|
||
```bash
|
||
curl -fsSL https://bun.sh/install | bash
|
||
```
|
||
|
||
## 1. Initialize Submodules
|
||
|
||
Clawdbot depends on several submodules (like `Peekaboo`). You must initialize these recursively:
|
||
|
||
```bash
|
||
git submodule update --init --recursive
|
||
```
|
||
|
||
## 2. Install Dependencies
|
||
|
||
Install the project-wide dependencies:
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
## 3. Build and Package the App
|
||
|
||
To build the macOS app and package it into `dist/Clawdbot.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** (`-`).
|
||
|
||
> **Note**: Ad-hoc signed apps may trigger security prompts. If the app crashes immediately with "Abort trap 6", see the [Troubleshooting](#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:
|
||
```bash
|
||
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:**
|
||
```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 due to a corrupted TCC cache or signature mismatch.
|
||
|
||
**Fix:**
|
||
1. Reset the TCC permissions:
|
||
```bash
|
||
tccutil reset All com.clawdbot.mac.debug
|
||
```
|
||
2. If that fails, change the `BUNDLE_ID` temporarily in [`scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/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
|
||
lsof -nP -i :18789
|
||
```
|
||
Kill any existing `node` or `clawdbot` processes listening on that port and restart the app.
|