mirror of
https://github.com/hansjone/oclaw.git
synced 2026-10-10 06:23:15 +08:00
oliver
dbbe3add6a
同时收敛启动与运维脚本默认行为（含 wiki worker）、更新 Admin 可观测性与相关测试，降低首轮时延并提高运行稳定性。 Made-with: Cursor
107 lines
3.1 KiB
Markdown
107 lines
3.1 KiB
Markdown
---
|
||
summary: "Setup guide for developers working on the OpenClaw macOS app"
|
||
read_when:
|
||
- Setting up the macOS development environment
|
||
title: "macOS Dev Setup"
|
||
---
|
||
|
||
# macOS Developer Setup
|
||
|
||
This guide covers the necessary steps to build and run the OpenClaw 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 24 & pnpm**: Recommended for the gateway, CLI, and packaging scripts. Node 22 LTS, currently `22.14+`, remains supported for compatibility.
|
||
|
||
## 1. Install Dependencies
|
||
|
||
Install the project-wide 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** (`-`).
|
||
|
||
For dev run modes, signing flags, and Team ID troubleshooting, see the macOS app README:
|
||
[https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md](https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md)
|
||
|
||
> **Note**: Ad-hoc signed apps may trigger security prompts. If the app crashes immediately with "Abort trap 6", see the [Troubleshooting](#troubleshooting) section.
|
||
|
||
## 3. Install the CLI
|
||
|
||
The macOS app expects a global `openclaw` CLI install to manage background tasks.
|
||
|
||
**To install it (recommended):**
|
||
|
||
1. Open the OpenClaw app.
|
||
2. Go to the **General** settings tab.
|
||
3. Click **"Install CLI"**.
|
||
|
||
Alternatively, install it manually:
|
||
|
||
```bash
|
||
npm install -g openclaw@<version>
|
||
```
|
||
|
||
`pnpm add -g openclaw@<version>` and `bun add -g openclaw@<version>` also work.
|
||
For the Gateway runtime, Node remains the recommended path.
|
||
|
||
## 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 ai.openclaw.mac.debug
|
||
```
|
||
|
||
2. If that fails, change the `BUNDLE_ID` temporarily in [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/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
|
||
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 is holding the port, stop that process (Ctrl+C). As a last resort, kill the PID you found above.
|