---
read_when:
    - Gateway-Prozess ausführen oder debuggen
summary: Runbook für den Gateway-Dienst, den Lebenszyklus und den Betrieb
title: Gateway-Runbook
x-i18n:
    generated_at: "2026-04-21T06:24:57Z"
    model: gpt-5.4
    provider: openai
    source_hash: e1004cdd43b1db6794f3ca83da38dbdb231a1976329d9d6d851e2b02405278d8
    source_path: gateway/index.md
    workflow: 15
---

# Gateway-Runbook

Verwenden Sie diese Seite für den Start am ersten Tag und den Betrieb am zweiten Tag des Gateway-Dienstes.

<CardGroup cols={2}>
  <Card title="Tiefgehende Fehlerbehebung" icon="siren" href="/de/gateway/troubleshooting">
    Symptomorientierte Diagnose mit exakten Befehlsabfolgen und Log-Signaturen.
  </Card>
  <Card title="Konfiguration" icon="sliders" href="/de/gateway/configuration">
    Aufgabenorientierte Einrichtungsanleitung + vollständige Konfigurationsreferenz.
  </Card>
  <Card title="Secret-Management" icon="key-round" href="/de/gateway/secrets">
    SecretRef-Vertrag, Verhalten von Runtime-Snapshots und Operationen für Migration/Reload.
  </Card>
  <Card title="Secrets-Plan-Vertrag" icon="shield-check" href="/de/gateway/secrets-plan-contract">
    Exakte Regeln für Ziele/Pfade von `secrets apply` und Ref-only-Verhalten bei Auth-Profilen.
  </Card>
</CardGroup>

## Lokaler Start in 5 Minuten

<Steps>
  <Step title="Das Gateway starten">

```bash
openclaw gateway --port 18789
# Debug/Trace nach stdio spiegeln
openclaw gateway --port 18789 --verbose
# Listener auf dem gewählten Port zwangsweise beenden, dann starten
openclaw gateway --force
```

  </Step>

  <Step title="Zustand des Dienstes prüfen">

```bash
openclaw gateway status
openclaw status
openclaw logs --follow
```

Gesunde Basis: `Runtime: running`, `Connectivity probe: ok` und `Capability: ...`, passend zu dem, was Sie erwarten. Verwenden Sie `openclaw gateway status --require-rpc`, wenn Sie einen Nachweis für RPC mit Leseberechtigung benötigen, nicht nur Erreichbarkeit.

  </Step>

  <Step title="Bereitschaft der Channels validieren">

```bash
openclaw channels status --probe
```

Mit einem erreichbaren Gateway führt dies Live-Probes pro Account für Channels und optionale Audits aus.
Wenn das Gateway nicht erreichbar ist, greift die CLI auf reine konfigurationsbasierte Channel-Zusammenfassungen zurück
statt auf die Ausgabe von Live-Probes.

  </Step>
</Steps>

<Note>
Der Reload der Gateway-Konfiguration beobachtet den aktiven Pfad der Konfigurationsdatei (aufgelöst aus Profil-/State-Standards oder `OPENCLAW_CONFIG_PATH`, wenn gesetzt).
Der Standardmodus ist `gateway.reload.mode="hybrid"`.
Nach dem ersten erfolgreichen Laden liefert der laufende Prozess den aktiven In-Memory-Snapshot der Konfiguration; ein erfolgreicher Reload tauscht diesen Snapshot atomar aus.
</Note>

## Runtime-Modell

- Ein immer laufender Prozess für Routing, Control Plane und Channel-Verbindungen.
- Ein einzelner multiplexter Port für:
  - WebSocket-Control/RPC
  - HTTP-APIs, OpenAI-kompatibel (`/v1/models`, `/v1/embeddings`, `/v1/chat/completions`, `/v1/responses`, `/tools/invoke`)
  - Control UI und Hooks
- Standard-Bind-Modus: `loopback`.
- Auth ist standardmäßig erforderlich. Setups mit gemeinsamem Secret verwenden
  `gateway.auth.token` / `gateway.auth.password` (oder
  `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`), und Reverse-Proxy-Setups
  ohne Loopback können `gateway.auth.mode: "trusted-proxy"` verwenden.

## OpenAI-kompatible Endpunkte

Die wichtigste Kompatibilitätsoberfläche von OpenClaw ist jetzt:

- `GET /v1/models`
- `GET /v1/models/{id}`
- `POST /v1/embeddings`
- `POST /v1/chat/completions`
- `POST /v1/responses`

Warum diese Auswahl wichtig ist:

- Die meisten Integrationen mit Open WebUI, LobeChat und LibreChat prüfen zuerst `/v1/models`.
- Viele RAG- und Memory-Pipelines erwarten `/v1/embeddings`.
- Agent-native Clients bevorzugen zunehmend `/v1/responses`.

