macOS App Anleitung

Die OpenClaw macOS App ist nicht der ganze Motor. Sie ist das Cockpit. Das Gateway übernimmt weiter die schwere Arbeit, aber die App gibt dir Menüleisten-Steuerung, Apple-Berechtigungen, native Mitteilungen und Mac-spezifische Fähigkeiten, die man von Hand nur ungern pflegt.

Genau dieser Unterschied ist wichtig. Viele Setups haken daran, dass Nutzer eine komplett eigenständige Desktop-App erwarten. In Wirklichkeit ist sie eher der Tower für dein lokales oder entferntes OpenClaw-Setup.

Was die macOS App wirklich macht

• Sie zeigt den OpenClaw-Status in der Menüleiste
• Sie übernimmt sensible macOS-Prompts wie Bedienungshilfen, Bildschirmaufnahme, Mikrofon und Automation
• Sie startet oder verbindet sich im lokalen Modus mit einem lokalen Gateway
• Sie verbindet sich im Remote-Modus per SSH oder direkt per ws und wss mit einem entfernten Gateway
• Sie stellt diesen Mac als Node für Canvas, Kamera, Screen-Tools, Mitteilungen und system.run bereit

Was du vor dem Start brauchst

• Einen Mac mit installierter OpenClaw App
• Node 24 empfohlen, oder Node 22.16+ für Kompatibilität
• Eine globale openclaw-CLI für den lokalen Modus
• Etwa 10 bis 15 Minuten
• Etwas Geduld für macOS-Berechtigungen, weil Apple daraus gern ein kleines Drama macht

Schritt 1: CLI für den lokalen Modus installieren

Die App bringt weder Node noch die Gateway-Laufzeit mit. Wenn dein Mac OpenClaw lokal ausführen soll, installiere zuerst die CLI.

npm install -g openclaw@latest
openclaw --version

Du kannst auch den Install-CLI-Button in der App nutzen. Intern bevorzugt die App npm, dann pnpm, dann bun. Wenn später ein Versionshinweis erscheint, bring die CLI auf die passende Version zur App.

Schritt 2: Zwischen lokalem und Remote-Modus wählen

Hier teilt sich der Weg zum ersten Mal.

Lokaler Modus

Nimm ihn, wenn dieser Mac das Gateway selbst ausführen oder sich an ein lokales Gateway anhängen soll. Die App kann den Launchd-Dienst automatisch aktivieren, falls noch nichts läuft.

Remote-Modus

Nimm ihn, wenn das eigentliche Gateway auf einem Server, einem anderen Desktop oder einem Home-Server lebt. Die Mac App wird dann Fernbedienung und lokaler Node zugleich. Standard ist ein SSH-Tunnel, direkte ws- oder wss-Verbindungen gehen aber ebenfalls.

Schritt 3: Das Gateway auf macOS von der App verwalten lassen

Im lokalen Modus verwaltet die App einen LaunchAgent pro Benutzer. Wenn auf dem konfigurierten Port schon ein Gateway läuft, hängt sie sich daran, statt ein zweites zu starten.

# Launchd-Dienst installieren oder auffrischen
openclaw gateway install

# Dienst starten oder neu anstoßen
launchctl kickstart -k gui/$UID/ai.openclaw.gateway

# Dienst stoppen
launchctl bootout gui/$UID/ai.openclaw.gateway

Nützlicher Log-Pfad:

/tmp/openclaw/openclaw-gateway.log

Schritt 4: macOS-Berechtigungen ernst nehmen, bevor sie dich später nerven

Das ist der Teil, den viele überspringen und später bereuen. Die App übernimmt TCC-Prompts für Bedienungshilfen, Bildschirmaufnahme, Mikrofon, Spracherkennung, Mitteilungen und AppleScript-Automation.

Stell dir TCC wie einen Türsteher mit Klemmbrett vor. Wenn sich App-Pfad, Bundle-ID oder Signatur ändern, zählt dein alter Stempel nicht mehr. macOS tut dann so, als hätte es dich noch nie gesehen.

Regeln für stabile Berechtigungen

• Die App immer von einem stabilen Pfad starten
• Den gleichen Bundle-Identifier behalten
• Bei signierten Builds eine konsistente echte Signatur verwenden
• Ad-hoc-Builds nicht wie Produktions-Installationen behandeln

Wenn Prompts verschwinden

1. App beenden
2. Einträge in den Systemeinstellungen unter Datenschutz & Sicherheit entfernen
3. Die App vom gleichen Pfad erneut starten
4. Falls nötig die passende TCC-Kategorie zurücksetzen und neu versuchen

