macOS-Entwickler-Setup

Diese Anleitung beschreibt die notwendigen Schritte, um die OpenClaw macOS-Anwendung aus dem Quellcode zu bauen und auszuführen.

Voraussetzungen

Stelle vor dem Bauen der App sicher, dass Folgendes installiert ist:

Xcode 26.2+: Erforderlich für Swift-Entwicklung.
Node.js 24 & pnpm: Empfohlen für das Gateway, die CLI und Paketierungsskripte. Node 22 LTS, aktuell 22.16+, wird weiterhin zur Kompatibilität unterstützt.

1. Abhängigkeiten installieren

Installiere die projektweiten Abhängigkeiten:

pnpm install

2. App bauen und paketieren

Um die macOS-App zu bauen und als dist/OpenClaw.app zu paketieren:

./scripts/package-mac-app.sh

Falls du kein Apple Developer ID-Zertifikat hast, verwendet das Skript automatisch Ad-hoc-Signierung (-).

Für Dev-Run-Modi, Signierungs-Flags und Team-ID-Fehlerbehebung siehe die macOS-App-README: https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

Hinweis: Ad-hoc signierte Apps können Sicherheitswarnungen auslösen. Falls die App sofort mit „Abort trap 6” abstürzt, siehe den Abschnitt Fehlerbehebung.

3. CLI installieren

Die macOS-App erwartet eine globale openclaw-CLI-Installation zur Verwaltung von Hintergrundaufgaben.

Zum Installieren (empfohlen):

Öffne die OpenClaw-App.
Gehe zum Allgemein-Tab in den Einstellungen.
Klicke auf „CLI installieren”.

Alternativ manuell installieren:

npm install -g openclaw@<version>

Fehlerbehebung

Build schlägt fehl: Toolchain- oder SDK-Mismatch

Der macOS-App-Build erwartet das neueste macOS SDK und die Swift 6.2-Toolchain.

Systemabhängigkeiten (erforderlich):

Neueste macOS-Version aus Software-Update (erforderlich von Xcode 26.2 SDKs)
Xcode 26.2 (Swift 6.2-Toolchain)

Prüfung:

xcodebuild -version
xcrun swift --version

Falls die Versionen nicht übereinstimmen, aktualisiere macOS/Xcode und führe den Build erneut aus.

App stürzt bei Berechtigungsvergabe ab

Falls die App abstürzt, wenn du Spracherkennung oder Mikrofon-Zugriff erlaubst, kann das an einem beschädigten TCC-Cache oder Signatur-Mismatch liegen.

Lösung:

Setze die TCC-Berechtigungen zurück:
```
tccutil reset All ai.openclaw.mac.debug
```
Falls das nicht hilft, ändere die BUNDLE_ID temporär in scripts/package-mac-app.sh, um macOS einen „sauberen Neuanfang” zu erzwingen.

Gateway bleibt bei „Starting…” hängen

Falls der Gateway-Status bei „Starting…” bleibt, prüfe ob ein Zombie-Prozess den Port belegt:

openclaw gateway status
openclaw gateway stop

# Falls du keinen LaunchAgent verwendest (Dev-Modus / manuelle Starts), finde den Listener:
lsof -nP -iTCP:18789 -sTCP:LISTEN

Falls ein manueller Lauf den Port belegt, stoppe den Prozess (Ctrl+C). Als letzten Ausweg beende die PID, die du oben gefunden hast.