Hinweis zur Planung:

- `/v1/models` ist agent-first: Es gibt `openclaw`, `openclaw/default` und `openclaw/<agentId>` zurück.
- `openclaw/default` ist der stabile Alias, der immer auf den konfigurierten Standard-Agenten verweist.
- Verwenden Sie `x-openclaw-model`, wenn Sie einen Override für Backend-Provider/Modell wünschen; andernfalls bleiben das normale Modell und das Embedding-Setup des ausgewählten Agenten maßgeblich.

Alle diese Endpunkte laufen auf dem Hauptport des Gateway und verwenden dieselbe Auth-Grenze für vertrauenswürdige Betreiber wie der Rest der Gateway-HTTP-API.

### Port- und Bind-Priorität

| Einstellung  | Reihenfolge der Auflösung                                        |
| ------------ | ---------------------------------------------------------------- |
| Gateway-Port | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789`    |
| Bind-Modus   | CLI/Override → `gateway.bind` → `loopback`                       |

### Hot-Reload-Modi

| `gateway.reload.mode` | Verhalten                                  |
| --------------------- | ------------------------------------------ |
| `off`                 | Kein Konfigurations-Reload                 |
| `hot`                 | Nur hot-sichere Änderungen anwenden        |
| `restart`             | Bei reload-pflichtigen Änderungen neu starten |
| `hybrid` (Standard)   | Wenn sicher hot anwenden, sonst neu starten |

## Operator-Befehlssatz

```bash
openclaw gateway status
openclaw gateway status --deep   # fügt einen systemweiten Dienst-Scan hinzu
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor
```

`gateway status --deep` dient der zusätzlichen Dienst-Erkennung (LaunchDaemons/systemd-System-
Units/schtasks), nicht für eine tiefere RPC-Zustandsprüfung.

## Mehrere Gateways (gleicher Host)

Die meisten Installationen sollten ein Gateway pro Maschine ausführen. Ein einzelnes Gateway kann mehrere
Agenten und Channels hosten.

Sie benötigen nur mehrere Gateways, wenn Sie bewusst Isolation oder einen Rescue-Bot möchten.

Nützliche Prüfungen:

```bash
openclaw gateway status --deep
openclaw gateway probe
```

Was Sie erwarten können:

- `gateway status --deep` kann `Other gateway-like services detected (best effort)`
  melden und Hinweise zur Bereinigung ausgeben, wenn noch veraltete Installationen von launchd/systemd/schtasks vorhanden sind.
- `gateway probe` kann vor `multiple reachable gateways` warnen, wenn mehr als ein Ziel
  antwortet.
- Falls das beabsichtigt ist, trennen Sie Ports, Konfiguration/State und Workspace-Roots pro Gateway.

Detaillierte Einrichtung: [/gateway/multiple-gateways](/de/gateway/multiple-gateways).

## Remote-Zugriff

Bevorzugt: Tailscale/VPN.
Fallback: SSH-Tunnel.

```bash
ssh -N -L 18789:127.0.0.1:18789 user@host
```

Verbinden Sie Clients dann lokal mit `ws://127.0.0.1:18789`.

<Warning>
SSH-Tunnel umgehen die Gateway-Authentifizierung nicht. Bei Auth mit gemeinsamem Secret müssen Clients
auch über den Tunnel weiterhin `token`/`password` senden. Bei identitätstragenden Modi
muss die Anfrage weiterhin diesen Auth-Pfad erfüllen.
</Warning>

Siehe: [Remote Gateway](/de/gateway/remote), [Authentication](/de/gateway/authentication), [Tailscale](/de/gateway/tailscale).

## Überwachung und Dienstlebenszyklus

Verwenden Sie überwachte Läufe für produktionsähnliche Zuverlässigkeit.

<Tabs>
  <Tab title="macOS (launchd)">

```bash
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
```

LaunchAgent-Labels sind `ai.openclaw.gateway` (Standard) oder `ai.openclaw.<profile>` (benanntes Profil). `openclaw doctor` prüft und repariert Drift in der Dienstkonfiguration.

  </Tab>

  <Tab title="Linux (systemd user)">

```bash
openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status
```

Aktivieren Sie für Persistenz nach dem Logout lingering:

```bash
sudo loginctl enable-linger <user>
```

Beispiel für eine manuelle User-Unit, wenn Sie einen benutzerdefinierten Installationspfad benötigen:

```ini
[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target
```

  </Tab>

  <Tab title="Windows (nativ)">

```powershell
openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop
```

