macOS-Entwickler-Setup

Erstellen Sie die OpenClaw-macOS-Anwendung aus dem Quellcode und führen Sie sie aus.

Voraussetzungen

• Xcode 26.2+ (Swift-6.2-Toolchain) auf der neuesten macOS-Version, die über Software Update verfügbar ist.
• Node.js 24.15+ und pnpm für das Gateway, die CLI und die Paketierungsskripte. Node 22.22.3+ funktioniert ebenfalls.

1. Abhängigkeiten installieren

pnpm install

2. Anwendung erstellen und paketieren

./scripts/package-mac-app.sh

Erzeugt dist/OpenClaw.app. Ohne ein Apple-Developer-ID-Zertifikat greift das Skript auf eine Ad-hoc-Signierung zurück.

Informationen zu Ausführungsmodi für die Entwicklung, Signierungsflags und zur Fehlerbehebung bei der Team-ID finden Sie unter apps/macos/README.md. Schneller Entwicklungszyklus vom Repository-Stammverzeichnis aus: scripts/restart-mac.sh (fügen Sie --no-sign für die Ad-hoc-Signierung hinzu; TCC-Berechtigungen bleiben mit --no-sign nicht erhalten).

3. CLI und Gateway installieren

Die paketierte Anwendung enthält das kanonische Installationsprogramm scripts/install-cli.sh. Wählen Sie bei einem neuen Profil während des Onboardings This Mac aus; die Anwendung installiert die passende CLI und Laufzeitumgebung im Benutzerbereich, bevor sie den Gateway-Assistenten startet.

Installieren Sie zur manuellen Wiederherstellung der Entwicklungsumgebung die passende CLI selbst:

npm install -g openclaw@<version>

pnpm add -g openclaw@<version> und bun add -g openclaw@<version> funktionieren ebenfalls. Node bleibt die empfohlene Laufzeitumgebung für das Gateway selbst.

Fehlerbehebung

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

Der Build der macOS-Anwendung setzt das neueste macOS-SDK und die Swift-6.2-Toolchain (Xcode 26.2+) voraus.

xcodebuild -versionxcrun swift --version

Wenn die Versionen nicht übereinstimmen, aktualisieren Sie macOS/Xcode und führen Sie den Build erneut aus.

Anwendung stürzt beim Erteilen einer Berechtigung ab

Wenn die Anwendung abstürzt, während Sie versuchen, den Zugriff auf Speech Recognition oder Microphone zu erlauben, kann die Ursache ein beschädigter TCC-Cache oder eine nicht übereinstimmende Signatur sein.

1. Setzen Sie die TCC-Berechtigungen für die Debug-Bundle-ID zurück:

   tccutil reset All ai.openclaw.mac.debug

2. Falls dies fehlschlägt, ändern Sie vorübergehend BUNDLE_ID in scripts/package-mac-app.sh, um einen vollständig neuen Ausgangszustand unter macOS zu erzwingen.

Gateway verbleibt unbegrenzt bei „Starting...“

Prüfen Sie, ob ein Zombie-Prozess den Port belegt:

openclaw gateway statusopenclaw gateway stop # Wenn Sie keinen LaunchAgent verwenden (Entwicklungsmodus/manuelle Ausführungen), suchen Sie den Listener:lsof -nP -iTCP:18789 -sTCP:LISTEN

Wenn eine manuelle Ausführung den Port belegt, beenden Sie sie (Ctrl+C), oder beenden Sie als letztes Mittel die oben ermittelte PID.

Verwandte Themen

• macOS-Anwendung
• Installationsübersicht