> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway unter macOS

OpenClaw\.app bündelt Node/Bun oder die Gateway-Laufzeit nicht mehr. Die macOS-App
erwartet eine **externe** `openclaw`-CLI-Installation, startet das Gateway nicht als
Kindprozess und verwaltet einen launchd-Dienst pro Benutzer, um das Gateway
auszuführen (oder verbindet sich mit einem bestehenden lokalen Gateway, falls bereits eines läuft).

## Automatische Einrichtung

Wählen Sie auf einem neuen Mac während des Onboardings **Dieser Mac** aus. Die App führt ihr signiertes,
gebündeltes Installationsprogramm vor dem Gateway-Assistenten aus, installiert eine Node-Laufzeit im Benutzerbereich
und die passende `openclaw`-CLI unter `~/.openclaw` und installiert und startet anschließend den
launchd-Dienst pro Benutzer. Dieser Weg erfordert kein Terminal, kein Homebrew und keinen
Administratorzugriff.

Die App bündelt das Installationsskript, nicht die Node- oder Gateway-Nutzlast. Die Einrichtung
benötigt daher eine Internetverbindung, um die Laufzeit und das passende
OpenClaw-Paket herunterzuladen.

## Manuelle Wiederherstellung

Node 24 wird für eine manuelle Installation empfohlen. Node 22 LTS, derzeit `22.19+`,
funktioniert ebenfalls. Installieren Sie dann `openclaw` global:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
npm install -g openclaw@<version>
```

Verwenden Sie nach einer fehlgeschlagenen automatischen Einrichtung **Einrichtung erneut versuchen**. Falls dies weiterhin fehlschlägt, installieren Sie
die CLI manuell mit dem obigen Befehl und wählen Sie dann im Onboarding **Erneut prüfen**.
Node bleibt die empfohlene Gateway-Laufzeit.

## Launchd (Gateway als LaunchAgent)

Label:

* `ai.openclaw.gateway` (oder `ai.openclaw.<profile>`; veraltetes `com.openclaw.*` kann bestehen bleiben)

Plist-Speicherort (pro Benutzer):

* `~/Library/LaunchAgents/ai.openclaw.gateway.plist`
  (oder `~/Library/LaunchAgents/ai.openclaw.<profile>.plist`)

Manager:

* Die macOS-App ist im lokalen Modus für Installation/Aktualisierung des LaunchAgent verantwortlich.
* Die CLI kann ihn ebenfalls installieren: `openclaw gateway install`.

Verhalten:

* "OpenClaw Aktiv" aktiviert/deaktiviert den LaunchAgent.
* Das Beenden der App stoppt das Gateway **nicht** (launchd hält es am Leben).
* Wenn bereits ein Gateway auf dem konfigurierten Port läuft, verbindet sich die App
  damit, statt ein neues zu starten.

Protokollierung:

* launchd stdout: `~/Library/Logs/openclaw/gateway.log` (Profile verwenden `gateway-<profile>.log`)
* launchd stderr: unterdrückt

## Versionskompatibilität

Die macOS-App prüft die Gateway-Version gegen ihre eigene Version. Das Onboarding
führt die verwaltete Einrichtung automatisch aus, wenn eine vorhandene CLI fehlt oder
inkompatibel ist. Verwenden Sie **Einrichtung erneut versuchen**, um die Installation zu wiederholen, oder **Erneut prüfen**
nachdem Sie eine externe CLI repariert haben.

## Zustandsverzeichnis unter macOS

Speichern Sie den OpenClaw-Zustand auf einem lokalen, nicht synchronisierten Datenträger. Vermeiden Sie iCloud Drive und andere
cloud-synchronisierte Ordner, da Synchronisierungslatenz und Dateisperren Sitzungen,
Anmeldeinformationen und Gateway-Zustand beeinflussen können.

Setzen Sie `OPENCLAW_STATE_DIR` nur dann auf einen lokalen Pfad, wenn Sie eine Überschreibung benötigen.
`openclaw doctor` warnt vor gängigen cloud-synchronisierten Zustandspfaden und empfiehlt,
zurück auf lokalen Speicher zu wechseln. Siehe
[Umgebungsvariablen](/de/help/environment#path-related-env-vars) und
[Doctor](/de/gateway/doctor).

## App-Konnektivität debuggen

Verwenden Sie die macOS-Debug-CLI aus einem Source-Checkout, um denselben Gateway-
WebSocket-Handshake und dieselbe Discovery-Logik auszuführen, die die App verwendet:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json
```

`connect` akzeptiert `--url`, `--token`, `--timeout` und `--json`. `discover`
akzeptiert `--timeout`, `--json` und `--include-local`. Vergleichen Sie die Discovery-Ausgabe
mit `openclaw gateway discover --json`, wenn Sie CLI-Discovery
von appseitigen Verbindungsproblemen trennen müssen.

## Smoke-Check

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw --version

OPENCLAW_SKIP_CHANNELS=1 \
OPENCLAW_SKIP_CANVAS_HOST=1 \
openclaw gateway --port 18999 --bind loopback
```

Dann:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000
```

## Verwandt

* [macOS-App](/de/platforms/macos)
* [Gateway-Runbook](/de/gateway)