Der nativ verwaltete Windows-Start verwendet eine Scheduled Task namens `OpenClaw Gateway`
(oder `OpenClaw Gateway (<profile>)` für benannte Profile). Wenn die Erstellung einer Scheduled Task
verweigert wird, fällt OpenClaw auf einen Launcher im benutzerspezifischen Startup-Ordner zurück,
der auf `gateway.cmd` im State-Verzeichnis zeigt.

  </Tab>

  <Tab title="Linux (Systemdienst)">

Verwenden Sie für Multi-User-/Always-on-Hosts eine System-Unit.

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway[-<profile>].service
```

Verwenden Sie denselben Service-Body wie für die User-Unit, installieren Sie ihn aber unter
`/etc/systemd/system/openclaw-gateway[-<profile>].service` und passen Sie
`ExecStart=` an, wenn sich Ihr `openclaw`-Binary an einem anderen Ort befindet.

  </Tab>
</Tabs>

## Mehrere Gateways auf einem Host

Die meisten Setups sollten **ein** Gateway ausführen.
Verwenden Sie mehrere nur für strikte Isolation/Redundanz (zum Beispiel ein Rescue-Profil).

Checkliste pro Instanz:

- Eindeutiger `gateway.port`
- Eindeutiges `OPENCLAW_CONFIG_PATH`
- Eindeutiges `OPENCLAW_STATE_DIR`
- Eindeutiges `agents.defaults.workspace`

Beispiel:

```bash
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
```

Siehe: [Multiple gateways](/de/gateway/multiple-gateways).

### Dev-Profil: schneller Pfad

```bash
openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
```

Die Standards enthalten isolierte State-/Config-Werte und den Basis-Gateway-Port `19001`.

## Kurzübersicht zum Protokoll (Operator-Sicht)

- Das erste Client-Frame muss `connect` sein.
- Das Gateway gibt den Snapshot `hello-ok` zurück (`presence`, `health`, `stateVersion`, `uptimeMs`, limits/policy).
- `hello-ok.features.methods` / `events` sind eine konservative Discovery-Liste, kein
  generierter Dump jeder aufrufbaren Helper-Route.
- Anfragen: `req(method, params)` → `res(ok/payload|error)`.
- Gängige Ereignisse sind unter anderem `connect.challenge`, `agent`, `chat`,
  `session.message`, `session.tool`, `sessions.changed`, `presence`, `tick`,
  `health`, `heartbeat`, Pairing-/Approval-Lebenszyklusereignisse und `shutdown`.

Agent-Läufe sind zweistufig:

1. Sofortige Bestätigungs-Antwort (`status:"accepted"`)
2. Endgültige Abschlussantwort (`status:"ok"|"error"`), mit gestreamten `agent`-Ereignissen dazwischen.

Die vollständige Protokolldokumentation finden Sie unter: [Gateway Protocol](/de/gateway/protocol).

## Betriebskontrollen

### Liveness

- WS öffnen und `connect` senden.
- `hello-ok`-Antwort mit Snapshot erwarten.

### Readiness

```bash
openclaw gateway status
openclaw channels status --probe
openclaw health
```

### Gap-Recovery

Ereignisse werden nicht erneut abgespielt. Bei Sequenzlücken Zustand aktualisieren (`health`, `system-presence`), bevor Sie fortfahren.

## Häufige Fehlersignaturen

| Signatur                                                       | Wahrscheinliches Problem                                                         |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `refusing to bind gateway ... without auth`                    | Bind ohne Loopback ohne gültigen Gateway-Auth-Pfad                              |
| `another gateway instance is already listening` / `EADDRINUSE` | Portkonflikt                                                                     |
| `Gateway start blocked: set gateway.mode=local`                | Konfiguration auf Remote-Modus gesetzt oder Local-Mode-Stempel fehlt in beschädigter Konfiguration |
| `unauthorized` during connect                                  | Auth-Mismatch zwischen Client und Gateway                                        |

Für vollständige Diagnosepfade verwenden Sie [Gateway Troubleshooting](/de/gateway/troubleshooting).

## Sicherheitsgarantien

- Gateway-Protokoll-Clients schlagen schnell fehl, wenn das Gateway nicht verfügbar ist (kein impliziter direkter Channel-Fallback).
- Ungültige erste Frames bzw. erste Frames ohne `connect` werden abgewiesen und die Verbindung wird geschlossen.
- Ein Graceful Shutdown sendet vor dem Schließen des Sockets ein `shutdown`-Ereignis.

---

Verwandt:

- [Troubleshooting](/de/gateway/troubleshooting)
- [Background Process](/de/gateway/background-process)
- [Configuration](/de/gateway/configuration)
- [Health](/de/gateway/health)
- [Doctor](/de/gateway/doctor)
- [Authentication](/de/gateway/authentication)
