macOS Developer Setup

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

Voraussetzungen

Bevor du die App baust, stelle sicher, dass du Folgendes installiert hast:

  1. Xcode 26.2+: Erforderlich für die Swift-Entwicklung.
  2. Node.js 22+ & pnpm: Erforderlich für Gateway, CLI und Packaging-Skripte.

1. Dependencies installieren

Installiere die projektweiten Dependencies:

pnpm install

2. App bauen und packen

Um die macOS-App zu bauen und in dist/OpenClaw.app zu packen, führe aus:

./scripts/package-mac-app.sh

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

Für Dev-Run-Modi, Signing-Flags und Team-ID-Troubleshooting schau dir die macOS-App-README an: https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

Hinweis: Ad-hoc-signierte Apps können Sicherheitswarnungen auslösen. Wenn die App sofort mit “Abort trap 6” abstürzt, schau dir den Troubleshooting-Abschnitt an.

3. CLI installieren

Die macOS-App erwartet eine globale openclaw CLI-Installation, um Hintergrundaufgaben zu verwalten.

Installation (empfohlen):

  1. Öffne die OpenClaw-App.
  2. Gehe zum Tab General in den Einstellungen.
  3. Klicke auf “Install CLI”.

Alternativ kannst du sie manuell installieren:

npm install -g openclaw@<version>

Troubleshooting

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

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

System-Dependencies (erforderlich):

  • Neueste macOS-Version aus dem Software-Update (erforderlich für Xcode 26.2 SDKs)
  • Xcode 26.2 (Swift 6.2 Toolchain)

Checks:

xcodebuild -version
xcrun swift --version

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

App stürzt bei Berechtigungserteilung ab

Wenn die App abstürzt, sobald du Spracherkennung oder Mikrofon-Zugriff erlaubst, kann das an einem beschädigten TCC-Cache oder einer Signatur-Inkompatibilität liegen.

Lösung:

  1. Setze die TCC-Berechtigungen zurück: 
    tccutil reset All bot.molt.mac.debug
  2. Falls das nicht hilft, ändere die BUNDLE_ID vorübergehend in scripts/package-mac-app.sh, um einen “sauberen Neustart” von macOS zu erzwingen.

Gateway bleibt bei “Starting…” hängen

Wenn der Gateway-Status auf “Starting…” stehen bleibt, prüfe, ob ein Zombie-Prozess den Port blockiert:

openclaw gateway status
openclaw gateway stop

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

Wenn ein manueller Prozess den Port hält, stoppe ihn (Ctrl+C). Als letzten Ausweg kannst du die PID, die du oben gefunden hast, killen.