sudo tccutil reset Accessibility ai.openclaw.mac
sudo tccutil reset ScreenCapture ai.openclaw.mac
sudo tccutil reset AppleEvents

Schritt 5: State nicht in iCloud legen

Lege dein OpenClaw-State-Verzeichnis nicht in iCloud Drive oder einen anderen Sync-Ordner. Sessions und Zugangsdaten verlieren gern gegen Sync-Rennen.

OPENCLAW_STATE_DIR=~/.openclaw

Wenn du seltsame File-Locks, Verzögerungen oder verschwindenden State siehst, prüfe das zuerst.

Schritt 6: Remote-Modus einrichten, wenn dein Gateway woanders läuft

Im Remote-Modus fühlt sich die macOS App plötzlich wie eine echte Steuerzentrale an. Die schwere Laufzeit bleibt auf dem Server, aber du nutzt den Mac weiter für Berechtigungen, UI, Mitteilungen und Node-Funktionen.

Voraussetzungen für Remote

• Eine funktionierende OpenClaw-CLI auf dem Zielsystem
• SSH-Zugang mit Key-Auth
• Einen stabilen Remote-Pfad und eine CLI auf PATH für nicht-interaktive Shells
• Ein gesundes Gateway auf dem Zielhost

Typischer Ablauf

1. Settings → General in der macOS App öffnen
2. Remote over SSH wählen
3. SSH-Target wie user@host oder user@host:port setzen
4. SSH-Tunnel oder direkten ws- und wss-Transport wählen
5. Test remote ausführen

Ein wichtiges Detail: Im SSH-Tunnel-Modus sieht das Gateway diesen Mac als 127.0.0.1. Das ist normal. Wenn du die echte Client-IP brauchst, nimm direkten ws- oder wss-Transport.

Schritt 7: Health über die Menüleiste prüfen

Die Menüleiste ist nicht nur Dekoration. Nutze sie.

• Grün → verbunden und zuletzt gesund
• Orange → verbindet sich oder versucht es erneut
• Rot → ausgeloggt, getrennt oder Probe fehlgeschlagen

Wenn sich die UI zu vage anfühlt, hilft ein schneller CLI-Check.

openclaw status
openclaw status --deep
openclaw health --json

Welche Mac-Fähigkeiten du damit freischaltest

Wenn alles sauber gekoppelt ist, ist die App mehr als nur ein Statussymbol.

• Canvas: lokale UI rendern, Snapshots und Auswertungen fahren
• Kamera: Bilder oder Clips aufnehmen
• Screen-Tools: Screenshots und Bildschirmaufnahmen
• System-Aktionen: Mitteilungen und freigegebene lokale Befehle über system.run

Ab hier ist die App keine Bequemlichkeit mehr, sondern ein echter Teil des Agent-Systems.

Fehlerbehebung

Die App findet die CLI nicht

Installiere die globale CLI und prüfe, ob sie im gleichen Shell-Kontext auf PATH liegt, den die App verwendet. Im Remote-Modus bedeutet Exit 127 fast immer, dass der Zielhost openclaw nicht findet.

Berechtigungen setzen sich ständig zurück

Prüfe, ob sich der App-Pfad geändert hat, die Signatur anders ist oder du mit Ad-hoc-Builds testest. Diese drei Ursachen decken fast das ganze Drama ab.

Dashboard geht, aber Mac-Funktionen bleiben offline

Dann ist die Steuerverbindung meist okay, aber die Mac-Node-Verbindung nicht. Prüfe Pairing, Node-Status und ob die nötigen Berechtigungen noch aktiv sind.

Dateizugriff hängt in Schreibtisch oder Dokumente

macOS blockiert solche Ordner oft pro Prozesskontext. Verschiebe Dateien nach ~/.openclaw/workspace, wenn du weniger Überraschungen willst.

Best Practices

• Nutze den lokalen Modus für das einfachste Single-Machine-Setup
• Nutze den Remote-Modus, wenn Uptime wichtiger ist als Laptop-Bequemlichkeit
• Halte State lokal, nicht in Sync-Ordnern
• Ignoriere die Health-Farben in der Menüleiste nicht
• Behandle macOS-Berechtigungen als festen Teil des Setups

Zusammenfassung

Die OpenClaw macOS App versteht man am besten als Begleiter, nicht als Zauberkiste. Sie übernimmt die unangenehmen Mac-spezifischen Teile, gibt dir eine saubere Steueroberfläche und kann deinen Mac zu einem starken Node für Automation, Medien und UI-Arbeit machen.

Wenn CLI, Moduswahl und Berechtigungen sauber sitzen, wird das Ganze angenehm langweilig. Unter macOS ist das fast schon ein kleines Wunder.